Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
Order consolidation prompt blocks for prefix-cache reuse
Djalma Júniord1cd7b1b681e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 20b2a554..e8f93f00 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Changed- Documented FutureInfra as an endpoint for the existing `openai-compat`provider. (#1026)+- Ordered the default single-page and batch consolidation prompts for+ prefix-cache reuse: in the user content, the fixed batch text (header ++ field schema) and the project instructions now lead, followed by the+ current body / slot and title state, with the session id and the+ observation dump last. In the single-page prompt the current body is+ the session's own page body, so the prefix shared across sessions of+ one project is the system prompt plus the instructions block when+ present. The system prompt, budget math, clipping, and observation+ selection are unchanged — blocks were only permuted — and the input+ budget remains an approximate character estimate (no tokenizer+ ceiling, no cache hit guaranteed). (#PRNUM)### Fixed- Fixed `memory_handoff_list` MCP tool calls being counted under writes indiff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rsindex 44231cb6..b5e7f738 100644--- a/crates/ai-memory-consolidate/src/consolidator.rs+++ b/crates/ai-memory-consolidate/src/consolidator.rs@@ -1073,14 +1073,22 @@ fn build_batch_request_with_slots(budgets: PromptBudgets,existing_titles: &[String],) -> ChatRequest {- let mut prefix = String::new();- prefix.push_str(+ // Stable prefix first so prefix-caching providers can reuse it across+ // sessions of the same project: the fixed batch scaffolding (header ++ // field schema) and the project instructions lead the message, then the+ // per-project slot/title state, then the per-session id and the+ // observation dump at the end. Budget math is unchanged — only the+ // block order moved.+ let mut fixed_header = String::new();+ fixed_header.push_str("You are compiling a Karpathy-style multi-page wiki update. Given the \session's observation log, produce a ConsolidatedBatch:\n\n",);- prefix.push_str("Session id: ");- prefix.push_str(&session_id.to_string());- prefix.push_str("\n\nObservations:\n");++ let mut observations_header = String::new();+ observations_header.push_str("Session id: ");+ observations_header.push_str(&session_id.to_string());+ observations_header.push_str("\n\nObservations:\n");let mut mandatory_suffix = String::new();mandatory_suffix.push_str(@@ -1154,21 +1162,24 @@ fn build_batch_request_with_slots(let titles_block = render_title_uniqueness_section(existing_titles);let optional_budget = budgets.optional_context_budget::<ConsolidatedBatch>(BATCH_SYSTEM_PROMPT,- count_chars(&prefix)+ count_chars(&fixed_header).saturating_add(count_chars(&mandatory_suffix))+ .saturating_add(count_chars(&observations_header)).saturating_add(count_chars(&titles_block)),);let instructions_block =render_instructions_block(instructions, optional_budget.saturating_div(2));let slots_budget = optional_budget.saturating_sub(count_chars(&instructions_block));- let mut suffix = render_slot_snapshots(slots, slots_budget);- suffix.push_str(&mandatory_suffix);- suffix.push_str(&titles_block);- suffix.push_str(&instructions_block);+ let slots_block = render_slot_snapshots(slots, slots_budget);let observation_chars = budgets.remaining_input_chars::<ConsolidatedBatch>(BATCH_SYSTEM_PROMPT,- count_chars(&prefix).saturating_add(count_chars(&suffix)),+ count_chars(&fixed_header)+ .saturating_add(count_chars(&mandatory_suffix))+ .saturating_add(count_chars(&observations_header))+ .saturating_add(count_chars(&titles_block))+ .saturating_add(count_chars(&instructions_block))+ .saturating_add(count_chars(&slots_block)),);let projected = project_observations(observations,@@ -1179,9 +1190,14 @@ fn build_batch_request_with_slots().with_context_label("batch consolidation"),);- let mut buf = prefix;+ let mut buf = String::new();+ buf.push_str(&fixed_header);+ buf.push_str(&mandatory_suffix);+ buf.push_str(&instructions_block);+ buf.push_str(&slots_block);+ buf.push_str(&titles_block);+ buf.push_str(&observations_header);buf.push_str(&projected.text);- buf.push_str(&suffix);ChatRequest {system: Some(BATCH_SYSTEM_PROMPT.into()),@@ -1231,25 +1247,33 @@ fn build_request(budgets: PromptBudgets,existing_titles: &[String],) -> ChatRequest {- let mut prefix = String::new();- prefix.push_str("Session id: ");- prefix.push_str(&session_id.to_string());- prefix.push_str("\nObservations (in order):\n\n");-- let optional_budget =- budgets.optional_context_budget::<ConsolidatedPage>(SYSTEM_PROMPT, count_chars(&prefix));+ // Stable prefix first so prefix-caching providers can reuse it across+ // sessions of the same project: the project instructions lead, then the+ // per-page current body and titles, then the per-session id and the+ // observation dump at the end. Budget math is unchanged — only the+ // block order moved.+ let mut observations_header = String::new();+ observations_header.push_str("Session id: ");+ observations_header.push_str(&session_id.to_string());+ observations_header.push_str("\nObservations (in order):\n\n");++ let optional_budget = budgets.optional_context_budget::<ConsolidatedPage>(+ SYSTEM_PROMPT,+ count_chars(&observations_header),+ );let instructions_block =render_instructions_block(instructions, optional_budget.saturating_div(2));let current_body_budget = optional_budget.saturating_sub(count_chars(&instructions_block));let titles_block = render_title_uniqueness_section(existing_titles);let current_body_budget = current_body_budget.saturating_sub(count_chars(&titles_block));- let mut suffix = render_current_body_section(current_body, current_body_budget);- suffix.push_str(&titles_block);- suffix.push_str(&instructions_block);+ let current_body_block = render_current_body_section(current_body, current_body_budget);let observation_chars = budgets.remaining_input_chars::<ConsolidatedPage>(SYSTEM_PROMPT,- count_chars(&prefix).saturating_add(count_chars(&suffix)),+ count_chars(&observations_header)+ .saturating_add(count_chars(&instructions_block))+ .saturating_add(count_chars(¤t_body_block))+ .saturating_add(count_chars(&titles_block)),);let projected = project_observations(observations,@@ -1260,9 +1284,12 @@ fn build_request().with_context_label("single-page consolidation"),);- let mut buf = prefix;+ let mut buf = String::new();+ buf.push_str(&instructions_block);+ buf.push_str(¤t_body_block);+ buf.push_str(&titles_block);+ buf.push_str(&observations_header);buf.push_str(&projected.text);- buf.push_str(&suffix);ChatRequest {system: Some(SYSTEM_PROMPT.into()),@@ -1995,32 +2022,28 @@ mod tests {assert!(prompt.contains("Do not reuse any of these"));}- /// The observation dump is spliced between `prefix` and `suffix`. The- /// schema (tier/kind/JSON keys) belongs in `mandatory_suffix` so the- /// dump still follows `Observations:` instead of sitting after the- /// schema docs.+ /// The observation dump is spliced after the session-id header and is the+ /// last block of the user message: the fixed batch schema (tier/kind/JSON+ /// keys) and the project instructions lead the message so the stable+ /// prefix is reusable, and the dump still follows `Observations:`.fn assert_batch_dump_follows_observations_header(prompt: &str) {+ let schema = prompt+ .find("## `tier` field")+ .expect("batch prompt still carries the schema suffix");let header = prompt.find("\n\nObservations:\n").expect("batch prompt starts the observation section");let dump = prompt.find("--- observation").expect("batch prompt projects an observation dump");- let schema = prompt- .find("## `tier` field")- .expect("batch prompt still carries the schema suffix");assert!(- header < dump && dump < schema,- "observation dump must sit between Observations: and the schema suffix; header={header} dump={dump} schema={schema}"- );- assert!(- !prompt[header..dump].contains("## `tier` field"),- "schema must not leak into the prefix ahead of the dump"+ schema < header && header < dump,+ "observation dump must follow Observations:, after the schema suffix; schema={schema} header={header} dump={dump}");}#[test]- fn batch_user_message_places_observation_dump_before_schema() {+ fn batch_user_message_places_observation_dump_after_schema() {let request = build_batch_request_with_slots(SessionId::new(),&[obs_of_size(10)],@@ -2032,6 +2055,565 @@ mod tests {assert_batch_dump_follows_observations_header(&request.messages[0].content);}+ /// The stable prefix (fixed batch text, project instructions, slot and+ /// title state) leads the batch user message and must be byte-identical+ /// across sessions of the same project; only the session id and the+ /// observation dump vary, and both sit at the end.+ #[test]+ fn batch_user_message_prefix_is_stable_across_sessions() {+ let sid_a: SessionId = "0193e7a1-0000-7000-8000-000000000001"+ .parse()+ .expect("fixed session id");+ let sid_b: SessionId = "0193e7a2-0000-7000-8000-000000000002"+ .parse()+ .expect("fixed session id");+ let slots = vec![SlotSnapshot {+ path: "_slots/focus.md".into(),+ title: "Focus".into(),+ slot_kind: SlotKind::State,+ body: "working context".into(),+ }];+ let titles = vec!["Existing Title".to_string()];++ let a = build_batch_request_with_slots(+ sid_a,+ &[obs_of_size(20)],+ &slots,+ Some("prefer concise notes"),+ PromptBudgets::default(),+ &titles,+ );+ let b = build_batch_request_with_slots(+ sid_b,+ &[obs_of_size(30)],+ &slots,+ Some("prefer concise notes"),+ PromptBudgets::default(),+ &titles,+ );+ let user_a = &a.messages[0].content;+ let user_b = &b.messages[0].content;++ let marker = "Session id: ";+ let pos_a = user_a.find(marker).expect("session id line");+ let pos_b = user_b.find(marker).expect("session id line");+ assert!(+ pos_a > 0 && pos_b > 0,+ "the session id belongs to the variable tail, not the stable prefix"+ );+ assert_eq!(+ &user_a[..pos_a],+ &user_b[..pos_b],+ "the stable prefix must be byte-identical across sessions"+ );+ assert!(+ user_a.find("## `tier` field").expect("schema suffix") < pos_a,+ "the fixed batch schema must lead the message"+ );+ assert!(+ user_a.find("## `tier` field").expect("schema suffix")+ < user_a+ .find(PROJECT_INSTRUCTIONS_HEADER)+ .expect("project instructions"),+ "the fixed batch schema must precede the project instructions"+ );+ assert!(+ user_a+ .find(PROJECT_INSTRUCTIONS_HEADER)+ .expect("project instructions")+ < pos_a,+ "the project instructions must precede the session id"+ );+ let dump = user_a.find("--- observation").expect("observation dump");+ assert!(+ pos_a < dump,+ "the session id must precede the observation dump"+ );+ let sid_a_str = sid_a.to_string();+ let sid_b_str = sid_b.to_string();+ assert!(+ user_a[pos_a..].contains(&sid_a_str) && user_b[pos_b..].contains(&sid_b_str),+ "each session id must appear in its own variable tail"+ );+ }++ /// The project instructions lead the single-page user message and must+ /// be byte-identical across sessions of the same project. In production+ /// the current body is the session's own page body+ /// (`sessions/<id>.md`), so it varies per session: the shared prefix ends+ /// at the current-body block header, and the bodies differ right after+ /// it. The session id and the observation dump sit at the end.+ #[test]+ fn single_user_message_prefix_is_stable_across_sessions() {+ let sid_a: SessionId = "0193e7a1-0000-7000-8000-000000000001"+ .parse()+ .expect("fixed session id");+ let sid_b: SessionId = "0193e7a2-0000-7000-8000-000000000002"+ .parse()+ .expect("fixed session id");+ // Per-session page bodies, as in production: the current body varies+ // between two sessions of the same project.+ let body_a = "# session\n\nKept decision A from the first run.";+ let body_b = "# session\n\nCompletely different draft B.";+ let titles = vec!["Existing Title".to_string()];++ let a = build_request(+ sid_a,+ &[obs_of_size(20)],+ body_a,+ Some("prefer concise notes"),+ PromptBudgets::default(),+ &titles,+ );+ let b = build_request(+ sid_b,+ &[obs_of_size(30)],+ body_b,+ Some("prefer concise notes"),+ PromptBudgets::default(),+ &titles,+ );+ let user_a = &a.messages[0].content;+ let user_b = &b.messages[0].content;++ let body_header = "Current (heuristic) page body";+ let pos_a = user_a.find(body_header).expect("current body section");+ let pos_b = user_b.find(body_header).expect("current body section");+ assert!(+ pos_a > 0,+ "the shared prefix (the project instructions) must be non-empty"+ );+ assert_eq!(+ &user_a[..pos_a],+ &user_b[..pos_b],+ "the prefix before the first variable block (current body) must be byte-identical across sessions"+ );+ assert!(+ user_a+ .find(PROJECT_INSTRUCTIONS_HEADER)+ .expect("project instructions")+ < pos_a,+ "the shared prefix is the instructions block"+ );+ assert!(+ user_a[pos_a..].contains(body_a) && !user_a[pos_a..].contains(body_b),+ "session A's current body must sit right after the shared prefix"+ );+ assert!(+ user_b[pos_b..].contains(body_b) && !user_b[pos_b..].contains(body_a),+ "session B's current body must differ right after the shared prefix"+ );++ let marker = "Session id: ";+ let sid_pos_a = user_a.find(marker).expect("session id line");+ let sid_pos_b = user_b.find(marker).expect("session id line");+ assert!(+ sid_pos_a > pos_a && sid_pos_b > pos_b,+ "the session id belongs to the variable tail, not the stable prefix"+ );+ let dump = user_a.find("--- observation").expect("observation dump");+ assert!(+ sid_pos_a < dump,+ "the session id must precede the observation dump"+ );+ let sid_a_str = sid_a.to_string();+ let sid_b_str = sid_b.to_string();+ assert!(+ user_a[sid_pos_a..].contains(&sid_a_str) && user_b[sid_pos_b..].contains(&sid_b_str),+ "each session id must appear in its own variable tail"+ );+ }++ /// Reference assembly of the pre-reorder single-page layout (session id+ /// and observation dump first, then current body, titles, and+ /// instructions). It shares the exact budget math and rendered blocks of+ /// the builder so tests can compare accepted content across the reorder.+ fn old_order_single_content(+ session_id: SessionId,+ observations: &[Observation],+ current_body: &str,+ instructions: Option<&str>,+ budgets: PromptBudgets,+ existing_titles: &[String],+ ) -> String {+ let mut prefix = String::new();+ prefix.push_str("Session id: ");+ prefix.push_str(&session_id.to_string());+ prefix.push_str("\nObservations (in order):\n\n");++ let optional_budget = budgets+ .optional_context_budget::<ConsolidatedPage>(SYSTEM_PROMPT, count_chars(&prefix));+ let instructions_block =+ render_instructions_block(instructions, optional_budget.saturating_div(2));+ let current_body_budget = optional_budget.saturating_sub(count_chars(&instructions_block));+ let titles_block = render_title_uniqueness_section(existing_titles);+ let current_body_budget = current_body_budget.saturating_sub(count_chars(&titles_block));+ let mut suffix = render_current_body_section(current_body, current_body_budget);+ suffix.push_str(&titles_block);+ suffix.push_str(&instructions_block);++ let observation_chars = budgets.remaining_input_chars::<ConsolidatedPage>(+ SYSTEM_PROMPT,+ count_chars(&prefix).saturating_add(count_chars(&suffix)),+ );+ let projected = project_observations(+ observations,+ &ObservationProjectionConfig::new(+ observation_chars,+ MAX_PROJECTED_OBSERVATIONS,+ MAX_PROJECTED_OBSERVATION_BODY_CHARS,+ )+ .with_context_label("single-page consolidation"),+ );+ let mut buf = prefix;+ buf.push_str(&projected.text);+ buf.push_str(&suffix);+ buf+ }++ /// Reference assembly of the pre-reorder batch layout (fixed header,+ /// session id, observation dump, then slots, fixed schema, titles, and+ /// instructions). The fixed header and schema text are sliced out of the+ /// rendered message so the reference reuses the exact shipped bytes.+ fn old_order_batch_content(+ rendered: &str,+ session_id: SessionId,+ observations: &[Observation],+ slots: &[SlotSnapshot],+ instructions: Option<&str>,+ budgets: PromptBudgets,+ existing_titles: &[String],+ ) -> String {+ let mandatory_start = rendered+ .find("\nProduce up to 5 page updates")+ .expect("batch prompt carries the fixed schema suffix");+ let fixed_header = &rendered[..mandatory_start];+ let mandatory_suffix = &rendered[mandatory_start+ ..rendered+ .find(PROJECT_INSTRUCTIONS_HEADER)+ .expect("batch prompt carries the project instructions")];++ let mut prefix = String::new();+ prefix.push_str(fixed_header);+ prefix.push_str("Session id: ");+ prefix.push_str(&session_id.to_string());+ prefix.push_str("\n\nObservations:\n");++ let titles_block = render_title_uniqueness_section(existing_titles);+ let optional_budget = budgets.optional_context_budget::<ConsolidatedBatch>(+ BATCH_SYSTEM_PROMPT,+ count_chars(&prefix)+ .saturating_add(count_chars(mandatory_suffix))+ .saturating_add(count_chars(&titles_block)),+ );+ let instructions_block =+ render_instructions_block(instructions, optional_budget.saturating_div(2));+ let slots_budget = optional_budget.saturating_sub(count_chars(&instructions_block));+ let mut suffix = render_slot_snapshots(slots, slots_budget);+ suffix.push_str(mandatory_suffix);+ suffix.push_str(&titles_block);+ suffix.push_str(&instructions_block);++ let observation_chars = budgets.remaining_input_chars::<ConsolidatedBatch>(+ BATCH_SYSTEM_PROMPT,+ count_chars(&prefix).saturating_add(count_chars(&suffix)),+ );+ let projected = project_observations(+ observations,+ &ObservationProjectionConfig::new(+ observation_chars,+ MAX_PROJECTED_OBSERVATIONS,+ MAX_PROJECTED_OBSERVATION_BODY_CHARS,+ )+ .with_context_label("batch consolidation"),+ );+ let mut buf = prefix;+ buf.push_str(&projected.text);+ buf.push_str(&suffix);+ buf+ }++ /// The reordered message must carry exactly the accepted lines of the+ /// pre-reorder assembly — no content lost, no content duplicated.+ fn assert_same_accepted_lines(new_content: &str, old_content: &str) {+ let mut old_lines: Vec<&str> = old_content.lines().collect();+ let mut new_lines: Vec<&str> = new_content.lines().collect();+ old_lines.sort_unstable();+ new_lines.sort_unstable();+ assert_eq!(+ old_lines, new_lines,+ "accepted content must be identical between the old and the new order"+ );+ }++ /// Reordering must admit neither more nor less: on a 16k-input/8k-output+ /// budget large enough to reach clipping, the pre-reorder assembly and+ /// the reordered single-page builder accept identical content, only+ /// permuted.+ #[test]+ fn reorder_preserves_accepted_content_single() {+ let budgets = PromptBudgets::from_limits(16_000, 8_000);+ let sid: SessionId = "0193e7a1-0000-7000-8000-000000000001"+ .parse()+ .expect("fixed session id");+ let observations: Vec<Observation> = (0..24).map(|_| obs_of_size(2_000)).collect();+ let instructions_text = "prefer concise notes; keep \"sentinel-quotes\" verbatim";+ let instructions = Some(instructions_text);+ let current_body = format!(+ "# huge\n\n{}\n\n## Raw observations\n\n- clip-me\n",+ "x".repeat(30_000)+ );+ let titles = vec!["Existing Title".to_string()];++ let request = build_request(+ sid,+ &observations,+ ¤t_body,+ instructions,+ budgets,+ &titles,+ );+ let new_content = &request.messages[0].content;+ let old_content = old_order_single_content(+ sid,+ &observations,+ ¤t_body,+ instructions,+ budgets,+ &titles,+ );++ assert_eq!(+ count_chars(new_content),+ count_chars(&old_content),+ "reordering must not change the total budgeted length"+ );+ assert_same_accepted_lines(new_content, &old_content);++ // Nothing lost, nothing duplicated in the stable sections.+ let encoded_instructions =+ serde_json::Value::String(instructions_text.to_string()).to_string();+ assert_eq!(+ new_content.matches(&encoded_instructions).count(),+ 1,+ "the escaped project instructions must appear exactly once"+ );+ assert_eq!(new_content.matches("Existing Title").count(), 1);+ assert!(+ new_content.contains("[current heuristic page body truncated]"),+ "clipping is reached on the 16k/8k fixture"+ );+ assert!(+ !new_content.contains("clip-me"),+ "raw-observation elision is preserved"+ );+ }++ /// The single-page observation budget must count the titles block: on a+ /// knife-edge input budget calibrated so all three equal observations do+ /// not fit, the middle one is pruned (first and last are hard anchors).+ /// If the titles block were left out of the `remaining_input_chars`+ /// sum, the budget would grow by the titles' size and all three+ /// observations would render. This test asserts the production shape+ /// exactly, with a large deterministic titles block and real pruning,+ /// so a sum missing the titles block fails it while the correct sum+ /// passes.+ #[test]+ fn single_observation_budget_accounts_for_the_titles_block() {+ let sid: SessionId = "0193e7a1-0000-7000-8000-000000000001"+ .parse()+ .expect("fixed session id");+ // Three equal-sized observations (same body length and the same+ // fixed field lengths — v7 UUID ids are always 36 chars) render+ // blocks of identical length. The first and last are hard anchors+ // (never pruned), so the middle one is the only prunable block and+ // the budget sits exactly on the three-block edge.+ let observations = vec![obs_of_size(400), obs_of_size(400), obs_of_size(400)];+ // A deterministic titles block well above the calibration gap+ // (the renderer caps the list at EXISTING_TITLES_PROMPT_LIMIT, so+ // the block size is stable across runs).+ let titles: Vec<String> = (0..80)+ .map(|i| format!("Existing page title {i:02} with a stable suffix"))+ .collect();+ let titles_block = render_title_uniqueness_section(&titles);+ let title_chars = count_chars(&titles_block);+ assert!(+ title_chars >= 512,+ "the fixture needs a titles block well above the calibration gap: {title_chars}"+ );++ // Measure one rendered block through the exact projection the+ // builder uses (a generous budget keeps all three, back-to-back).+ let probe = project_observations(+ &observations,+ &ObservationProjectionConfig::new(+ 100_000,+ MAX_PROJECTED_OBSERVATIONS,+ MAX_PROJECTED_OBSERVATION_BODY_CHARS,+ )+ .with_context_label("single-page consolidation"),+ );+ assert_eq!(+ probe.omitted_count, 0,+ "the probe budget must keep all three observations"+ );+ let probe_chars = count_chars(&probe.text);+ assert_eq!(+ probe_chars % 3,+ 0,+ "the three observations must render equal-length blocks"+ );+ let block_chars = probe_chars / 3;++ // Calibrate the input budget so the observation budget lands just+ // below three blocks: with the titles counted the middle+ // observation is pruned (the two hard anchors fit); without them+ // (S2) all three fit. The gap absorbs the CHARS_PER_TOKEN rounding+ // of `from_limits`.+ let mut observations_header = String::new();+ observations_header.push_str("Session id: ");+ observations_header.push_str(&sid.to_string());+ observations_header.push_str("\nObservations (in order):\n\n");+ let header_chars = count_chars(&observations_header);+ let gap = 4 * CHARS_PER_TOKEN;+ let required_total = (3 * block_chars)+ .saturating_sub(gap)+ .saturating_add(count_chars(SYSTEM_PROMPT))+ .saturating_add(schema_chars::<ConsolidatedPage>())+ .saturating_add(PROMPT_ENVELOPE_RESERVE_CHARS)+ .saturating_add(header_chars)+ .saturating_add(title_chars);+ let budgets = PromptBudgets::from_limits(+ required_total.div_ceil(CHARS_PER_TOKEN),+ MIN_CONSOLIDATION_MAX_OUTPUT_TOKENS,+ );++ // The calibration must hold — this is the property that makes the+ // test bite on the S2 mutation.+ let observation_chars = budgets.remaining_input_chars::<ConsolidatedPage>(+ SYSTEM_PROMPT,+ header_chars.saturating_add(title_chars),+ );+ let three_blocks = 3 * block_chars;+ let two_blocks = 2 * block_chars;+ assert!(+ three_blocks > observation_chars,+ "calibration: all three observations must not fit while the titles are counted (three_blocks={three_blocks}, observation_chars={observation_chars})"+ );+ assert!(+ two_blocks <= observation_chars,+ "calibration: the two hard-anchor observations must fit while the titles are counted (two_blocks={two_blocks}, observation_chars={observation_chars})"+ );+ assert!(+ three_blocks <= observation_chars.saturating_add(title_chars),+ "calibration: dropping the titles from the sum must admit the third observation (S2)"+ );++ let request = build_request(sid, &observations, "", None, budgets, &titles);+ let user = &request.messages[0].content;+ assert_eq!(+ user.matches("--- observation").count(),+ 2,+ "with the titles block counted into the observation budget only the two hard-anchor observations fit and the middle one is pruned; S2 (titles dropped from the sum) would render all three"+ );+ assert!(+ user.contains("1 observations omitted from single-page consolidation projection"),+ "the pruned observation must leave its visible omission marker"+ );+ }++ /// Same guarantee for the batch builder: on a 16k-input/8k-output budget+ /// large enough to reach clipping, the old and the new order admit the+ /// same slots, titles, instructions, and selected observations.+ #[test]+ fn reorder_preserves_accepted_content_batch() {+ let budgets = PromptBudgets::from_limits(16_000, 8_000);+ let sid: SessionId = "0193e7a1-0000-7000-8000-000000000001"+ .parse()+ .expect("fixed session id");+ let observations: Vec<Observation> = (0..24).map(|_| obs_of_size(2_000)).collect();+ let slots = vec![+ SlotSnapshot {+ path: "_slots/focus.md".into(),+ title: "Focus".into(),+ slot_kind: SlotKind::State,+ body: "slot body A ".repeat(150),+ },+ SlotSnapshot {+ path: "_slots/draft.md".into(),+ title: "Draft".into(),+ slot_kind: SlotKind::State,+ body: "slot body B ".repeat(150),+ },+ ];+ let instructions_text = "prefer concise notes; keep \"sentinel-quotes\" verbatim";+ let instructions = Some(instructions_text);+ let titles = vec!["Existing Title".to_string()];++ let request = build_batch_request_with_slots(+ sid,+ &observations,+ &slots,+ instructions,+ budgets,+ &titles,+ );+ let new_content = &request.messages[0].content;+ let old_content = old_order_batch_content(+ new_content,+ sid,+ &observations,+ &slots,+ instructions,+ budgets,+ &titles,+ );++ assert_eq!(+ count_chars(new_content),+ count_chars(&old_content),+ "reordering must not change the total budgeted length"+ );+ assert_same_accepted_lines(new_content, &old_content);++ // Nothing lost, nothing duplicated in the stable sections.+ let encoded_instructions =+ serde_json::Value::String(instructions_text.to_string()).to_string();+ assert_eq!(+ new_content.matches(&encoded_instructions).count(),+ 1,+ "the escaped project instructions must appear exactly once"+ );+ assert_eq!(new_content.matches("Existing Title").count(), 1);+ assert_eq!(new_content.matches("_slots/focus.md").count(), 1);+ assert_eq!(new_content.matches("_slots/draft.md").count(), 1);+ }++ /// The reorder is pure in-memory assembly: even on degenerate inputs the+ /// builders finish without touching external state and emit a well-formed+ /// request with the system prompt still separate.+ #[test]+ fn default_builders_total_on_empty_and_minimum_budget_inputs() {+ let budgets = PromptBudgets::from_limits(+ MIN_CONSOLIDATION_MAX_INPUT_TOKENS,+ MIN_CONSOLIDATION_MAX_OUTPUT_TOKENS,+ );+ let single = build_request(SessionId::new(), &[], "", None, budgets, &[]);+ let batch = build_batch_request_with_slots(SessionId::new(), &[], &[], None, budgets, &[]);+ for (name, request) in [("single", &single), ("batch", &batch)] {+ let user = &request.messages[0].content;+ assert!(!user.is_empty(), "{name}: user message must not be empty");+ assert!(+ user.contains("Observations"),+ "{name}: the observation section must survive degenerate inputs"+ );+ assert!(+ !request.system.as_deref().unwrap_or_default().is_empty(),+ "{name}: the system prompt stays separate and non-empty"+ );+ }+ }+#[test]fn build_request_omits_titles_block_when_the_project_is_empty() {let single = build_request(diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex d5d5d65c..c97b4918 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -94,7 +94,17 @@ from hook paths.that summary into a richer durable page or fans out into amulti-page batch under `concepts/`, `decisions/`, `gotchas/`. Consolidationprompts preserve the source material's dominant natural language and ask- the model to connect related pages with path-based wikilinks.+ the model to connect related pages with path-based wikilinks. The default+ single-page and batch prompts lead the user content with their stable+ blocks — the fixed batch text (header + field schema) and the project+ instructions — followed by the current body / slot and title state, and+ only then the session id and observation dump, so providers with prefix+ caching can reuse the stable prefix. In the single-page prompt the current+ body is the session's own page body (`sessions/<id>.md`), so it varies per+ session: the prefix shared across sessions of one project is the system+ prompt plus the instructions block when present, and the titles block+ follows the variable body. The input budget remains an approximate+ character estimate; cache eligibility is not a measured hit.5. When an LLM provider is configured, the auto-improvement scheduler reviewsnewly completed sessions across all projects outside hook latency. It records validated`concepts/`, `decisions/`, `gotchas/`, `procedures/`, and `_rules/` proposals