From 8e6bf9bde1e3ef62280aa34e3348d1f4843a1b5b Mon Sep 17 00:00:00 2001
From: Jack Chen <jack_ai@qq.com>
Date: Fri, 24 Apr 2026 02:30:50 +0800
Subject: [PATCH] chore: cosmetic polish following #161 (#162)

- Restore backticks around `prompt` in `Agent.prompt()` comment.
- Drop two stray blank lines around `mergedRecent` in `summarizeMessages`.
- Collapse deliberation comments in the new context-strategy test to one line.
- Add JSDoc note on `contextStrategy.custom.compress` that it fires every turn including the first; implementations must self-gate.
---
 src/agent/agent.ts             | 2 +-
 src/agent/runner.ts            | 2 --
 src/types.ts                   | 5 +++++
 tests/context-strategy.test.ts | 8 +-------
 4 files changed, 7 insertions(+), 10 deletions(-)

diff --git a/src/agent/agent.ts b/src/agent/agent.ts
index f55e9c1..d7c808e 100644
--- a/src/agent/agent.ts
+++ b/src/agent/agent.ts
@@ -206,7 +206,7 @@ export class Agent {
 
     const result = await this.executeRun([...this.messageHistory])
 
-    // Persist the new messages into history so the next prompt sees them.
+    // Persist the new messages into history so the next `prompt` sees them.
     for (const msg of result.messages) {
       this.messageHistory.push(msg)
     }
diff --git a/src/agent/runner.ts b/src/agent/runner.ts
index 714af3c..d6b5799 100644
--- a/src/agent/runner.ts
+++ b/src/agent/runner.ts
@@ -374,12 +374,10 @@ export class AgentRunner {
       : '[Conversation summary unavailable]'
 
     this.summarizeCache = { oldSignature, summaryPrefix }
-    
     const mergedRecent = prependSyntheticPrefixToFirstUser(
       recentPortion,
       `${summaryPrefix}\n\n`,
     )
-    
     return {
       messages: [firstUser, ...mergedRecent],
       usage: summaryResponse.usage,
diff --git a/src/types.ts b/src/types.ts
index 24d3536..ea73955 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -85,6 +85,11 @@ export type ContextStrategy =
     }
   | {
     type: 'custom'
+    /**
+     * Compaction callback. Invoked before every LLM turn including the first,
+     * so implementations that should only fire past a token threshold must
+     * self-gate inside this function.
+     */
     compress: (
       messages: LLMMessage[],
       estimatedTokens: number,
diff --git a/tests/context-strategy.test.ts b/tests/context-strategy.test.ts
index b49de3a..1df69f4 100644
--- a/tests/context-strategy.test.ts
+++ b/tests/context-strategy.test.ts
@@ -205,13 +205,7 @@ describe('AgentRunner contextStrategy', () => {
 
     const result = await runner.run(initialMessages)
 
-    // 2 new messages were generated (the tool use, and the tool result).
-    // The `done` response is returned but not pushed as a new message to the list in `run()`.
-    // Wait, the `done` text response *is* pushed.
-    // Let's verify the exact length of new messages.
-    // The stream loop pushes the assistant message (tool use), then the user message (tool result),
-    // then loops back and pushes the final assistant message (text).
-    // So 3 new messages are added during this run.
+    // Three new messages produced: assistant tool_use, user tool_result, assistant text.
     expect(result.messages).toHaveLength(3)
     expect(result.messages[0]!.role).toBe('assistant')
     expect(result.messages[1]!.role).toBe('user') // The tool_result