fix: bound agent communication memory growth (#369)

* fix: bound agent communication memory growth

UDS messaging now uses private local capabilities instead of exposing auth tokens through SDK metadata, environment variables, session registry, peer listing, or tool output. The receive path bounds NDJSON frames, response buffers, active clients, and pending inbox bytes, and strips auth metadata before messages enter the prompt queue.

Teammate mailboxes now validate file and message sizes, fail closed on corrupt mutation inputs, compact by count and retained bytes, and use stable message identity for in-process acknowledgements. Agent summaries now fork only a bounded recent context using lazy size estimation and content fingerprints instead of retaining or serializing unbounded histories.

Constraint: PR #361 was already merged; this branch is based on upstream/main@c2ac9a74.
Rejected: Default-disabling COORDINATOR_MODE/TEAMMEM only | explicit feature enablement still hit unbounded paths.
Rejected: Persisting UDS auth in SDK/env/session registry | bridge/remote metadata can leak local capability secrets.
Rejected: Inline uds #token addresses | observable/tool/classifier paths can reflect raw addresses outside the UDS request frame.
Rejected: Positional mailbox marking after compaction | compaction can shift indices across the lock boundary.
Confidence: high
Scope-risk: moderate
Directive: Do not expose UDS capability tokens through SDK messages, environment variables, session registry, peer-list output, or SendMessage result/classifier surfaces.
Directive: Do not reintroduce positional mailbox acknowledgements unless compaction is removed or read+mark is atomic under one lock.
Tested: bun test src/utils/__tests__/ndjsonFramer.test.ts src/utils/__tests__/udsMessaging.test.ts packages/builtin-tools/src/tools/SendMessageTool/__tests__/udsRecipientSanitization.test.ts
Tested: bunx tsc --noEmit --pretty false
Tested: bun run lint
Tested: bunx biome lint modified src/package files
Tested: bun run test:all (3704 pass, 0 fail, 6734 expects)
Tested: bun audit (No vulnerabilities found)
Tested: bun run build
Tested: bun run build:vite
Tested: git diff --check
Not-tested: End-to-end external UDS client driving a full production headless model turn.

* fix: harden bounded agent communication review fixes

CodeRabbit and Codecov surfaced real gaps in UDS framing, peer discovery, mailbox retention, and summary context coverage. This tightens those paths without suppressing review or coverage signals.

Constraint: PR #369 must address CodeRabbit and Codecov findings without warning suppression or fake fallbacks

Rejected: Suppress Codecov or CodeRabbit warnings | leaves real receive-path and test-isolation gaps

Rejected: Add unreachable feature-gated tests | bun:bundle keeps those branches compile-time gated in local tests

Confidence: high

Scope-risk: moderate

Directive: Keep UDS auth-token rejection outside feature flags; do not reintroduce inline token fallbacks

Tested: bun test --coverage --coverage-reporter lcov --coverage-dir coverage; bun run test:all; bun run lint; bun run build; bun run build:vite; bun audit; git diff --cached --check

Not-tested: Remote Codecov/CodeRabbit refreshed reports until pushed

* fix: prevent agent communication bounds from hiding CI regressions

Tighten the UDS auth, framing, and response-reader boundaries while keeping the AgentSummary lifecycle covered so Codecov and CI fail on real regressions instead of missing coverage. The poorMode settings mock mirrors unrelated real settings defaults to avoid Bun mock retention changing later permission tests.

Constraint: PR #369 must fix Codecov/CI precisely without warning suppression, fallback masking, or mock pollution

Rejected: Delete AgentSummary lifecycle coverage | would hide Codecov loss and stale-summary behavior

Rejected: Store inline UDS rejection in a hidden input sentinel | cloned observable inputs can drop it and bypass rejection

Rejected: Ignore malformed UDS frames until timeout | leaves client slots and SendMessage calls open to exhaustion

Confidence: high

Scope-risk: moderate

Directive: Keep empty #token= markers rejected; do not require a non-empty token value in hasInlineUdsToken

Tested: bun test packages/builtin-tools/src/tools/SendMessageTool/__tests__/udsRecipientSanitization.test.ts src/utils/__tests__/udsMessaging.test.ts src/utils/__tests__/udsResponseReader.test.ts src/utils/__tests__/ndjsonFramer.test.ts

Tested: bunx tsc --noEmit --pretty false

Tested: bun run lint

Tested: bun test --coverage --coverage-reporter lcov --coverage-dir coverage

Tested: bun run test:all

Tested: bun audit

Tested: bun run build

Tested: bun run build:vite

Not-tested: GitHub-hosted Codecov upload until pushed PR checks rerun

---------

Co-authored-by: unraid <local@unraid.local>

src/services/AgentSummary/__tests__/agentSummary.test.ts

@@ -0,0 +1,152 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+import { asAgentId } from '../../../types/ids.js'
+import type { Message } from '../../../types/message.js'
+import type {
+  CacheSafeParams,
+  ForkedAgentResult,
+} from '../../../utils/forkedAgent.js'
+import { startAgentSummarization } from '../agentSummary.js'
+
+const transcriptMessages = [
+  { type: 'user', message: { content: 'start' }, uuid: 'u1' },
+  {
+    type: 'assistant',
+    message: { content: [{ type: 'text', text: 'working' }] },
+    uuid: 'a1',
+  },
+  { type: 'user', message: { content: 'continue' }, uuid: 'u2' },
+] as unknown as Message[]
+
+type ForkCall = {
+  cacheSafeParams: CacheSafeParams
+}
+
+describe('startAgentSummarization', () => {
+  let scheduled: (() => void | Promise<void>) | undefined
+  let handle: { stop: () => void } | undefined
+  let forkCalls: ForkCall[]
+  let updateCalls: Array<{ taskId: string; summary: string }>
+  let transcriptMessagesForTest: Message[]
+
+  beforeEach(() => {
+    forkCalls = []
+    updateCalls = []
+    scheduled = undefined
+    handle = undefined
+    transcriptMessagesForTest = transcriptMessages
+  })
+
+  test('summarizes bounded transcript once and skips unchanged fingerprints', async () => {
+    handle = startAgentSummarization(
+      'task-1',
+      asAgentId('a0000000000000000'),
+      {
+        forkContextMessages: [
+          { type: 'user', message: { content: 'stale' }, uuid: 'old' },
+        ],
+        model: 'claude-test',
+      } as unknown as CacheSafeParams,
+      () => undefined,
+      {
+        clearTimeout: () => undefined,
+        getAgentTranscript: async () => ({
+          messages: transcriptMessagesForTest,
+          contentReplacements: [],
+        }),
+        isPoorModeActive: () => false,
+        logError: () => undefined,
+        logForDebugging: () => undefined,
+        runForkedAgent: async (args: ForkCall) => {
+          forkCalls.push(args)
+          return {
+            messages: [
+              {
+                type: 'assistant',
+                message: {
+                  content: [{ type: 'text', text: 'Reading udsClient.ts' }],
+                },
+              },
+            ],
+          } as unknown as ForkedAgentResult
+        },
+        setTimeout: ((callback: TimerHandler) => {
+          if (typeof callback !== 'function') {
+            throw new Error('Expected timer callback')
+          }
+          scheduled = callback as () => void | Promise<void>
+          return 1 as unknown as ReturnType<typeof setTimeout>
+        }) as unknown as typeof setTimeout,
+        updateAgentSummary: (taskId: string, summary: string) => {
+          updateCalls.push({ taskId, summary })
+        },
+      },
+    )
+
+    expect(typeof scheduled).toBe('function')
+    await scheduled!()
+
+    expect(forkCalls).toHaveLength(1)
+    expect(updateCalls).toEqual([
+      { taskId: 'task-1', summary: 'Reading udsClient.ts' },
+    ])
+
+    const forkContext = forkCalls[0].cacheSafeParams.forkContextMessages ?? []
+    expect(forkContext.map(message => String(message.uuid))).toEqual([
+      'u1',
+      'a1',
+      'u2',
+    ])
+    expect(forkContext.some(message => String(message.uuid) === 'old')).toBe(
+      false,
+    )
+
+    await scheduled!()
+
+    expect(forkCalls).toHaveLength(1)
+    expect(updateCalls).toHaveLength(1)
+  })
+
+  test('skips summarization when bounded context is too small', async () => {
+    transcriptMessagesForTest = transcriptMessages.slice(0, 2)
+
+    handle = startAgentSummarization(
+      'task-1',
+      asAgentId('a0000000000000000'),
+      {
+        forkContextMessages: transcriptMessages,
+        model: 'claude-test',
+      } as unknown as CacheSafeParams,
+      () => undefined,
+      {
+        clearTimeout: () => undefined,
+        getAgentTranscript: async () => ({
+          messages: transcriptMessagesForTest,
+          contentReplacements: [],
+        }),
+        isPoorModeActive: () => false,
+        logError: () => undefined,
+        logForDebugging: () => undefined,
+        runForkedAgent: async (args: ForkCall) => {
+          forkCalls.push(args)
+          return { messages: [] } as unknown as ForkedAgentResult
+        },
+        setTimeout: ((callback: TimerHandler) => {
+          if (typeof callback !== 'function') {
+            throw new Error('Expected timer callback')
+          }
+          scheduled = callback as () => void | Promise<void>
+          return 1 as unknown as ReturnType<typeof setTimeout>
+        }) as unknown as typeof setTimeout,
+        updateAgentSummary: (taskId: string, summary: string) => {
+          updateCalls.push({ taskId, summary })
+        },
+      },
+    )
+
+    expect(typeof scheduled).toBe('function')
+    await scheduled!()
+
+    expect(forkCalls).toEqual([])
+    expect(updateCalls).toEqual([])
+  })
+})

src/services/AgentSummary/__tests__/summaryContext.test.ts

@@ -0,0 +1,261 @@
+import { describe, expect, test } from 'bun:test'
+import type { Message } from '../../../types/message.js'
+import {
+  buildSummaryContext,
+  estimateMessageChars,
+  getSummaryContextFingerprint,
+  MAX_SUMMARY_CONTEXT_CHARS,
+  selectSummaryContextMessages,
+} from '../summaryContext.js'
+
+function makeMessage(
+  type: 'user' | 'assistant',
+  uuid: string,
+  content: string,
+): Message {
+  return {
+    type,
+    uuid,
+    message: {
+      role: type,
+      content,
+    },
+  } as unknown as Message
+}
+
+describe('selectSummaryContextMessages', () => {
+  test('keeps a bounded recent suffix that starts with a user message', () => {
+    const messages = [
+      makeMessage('assistant', 'a0', 'older assistant'),
+      makeMessage('user', 'u1', 'first prompt'),
+      makeMessage('assistant', 'a1', 'first response'),
+      makeMessage('user', 'u2', 'second prompt'),
+      makeMessage('assistant', 'a2', 'second response'),
+    ]
+
+    const selected = selectSummaryContextMessages(messages, {
+      maxMessages: 3,
+      maxChars: 1_000,
+    })
+
+    expect(selected.map(message => String(message.uuid))).toEqual(['u2', 'a2'])
+  })
+
+  test('returns no context when the newest message exceeds the byte budget', () => {
+    const messages = [
+      makeMessage('user', 'u1', 'first prompt'),
+      makeMessage('assistant', 'a1', 'x'.repeat(100)),
+    ]
+
+    const selected = selectSummaryContextMessages(messages, {
+      maxMessages: 10,
+      maxChars: 10,
+    })
+
+    expect(selected).toEqual([])
+  })
+
+  test('uses serialized message size for nested content budgets', () => {
+    const messages = [
+      makeMessage('user', 'u1', 'first prompt'),
+      {
+        ...makeMessage('assistant', 'a1', 'short'),
+        nested: {
+          payload: Array.from({ length: 50 }, (_value, index) => ({
+            index,
+            text: 'x'.repeat(20),
+          })),
+        },
+      } as unknown as Message,
+    ]
+
+    const selected = selectSummaryContextMessages(messages, {
+      maxMessages: 10,
+      maxChars: 200,
+    })
+
+    expect(selected).toEqual([])
+  })
+
+  test('stops at an older oversized message after keeping the recent suffix', () => {
+    const messages = [
+      makeMessage('user', 'u1', 'x'.repeat(5_000)),
+      makeMessage('user', 'u2', 'small prompt'),
+      makeMessage('assistant', 'a2', 'small answer'),
+    ]
+
+    const selected = selectSummaryContextMessages(messages, {
+      maxMessages: 10,
+      maxChars: 1_000,
+    })
+
+    expect(selected.map(message => String(message.uuid))).toEqual(['u2', 'a2'])
+  })
+
+  test('drops leading orphan tool results after bounding', () => {
+    const messages = [
+      makeMessage('assistant', 'a0', 'older assistant'),
+      {
+        type: 'user',
+        uuid: 'u1',
+        message: {
+          role: 'user',
+          content: [
+            { type: 'tool_result', tool_use_id: 'tool-1', content: 'ok' },
+          ],
+        },
+      } as unknown as Message,
+      makeMessage('assistant', 'a1', 'after orphan'),
+      makeMessage('user', 'u2', 'next prompt'),
+    ]
+
+    const selected = selectSummaryContextMessages(messages, {
+      maxMessages: 3,
+      maxChars: 1_000,
+    })
+
+    expect(selected.map(message => String(message.uuid))).toEqual(['u2'])
+  })
+})
+
+describe('getSummaryContextFingerprint', () => {
+  test('estimates circular messages as unbounded', () => {
+    const circular = makeMessage('assistant', 'a1', 'cycle') as Message & {
+      self?: unknown
+    }
+    circular.self = circular
+
+    expect(estimateMessageChars(circular)).toBe(Number.POSITIVE_INFINITY)
+  })
+
+  test('ignores non-json primitive fields in size estimates', () => {
+    const message = makeMessage('assistant', 'a1', 'metadata') as Message & {
+      skipUndefined?: undefined
+      skipFunction?: () => void
+      skipSymbol?: symbol
+    }
+    message.skipUndefined = undefined
+    message.skipFunction = () => undefined
+    message.skipSymbol = Symbol('ignored')
+
+    expect(estimateMessageChars(message)).toBeGreaterThan(0)
+  })
+
+  test('returns null for an empty transcript', () => {
+    expect(getSummaryContextFingerprint([])).toBeNull()
+  })
+
+  test('changes when the transcript grows', () => {
+    const messages = [
+      makeMessage('user', 'u1', 'first prompt'),
+      makeMessage('assistant', 'a1', 'first response'),
+    ]
+
+    const first = getSummaryContextFingerprint(messages)
+    const second = getSummaryContextFingerprint([
+      ...messages,
+      makeMessage('user', 'u2', 'next prompt'),
+    ])
+    expect(first?.startsWith('2:a1:')).toBe(true)
+    expect(second?.startsWith('3:u2:')).toBe(true)
+    expect(first).not.toBe(second)
+  })
+
+  test('changes when message content changes under the same uuid', () => {
+    const first = getSummaryContextFingerprint([
+      makeMessage('user', 'u1', 'first prompt'),
+      makeMessage('assistant', 'a1', 'first response'),
+    ])
+    const second = getSummaryContextFingerprint([
+      makeMessage('user', 'u1', 'first prompt'),
+      makeMessage('assistant', 'a1', 'updated response'),
+    ])
+
+    expect(first).not.toBe(second)
+  })
+
+  test('includes a truncation marker for oversized primitive values', () => {
+    const prefix = 'x'.repeat(MAX_SUMMARY_CONTEXT_CHARS + 100)
+    const first = getSummaryContextFingerprint([
+      makeMessage('assistant', 'a1', `${prefix}a`),
+    ])
+    const second = getSummaryContextFingerprint([
+      makeMessage('assistant', 'a1', `${prefix}b`),
+    ])
+
+    expect(first).not.toBe(second)
+  })
+
+  test('fingerprints circular message references without recursing forever', () => {
+    const circular = makeMessage('assistant', 'a1', 'cycle') as Message & {
+      self?: unknown
+    }
+    circular.self = circular
+
+    expect(getSummaryContextFingerprint([circular])).toContain(':a1:')
+  })
+})
+
+describe('buildSummaryContext', () => {
+  test('returns bounded messages and fingerprint for summarizable context', () => {
+    const messages = [
+      { type: 'user', uuid: 'u1', message: { content: 'start' } },
+      {
+        type: 'assistant',
+        uuid: 'a1',
+        message: { content: [{ type: 'text', text: 'working' }] },
+      },
+      { type: 'user', uuid: 'u2', message: { content: 'continue' } },
+    ] as unknown as Message[]
+
+    const result = buildSummaryContext(messages, null)
+
+    expect(result.skipReason).toBeUndefined()
+    expect(result.messages.map(message => String(message.uuid))).toEqual([
+      'u1',
+      'a1',
+      'u2',
+    ])
+    expect(result.fingerprint).toContain('3:u2:')
+  })
+
+  test('reports unchanged contexts by fingerprint', () => {
+    const messages = [
+      { type: 'user', uuid: 'u1', message: { content: 'start' } },
+      {
+        type: 'assistant',
+        uuid: 'a1',
+        message: { content: [{ type: 'text', text: 'working' }] },
+      },
+      { type: 'user', uuid: 'u2', message: { content: 'continue' } },
+    ] as unknown as Message[]
+    const first = buildSummaryContext(messages, null)
+
+    const second = buildSummaryContext(messages, first.fingerprint)
+
+    expect(second.skipReason).toBe('unchanged')
+    expect(second.fingerprint).toBe(first.fingerprint)
+  })
+
+  test('filters incomplete tool calls before deciding context is too small', () => {
+    const messages = [
+      { type: 'user', uuid: 'u1', message: { content: 'start' } },
+      {
+        type: 'assistant',
+        uuid: 'a1',
+        message: {
+          content: [{ type: 'tool_use', id: 'missing', name: 'Read' }],
+        },
+      },
+      { type: 'user', uuid: 'u2', message: { content: 'continue' } },
+    ] as unknown as Message[]
+
+    const result = buildSummaryContext(messages, null)
+
+    expect(result.skipReason).toBe('too_small')
+    expect(result.messages.map(message => String(message.uuid))).toEqual([
+      'u1',
+      'u2',
+    ])
+  })
+})

src/services/AgentSummary/__tests__/summaryPrompt.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  buildSummaryPrompt,
+  createSummaryPromptMessage,
+} from '../summaryPrompt.js'
+
+describe('buildSummaryPrompt', () => {
+  test('builds the first summary prompt without previous-summary pressure', () => {
+    const prompt = buildSummaryPrompt(null)
+
+    expect(prompt).toContain('Describe your most recent action')
+    expect(prompt).toContain('Good: "Reading runAgent.ts"')
+    expect(prompt).not.toContain('Previous:')
+  })
+
+  test('asks for a new summary when a previous one exists', () => {
+    const prompt = buildSummaryPrompt('Reading udsMessaging.ts')
+
+    expect(prompt).toContain('Previous: "Reading udsMessaging.ts"')
+    expect(prompt).toContain('say something NEW')
+  })
+})
+
+describe('createSummaryPromptMessage', () => {
+  test('creates the minimal user message shape used by forked summaries', () => {
+    const message = createSummaryPromptMessage('Summarize progress')
+
+    expect(message.type).toBe('user')
+    expect(message.message.role).toBe('user')
+    expect(message.message.content).toBe('Summarize progress')
+    expect(message.uuid).toBeString()
+    expect(message.timestamp).toBeString()
+  })
+})

src/services/AgentSummary/agentSummary.ts

@@ -13,7 +13,6 @@
 import type { TaskContext } from '../../Task.js'
 import { isPoorModeActive } from '../../commands/poor/poorMode.js'
 import { updateAgentSummary } from '../../tasks/LocalAgentTask/LocalAgentTask.js'
-import { filterIncompleteToolCalls } from '@claude-code-best/builtin-tools/tools/AgentTool/runAgent.js'
 import type { AgentId } from '../../types/ids.js'
 import { logForDebugging } from '../../utils/debug.js'
 import {
@@ -21,34 +20,32 @@ import {
   runForkedAgent,
 } from '../../utils/forkedAgent.js'
 import { logError } from '../../utils/log.js'
-import { createUserMessage } from '../../utils/messages.js'
 import { getAgentTranscript } from '../../utils/sessionStorage.js'
+import { buildSummaryContext } from './summaryContext.js'
+import {
+  buildSummaryPrompt,
+  createSummaryPromptMessage,
+} from './summaryPrompt.js'
 
 const SUMMARY_INTERVAL_MS = 30_000
 
-function buildSummaryPrompt(previousSummary: string | null): string {
-  const prevLine = previousSummary
-    ? `\nPrevious: "${previousSummary}" — say something NEW.\n`
-    : ''
-
-  return `Describe your most recent action in 3-5 words using present tense (-ing). Name the file or function, not the branch. Do not use tools.
-${prevLine}
-Good: "Reading runAgent.ts"
-Good: "Fixing null check in validate.ts"
-Good: "Running auth module tests"
-Good: "Adding retry logic to fetchUser"
-
-Bad (past tense): "Analyzed the branch diff"
-Bad (too vague): "Investigating the issue"
-Bad (too long): "Reviewing full branch diff and AgentTool.tsx integration"
-Bad (branch name): "Analyzed adam/background-summary branch diff"`
-}
+export type AgentSummaryDependencies = Partial<{
+  clearTimeout: typeof clearTimeout
+  getAgentTranscript: typeof getAgentTranscript
+  isPoorModeActive: typeof isPoorModeActive
+  logError: typeof logError
+  logForDebugging: typeof logForDebugging
+  runForkedAgent: typeof runForkedAgent
+  setTimeout: typeof setTimeout
+  updateAgentSummary: typeof updateAgentSummary
+}>
 
 export function startAgentSummarization(
   taskId: string,
   agentId: AgentId,
   cacheSafeParams: CacheSafeParams,
   setAppState: TaskContext['setAppState'],
+  dependencies: AgentSummaryDependencies = {},
 ): { stop: () => void } {
   // Drop forkContextMessages from the closure — runSummary rebuilds it each
   // tick from getAgentTranscript(). Without this, the original fork messages
@@ -58,39 +55,67 @@ export function startAgentSummarization(
   let timeoutId: ReturnType<typeof setTimeout> | null = null
   let stopped = false
   let previousSummary: string | null = null
+  let lastHandledTranscriptFingerprint: string | null = null
+  const clearTimeoutImpl = dependencies.clearTimeout ?? clearTimeout
+  const getAgentTranscriptImpl =
+    dependencies.getAgentTranscript ?? getAgentTranscript
+  const isPoorModeActiveImpl =
+    dependencies.isPoorModeActive ?? isPoorModeActive
+  const logErrorImpl = dependencies.logError ?? logError
+  const logForDebuggingImpl =
+    dependencies.logForDebugging ?? logForDebugging
+  const runForkedAgentImpl = dependencies.runForkedAgent ?? runForkedAgent
+  const setTimeoutImpl = dependencies.setTimeout ?? setTimeout
+  const updateAgentSummaryImpl =
+    dependencies.updateAgentSummary ?? updateAgentSummary
 
   async function runSummary(): Promise<void> {
     if (stopped) return
-    if (isPoorModeActive()) {
-      logForDebugging('[AgentSummary] Skipping summary — poor mode active')
+    if (isPoorModeActiveImpl()) {
+      logForDebuggingImpl('[AgentSummary] Skipping summary — poor mode active')
       scheduleNext()
       return
     }
 
-    logForDebugging(`[AgentSummary] Timer fired for agent ${agentId}`)
+    logForDebuggingImpl(`[AgentSummary] Timer fired for agent ${agentId}`)
 
     try {
       // Read current messages from transcript
-      const transcript = await getAgentTranscript(agentId)
+      const transcript = await getAgentTranscriptImpl(agentId)
       if (!transcript || transcript.messages.length < 3) {
         // Not enough context yet — finally block will schedule next attempt
-        logForDebugging(
+        logForDebuggingImpl(
           `[AgentSummary] Skipping summary for ${taskId}: not enough messages (${transcript?.messages.length ?? 0})`,
         )
         return
       }
 
-      // Filter to clean message state
-      const cleanMessages = filterIncompleteToolCalls(transcript.messages)
+      const summaryContext = buildSummaryContext(
+        transcript.messages,
+        lastHandledTranscriptFingerprint,
+      )
+      if (summaryContext.skipReason === 'unchanged') {
+        logForDebuggingImpl(
+          `[AgentSummary] Skipping summary for ${taskId}: transcript unchanged`,
+        )
+        return
+      }
+
+      if (summaryContext.skipReason === 'too_small') {
+        logForDebuggingImpl(
+          `[AgentSummary] Skipping summary for ${taskId}: no bounded context available`,
+        )
+        return
+      }
 
       // Build fork params with current messages
       const forkParams: CacheSafeParams = {
         ...baseParams,
-        forkContextMessages: cleanMessages,
+        forkContextMessages: summaryContext.messages,
       }
 
-      logForDebugging(
-        `[AgentSummary] Forking for summary, ${cleanMessages.length} messages in context`,
+      logForDebuggingImpl(
+        `[AgentSummary] Forking for summary, ${summaryContext.messages.length} messages in context`,
       )
 
       // Create abort controller for this summary
@@ -112,9 +137,9 @@ export function startAgentSummarization(
       // ContentReplacementState is cloned by default in createSubagentContext
       // from forkParams.toolUseContext (the subagent's LIVE state captured at
       // onCacheSafeParams time). No explicit override needed.
-      const result = await runForkedAgent({
+      const result = await runForkedAgentImpl({
         promptMessages: [
-          createUserMessage({ content: buildSummaryPrompt(previousSummary) }),
+          createSummaryPromptMessage(buildSummaryPrompt(previousSummary)),
         ],
         cacheSafeParams: forkParams,
         canUseTool,
@@ -136,21 +161,24 @@ export function startAgentSummarization(
           )
           continue
         }
-        const contentArr = Array.isArray(msg.message!.content) ? msg.message!.content : []
+        const contentArr = Array.isArray(msg.message!.content)
+          ? msg.message!.content
+          : []
         const textBlock = contentArr.find(b => b.type === 'text')
         if (textBlock?.type === 'text' && textBlock.text.trim()) {
           const summaryText = textBlock.text.trim()
-          logForDebugging(
+          logForDebuggingImpl(
             `[AgentSummary] Summary result for ${taskId}: ${summaryText}`,
           )
+          lastHandledTranscriptFingerprint = summaryContext.fingerprint
           previousSummary = summaryText
-          updateAgentSummary(taskId, summaryText, setAppState)
+          updateAgentSummaryImpl(taskId, summaryText, setAppState)
           break
         }
       }
     } catch (e) {
       if (!stopped && e instanceof Error) {
-        logError(e)
+        logErrorImpl(e)
       }
     } finally {
       summaryAbortController = null
@@ -163,14 +191,14 @@ export function startAgentSummarization(
 
   function scheduleNext(): void {
     if (stopped) return
-    timeoutId = setTimeout(runSummary, SUMMARY_INTERVAL_MS)
+    timeoutId = setTimeoutImpl(runSummary, SUMMARY_INTERVAL_MS)
   }
 
   function stop(): void {
-    logForDebugging(`[AgentSummary] Stopping summarization for ${taskId}`)
+    logForDebuggingImpl(`[AgentSummary] Stopping summarization for ${taskId}`)
     stopped = true
     if (timeoutId) {
-      clearTimeout(timeoutId)
+      clearTimeoutImpl(timeoutId)
       timeoutId = null
     }
     if (summaryAbortController) {

src/services/AgentSummary/summaryContext.ts

@@ -0,0 +1,219 @@
+import { createHash } from 'node:crypto'
+import { filterIncompleteToolCalls } from '@claude-code-best/builtin-tools/tools/AgentTool/filterIncompleteToolCalls.js'
+import type { Message } from '../../types/message.js'
+
+export const MAX_SUMMARY_CONTEXT_MESSAGES = 120
+export const MAX_SUMMARY_CONTEXT_CHARS = 200_000
+
+function estimateJsonChars(
+  value: unknown,
+  limit: number,
+  seen = new Set<object>(),
+): number {
+  if (value === null) return 4
+  switch (typeof value) {
+    case 'string':
+      return value.length + 2
+    case 'number':
+    case 'boolean':
+      return String(value).length
+    case 'undefined':
+    case 'function':
+    case 'symbol':
+      return 0
+    case 'object': {
+      if (seen.has(value)) return Number.POSITIVE_INFINITY
+      seen.add(value)
+      let total = 2
+      if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++) {
+          total += String(index).length + 3
+          total += estimateJsonChars(value[index], limit - total, seen)
+          if (total > limit) return total
+        }
+      } else {
+        const record = value as Record<string, unknown>
+        for (const key in record) {
+          if (!Object.hasOwn(record, key)) continue
+          total += key.length + 3
+          total += estimateJsonChars(record[key], limit - total, seen)
+          if (total > limit) return total
+        }
+      }
+      seen.delete(value)
+      return total
+    }
+  }
+  return 0
+}
+
+function updateFingerprintHash(
+  hash: ReturnType<typeof createHash>,
+  value: unknown,
+  limit: { remaining: number },
+  seen = new Set<object>(),
+): void {
+  if (limit.remaining <= 0) return
+  if (value === null || typeof value !== 'object') {
+    const text = String(value)
+    const consumed = Math.min(text.length, limit.remaining)
+    if (consumed <= 0) return
+    hash.update(typeof value)
+    hash.update(':')
+    hash.update(text.slice(0, consumed))
+    if (consumed < text.length) {
+      hash.update(`#truncated:${text.length}:${text.slice(-64)}`)
+    }
+    limit.remaining -= consumed
+    return
+  }
+  if (seen.has(value)) {
+    hash.update('[Circular]')
+    return
+  }
+  seen.add(value)
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      if (limit.remaining <= 0) break
+      const key = String(index)
+      hash.update(key)
+      limit.remaining -= key.length
+      updateFingerprintHash(hash, value[index], limit, seen)
+    }
+  } else {
+    const record = value as Record<string, unknown>
+    for (const key in record) {
+      if (limit.remaining <= 0) break
+      if (!Object.hasOwn(record, key)) continue
+      hash.update(key)
+      limit.remaining -= key.length
+      updateFingerprintHash(hash, record[key], limit, seen)
+    }
+  }
+  seen.delete(value)
+}
+
+export function estimateMessageChars(
+  message: Message,
+  limit = Number.POSITIVE_INFINITY,
+): number {
+  const estimated = estimateJsonChars(message, limit)
+  if (!Number.isFinite(estimated)) {
+    return Number.POSITIVE_INFINITY
+  }
+  return estimated
+}
+
+function hasToolResultBlock(message: Message): boolean {
+  if (message.type !== 'user') return false
+  const content = message.message?.content
+  return (
+    Array.isArray(content) &&
+    content.some(block => {
+      return Boolean(
+        block &&
+          typeof block === 'object' &&
+          'type' in block &&
+          block.type === 'tool_result',
+      )
+    })
+  )
+}
+
+export function getSummaryContextFingerprint(
+  messages: Message[],
+): string | null {
+  const lastMessage = messages.at(-1)
+  if (!lastMessage) return null
+  const hash = createHash('sha256')
+  updateFingerprintHash(hash, messages, {
+    remaining: MAX_SUMMARY_CONTEXT_CHARS,
+  })
+  return `${messages.length}:${lastMessage.uuid}:${hash.digest('hex').slice(0, 16)}`
+}
+
+export function selectSummaryContextMessages(
+  messages: Message[],
+  limits: {
+    maxMessages?: number
+    maxChars?: number
+  } = {},
+): Message[] {
+  const maxMessages = limits.maxMessages ?? MAX_SUMMARY_CONTEXT_MESSAGES
+  const maxChars = limits.maxChars ?? MAX_SUMMARY_CONTEXT_CHARS
+  if (maxMessages <= 0 || maxChars <= 0) return []
+
+  const selected: Message[] = []
+  let selectedChars = 0
+
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i]
+    if (!message) continue
+
+    const messageChars = estimateMessageChars(message, maxChars - selectedChars)
+    if (messageChars > maxChars) {
+      if (selected.length === 0) return []
+      break
+    }
+
+    if (
+      selected.length >= maxMessages ||
+      selectedChars + messageChars > maxChars
+    ) {
+      break
+    }
+
+    selected.unshift(message)
+    selectedChars += messageChars
+  }
+
+  while (selected.length > 0) {
+    const first = selected[0]
+    if (!first) break
+    if (first.type !== 'user' || hasToolResultBlock(first)) {
+      selected.shift()
+      continue
+    }
+    break
+  }
+
+  return selected
+}
+
+export type SummaryContextBuildResult = {
+  messages: Message[]
+  fingerprint: string | null
+  skipReason?: 'too_small' | 'unchanged'
+}
+
+export function buildSummaryContext(
+  messages: Message[],
+  previousFingerprint: string | null,
+): SummaryContextBuildResult {
+  const cleanMessages = filterIncompleteToolCalls(messages)
+  const boundedMessages = filterIncompleteToolCalls(
+    selectSummaryContextMessages(cleanMessages),
+  )
+  const fingerprint = getSummaryContextFingerprint(boundedMessages)
+
+  if (fingerprint && fingerprint === previousFingerprint) {
+    return {
+      messages: boundedMessages,
+      fingerprint,
+      skipReason: 'unchanged',
+    }
+  }
+
+  if (boundedMessages.length < 3) {
+    return {
+      messages: boundedMessages,
+      fingerprint,
+      skipReason: 'too_small',
+    }
+  }
+
+  return {
+    messages: boundedMessages,
+    fingerprint,
+  }
+}

src/services/AgentSummary/summaryPrompt.ts

@@ -0,0 +1,32 @@
+import { randomUUID, type UUID } from 'node:crypto'
+import type { UserMessage } from '../../types/message.js'
+
+export function buildSummaryPrompt(previousSummary: string | null): string {
+  const prevLine = previousSummary
+    ? `\nPrevious: "${previousSummary}" — say something NEW.\n`
+    : ''
+
+  return `Describe your most recent action in 3-5 words using present tense (-ing). Name the file or function, not the branch. Do not use tools.
+${prevLine}
+Good: "Reading runAgent.ts"
+Good: "Fixing null check in validate.ts"
+Good: "Running auth module tests"
+Good: "Adding retry logic to fetchUser"
+
+Bad (past tense): "Analyzed the branch diff"
+Bad (too vague): "Investigating the issue"
+Bad (too long): "Reviewing full branch diff and AgentTool.tsx integration"
+Bad (branch name): "Analyzed adam/background-summary branch diff"`
+}
+
+export function createSummaryPromptMessage(content: string): UserMessage {
+  return {
+    type: 'user',
+    message: {
+      role: 'user',
+      content,
+    },
+    uuid: randomUUID() as UUID,
+    timestamp: new Date().toISOString(),
+  }
+}