onbuzz 4.8.1 → 4.8.3

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

@@ -19,11 +19,11 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
   };
 
   const mockModelsService = {
-    getAvailableModelNames: jest.fn().mockReturnValue(['gpt-5.1-codex-mini', 'gpt-5-mini']),
+    getAvailableModelNames: jest.fn().mockReturnValue(['gpt-4.1-nano', 'gpt-4.1-mini']),
     getModels: jest.fn().mockReturnValue([
-      { name: 'gpt-5.1-codex-mini', type: 'chat', contextWindow: 400000 },
-      { name: 'gpt-5-mini', type: 'chat', contextWindow: 400000 },
-      { name: 'gpt-5-nano', type: 'chat', contextWindow: 400000 },
+      { name: 'gpt-4.1-nano', type: 'chat', contextWindow: 400000 },
+      { name: 'gpt-4.1-mini', type: 'chat', contextWindow: 400000 },
+      { name: 'gpt-4.1-nano', type: 'chat', contextWindow: 400000 },
       { name: 'random-model-xyz', type: 'chat', contextWindow: 200000 }
     ])
   };
@@ -53,12 +53,12 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
       const onRetryAttempt = jest.fn();
 
       // Only 2 validated models available; first fails, second succeeds
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini', 'gpt-5-mini']);
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano', 'gpt-4.1-mini']);
       mockAiService.sendMessage
         .mockRejectedValueOnce(new Error('Service unavailable'))
         .mockResolvedValueOnce({ content: 'Summary of conversation' });
 
-      await service._generateSummary(testMessages, 'gpt-5.1-codex-mini', { onRetryAttempt });
+      await service._generateSummary(testMessages, 'gpt-4.1-nano', { onRetryAttempt });
 
       expect(onRetryAttempt).toHaveBeenCalledTimes(1);
     });
@@ -66,18 +66,18 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
     test('onRetryAttempt receives correct message, failedModel, nextModel, attempt', async () => {
       const onRetryAttempt = jest.fn();
 
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini', 'gpt-5-mini']);
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano', 'gpt-4.1-mini']);
       mockAiService.sendMessage
         .mockRejectedValueOnce(new Error('Service unavailable'))
         .mockResolvedValueOnce({ content: 'Summary of conversation' });
 
-      await service._generateSummary(testMessages, 'gpt-5.1-codex-mini', { onRetryAttempt });
+      await service._generateSummary(testMessages, 'gpt-4.1-nano', { onRetryAttempt });
 
       expect(onRetryAttempt).toHaveBeenCalledWith(
         expect.objectContaining({
           type: 'compaction_retry',
-          failedModel: 'gpt-5.1-codex-mini',
-          nextModel: 'gpt-5-mini',
+          failedModel: 'gpt-4.1-nano',
+          nextModel: 'gpt-4.1-mini',
           attempt: 1
         })
       );
@@ -87,14 +87,14 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
       const onRetryAttempt = jest.fn();
 
       // Only 1 validated model, and no suitable random models
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini']);
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano']);
       mockModelsService.getModels.mockReturnValue([
-        { name: 'gpt-5.1-codex-mini', type: 'chat', contextWindow: 400000 }
+        { name: 'gpt-4.1-nano', type: 'chat', contextWindow: 400000 }
       ]);
       mockAiService.sendMessage.mockRejectedValue(new Error('Service unavailable'));
 
       await expect(
-        service._generateSummary(testMessages, 'gpt-5.1-codex-mini', { onRetryAttempt })
+        service._generateSummary(testMessages, 'gpt-4.1-nano', { onRetryAttempt })
       ).rejects.toThrow();
 
       // The only call to onRetryAttempt would be from the last-resort block, but
@@ -108,16 +108,16 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
 
   describe('Random model fallback', () => {
     test('after all recommended models fail, tries a random model from modelsService', async () => {
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini']);
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano']);
       mockModelsService.getModels.mockReturnValue([
-        { name: 'gpt-5.1-codex-mini', type: 'chat', contextWindow: 400000 },
+        { name: 'gpt-4.1-nano', type: 'chat', contextWindow: 400000 },
         { name: 'random-model-xyz', type: 'chat', contextWindow: 200000 }
       ]);
       mockAiService.sendMessage
         .mockRejectedValueOnce(new Error('Service unavailable'))  // recommended model fails
         .mockResolvedValueOnce({ content: 'Last-resort summary' }); // random model succeeds
 
-      const result = await service._generateSummary(testMessages, 'gpt-5.1-codex-mini', {});
+      const result = await service._generateSummary(testMessages, 'gpt-4.1-nano', {});
 
       // Should have been called twice: once for recommended, once for random
       expect(mockAiService.sendMessage).toHaveBeenCalledTimes(2);
@@ -125,16 +125,16 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
     });
 
     test('random model success returns valid summary and does not throw', async () => {
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini']);
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano']);
       mockModelsService.getModels.mockReturnValue([
-        { name: 'gpt-5.1-codex-mini', type: 'chat', contextWindow: 400000 },
+        { name: 'gpt-4.1-nano', type: 'chat', contextWindow: 400000 },
         { name: 'fallback-model', type: 'chat', contextWindow: 200000 }
       ]);
       mockAiService.sendMessage
         .mockRejectedValueOnce(new Error('Service unavailable'))
         .mockResolvedValueOnce({ content: 'Fallback summary content' });
 
-      const result = await service._generateSummary(testMessages, 'gpt-5.1-codex-mini', {});
+      const result = await service._generateSummary(testMessages, 'gpt-4.1-nano', {});
 
       expect(result.role).toBe('system');
       expect(result.type).toBe('summary');
@@ -142,44 +142,44 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
     });
 
     test('random model failure still throws ALL_MODELS_EXHAUSTED', async () => {
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini']);
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano']);
       mockAiService.sendMessage.mockRejectedValue(new Error('Everything is broken'));
 
       await expect(
-        service._generateSummary(testMessages, 'gpt-5.1-codex-mini', {})
+        service._generateSummary(testMessages, 'gpt-4.1-nano', {})
       ).rejects.toThrow('ALL_MODELS_EXHAUSTED');
     });
 
     test('random model is NOT one already attempted (filtered out)', async () => {
-      // Only gpt-5.1-codex-mini is validated; random pool has others
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini']);
+      // Only gpt-4.1-nano is validated; random pool has others
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano']);
       mockModelsService.getModels.mockReturnValue([
-        { name: 'gpt-5.1-codex-mini', type: 'chat', contextWindow: 400000 },
+        { name: 'gpt-4.1-nano', type: 'chat', contextWindow: 400000 },
         { name: 'random-model-xyz', type: 'chat', contextWindow: 200000 }
       ]);
       mockAiService.sendMessage
-        .mockRejectedValueOnce(new Error('fail'))  // gpt-5.1-codex-mini fails
+        .mockRejectedValueOnce(new Error('fail'))  // gpt-4.1-nano fails
         .mockResolvedValueOnce({ content: 'Random success' }); // random-model-xyz succeeds
 
-      const result = await service._generateSummary(testMessages, 'gpt-5.1-codex-mini', {});
+      const result = await service._generateSummary(testMessages, 'gpt-4.1-nano', {});
 
       // Second call should be the random model, not the already-attempted one
       const secondCallModel = mockAiService.sendMessage.mock.calls[1][0];
-      expect(secondCallModel).not.toBe('gpt-5.1-codex-mini');
-      expect(result.metadata.compactionModel).not.toBe('gpt-5.1-codex-mini');
+      expect(secondCallModel).not.toBe('gpt-4.1-nano');
+      expect(result.metadata.compactionModel).not.toBe('gpt-4.1-nano');
     });
 
     test('random model must have sufficient context window', async () => {
       // All models except the recommended one have tiny context windows
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini']);
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano']);
       mockModelsService.getModels.mockReturnValue([
-        { name: 'gpt-5.1-codex-mini', type: 'chat', contextWindow: 400000 },
+        { name: 'gpt-4.1-nano', type: 'chat', contextWindow: 400000 },
         { name: 'tiny-model', type: 'chat', contextWindow: 100 } // too small
       ]);
       mockAiService.sendMessage.mockRejectedValue(new Error('fail'));
 
       await expect(
-        service._generateSummary(testMessages, 'gpt-5.1-codex-mini', {})
+        service._generateSummary(testMessages, 'gpt-4.1-nano', {})
       ).rejects.toThrow('ALL_MODELS_EXHAUSTED');
 
       // Should only have tried the recommended model, not the tiny one
@@ -193,11 +193,11 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
     test('onAllModelsExhausted is called only after ALL models (including random) fail', async () => {
       const onAllModelsExhausted = jest.fn();
 
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini']);
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano']);
       mockAiService.sendMessage.mockRejectedValue(new Error('fail'));
 
       await expect(
-        service._generateSummary(testMessages, 'gpt-5.1-codex-mini', { onAllModelsExhausted })
+        service._generateSummary(testMessages, 'gpt-4.1-nano', { onAllModelsExhausted })
       ).rejects.toThrow('ALL_MODELS_EXHAUSTED');
 
       expect(onAllModelsExhausted).toHaveBeenCalledTimes(1);
@@ -211,16 +211,16 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
     test('onAllModelsExhausted includes all attempted model names', async () => {
       const onAllModelsExhausted = jest.fn();
 
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini', 'gpt-5-mini']);
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano', 'gpt-4.1-mini']);
       mockAiService.sendMessage.mockRejectedValue(new Error('fail'));
 
       await expect(
-        service._generateSummary(testMessages, 'gpt-5.1-codex-mini', { onAllModelsExhausted })
+        service._generateSummary(testMessages, 'gpt-4.1-nano', { onAllModelsExhausted })
       ).rejects.toThrow('ALL_MODELS_EXHAUSTED');
 
       const callArg = onAllModelsExhausted.mock.calls[0][0];
-      expect(callArg.models).toContain('gpt-5.1-codex-mini');
-      expect(callArg.models).toContain('gpt-5-mini');
+      expect(callArg.models).toContain('gpt-4.1-nano');
+      expect(callArg.models).toContain('gpt-4.1-mini');
       // Should also include at least one random model that was attempted
       expect(callArg.models.length).toBeGreaterThanOrEqual(2);
     });
@@ -233,10 +233,10 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
       const onRetryAttempt = jest.fn();
       const onAllModelsExhausted = jest.fn();
 
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini', 'gpt-5-mini']);
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano', 'gpt-4.1-mini']);
       mockAiService.sendMessage.mockResolvedValueOnce({ content: 'Great summary here' });
 
-      const result = await service._generateSummary(testMessages, 'gpt-5.1-codex-mini', {
+      const result = await service._generateSummary(testMessages, 'gpt-4.1-nano', {
         onRetryAttempt,
         onAllModelsExhausted
       });
@@ -253,12 +253,12 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
       const onRetryAttempt = jest.fn();
       const onAllModelsExhausted = jest.fn();
 
-      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-5.1-codex-mini', 'gpt-5-mini']);
+      mockModelsService.getAvailableModelNames.mockReturnValue(['gpt-4.1-nano', 'gpt-4.1-mini']);
       mockAiService.sendMessage
         .mockRejectedValueOnce(new Error('429 rate limit'))
         .mockResolvedValueOnce({ content: 'Second model summary' });
 
-      const result = await service._generateSummary(testMessages, 'gpt-5.1-codex-mini', {
+      const result = await service._generateSummary(testMessages, 'gpt-4.1-nano', {
         onRetryAttempt,
         onAllModelsExhausted
       });
@@ -266,7 +266,7 @@ describe('ConversationCompactionService - _generateSummary retry behavior', () =
       expect(onRetryAttempt).toHaveBeenCalledTimes(1);
       expect(onAllModelsExhausted).not.toHaveBeenCalled();
       expect(result.content).toContain('Second model summary');
-      expect(result.metadata.compactionModel).toBe('gpt-5-mini');
+      expect(result.metadata.compactionModel).toBe('gpt-4.1-mini');
     });
   });
 });

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/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

@@ -421,6 +421,35 @@ describe('ToolsRegistry', () => {
       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