onbuzz 4.8.0 → 4.8.2

package/src/services/__tests__/conversationCompactionService.test.js

@@ -34,6 +34,147 @@ describe('ConversationCompactionService', () => {
     expect(service.compactionModelIndex).toBe(0);
   });
 
+  // ─── Compaction-input pre-tagging ─────────────────────────────────────
+  //
+  // The summarizer is fed PRE-TAGGED messages so it doesn't have to
+  // guess whether a `role: user` message is a real user typing or a
+  // tool-result wrapper. We pin the tagging rules here.
+
+  describe('_categorizeMessage — input pre-tagging', () => {
+    test('assistant role → AGENT', () => {
+      expect(service._categorizeMessage({ role: 'assistant', content: 'hi' })).toBe('AGENT');
+    });
+
+    test('system role → SYSTEM', () => {
+      expect(service._categorizeMessage({ role: 'system', content: 'note' })).toBe('SYSTEM');
+    });
+
+    test('user role with plain content → REAL_USER', () => {
+      expect(service._categorizeMessage({ role: 'user', content: 'please fix the board' })).toBe('REAL_USER');
+    });
+
+    test('user role with [Tool Results …] prefix → TOOL_RESULT', () => {
+      expect(service._categorizeMessage({
+        role: 'user',
+        content: '[Tool Results — 1 result] [filesystem] {...}',
+      })).toBe('TOOL_RESULT');
+    });
+
+    test('user role with [Previous Task …] prefix → PREVIOUS_TASK', () => {
+      expect(service._categorizeMessage({
+        role: 'user',
+        content: '[Previous Task — Final Tool Results] [jobdone] {...}',
+      })).toBe('PREVIOUS_TASK');
+    });
+
+    test('REGRESSION: leading whitespace before [Tool Results doesn\'t fool the categorizer', () => {
+      expect(service._categorizeMessage({
+        role: 'user',
+        content: '\n  [Tool Results — 1] {}',
+      })).toBe('TOOL_RESULT');
+    });
+
+    test('non-string content (rare) is treated as REAL_USER (defensive)', () => {
+      // If content somehow isn't a string, we can't sniff the prefix —
+      // safest fallback is to treat it as a real user message so it
+      // surfaces in PASS 1 rather than being silently dropped.
+      expect(service._categorizeMessage({ role: 'user', content: { foo: 1 } })).toBe('REAL_USER');
+    });
+  });
+
+  // ─── Summary prompt contract — anti-lossy-compaction guard ────────────
+  //
+  // History: an earlier prompt told the summarizer to paraphrase user
+  // requests "under HIGH PRIORITY". The Talisman case study (May 2026)
+  // showed that paraphrasing alone caused the agent to lose track of
+  // literal user asks → off-track work (building a Settings screen
+  // nobody asked for). Then a verbatim-everything prompt fixed that
+  // half but ate the agent-side narrative — PASS 2 never reached.
+  // The final prompt (3-pass, pre-tagged input, EVENT LOG + STATE)
+  // was validated across 3 models × 7 variants. These tests pin it.
+
+  describe('_createSummaryPromptTemplate — three-pass contract', () => {
+    test('includes the {middle_segment} placeholder for interpolation', () => {
+      const tpl = service._createSummaryPromptTemplate();
+      expect(tpl).toContain('{middle_segment}');
+    });
+
+    test('declares the pre-tagging categories the summarizer can trust', () => {
+      // The prompt must list every category the categorizer emits, so
+      // the summarizer doesn't fall back to guessing from content.
+      const tpl = service._createSummaryPromptTemplate();
+      expect(tpl).toContain('[REAL_USER]');
+      expect(tpl).toContain('[TOOL_RESULT]');
+      expect(tpl).toContain('[PREVIOUS_TASK]');
+      expect(tpl).toContain('[AGENT]');
+      expect(tpl).toContain('[SYSTEM]');
+    });
+
+    test('mandates VERBATIM user-message transcription, NOT paraphrase', () => {
+      const tpl = service._createSummaryPromptTemplate();
+      expect(tpl).toMatch(/word[\s,-]?for[\s,-]?word/i);
+      expect(tpl).toMatch(/transcription/i);
+      expect(tpl).toMatch(/(do not|don't|never).*(paraphras|condens|omit)/i);
+    });
+
+    test('uses a 3-pass shape: USER VOICE → EVENT LOG → STATE NARRATIVE', () => {
+      const tpl = service._createSummaryPromptTemplate();
+      const userIdx  = tpl.indexOf('USER VOICE');
+      const eventIdx = tpl.indexOf('EVENT LOG');
+      const stateIdx = tpl.indexOf('STATE NARRATIVE');
+      expect(userIdx).toBeGreaterThan(-1);
+      expect(eventIdx).toBeGreaterThan(-1);
+      expect(stateIdx).toBeGreaterThan(-1);
+      // User voice first, then event log, then narrative.
+      expect(userIdx).toBeLessThan(eventIdx);
+      expect(eventIdx).toBeLessThan(stateIdx);
+    });
+
+    test('PASS 1 forbids quoting non-REAL_USER tagged messages', () => {
+      // The most common failure mode in early experiments was the
+      // summarizer quoting tool-result wrappers as if they were user
+      // messages. The prompt explicitly forbids this.
+      const tpl = service._createSummaryPromptTemplate();
+      expect(tpl).toMatch(/only \[REAL_USER\] messages/i);
+      // And lists the categories it must NOT quote.
+      expect(tpl).toMatch(/do not quote.*\[TOOL_RESULT\]/i);
+    });
+
+    test('PASS 2 demands concrete details (file paths, tool names, line numbers)', () => {
+      const tpl = service._createSummaryPromptTemplate();
+      expect(tpl).toMatch(/file path/i);
+      expect(tpl).toMatch(/tool name/i);
+      expect(tpl).toMatch(/line number/i);
+    });
+
+    test('PASS 3 must explicitly map back to [REAL_USER] requests', () => {
+      // The Talisman bug was the agent doing work UNRELATED to the
+      // user's requests. PASS 3 must surface that misalignment when
+      // it exists — the prompt requires "name the gaps clearly".
+      const tpl = service._createSummaryPromptTemplate();
+      expect(tpl).toMatch(/map back/i);
+      expect(tpl).toMatch(/name the gaps/i);
+    });
+
+    test('forbids skipping a [REAL_USER] message on "already addressed" reasoning', () => {
+      const tpl = service._createSummaryPromptTemplate();
+      expect(tpl).toMatch(/(do not|don't|never).*skip.*\[?REAL_USER\]?/i);
+      expect(tpl).toMatch(/already addressed/i);
+    });
+
+    test('output contract: no preamble, exact headers', () => {
+      const tpl = service._createSummaryPromptTemplate();
+      expect(tpl).toMatch(/no preamble/i);
+      expect(tpl).toMatch(/exactly the section headers above/i);
+    });
+
+    test('REGRESSION: does NOT carry forward the lossy "HIGH PRIORITY paraphrase" guidance', () => {
+      const tpl = service._createSummaryPromptTemplate();
+      expect(tpl).not.toMatch(/HIGH PRIORITY \(Always Preserve\)/);
+      expect(tpl).not.toMatch(/PRESERVATION GUIDELINES/);
+    });
+  });
+
   // ─── compactConversation ─────────────────────────────────────────────
 
   test('compactConversation throws on empty messages array', async () => {

package/src/services/__tests__/modelRouterNaming.test.js

@@ -1,47 +1,65 @@
 /**
  * Regression tests for the router model name convention.
  *
- * Background: Dynamic Routing silently no-op'd for an entire release
- * because the CLI's `ROUTER_MODEL` constant was `'autopilot-model-router'`
- * while the catalog (the source of truth that the backend's /llm/chat
- * looks up) keys the entry as `'model-router'`. The catalog's regex
- * fallback is wrapped with ^…$ at index-build time in the backend
- * (services/modelCatalogService.js:109), so the `autopilot-` prefix
- * caused every routing-decision call to return 400, the
- * ModelRouterService caught + fell back to the current model, and no
- * routing ever happened.
+ * Background — two rounds of this same shape of bug:
  *
- * These tests pin the post-fix invariant and catch any reintroduction
- * of a product-name prefix in the future.
+ *   Round 1: Dynamic Routing silently no-op'd because ROUTER_MODEL
+ *   was `'autopilot-model-router'` while the catalog keyed the entry
+ *   as `'model-router'`. Fixed by changing the constant to the bare
+ *   form.
+ *
+ *   Round 2: Even the bare `'model-router'` key didn't exist in the
+ *   live catalog, because the catalog discovers deployments by
+ *   underlying-model-name (not by Azure deployment-name). The team's
+ *   actual deployment was named `autopilot-model-router` in Azure but
+ *   its underlying model is `gpt-4.1-nano` — so the live catalog
+ *   keys the entry under `gpt-4.1-nano`. The CLI now defaults to
+ *   that name.
+ *
+ * These tests pin the new invariant + the override mechanism + catch
+ * any reintroduction of a product-name prefix.
  *
  * Why a separate test file: the existing modelRouterService.test.js
  * mocks the constants module at the top of the file, so it cannot
  * assert anything about the REAL value of MODEL_ROUTER_CONFIG. This
  * file imports the real constants instead.
  */
-import { describe, test, expect } from '@jest/globals';
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { MODEL_ROUTER_CONFIG } from '../../utilities/constants.js';
-
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SRC_ROOT  = path.resolve(__dirname, '../..');
 
 describe('Router model naming — matches catalog convention', () => {
-  test('ROUTER_MODEL is exactly "model-router"', () => {
-    // This is the modelKey in autopilot-model-catalog's models_registry.json.
-    // Any other value would force the backend through the regex fallback,
-    // which is anchored ^…$ and will reject product-prefixed forms.
-    expect(MODEL_ROUTER_CONFIG.ROUTER_MODEL).toBe('model-router');
+  test('default ROUTER_MODEL is "gpt-4.1-nano" (current live catalog key)', async () => {
+    // The autopilot-model-router deployment's underlying model is
+    // gpt-4.1-nano. The catalog keys entries by underlying model, so
+    // this is the canonical name the CLI must request.
+    delete process.env.LOXIA_ROUTER_MODEL;
+    // Re-import to pick up the (re-)evaluated default.
+    const fresh = await import(`../../utilities/constants.js?nocache=${Date.now()}`);
+    expect(fresh.MODEL_ROUTER_CONFIG.ROUTER_MODEL).toBe('gpt-4.1-nano');
+  });
+
+  test('LOXIA_ROUTER_MODEL env var overrides the default (no rebuild needed)', async () => {
+    process.env.LOXIA_ROUTER_MODEL = 'gpt-4o-mini';
+    try {
+      const fresh = await import(`../../utilities/constants.js?nocache=${Date.now()}`);
+      expect(fresh.MODEL_ROUTER_CONFIG.ROUTER_MODEL).toBe('gpt-4o-mini');
+    } finally {
+      delete process.env.LOXIA_ROUTER_MODEL;
+    }
   });
 
-  test('ROUTER_MODEL does NOT carry a product/brand prefix', () => {
-    // Defense-in-depth: even if the catalog modelKey ever changes,
-    // the name must not start with a product prefix like "autopilot-"
+  test('ROUTER_MODEL does NOT carry a product/brand prefix', async () => {
+    // Defense-in-depth: even if the canonical name ever changes,
+    // it must not start with a product prefix like "autopilot-"
     // or "onbuzz-". The catalog's canonical names are product-agnostic.
-    const v = MODEL_ROUTER_CONFIG.ROUTER_MODEL;
+    delete process.env.LOXIA_ROUTER_MODEL;
+    const fresh = await import(`../../utilities/constants.js?nocache=${Date.now()}`);
+    const v = fresh.MODEL_ROUTER_CONFIG.ROUTER_MODEL;
     expect(v).not.toMatch(/^autopilot[-_]/i);
     expect(v).not.toMatch(/^onbuzz[-_]/i);
     expect(v).not.toMatch(/^loxia[-_]/i);

package/src/services/conversationCompactionService.js

@@ -632,10 +632,27 @@ class ConversationCompactionService {
       };
     }
 
-    // Format middle messages for summarization
+    // Format middle messages for summarization — PRE-TAG each message
+    // with a category the summarizer can trust without inference.
+    //
+    // Why pre-tag instead of letting the summarizer figure it out:
+    // tool-result wrappers carry `role: user` (they come back as
+    // user-role messages by convention in this codebase). A summarizer
+    // staring at raw `user:` prefixes can't reliably tell a literal
+    // user typing from a tool-result blob — and in our experiments
+    // both gpt-4.1-mini and gpt-4.1-nano routinely quoted tool blobs
+    // as if they were user messages, wasting budget and corrupting
+    // the user-voice section. Categorizing here eliminates that whole
+    // failure class. See _categorizeMessage for the rules.
     let middleContent = middleMessages
-      .map(msg => `${msg.role}: ${typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)}`)
-      .join('\n\n');
+      .map(msg => {
+        const cat = this._categorizeMessage(msg);
+        const body = typeof msg.content === 'string'
+          ? msg.content
+          : JSON.stringify(msg.content);
+        return `[${cat}] ${body}`;
+      })
+      .join('\n\n────────\n\n');
 
     // Estimate input tokens
     const estimatedInputTokens = Math.ceil(middleContent.length / COMPACTION_CONFIG.CHARS_PER_TOKEN_ESTIMATE);
@@ -1128,55 +1145,112 @@ class ConversationCompactionService {
   }
 
   /**
-   * Create summary prompt template with preservation guidelines
+   * Categorize one conversation message for compaction tagging.
+   *
+   * Returns one of:
+   *   REAL_USER      — a literal user typing turn
+   *   TOOL_RESULT    — a `[Tool Results …]` wrapper (carries role:user)
+   *   PREVIOUS_TASK  — a `[Previous Task — Final Tool Results]` boundary
+   *   AGENT          — assistant turn
+   *   SYSTEM         — system message
+   *
+   * The categorization is deterministic — text-prefix sniffing on the
+   * content, not heuristic. Matches the convention used everywhere
+   * else in the CLI for marking tool-result envelopes.
+   *
+   * @param {object} msg - { role, content }
+   * @returns {string} one of the categories above
+   * @private
+   */
+  _categorizeMessage(msg) {
+    if (msg.role === 'assistant') return 'AGENT';
+    if (msg.role === 'system')    return 'SYSTEM';
+    // role === 'user' — could be a real user message OR a tool-result wrapper.
+    const c = typeof msg.content === 'string' ? msg.content.trimStart() : '';
+    if (c.startsWith('[Tool Results'))  return 'TOOL_RESULT';
+    if (c.startsWith('[Previous Task')) return 'PREVIOUS_TASK';
+    return 'REAL_USER';
+  }
+
+  /**
+   * Create the compaction-summary prompt template.
+   *
+   * Why this prompt is shaped this way:
+   *   The previous "paraphrase-everything" template was found to drop
+   *   the user's literal asks during compaction (see the Talisman
+   *   case study: the agent paraphrased the user's 3-point UI request
+   *   into "redesign UI" and then went off and built a Settings
+   *   screen). Re-tested across 3 models × 5 prompt variants, this
+   *   two-pass shape was the highest-fidelity option that worked
+   *   uniformly well across gpt-4.1-mini, gpt-4.1-nano, and
+   *   FW-Kimi-K2.5. See tmp-compaction-experiment/ for the harness.
+   *
+   *   PASS 1 is transcription. The summarizer is NOT allowed to filter
+   *   user messages by "I think the agent already handled this." That
+   *   determination belongs to the consumer agent reading the summary,
+   *   not to the summarizer itself — making the summarizer choose was
+   *   how completed-vs-open misjudgments crept in. The blockquote
+   *   format gives the consumer agent a strong visual signal to
+   *   anchor on those literal asks.
+   *
+   *   PASS 2 is the narrative summary of the agent's work — files,
+   *   tools, decisions, state. Heavy compression OK here; only the
+   *   user-voice section is sacred.
+   *
    * @private
    */
   _createSummaryPromptTemplate() {
-    return `You are compacting a conversation to preserve critical information while reducing token count.
-
-CONTEXT: You are summarizing the EARLIEST portion of a conversation. The most recent messages are preserved separately. Your summary should capture what was accomplished, key decisions, and any information still relevant for continuation. Focus on outcomes over process.
-
-PRESERVATION GUIDELINES:
-
-HIGH PRIORITY (Always Preserve):
-- User requests and goals: What the user asked for, their stated preferences, and desired outcomes — these drive all ongoing work
-- Current task and next steps: What the agent is actively working on and what remains to be done
-- Recent achievements and current status: What was accomplished, what state the work is in now
-- Files created or modified successfully: Full file paths that were written, created, or changed
-- Meaningful tool invocations and their outcomes: Tool calls that produced important results or side effects
-- Future reference value: Information likely to be referenced again
-- Decisions and reasoning: WHY things were decided, not just what
-- API signatures and interfaces: Function definitions, method calls
-- Active dependencies: Information that ongoing work relies on
-- Error patterns and solutions: What failed and how it was fixed
-- Key facts and data: Specific numbers, names, configurations
-
-MEDIUM PRIORITY (Compress Intelligently):
-- Code blocks: Keep function signatures + brief description, compress implementation details
-- Working solutions: Essence and outcome, not every implementation step
-- Failed attempts: Brief mention of what didn't work and why, skip detailed troubleshooting
-- Repetitive content: Consolidate similar examples or explanations
-
-LOW PRIORITY (Heavily Compress/Remove):
-- Completed calculations: Keep results, skip intermediate steps
-- Verbose explanations: Summarize well-known concepts
-- Debug output: Skip terminal logs and error messages that served their purpose
-- Trial-and-error sequences: Skip multiple failed attempts with no lasting value
-- Acknowledgments and pleasantries: Skip "thank you", "sure", "okay" type exchanges
-
-CONVERSATION SEGMENT TO SUMMARIZE:
-{middle_segment}
+    return `You are compacting an earlier portion of an agent-user conversation. The input has been PRE-TAGGED — every message starts with one of:
+
+  [REAL_USER]      — a literal user message; TRANSCRIBE VERBATIM in PASS 1
+  [AGENT]          — assistant turn (tool calls + reasoning)
+  [TOOL_RESULT]    — a tool's output; the consumer agent does NOT need these verbatim
+  [PREVIOUS_TASK]  — final tool-result block from a previous task boundary
+  [SYSTEM]         — system note
 
-TASK: Create a concise summary that preserves logical flow and critical information. Focus on:
-1. Key decisions and their reasoning
-2. Important facts, data, and configurations
-3. Active context needed for continuation
-4. Problem-solving outcomes (skip the debugging process)
-5. Dependencies and interfaces that code/work relies on
+You DO NOT need to detect categories yourself. Trust the tags. The pre-tagging is deterministic.
 
-Someone reading this should understand the conversation progression and have all information needed for effective continuation.
+Write the summary in THREE passes, in this exact order.
+
+──────────────────────────────────────────────
+PASS 1 — USER VOICE  (transcription only, no judgment)
+──────────────────────────────────────────────
+
+For EVERY [REAL_USER] message — and ONLY [REAL_USER] messages — emit a blockquote:
+
+> **User said (orig idx N):** "<exact text, word for word, all of it>"
+
+Absolute rules:
+- Do NOT quote any [TOOL_RESULT], [AGENT], [PREVIOUS_TASK], or [SYSTEM] message here.
+- Do NOT condense, paraphrase, or omit any [REAL_USER] message.
+- Do NOT skip a [REAL_USER] message on the assumption "the agent already addressed it." That determination belongs to the consumer agent, not to you. Your job here is transcription.
+- Reproduce every [REAL_USER] message, in original order, including punctuation and typos.
+- If the input has no [REAL_USER] messages, write "(no user messages in this segment)" and proceed.
+
+──────────────────────────────────────────────
+PASS 2 — EVENT LOG  (chronological bullets, concrete details)
+──────────────────────────────────────────────
+
+A bulleted list of every notable event between/after the user messages. ONE bullet per event:
+
+- [orig idx N] <one-line description — include full file paths, tool names, line numbers, status, and outcome>
+
+Cover: file writes, successful tool calls that changed state, decisions made by the agent, errors that affected outcome, task-list changes (especially destructive ones like 'removed: N tasks'). Skip: pure-read tool calls that didn't change state, repeated reads, pleasantries, verbose tool output dumps.
+
+A consumer agent should be able to read this log and reconstruct the cause-and-effect chain — what happened to each [REAL_USER] request.
+
+──────────────────────────────────────────────
+PASS 3 — STATE NARRATIVE  (2–4 sentences)
+──────────────────────────────────────────────
+
+Plain prose describing the situation at the end of this segment: what is done, what is mid-flight, what is open — and where possible, map back to which [REAL_USER] request each piece corresponds to. If [REAL_USER] requests are still open with no work toward them, say so explicitly. This is the place where lossy paraphrase is most dangerous — name the gaps clearly.
+
+──────────────────────────────────────────────
+
+CONVERSATION SEGMENT TO COMPACT:
+{middle_segment}
 
-OUTPUT: Provide ONLY the summary text without preamble, explanation, or meta-commentary.`;
+OUTPUT: PASS 1, PASS 2, PASS 3 in that order. Use exactly the section headers above. No preamble, no meta-commentary.`;
   }
 }
 

package/src/tools/__tests__/baseTool.test.js

@@ -364,6 +364,177 @@ describe('ToolsRegistry', () => {
     expect(desc).toContain('HOW TO GET TOOL DOCUMENTATION');
   });
 
+  describe('OPERATING POSTURE section', () => {
+    // Minimal fakes so the registry will accept these as memory/skills/taskmanager.
+    // BaseTool derives `this.id` from the class name (lowercased, with
+    // "Tool" stripped) — so the class must be named exactly *Tool* and
+    // the id is derived. We override `this.id` after super() to pin it
+    // independently of the class name, which keeps the test classes
+    // readable. validateTool() also requires parseParameters.
+    class FakeMemoryTool extends BaseTool {
+      constructor() { super(); this.id = 'memory'; }
+      getDescription() { return 'Memory tool stub'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+    class FakeSkillsTool extends BaseTool {
+      constructor() { super(); this.id = 'skills'; }
+      getDescription() { return 'Skills tool stub'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+    class FakeTaskManagerTool extends BaseTool {
+      constructor() { super(); this.id = 'taskmanager'; }
+      getDescription() { return 'TaskManager tool stub'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+
+    test('appears when memory tool is in capabilities (proactive memory nudge)', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['memory']);
+      expect(desc).toContain('OPERATING POSTURE');
+      expect(desc).toMatch(/memory.*list/i);
+      // Plan/* should be cross-referenced here so agents writing a plan
+      // memory isn't an isolated tip buried in the memory tool's own desc.
+      expect(desc).toContain('plan/');
+    });
+
+    test('appears when skills tool is in capabilities (proactive skills nudge)', async () => {
+      await registry.registerTool(FakeSkillsTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['skills']);
+      expect(desc).toContain('OPERATING POSTURE');
+      expect(desc).toMatch(/skills.*list/i);
+    });
+
+    test('does NOT appear when neither memory nor skills is in capabilities', async () => {
+      await registry.registerTool(TestTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['test']);
+      expect(desc).not.toContain('OPERATING POSTURE');
+    });
+
+    test('distinguishes memory vs taskmanager when both are present (so agents know which to use)', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      await registry.registerTool(FakeTaskManagerTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['memory', 'taskmanager']);
+      expect(desc).toContain('OPERATING POSTURE');
+      expect(desc).toContain('persistent knowledge'); // memory
+      expect(desc).toContain('step-by-step');          // taskmanager
+    });
+
+    // REGRESSION: production observation — agents had 0 memory writes
+    // across 670-message sessions despite the previous wording asking
+    // them to "save when you recognize multi-turn work". Vague
+    // judgment-based triggers don't produce action. Tests pin that
+    // the new triggers are concrete and event-based.
+    test('REGRESSION: write-triggers are concrete events, not vague judgment', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['memory']);
+      // The new wording should reference specific observable triggers,
+      // not "when you recognize" / "when you think".
+      expect(desc).toMatch(/numbered list|multi-bullet|substantive request/i);
+      expect(desc).toMatch(/before.*taskmanager.*sync|`taskmanager`.*sync/i);
+      expect(desc).toMatch(/non-obvious decision|tricky bug|unexpected error/i);
+      expect(desc).toMatch(/user gave you a preference/i);
+      // Should explicitly label the triggers as mandatory.
+      expect(desc).toMatch(/mandatory/i);
+      // And should NOT contain the old vague language.
+      expect(desc).not.toMatch(/when you recognize the work is multi-turn/i);
+    });
+
+    test('REGRESSION: write trigger mentions saving the user message VERBATIM', async () => {
+      // The Talisman bug was about losing the user's literal words.
+      // The trigger must instruct the agent to save the entire user
+      // message word-for-word, not a paraphrase of it.
+      await registry.registerTool(FakeMemoryTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['memory']);
+      expect(desc).toMatch(/user'?s entire message verbatim/i);
+    });
+  });
+
+  // ── Per-model prompt shape: skip text docs for tools with native schemas
+  //    when the target uses the Responses API (codex / o-series / gpt-5-pro).
+  describe('apiType="responses" — trims duplication with native function schemas', () => {
+    class FakeMemoryTool extends BaseTool {
+      constructor() { super(); this.id = 'memory'; }
+      getDescription() { return 'Memory tool stub with LONG description that would normally take many tokens'; }
+      getSummary() { return 'Persistent memory'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+    class FakeTerminalTool extends BaseTool {
+      constructor() { super(); this.id = 'terminal'; }
+      getDescription() { return 'Terminal tool LONG description that would normally take many tokens'; }
+      getSummary() { return 'Shell access'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+    class FakeWebTool extends BaseTool {
+      // 'web' is NOT in OPENAI_FUNCTION_SCHEMAS — its text doc must always appear.
+      constructor() { super(); this.id = 'web'; }
+      getDescription() { return 'Web tool LONG description that would normally take many tokens'; }
+      getSummary() { return 'Browser automation'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+
+    test('omits text description for tools that have native function schemas (memory, terminal)', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      await registry.registerTool(FakeTerminalTool);
+
+      const responsesDesc = registry.generateToolDescriptionsForPrompt(
+        ['memory', 'terminal'],
+        { apiType: 'responses' },
+      );
+      // Header still present + one-line pointer to structured schema.
+      expect(responsesDesc).toContain('AVAILABLE TOOLS');
+      expect(responsesDesc).toContain('see structured schema');
+      // The big multi-line text doc must NOT be repeated.
+      expect(responsesDesc).not.toContain('### MEMORY TOOL');
+      expect(responsesDesc).not.toContain('### TERMINAL TOOL');
+      expect(responsesDesc).not.toContain('LONG description that would normally take many tokens');
+    });
+
+    test('keeps text description for tools that do NOT have native function schemas (e.g. web)', async () => {
+      await registry.registerTool(FakeWebTool);
+      const responsesDesc = registry.generateToolDescriptionsForPrompt(
+        ['web'],
+        { apiType: 'responses' },
+      );
+      // 'web' has no native schema → text doc MUST be present.
+      expect(responsesDesc).toContain('### WEB TOOL');
+      expect(responsesDesc).toContain('LONG description that would normally take many tokens');
+    });
+
+    test('BACKWARD COMPAT: without apiType option, behaves exactly as before (full text for everything)', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      await registry.registerTool(FakeTerminalTool);
+
+      const defaultDesc = registry.generateToolDescriptionsForPrompt(['memory', 'terminal']);
+      // No apiType → keep the heavy text docs as today.
+      expect(defaultDesc).toContain('### MEMORY TOOL');
+      expect(defaultDesc).toContain('### TERMINAL TOOL');
+    });
+
+    test('BACKWARD COMPAT: apiType="chat_completion" is equivalent to no apiType', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      const a = registry.generateToolDescriptionsForPrompt(['memory'], { apiType: 'chat_completion' });
+      const b = registry.generateToolDescriptionsForPrompt(['memory']);
+      expect(a).toBe(b);
+    });
+
+    test('enhanceSystemPrompt forwards apiType option to the description builder', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      const native = registry.enhanceSystemPrompt('Base.', ['memory'], { apiType: 'responses' });
+      const inline = registry.enhanceSystemPrompt('Base.', ['memory']);
+      // Native form is meaningfully shorter (we dropped the per-tool block).
+      expect(native.length).toBeLessThan(inline.length);
+      // Both still contain the section headers and the original base prompt.
+      expect(native).toContain('Base.');
+      expect(native).toContain('AVAILABLE TOOLS');
+    });
+  });
+
   test('enhanceSystemPrompt appends tool docs', async () => {
     await registry.registerTool(TestTool);
     const enhanced = registry.enhanceSystemPrompt('Base prompt.', []);