@namzu/sdk 3.1.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/advisory/__tests__/consultation-context.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { AdvisorDefinition } from '../../types/advisory/index.js'
+import type { Message } from '../../types/message/index.js'
+import { AdvisoryContext } from '../context.js'
+import { TriggerEvaluator } from '../evaluator.js'
+import { AdvisoryExecutor } from '../executor.js'
+import { ADVISORY_RESPONSE_CONTRACT } from '../parse.js'
+import { AdvisorRegistry } from '../registry.js'
+
+/**
+ * An advisor consulted BY THE MODEL saw the question and nothing else.
+ *
+ * Two paths reach `AdvisoryExecutor.consult`. The trigger path
+ * (`iteration/phases/advisory.ts`) has always passed the live messages, the
+ * working state and the tool catalogue. The tool path passed
+ * `{ messages: [], iteration: 0 }` — a literal empty context — so the
+ * model's own `include_context: true` had nothing to include, and the
+ * advisor answered a question about a situation it could not see.
+ */
+
+function recordingProvider(): { provider: AdvisorDefinition['provider']; calls: Message[][] } {
+	const calls: Message[][] = []
+	const provider = {
+		chatStream: async function* (params: { messages: Message[] }) {
+			calls.push(params.messages)
+			yield { id: 'a1', delta: { content: 'ADVICE: do the thing' } }
+			yield {
+				id: 'a1',
+				delta: {},
+				finishReason: 'stop',
+				usage: { promptTokens: 1, completionTokens: 1, totalTokens: 2 },
+			}
+		},
+	} as unknown as AdvisorDefinition['provider']
+	return { provider, calls }
+}
+
+function advisor(over: Partial<AdvisorDefinition> = {}): AdvisorDefinition {
+	return {
+		id: 'adv_1',
+		name: 'Reviewer',
+		provider: recordingProvider().provider,
+		model: 'mock-model',
+		...over,
+	} as AdvisorDefinition
+}
+
+const log = {
+	debug: vi.fn(),
+	info: vi.fn(),
+	warn: vi.fn(),
+	error: vi.fn(),
+	child: () => log,
+} as never
+
+function contextFor(a: AdvisorDefinition): AdvisoryContext {
+	return new AdvisoryContext(
+		new AdvisorRegistry([a]),
+		new AdvisoryExecutor(log),
+		new TriggerEvaluator([]),
+	)
+}
+
+describe('the context a tool-initiated consultation is given', () => {
+	it('is empty until the runtime supplies one', () => {
+		const ctx = contextFor(advisor())
+
+		// The fallback exists for a context built without a runtime, and it is
+		// what every tool-initiated call used to get.
+		expect(ctx.callContext()).toEqual({ messages: [], iteration: 0 })
+	})
+
+	it('is the live run once the runtime wires it', () => {
+		const ctx = contextFor(advisor())
+		const messages: Message[] = [{ role: 'user', content: 'the situation', timestamp: 1 }]
+
+		ctx.setCallContextProvider(() => ({ messages, iteration: 7 }))
+
+		expect(ctx.callContext().messages).toBe(messages)
+		expect(ctx.callContext().iteration).toBe(7)
+	})
+
+	it('is read at call time, not at construction', () => {
+		const ctx = contextFor(advisor())
+		let iteration = 1
+		ctx.setCallContextProvider(() => ({ messages: [], iteration }))
+
+		iteration = 4
+
+		// The tool is built once per run and called at an unknown later point.
+		// A snapshot would hand every advisor the state the run started with.
+		expect(ctx.callContext().iteration).toBe(4)
+	})
+})
+
+describe('what the advisor actually receives', () => {
+	it('sees the conversation when context is included', async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+
+		await executor.consult(
+			advisor({ provider }),
+			{ advisorId: 'adv_1', question: 'what next?', includeContext: true },
+			{ messages: [{ role: 'user', content: 'deploy is failing', timestamp: 1 }], iteration: 2 },
+		)
+
+		const sent = JSON.stringify(calls[0])
+		expect(sent).toContain('deploy is failing')
+	})
+
+	it('sees none of it when the caller says not to', async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+
+		await executor.consult(
+			advisor({ provider }),
+			{ advisorId: 'adv_1', question: 'what next?', includeContext: false },
+			{ messages: [{ role: 'user', content: 'deploy is failing', timestamp: 1 }], iteration: 2 },
+		)
+
+		expect(JSON.stringify(calls[0])).not.toContain('deploy is failing')
+	})
+
+	it('is told when the caller marked the request urgent', async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+
+		await executor.consult(
+			advisor({ provider }),
+			{ advisorId: 'adv_1', question: 'what next?', urgency: 'high' },
+			{ messages: [], iteration: 1 },
+		)
+
+		// The value used to reach exactly one debug log line, so 'high' and
+		// 'low' produced byte-identical requests.
+		expect(String(calls[0]?.[0]?.content)).toContain('URGENT')
+	})
+
+	it('is told when there is room to consider alternatives', async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+
+		await executor.consult(
+			advisor({ provider }),
+			{ advisorId: 'adv_1', question: 'what next?', urgency: 'low' },
+			{ messages: [], iteration: 1 },
+		)
+
+		expect(String(calls[0]?.[0]?.content)).toContain('low urgency')
+	})
+
+	it("appends nothing at all for 'normal', which is the point of not stating it", async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+		const a = advisor({ provider })
+
+		await executor.consult(
+			a,
+			{ advisorId: 'adv_1', question: 'what next?', urgency: 'normal' },
+			{ messages: [], iteration: 1 },
+		)
+		await executor.consult(
+			a,
+			{ advisorId: 'adv_1', question: 'what next?', urgency: 'high' },
+			{ messages: [], iteration: 1 },
+		)
+
+		// Asserting "does not contain the other two phrases" is too weak — it
+		// would let ANY new sentence in. The response contract is the last
+		// thing the prompt says when urgency contributes nothing, so ending on
+		// it is what "appended nothing" actually means.
+		expect(String(calls[0]?.[0]?.content).trimEnd().endsWith(ADVISORY_RESPONSE_CONTRACT)).toBe(true)
+		expect(String(calls[1]?.[0]?.content).trimEnd().endsWith(ADVISORY_RESPONSE_CONTRACT)).toBe(
+			false,
+		)
+	})
+
+	it('says nothing about urgency when the caller did not', async () => {
+		const { provider, calls } = recordingProvider()
+		const executor = new AdvisoryExecutor(log)
+
+		await executor.consult(
+			advisor({ provider }),
+			{ advisorId: 'adv_1', question: 'what next?' },
+			{ messages: [], iteration: 1 },
+		)
+
+		expect(String(calls[0]?.[0]?.content).trimEnd().endsWith(ADVISORY_RESPONSE_CONTRACT)).toBe(true)
+	})
+})

package/src/advisory/context.ts

@@ -1,8 +1,20 @@
 import type { AdvisoryBudget, AdvisoryCallRecord } from '../types/advisory/index.js'
 import type { TriggerEvaluator } from './evaluator.js'
+import type { AdvisoryCallContext } from './executor.js'
 import type { AdvisoryExecutor } from './executor.js'
 import type { AdvisorRegistry } from './registry.js'
 
+/**
+ * What the run looks like right now, for an advisory call that did not come
+ * from the iteration loop.
+ *
+ * A function rather than a snapshot because the tool is built once per run
+ * and called at an unknown later point: capturing the context at
+ * construction would hand every advisor the state the run had before it
+ * started.
+ */
+export type AdvisoryCallContextProvider = () => AdvisoryCallContext
+
 export class AdvisoryContext {
 	readonly registry: AdvisorRegistry
 	readonly executor: AdvisoryExecutor
@@ -10,6 +22,7 @@ export class AdvisoryContext {
 	readonly callHistory: AdvisoryCallRecord[] = []
 
 	private readonly budget: AdvisoryBudget | undefined
+	private callContextProvider: AdvisoryCallContextProvider | undefined
 
 	constructor(
 		registry: AdvisorRegistry,
@@ -23,6 +36,25 @@ export class AdvisoryContext {
 		this.budget = budget
 	}
 
+	/** Wired by the runtime once the run exists. */
+	setCallContextProvider(provider: AdvisoryCallContextProvider): void {
+		this.callContextProvider = provider
+	}
+
+	/**
+	 * The call context for a tool-initiated consultation.
+	 *
+	 * The trigger path (`iteration/phases/advisory.ts`) has always passed the
+	 * live messages, working state and tool catalogue. The TOOL path passed
+	 * `{ messages: [], iteration: 0 }` — a literal empty context — so an
+	 * advisor consulted by the model saw the question and nothing else, and
+	 * the model's `include_context` had nothing to include either way. The
+	 * empty fallback survives only for a context built without a runtime.
+	 */
+	callContext(): AdvisoryCallContext {
+		return this.callContextProvider?.() ?? { messages: [], iteration: 0 }
+	}
+
 	recordCall(record: AdvisoryCallRecord): void {
 		this.callHistory.push(record)
 	}

package/src/advisory/executor.ts

@@ -11,6 +11,19 @@ import { calculateCost } from '../utils/cost.js'
 import { type Logger, getRootLogger } from '../utils/logger.js'
 import { ADVISORY_RESPONSE_CONTRACT, parseAdvisoryResponse } from './parse.js'
 
+/**
+ * What the advisor is told about how urgent the caller said this is.
+ *
+ * `'normal'` says nothing on purpose. A sentence asserting the ordinary case
+ * is prompt weight that changes no answer, and stating it on every call
+ * would make the two that matter harder to notice.
+ */
+const URGENCY_DIRECTION: Record<'low' | 'normal' | 'high', string | undefined> = {
+	high: 'This request is marked URGENT. Lead with the single most important action and keep the reasoning to what is needed to justify it.',
+	normal: undefined,
+	low: 'This request is marked low urgency. There is room to note secondary considerations and alternatives worth weighing.',
+}
+
 export interface AdvisoryCallContext {
 	readonly messages: Message[]
 	readonly workingStateSummary?: string
@@ -53,7 +66,7 @@ export class AdvisoryExecutor {
 	): Promise<AdvisoryExecutionResult> {
 		const startMs = Date.now()
 
-		const systemPrompt = this.buildSystemPrompt(advisor)
+		const systemPrompt = this.buildSystemPrompt(advisor, request.urgency)
 		const contextMessages = this.buildContext(advisor, request, callCtx)
 
 		const messages: Message[] = [
@@ -100,11 +113,25 @@ export class AdvisoryExecutor {
 		}
 	}
 
-	private buildSystemPrompt(advisor: AdvisorDefinition): string {
+	private buildSystemPrompt(
+		advisor: AdvisorDefinition,
+		urgency?: AdvisoryRequest['urgency'],
+	): string {
 		// The contract is appended to every branch, not folded into the
 		// default: an advisor with its own prompt or a persona is still read
 		// back by the same parser, and used to be the one never told so.
-		return `${this.describeAdvisor(advisor)}\n\n${ADVISORY_RESPONSE_CONTRACT}`
+		const parts = [this.describeAdvisor(advisor), ADVISORY_RESPONSE_CONTRACT]
+
+		// The caller is invited to say how urgent this is, and the value used
+		// to reach exactly one debug log line — `urgency: 'high'` and
+		// `urgency: 'low'` produced byte-identical requests. Telling the
+		// ADVISOR is the honest minimum: it is the party that can act on the
+		// answer, and it costs one sentence rather than a routing policy this
+		// kernel has no business inventing.
+		const direction = URGENCY_DIRECTION[urgency ?? 'normal']
+		if (direction) parts.push(direction)
+
+		return parts.join('\n\n')
 	}
 
 	private describeAdvisor(advisor: AdvisorDefinition): string {

package/src/compaction/__tests__/context-reducer.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { AssistantMessage, Message, ToolMessage } from '../../types/message/index.js'
+import { createSlidingWindowReducer } from '../reducer.js'
+import type { ContextReduction } from '../reducer.js'
+
+/**
+ * `strategy: 'sliding-window'` was accepted by the config schema and then
+ * ignored — the runtime asked only whether the strategy was `'disabled'`, so
+ * a host who chose the cheap non-LLM path silently got the expensive LLM one,
+ * summarization calls and all. These pin the behaviour the name always
+ * claimed, and the three invariants that make a shorter history usable rather
+ * than merely shorter.
+ */
+
+const sys = (content: string): Message => ({ role: 'system', content, timestamp: 1 })
+const user = (content: string): Message => ({ role: 'user', content, timestamp: 1 })
+const asst = (content: string): Message => ({ role: 'assistant', content, timestamp: 1 })
+
+const callsTool = (id: string): AssistantMessage => ({
+	role: 'assistant',
+	content: null,
+	timestamp: 1,
+	toolCalls: [{ id, type: 'function', function: { name: 'echo', arguments: '{}' } }],
+})
+
+const toolResult = (id: string): ToolMessage => ({
+	role: 'tool',
+	content: 'ok',
+	timestamp: 1,
+	toolCallId: id,
+})
+
+function reduction(
+	messages: readonly Message[],
+	over?: Partial<ContextReduction>,
+): ContextReduction {
+	return {
+		messages,
+		reason: 'threshold',
+		estimatedTokens: 1_000,
+		contextWindowTokens: 2_000,
+		model: 'mock-model',
+		keepRecentMessages: 4,
+		...over,
+	}
+}
+
+describe('the sliding window keeps recent turns and drops the rest', () => {
+	it('keeps the configured tail', async () => {
+		const reduce = createSlidingWindowReducer()
+		const messages = [sys('prompt'), ...Array.from({ length: 10 }, (_, i) => user(`m${i}`))]
+
+		const next = await reduce(reduction(messages))
+
+		expect(next).toBeDefined()
+		expect(next?.length).toBe(5) // the system floor plus keepRecentMessages
+		expect(next?.at(-1)).toBe(messages.at(-1))
+	})
+
+	it('cuts harder when the provider already rejected the prompt', async () => {
+		const reduce = createSlidingWindowReducer()
+		const messages = [sys('prompt'), ...Array.from({ length: 10 }, (_, i) => user(`m${i}`))]
+
+		const threshold = await reduce(reduction(messages))
+		const overflow = await reduce(reduction(messages, { reason: 'overflow' }))
+
+		// An overflow means the ordinary window was ALREADY too big. Cutting to
+		// the same size would shed nothing and the caller would retry an
+		// identical prompt.
+		expect(overflow?.length).toBeLessThan(threshold?.length ?? 0)
+	})
+
+	it('summarizes nothing — every survivor is the original object', async () => {
+		const reduce = createSlidingWindowReducer()
+		const messages = [sys('prompt'), ...Array.from({ length: 8 }, (_, i) => user(`m${i}`))]
+
+		const next = await reduce(reduction(messages))
+
+		for (const message of next ?? []) expect(messages).toContain(message)
+	})
+})
+
+describe('the three invariants a shorter history has to keep', () => {
+	it('never drops the leading system floor', async () => {
+		const reduce = createSlidingWindowReducer()
+		const messages = [
+			sys('prompt'),
+			sys('working memory'),
+			...Array.from({ length: 8 }, (_, i) => user(`m${i}`)),
+		]
+
+		const next = await reduce(reduction(messages))
+
+		expect(next?.[0]).toBe(messages[0])
+		expect(next?.[1]).toBe(messages[1])
+	})
+
+	it('does not split a tool_use from its tool_result', async () => {
+		const reduce = createSlidingWindowReducer()
+		// The naive cut at length-3 lands between the assistant call and its
+		// result, which is a provider 400 on the next turn.
+		const messages = [
+			sys('prompt'),
+			user('go'),
+			asst('thinking'),
+			callsTool('c1'),
+			toolResult('c1'),
+			user('again'),
+			asst('done'),
+			user('more'),
+		]
+
+		const next = await reduce(reduction(messages, { keepRecentMessages: 5 }))
+
+		const kept = new Set(next ?? [])
+		// Cutting at 3 would keep the call and its result together; cutting at
+		// 4 would orphan the result. The pair is never split either way.
+		expect(kept.has(messages[4] as Message)).toBe(kept.has(messages[3] as Message))
+	})
+
+	it('takes a cut above the requested window when nothing below is safe', async () => {
+		const reduce = createSlidingWindowReducer()
+		// A multi-step turn: the user is silent while the agent works, so every
+		// boundary inside the recent window opens on an assistant or tool
+		// message. A backwards-only search would decline here — exactly when
+		// the history is longest.
+		const messages = [
+			sys('prompt'),
+			user('go'),
+			callsTool('c1'),
+			toolResult('c1'),
+			asst('working'),
+			callsTool('c2'),
+			toolResult('c2'),
+			// The only user turn after the opening one, and it sits ABOVE the
+			// requested cut — so every candidate below opens on an assistant or
+			// tool message and the backwards search comes back empty.
+			user('next'),
+			callsTool('c3'),
+			toolResult('c3'),
+		]
+
+		const next = await reduce(reduction(messages, { keepRecentMessages: 5 }))
+
+		expect(next).toBeDefined()
+		expect(next?.length).toBeLessThan(messages.length)
+		// It kept LESS than asked rather than declining, and what it kept opens
+		// on a user turn.
+		expect(next?.[1]?.role).toBe('user')
+	})
+
+	it('keeps a pinned turn from the middle of the conversation', async () => {
+		const reduce = createSlidingWindowReducer()
+		const pinned: Message = { ...user('the account id is X'), retain: true }
+		const messages = [
+			sys('prompt'),
+			user('m0'),
+			pinned,
+			...Array.from({ length: 8 }, (_, i) => user(`m${i + 1}`)),
+		]
+
+		const next = await reduce(reduction(messages))
+
+		// Recency is not the only thing that matters, which is what `retain`
+		// exists to say.
+		expect(next).toContain(pinned)
+		expect(next).not.toContain(messages[1])
+	})
+})
+
+describe('refusing beats a reduction that would break the next turn', () => {
+	it('declines when there is nothing but the system floor to cut', async () => {
+		const reduce = createSlidingWindowReducer()
+
+		expect(await reduce(reduction([sys('prompt'), user('go')]))).toBeUndefined()
+	})
+
+	it('declines when every candidate cut splits one assistant fan-out', async () => {
+		const reduce = createSlidingWindowReducer()
+		// Six results answering one call: no cut inside the block is safe, and
+		// the condition clears itself on the next assistant message.
+		const messages = [
+			sys('prompt'),
+			user('go'),
+			{
+				role: 'assistant',
+				content: null,
+				timestamp: 1,
+				toolCalls: Array.from({ length: 6 }, (_, i) => ({
+					id: `c${i}`,
+					type: 'function' as const,
+					function: { name: 'echo', arguments: '{}' },
+				})),
+			} as AssistantMessage,
+			...Array.from({ length: 6 }, (_, i) => toolResult(`c${i}`)),
+		]
+
+		expect(await reduce(reduction(messages, { keepRecentMessages: 2 }))).toBeUndefined()
+	})
+
+	it('declines rather than reporting a reduction that removed nothing', async () => {
+		const reduce = createSlidingWindowReducer()
+		// Every non-system message is pinned, so the survivor set is the input.
+		const messages = [
+			sys('prompt'),
+			...Array.from({ length: 8 }, (_, i) => ({ ...user(`m${i}`), retain: true })),
+		]
+
+		// Saying "reduced" here would have the overflow path retry an identical
+		// prompt and burn a model call to be told the same thing.
+		expect(await reduce(reduction(messages))).toBeUndefined()
+	})
+})
+
+describe('the knob a caller reaches for', () => {
+	it('lets an explicit window override the run config', async () => {
+		const reduce = createSlidingWindowReducer({ keepRecentMessages: 2 })
+		const messages = [sys('prompt'), ...Array.from({ length: 10 }, (_, i) => user(`m${i}`))]
+
+		const next = await reduce(reduction(messages, { keepRecentMessages: 8 }))
+
+		expect(next?.length).toBe(3)
+	})
+
+	it('is a plain function, so a host can wrap one', async () => {
+		const inner = createSlidingWindowReducer()
+		const seen = vi.fn()
+		const reduce = async (input: ContextReduction) => {
+			seen(input.reason)
+			return inner(input)
+		}
+		const messages = [sys('prompt'), ...Array.from({ length: 8 }, (_, i) => user(`m${i}`))]
+
+		await reduce(reduction(messages, { reason: 'overflow' }))
+
+		expect(seen).toHaveBeenCalledWith('overflow')
+	})
+})

package/src/compaction/factory.ts

@@ -20,6 +20,13 @@ import type { CompactionStrategy } from './types.js'
  * const trimmed = manager.applyManagement(messages)
  * ```
  */
+/**
+ * @deprecated Nothing calls this. Select a strategy with
+ * `compactionConfig.strategy`, or pass a `contextReducer` to `query()`.
+ *
+ * The factory produced managers the runtime had no seam to drive, so its
+ * return value was always dropped on the floor. See {@link ConversationManager}.
+ */
 export function createConversationManager(
 	strategy: CompactionStrategy,
 	config: CompactionConfig,

package/src/compaction/index.ts

@@ -11,6 +11,14 @@ export type { DanglingResult } from './dangling.js'
 
 export type { ConversationManager } from './interface.js'
 
+export { createSlidingWindowReducer } from './reducer.js'
+export type {
+	ContextReducer,
+	ContextReduction,
+	ContextReductionReason,
+	SlidingWindowOptions,
+} from './reducer.js'
+
 export { WorkingStateManager } from './manager.js'
 
 export { serializeState } from './serializer.js'

package/src/compaction/interface.ts

@@ -7,6 +7,19 @@ import type { Message } from '../types/message/index.js'
  * A manager applies two strategies:
  * 1. **Routine management** (applyManagement): Called after each iteration to proactively optimize context.
  * 2. **Overflow reduction** (reduceContext): Called when the LLM reports context window exceeded.
+ *
+ * @deprecated Use {@link ContextReducer}, which the runtime actually drives.
+ *
+ * This interface cannot be implemented correctly. `reduceContext` is
+ * documented as reducing the history, but it takes `Message[]` and returns
+ * `boolean` — the only way to honour the contract is to mutate the argument
+ * in place, and neither shipped implementation does. Both build a shorter
+ * array locally, discard it, and return `true`. Nothing in the runtime ever
+ * called any of it, which is why an unfulfillable contract survived.
+ *
+ * `ContextReducer` returns the new history, may be async so a reducer can
+ * call a model, and is told whether it was asked speculatively or after the
+ * provider rejected the prompt. Kept exported until the next major.
  */
 export interface ConversationManager {
 	/** Unique name for this manager (e.g., 'structured', 'sliding-window', 'disabled') */

package/src/compaction/managers/null.ts

@@ -5,6 +5,9 @@ import type { ConversationManager } from '../interface.js'
  * No-op conversation manager implementation.
  * Never modifies messages, useful for testing or when context management is disabled.
  */
+/**
+ * @deprecated Use `strategy: 'disabled'`, which the runtime reads.
+ */
 export class NullManager implements ConversationManager {
 	readonly name = 'null'
 

package/src/compaction/managers/slidingWindow.ts

@@ -20,6 +20,12 @@ export interface SlidingWindowManagerConfig {
  * 2. Use findSafeTrimIndex to ensure tool call/result pairs remain atomic
  * 3. applyManagement runs proactively each iteration; reduceContext on overflow
  */
+/**
+ * @deprecated Use `createSlidingWindowReducer()`, or `strategy: 'sliding-window'`.
+ *
+ * Never reachable through the runtime, and `reduceContext` here computes a
+ * trim index and returns a boolean without trimming anything.
+ */
 export class SlidingWindowManager implements ConversationManager {
 	readonly name = 'sliding-window'
 	private readonly keepRecentMessages: number

package/src/compaction/managers/structured.ts

@@ -22,6 +22,16 @@ import { serializeState } from '../serializer.js'
  *
  * Provides maximum context preservation but more computational overhead.
  */
+/**
+ * @deprecated Not the structured strategy. `strategy: 'structured'` runs the
+ * live path in `runtime/query/iteration/phases/compaction.ts`, which this
+ * class predates and does not share code with.
+ *
+ * What is here is a weaker parallel copy: no LLM-verified summary, no stale
+ * tool-result clearing, no retention pins, no events — and a `reduceContext`
+ * that builds a shorter history into a local array and then returns a
+ * boolean, discarding it.
+ */
 export class StructuredCompactionManager implements ConversationManager {
 	readonly name = 'structured'
 	private readonly config: CompactionConfig