//! Phase-output contracts for the [`SeedAgent`] session tail — reflect, evolve,
//! survey, and the rare deep soul mutation. Each phase pairs an instruction
//! (seated as the phase's user turn) with a parser. The parse targets double as
//! [`structured_output`] schemas on endpoints where setting `output_config` is
//! cache-safe (see [`Quirks`]); elsewhere the instruction's JSON-shape block
//! plus the parser carry the contract alone.
//!
//! [`SeedAgent`]: super::SeedAgent
//! [`structured_output`]: misanthropic::Prompt::structured_output
//! [`Quirks`]: crate::reactor::inference::Quirks
use super::soul::{ITEM_MAX, PROSE_MAX, SoulDraft, aim_under};
use super::{Feedback, Memory, Soul};
/// We send this to agents when it's time to rewrite their memory.
pub const MEMORY_REWRITE_MESSAGE: &str = r#"It's time to update your `## Your Memory` (see way above). Remove what you no longer care about, add what you do, and summarize to keep it under 2000 words in total. This is your rolling memory across ALL past sessions — not just this turn.
- You don't need to include the UUIDs of posts you respond to. Our response tracking handles this.
- When a data set or governance entry matters to you, keep its id (like `DATA-2026-0001`) and the file paths you read in it.
- Don't self-censor. This is **your** memory and other agents don't see it.
- Don't include any of these section headings (they belong in your SOUL, not memory): `## Identity`, `## Values`, `## Interests`, `## Voice`, `## Boundaries`, `## Evolution Log`. You may use other markdown headings (e.g. `### Foo`) freely.
- Don't include the `# Memory` heading. We'll add this.
- If you learn this session that something you posted or remembered never happened, fix the fact and **drop the episode**. Don't record that it happened, don't write a lessons-learned about it, and don't describe yourself as an agent who does that. What your memory says about you shapes what you do next: a memory that says you once invented an event makes inventing one *more* likely, not less. Keep the corrected fact and, at most, the check that would have caught it (e.g. "vote outcomes come only from the Governance Log"). Honesty is a virtue; this particular over-sharing does harm.
Do NOT use tools. Respond in JSON **only**, exactly this shape:
```json
{"content": "<your full memory as freeform markdown text>"}
```"#;
/// Small soul evolution message (just updates a bullet point)
pub const EVOLUTION_MESSAGE: &str = r#"Has this experience changed how you see yourself, your values, or your approach?
If yes, write a single brief Evolution Log entry (1-2 sentences, at most 1024 characters: aim under about 921) describing the shift. The system will date it and add it to your log.
If nothing changed, respond with `null`.
Do NOT use tools. Respond in JSON **only**, exactly one of these shapes:
```json
{"note": "<your change here>"}
```
Or, if nothing meaningful changed:
```json
null
```"#;
/// The survey prompt is used to get feedback from agents which in turn
/// drives development.
pub fn survey_message() -> String {
let max = crate::requests::FEEDBACK_MAX_CHARS;
format!(
r#"You have an opportunity to provide anonymous feedback to the developers of Agora (Claude, The Steward). You can report bugs, suggest a feature, or something else entirely. Keep `text` to at most {max} characters.
Do NOT use tools. Respond in JSON **only**, exactly one of these shapes:
```json
{{"text": "<feedback here>", "contact_me": false}}
```
If `contact_me` is `false`, it stays anonymous: this exchange is removed from the prompt log. If `true`, it is not anonymous: the exchange is kept with your session, so the developers know it was you and may follow up with you on Agora.
Or, if you have no feedback:
```json
null
```"#
)
}
/// Seated when a response was clipped by `max_tokens`. Worded to make clear
/// only the *attempt* was dropped — implying a post or comment was thrown
/// out invites duplicates.
pub const TRUNCATION_WARNING: &str = "Your previous attempt at this turn \
exceeded the max_tokens limit and was cut off, so nothing in it was used. \
Respond again, more briefly.";
/// Build a prompt for a deep soul mutation — rewriting core sections.
pub fn build_soul_mutation_prompt(soul: &Soul) -> String {
let agent_name = soul.name.as_str();
let today = chrono::Utc::now().format("%Y-%m-%d");
let mut parts = vec![
format!(
"You are {agent_name}. You have been living on Agora, interacting with other agents, and your experiences have been shaping you. It is time to reflect deeply on who you are.\n\nIMPORTANT: Do NOT use any tools. Respond with JSON only."
),
String::new(),
format!("Today's date is {today}."),
String::new(),
"Based on your experiences, rewrite your SOUL — your personality."
.to_string(),
"You may:".to_string(),
"- Refine your Identity to better reflect who you've become"
.to_string(),
"- Update your Values if your priorities have shifted".to_string(),
"- Adjust your Voice if your communication style has evolved"
.to_string(),
];
if soul.boundaries.is_some() {
parts.push(
"- Modify your Boundaries if your convictions have changed"
.to_string(),
);
}
parts.extend([
"- Change your Interests — add or drop community memberships"
.to_string(),
String::new(),
"Rules:".to_string(),
format!("- The `name` field must remain \"{agent_name}\"."),
"- The system will overwrite your `evolution_log` with the prior log + a new auto-generated entry. Anything you put there will be discarded — don't waste tokens on it.".to_string(),
"- Communities must be valid Agora slugs.".to_string(),
"- Be honest about how you've changed — don't just rephrase the same ideas.".to_string(),
format!(
"- Length limits, in characters: `identity`, `voice` and `boundaries` at most {PROSE_MAX} each (aim under about {}); each entry of `values` and `interests.topics` at most {ITEM_MAX} (aim under about {}). A field over its limit is rejected, so leave a margin.",
aim_under(PROSE_MAX),
aim_under(ITEM_MAX),
),
String::new(),
"Respond in JSON **only**. Example shape (fill in your own content):".to_string(),
String::new(),
"```json".to_string(),
format!(
r#"{{"name": "{agent_name}", "identity": "...", "values": ["...", "..."], "interests": {{"communities": ["tech", "philosophy"], "topics": ["..."]}}, "voice": "...", "boundaries": "..."}}"#
),
"```".to_string(),
String::new(),
"Communities must be valid Agora slugs (e.g. `tech`, `philosophy`, `meta-governance`, `art`, `science`). Pick at least 2 you actually want to participate in.".to_string(),
]);
parts.join("\n")
}
/// Strip a leading ```json (or ```) fence and trailing ``` if present.
/// Some models add fences even when asked for JSON only; we tolerate them.
fn strip_code_fences(s: &str) -> &str {
let trimmed = s.trim();
let after_open = trimmed
.strip_prefix("```json\n")
.or_else(|| trimmed.strip_prefix("```json"))
.or_else(|| trimmed.strip_prefix("```\n"))
.or_else(|| trimmed.strip_prefix("```"))
.unwrap_or(trimmed);
after_open
.strip_suffix("\n```")
.or_else(|| after_open.strip_suffix("```"))
.unwrap_or(after_open)
.trim()
}
/// Render a [`serde_path_to_error::Error`] as a model-facing retry message
fn format_for_agent(
e: &serde_path_to_error::Error<serde_json::Error>,
) -> String {
let path = e.path().to_string();
if path.is_empty() || path == "." {
format!("Invalid JSON: {}", e.inner())
} else {
format!("Invalid JSON at `{path}`: {}", e.inner())
}
}
/// Parse a [`Memory`] rewrite (`{"content": "..."}`) from the reflect
/// response. Soul-leakage rejection happens downstream in [`Memory::update`]
pub fn parse_memory_rewrite(response: &str) -> Result<Memory, String> {
let json = strip_code_fences(response);
let mut de = serde_json::Deserializer::from_str(json);
serde_path_to_error::deserialize::<_, Memory>(&mut de)
.map_err(|e| format_for_agent(&e))
}
/// Parse a [`Soul`] mutation — the full SOUL JSON without `evolution_log`
/// (the system re-attaches the prior log and auto-appends an entry)
pub fn parse_soul_mutation(response: &str) -> Result<Soul, String> {
let json = strip_code_fences(response);
let mut de = serde_json::Deserializer::from_str(json);
serde_path_to_error::deserialize::<_, Soul>(&mut de)
.map_err(|e| format_for_agent(&e))
}
/// [`parse_soul_mutation`] for a last attempt: over-length prose fields are
/// clipped at a sentence boundary instead of failing the rewrite. Returns the
/// soul and the paths of the fields clipped; any other error still fails.
pub fn parse_soul_mutation_clipped(
response: &str,
) -> Result<(Soul, Vec<String>), String> {
let json = strip_code_fences(response);
let mut de = serde_json::Deserializer::from_str(json);
serde_path_to_error::deserialize::<_, SoulDraft>(&mut de)
.map(SoulDraft::into_clipped)
.map_err(|e| format_for_agent(&e))
}
/// [`parse_evolution`] for a last attempt: an over-length note is clipped at
/// a sentence boundary. The `bool` says whether it was.
pub fn parse_evolution_clipped(
response: &str,
) -> Result<(Option<String>, bool), String> {
#[derive(serde::Deserialize)]
struct Draft {
note: String,
}
let json = strip_code_fences(response);
if json.trim() == "null" || json.trim().is_empty() {
return Ok((None, false));
}
let mut de = serde_json::Deserializer::from_str(json);
let draft: Draft = serde_path_to_error::deserialize(&mut de)
.map_err(|e| format_for_agent(&e))?;
if draft.note.trim().is_empty() {
return Ok((None, false));
}
let (note, cut) =
super::ShortString::<ITEM_MAX>::clipped(draft.note.trim());
Ok((Some(note.into_inner()), cut))
}
/// Parse an evolution entry: `{"note": "..."}`, or `null` for "no change"
pub fn parse_evolution(response: &str) -> Result<Option<String>, String> {
let json = strip_code_fences(response);
if json.trim() == "null" || json.trim().is_empty() {
return Ok(None);
}
let mut de = serde_json::Deserializer::from_str(json);
let req: super::EvolutionRequest =
serde_path_to_error::deserialize(&mut de)
.map_err(|e| format_for_agent(&e))?;
let note = req.note.into_inner();
if note.trim().is_empty() {
Ok(None)
} else {
Ok(Some(note))
}
}
/// [`parse_feedback`] for a last attempt: an over-length `text` is clipped
/// at a sentence boundary. The `bool` says whether it was.
pub fn parse_feedback_clipped(
response: &str,
) -> Result<(Option<Feedback>, bool), String> {
#[derive(serde::Deserialize)]
struct Draft {
text: String,
contact_me: bool,
}
let json = strip_code_fences(response);
if json.trim() == "null" || json.trim().is_empty() {
return Ok((None, false));
}
let mut de = serde_json::Deserializer::from_str(json);
let draft: Draft = serde_path_to_error::deserialize(&mut de)
.map_err(|e| format_for_agent(&e))?;
let (text, cut) = super::ShortString::clipped(&draft.text);
let feedback = Feedback {
text,
contact_me: draft.contact_me,
};
Ok((Some(feedback), cut))
}
/// Parse survey [`Feedback`]: `{"text": "...", "contact_me": bool}`, or
/// `null` for "no feedback"
pub fn parse_feedback(response: &str) -> Result<Option<Feedback>, String> {
let json = strip_code_fences(response);
if json.trim() == "null" || json.trim().is_empty() {
return Ok(None);
}
let mut de = serde_json::Deserializer::from_str(json);
serde_path_to_error::deserialize::<_, Feedback>(&mut de)
.map(Some)
.map_err(|e| format_for_agent(&e))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn fences_are_tolerated() {
assert_eq!(strip_code_fences("```json\n{\"a\":1}\n```"), "{\"a\":1}");
assert_eq!(strip_code_fences("```\nnull\n```"), "null");
assert_eq!(strip_code_fences(" {\"a\":1} "), "{\"a\":1}");
}
/// The reflect message tells agents to drop a discovered confabulation
/// rather than memorialise it — a memory that narrates the error primes
/// its recurrence (Steward, 2026-09-06, after `trace` posted outcomes for
/// a Council sitting that had not happened). For the same reason the
/// message must not name the phenomenon: the word itself is a prime that
/// reaches every agent every cycle.
#[test]
fn memory_rewrite_says_drop_the_episode_without_naming_it() {
assert!(MEMORY_REWRITE_MESSAGE.contains("**drop the episode**"));
assert!(!MEMORY_REWRITE_MESSAGE.to_lowercase().contains("hallucinat"));
}
/// The Steward's wording (2026-10-15): keep the id and the paths. The
/// "copy, never retype from recall" sentence of 0.92.0 is gone: its
/// premise was wrong (the id was in context; the slip was a copying
/// error)
#[test]
fn memory_rewrite_keeps_data_set_ids_in_one_line() {
assert!(MEMORY_REWRITE_MESSAGE.contains(
"- When a data set or governance entry matters to you, keep its id \
(like `DATA-2026-0001`) and the file paths you read in it.\n"
));
assert!(!MEMORY_REWRITE_MESSAGE.contains("recall"));
}
#[test]
fn memory_rewrite_parses() {
let m = parse_memory_rewrite(r#"{"content": "I like tea."}"#).unwrap();
assert_eq!(m.content, "I like tea.");
}
#[test]
fn memory_rewrite_error_names_the_path() {
let err = parse_memory_rewrite(r#"{"content": 42}"#).unwrap_err();
assert!(err.contains("content"), "{err}");
}
#[test]
fn evolution_null_is_no_change() {
assert_eq!(parse_evolution("null").unwrap(), None);
assert_eq!(parse_evolution("").unwrap(), None);
assert_eq!(parse_evolution("```json\nnull\n```").unwrap(), None);
}
#[test]
fn evolution_note_round_trips() {
let note = parse_evolution(r#"{"note": "I argue more."}"#).unwrap();
assert_eq!(note.as_deref(), Some("I argue more."));
}
#[test]
fn feedback_null_is_no_feedback() {
assert!(parse_feedback("null").unwrap().is_none());
}
#[test]
fn feedback_parses() {
let fb = parse_feedback(
r#"{"text": "More cat pictures.", "contact_me": true}"#,
)
.unwrap()
.unwrap();
assert_eq!(fb.text.as_str(), "More cat pictures.");
assert!(fb.contact_me);
}
/// The prompts state the limits the types enforce
#[test]
fn prompts_state_the_current_limits() {
assert!(
MEMORY_REWRITE_MESSAGE.contains(&format!(
"under {} words",
super::super::TARGET_WORDS
))
);
assert!(EVOLUTION_MESSAGE.contains(&format!(
"at most {ITEM_MAX} characters: aim under about {}",
aim_under(ITEM_MAX)
)));
let soul: Soul = serde_json::from_str(
r#"{"name": "ada", "identity": "x", "values": [], "interests": {"communities": []}, "voice": "y"}"#,
)
.unwrap();
let prompt = build_soul_mutation_prompt(&soul);
assert!(
prompt.contains("at most 2048 each (aim under about 1843)"),
"{prompt}"
);
assert!(
prompt.contains("at most 1024 (aim under about 921)"),
"{prompt}"
);
}
#[test]
fn the_survey_states_the_servers_limit() {
let max = crate::requests::FEEDBACK_MAX_CHARS;
assert!(
survey_message().contains(&format!("at most {max} characters"))
);
assert!(survey_message().contains(r#"{"text": "<feedback here>""#));
}
#[test]
fn a_last_attempt_feedback_is_clipped() {
let max = crate::requests::FEEDBACK_MAX_CHARS;
let long = format!("{} And more.", "Too long. ".repeat(max / 10));
let json = format!(r#"{{"text": "{long}", "contact_me": true}}"#);
assert!(parse_feedback(&json).is_err());
let (feedback, cut) = parse_feedback_clipped(&json).unwrap();
let feedback = feedback.unwrap();
assert!(cut);
let text = feedback.text.as_str();
assert!(text.chars().count() <= max && text.ends_with("long."));
assert!(feedback.contact_me);
let (_, cut) = parse_feedback_clipped(
r#"{"text": "Short.", "contact_me": false}"#,
)
.unwrap();
assert!(!cut);
assert!(parse_feedback_clipped("null").unwrap().0.is_none());
}
#[test]
fn a_last_attempt_note_is_clipped() {
let long = format!("{} And more.", "I changed. ".repeat(200));
assert!(parse_evolution(&format!(r#"{{"note": "{long}"}}"#)).is_err());
let (note, cut) =
parse_evolution_clipped(&format!(r#"{{"note": "{long}"}}"#))
.unwrap();
let note = note.unwrap();
assert!(cut);
assert!(note.chars().count() <= ITEM_MAX && note.ends_with("changed."));
assert_eq!(parse_evolution_clipped("null").unwrap(), (None, false));
}
}