@namzu/sdk 4.0.0 → 5.0.0

package/src/runtime/query/__tests__/steering-reaches-the-model.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { MockLLMProvider, registerMock } from '../../../provider/index.js'
+import { ToolRegistry } from '../../../registry/index.js'
+import {
+	generateProjectId,
+	generateSessionId,
+	generateTenantId,
+	generateThreadId,
+} from '../../../utils/id.js'
+import { drainQuery } from '../index.js'
+import { SteeringBinding } from '../steering.js'
+
+/**
+ * The unit tests next door prove `attachSteering` builds the right message.
+ * They would all pass with the loop never calling it — which is the exact
+ * shape of defect this repo keeps finding, and the reason this file drives a
+ * real run instead.
+ *
+ * A steer queued while a tool is running must be visible in the messages the
+ * NEXT model call receives, or the channel is another declaration nothing
+ * drives.
+ */
+
+registerMock()
+
+async function runWithSteer(steerDuringTool?: string) {
+	const steering = new SteeringBinding()
+
+	const tools = new ToolRegistry()
+	tools.register({
+		name: 'inspect',
+		description: 'looks at something',
+		inputSchema: z.object({}),
+		execute: async () => {
+			// Queued from inside the tool, which is when a host would type it:
+			// the batch is in flight and there is no legal slot for a user
+			// message until it settles.
+			if (steerDuringTool) steering.steer(steerDuringTool)
+			return { success: true, output: 'inspection done' }
+		},
+	} as never)
+
+	const provider = new MockLLMProvider({
+		turns: [
+			{ toolCalls: [{ id: 'c1', name: 'inspect', rawArguments: '{}' }] },
+			{ text: 'finished' },
+		],
+	})
+
+	await drainQuery({
+		provider,
+		tools,
+		agentId: 'a',
+		agentName: 'A',
+		messages: [{ role: 'user', content: 'go' }],
+		workingDirectory: process.cwd(),
+		runConfig: {
+			model: 'mock-model',
+			tokenBudget: 100_000,
+			timeoutMs: 30_000,
+			maxIterations: 4,
+		},
+		projectId: generateProjectId(),
+		sessionId: generateSessionId(),
+		threadId: generateThreadId(),
+		tenantId: generateTenantId(),
+		steering,
+	} as never)
+
+	return { provider, steering }
+}
+
+/** Every message body the model saw on its Nth call, flattened to text. */
+function bodiesOn(provider: MockLLMProvider, call: number): string {
+	return (provider.requests[call]?.messages ?? [])
+		.map((m) => (typeof m.content === 'string' ? m.content : JSON.stringify(m.content)))
+		.join('\n')
+}
+
+describe('guidance queued during a tool batch reaches the model', () => {
+	it('is in the messages of the next model call', async () => {
+		const { provider } = await runWithSteer('actually, check the tests as well')
+
+		expect(provider.requests.length).toBeGreaterThan(1)
+		expect(bodiesOn(provider, 1)).toContain('actually, check the tests as well')
+	})
+
+	it('rides on the tool result rather than as a separate turn', async () => {
+		const { provider } = await runWithSteer('check the tests as well')
+
+		const second = provider.requests[1]?.messages ?? []
+		const carrier = second.find((m) =>
+			typeof m.content === 'string' ? m.content.includes('check the tests as well') : false,
+		)
+
+		// The slot matters: a `tool_use` block must be answered by a
+		// `tool_result` with the same id, so a user turn wedged in here is
+		// rejected by the provider outright.
+		expect(carrier?.role).toBe('tool')
+		expect(String(carrier?.content)).toContain('inspection done')
+	})
+
+	it('is delivered once and leaves the channel empty', async () => {
+		const { steering } = await runWithSteer('one time only')
+
+		expect(steering.pending).toBe(false)
+	})
+
+	it('changes nothing when nobody steers', async () => {
+		const { provider } = await runWithSteer()
+
+		expect(bodiesOn(provider, 1)).toContain('inspection done')
+		expect(bodiesOn(provider, 1)).not.toContain('operator')
+	})
+})

package/src/runtime/query/__tests__/steering.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest'
+
+import type { Message } from '../../../types/message/index.js'
+import { SteeringBinding, attachSteering, formatSteeringNote } from '../steering.js'
+
+/**
+ * `AgentManager.queueMessage` / `drainMessages` have existed for a while and
+ * nothing in the iteration loop ever read them — the type says so outright.
+ * So a host watching a run go wrong could cancel it, throwing away every tool
+ * result already paid for, or reject through the review gate, which only
+ * works when a call happens to be pending approval and says "no" when the
+ * host meant "yes, but read this first".
+ *
+ * The delivery is the interesting part. A `tool_use` block must be answered
+ * by a `tool_result` with the same id, so there is no legal slot for a user
+ * message mid-batch; this codebase had already worked that out for denials,
+ * which carry their reason inside the `tool_result` precisely because that is
+ * where the model looks.
+ */
+
+const toolMessage = (id: string, content: string): Message =>
+	({ role: 'tool', content, toolCallId: id, timestamp: 1 }) as unknown as Message
+
+const assistantMessage = (content: string): Message =>
+	({ role: 'assistant', content, timestamp: 1 }) as unknown as Message
+
+describe('steering a running turn', () => {
+	it('appends the guidance to the last tool result', () => {
+		const channel = new SteeringBinding()
+		channel.steer('check the tests too')
+
+		const out = attachSteering([toolMessage('a', 'first'), toolMessage('b', 'second')], channel)
+
+		expect(out[0]?.content).toBe('first')
+		// The LAST one: it is the final thing the model reads before deciding
+		// what to do next, where the first would be buried under every later
+		// result.
+		expect(out[1]?.content).toContain('second')
+		expect(out[1]?.content).toContain('check the tests too')
+	})
+
+	it('labels the guidance as the operator speaking, not the tool', () => {
+		const channel = new SteeringBinding()
+		channel.steer('stop and ask me first')
+
+		const out = attachSteering([toolMessage('a', 'output')], channel)
+
+		// Unlabelled it would read as something `bash` said.
+		expect(out[0]?.content).toContain('[Message from the operator')
+	})
+
+	it('accumulates repeated calls in order rather than replacing', () => {
+		const channel = new SteeringBinding()
+		channel.steer('first correction')
+		channel.steer('second correction')
+
+		const out = attachSteering([toolMessage('a', 'output')], channel)
+
+		const text = String(out[0]?.content)
+		expect(text.indexOf('first correction')).toBeLessThan(text.indexOf('second correction'))
+	})
+
+	it('ignores empty and whitespace-only guidance', () => {
+		const channel = new SteeringBinding()
+		channel.steer('   ')
+		channel.steer('')
+
+		expect(channel.pending).toBe(false)
+		expect(attachSteering([toolMessage('a', 'output')], channel)[0]?.content).toBe('output')
+	})
+
+	it('drains the channel, so guidance is delivered once', () => {
+		const channel = new SteeringBinding()
+		channel.steer('once')
+
+		attachSteering([toolMessage('a', 'output')], channel)
+		const second = attachSteering([toolMessage('b', 'later')], channel)
+
+		expect(channel.pending).toBe(false)
+		expect(second[0]?.content).toBe('later')
+	})
+
+	it('keeps guidance queued when the batch has no tool result to carry it', () => {
+		const channel = new SteeringBinding()
+		channel.steer('for the next turn')
+
+		const out = attachSteering([assistantMessage('just text')], channel)
+
+		expect(out[0]?.content).toBe('just text')
+		// Not dropped. A turn that called no tools has nothing in flight, so
+		// the guidance belongs to the next one.
+		expect(channel.pending).toBe(true)
+	})
+
+	it('leaves non-text tool content alone and re-queues rather than corrupting it', () => {
+		const channel = new SteeringBinding()
+		channel.steer('guidance')
+		const structured = {
+			role: 'tool',
+			content: [{ type: 'image', source: 'x' }],
+			toolCallId: 'a',
+			timestamp: 1,
+		} as unknown as Message
+
+		const out = attachSteering([structured], channel)
+
+		expect(out[0]?.content).toEqual([{ type: 'image', source: 'x' }])
+		expect(channel.pending).toBe(true)
+	})
+
+	it('does nothing at all without a channel', () => {
+		const messages = [toolMessage('a', 'output')]
+
+		expect(attachSteering(messages, undefined)).toBe(messages)
+	})
+
+	it('formats a note that names who is speaking', () => {
+		expect(formatSteeringNote('hello')).toContain('operator')
+		expect(formatSteeringNote('hello')).toContain('hello')
+	})
+})

package/src/runtime/query/index.ts

@@ -98,6 +98,7 @@ import {
 	recoverCompletedCalls,
 	unansweredToolCalls,
 } from './resume-pending.js'
+import type { SteeringChannel } from './steering.js'
 import { ToolGrantSet } from './tool-grants.js'
 import { createToolPause } from './tool-pause.js'
 import { ToolingBootstrap } from './tooling.js'
@@ -151,6 +152,16 @@ export interface QueryParams {
 	 */
 	questionParks?: QuestionParkBinding
 
+	/**
+	 * Channel a host uses to hand guidance to the running turn.
+	 *
+	 * Optional and additive: absent leaves the loop byte-identical. Present,
+	 * anything queued during a tool batch is appended to that batch's last
+	 * tool result — the only slot a provider will accept text in mid-batch,
+	 * and the one the model already reads for tool outcomes.
+	 */
+	steering?: SteeringChannel
+
 	/**
 	 * The registry a re-entered `ask_user_question` reads its answer from.
 	 *
@@ -827,6 +838,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		abortController: ctx.abortController,
 		log: ctx.log,
 		resumeHandler: params.resumeHandler,
+		...(params.steering ? { steering: params.steering } : {}),
 		checkpointMgr,
 		planManager: ctx.planManager,
 		taskGateway: params.taskGateway,

package/src/runtime/query/iteration/phases/context.ts

@@ -32,6 +32,7 @@ import type { CheckpointManager } from '../../checkpoint.js'
 import type { EmitEvent } from '../../events.js'
 import type { ToolExecutor } from '../../executor.js'
 import type { GuardCoordinator } from '../../guard.js'
+import type { SteeringChannel } from '../../steering.js'
 import type { ToolGrantSet } from '../../tool-grants.js'
 
 export interface LaunchedTaskMeta {
@@ -89,6 +90,14 @@ export interface IterationContext {
 	readonly abortController: AbortController
 	readonly log: Logger
 	readonly resumeHandler: ResumeHandler
+
+	/**
+	 * Guidance a host may hand to the turn while it runs.
+	 *
+	 * Absent means the loop behaves exactly as it always has — nothing is
+	 * drained and no tool result is extended.
+	 */
+	readonly steering?: SteeringChannel
 	readonly checkpointMgr: CheckpointManager
 	readonly planManager: PlanManager
 

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -2,6 +2,7 @@ import type { ChatCompletionResponse } from '../../../../types/provider/index.js
 import type { RunEvent } from '../../../../types/run/index.js'
 import type { VerificationGate } from '../../../../verification/index.js'
 import type { ToolCallDenials } from '../../executor.js'
+import { attachSteering } from '../../steering.js'
 import { type IterationContext, awaitDecisionDurably } from './context.js'
 
 interface VerificationAwareContext extends IterationContext {
@@ -82,7 +83,12 @@ export async function* runToolReview(
 		const batch = await ctx.toolExecutor.executeBatch(response, denials)
 		toolMs += Date.now() - startedAt
 		executed = batch.results
-		for (const msg of batch.messages) {
+		// Guidance the host queued while this batch was running rides out on
+		// the last result. This is the only legal slot for it: a `tool_use`
+		// block must be answered by a `tool_result` with the same id, so a
+		// user message wedged between them is rejected by the provider. Same
+		// delivery a denial already uses, without the refusal.
+		for (const msg of attachSteering(batch.messages, ctx.steering)) {
 			ctx.runMgr.pushMessage(msg)
 		}
 	}

package/src/runtime/query/steering.ts

@@ -0,0 +1,135 @@
+import type { Message } from '../../types/message/index.js'
+
+/**
+ * Guidance a host hands to a turn that is already running.
+ *
+ * The gap this closes is narrow and was documented rather than fixed:
+ * `AgentManager` has had `queueMessage` / `drainMessages` for a while, and
+ * nothing in the iteration loop ever read them — the type says so in as many
+ * words. So a host watching a run go the wrong way had two options, and both
+ * are worse than they sound. Cancel and start over throws away every tool
+ * result the run had already paid for. Reject through the review gate only
+ * works if a tool call happens to be pending approval, and it says "no" when
+ * the host wanted to say "yes, but look at this first".
+ *
+ * **Why the text rides on a tool result rather than arriving as a user
+ * message.** A `tool_use` block must be answered by a `tool_result` with the
+ * same id — providers reject a user turn wedged between them — so there is no
+ * legal place to insert a message mid-batch at all. The slot that already
+ * exists is the tool result itself, and this codebase had already worked that
+ * out for a neighbouring case: a denied call carries its reason INSIDE the
+ * `tool_result`, and `executor.ts` notes that this is also what makes a
+ * rejection *steer*, because the model reads it in the slot it already
+ * attends to for tool outcomes. Steering is the same delivery with the
+ * refusal removed.
+ *
+ * **What it deliberately is not.** It does not interrupt. The batch in flight
+ * finishes, and the guidance lands where the model looks next. A host that
+ * wants the current work stopped wants `AbortSignal`, which is a different
+ * question with a different answer — and conflating the two is how "please
+ * also check the tests" ends up killing a half-written file.
+ */
+export interface SteeringChannel {
+	/**
+	 * Queue guidance for the running turn.
+	 *
+	 * Repeated calls before the next drain accumulate in order rather than
+	 * replacing each other: two corrections typed a second apart are two
+	 * things the model should see, and keeping only the last one silently
+	 * discards a host's instruction.
+	 *
+	 * Empty and whitespace-only text is ignored, so a stray keystroke does
+	 * not append a blank line to a tool result.
+	 */
+	steer(text: string): void
+
+	/** Take everything queued, leaving the channel empty. */
+	drain(): string | undefined
+
+	/** True while guidance is queued and undelivered. */
+	readonly pending: boolean
+}
+
+export class SteeringBinding implements SteeringChannel {
+	private queued: string[] = []
+
+	steer(text: string): void {
+		const trimmed = text.trim()
+		if (!trimmed) return
+		this.queued.push(trimmed)
+	}
+
+	drain(): string | undefined {
+		if (this.queued.length === 0) return undefined
+		const joined = this.queued.join('\n')
+		this.queued = []
+		return joined
+	}
+
+	get pending(): boolean {
+		return this.queued.length > 0
+	}
+}
+
+/**
+ * The frame the guidance arrives in.
+ *
+ * Labelled because the model is being handed text from a party other than the
+ * tool whose result it is reading, in that tool's slot. Unlabelled, it reads
+ * as something the tool said — so a steer saying "stop and ask me first" would
+ * look like output from `bash`.
+ *
+ * This is NOT the untrusted-content envelope. The host operating the run is
+ * the one party whose words the agent SHOULD act on; framing them as material
+ * to be worked with rather than followed would inverting the very thing the
+ * host is trying to do. Different party, different frame, on purpose.
+ */
+export function formatSteeringNote(text: string): string {
+	return `\n\n[Message from the operator, received while this tool was running]\n${text}`
+}
+
+/**
+ * Append the guidance to the last tool result in a settled batch.
+ *
+ * The LAST one, so it is the final thing the model reads before deciding what
+ * to do next — appending to the first would bury it under every later result.
+ *
+ * Returns the messages unchanged when there is nothing queued, and when the
+ * batch carries no tool result to attach to. The second case is not a failure
+ * to handle: a turn that called no tools has nothing in flight, so guidance
+ * belongs to the next turn and stays queued for it.
+ */
+export function attachSteering(
+	messages: readonly Message[],
+	channel: SteeringChannel | undefined,
+): readonly Message[] {
+	if (!channel?.pending) return messages
+
+	let lastToolIndex = -1
+	for (let index = messages.length - 1; index >= 0; index--) {
+		if (messages[index]?.role === 'tool') {
+			lastToolIndex = index
+			break
+		}
+	}
+	if (lastToolIndex === -1) return messages
+
+	const guidance = channel.drain()
+	if (guidance === undefined) return messages
+
+	const target = messages[lastToolIndex] as Message
+	// Only text is extended. A tool that answered with structured content —
+	// an image block, say — has a shape the model reads positionally, and
+	// appending a string to it would either be dropped or corrupt the block.
+	// Such a result keeps its content and the note follows it as its own text
+	// part where the shape allows, and otherwise the guidance stays queued
+	// for the next turn rather than being forced into a slot it does not fit.
+	if (typeof target.content !== 'string') {
+		channel.steer(guidance)
+		return messages
+	}
+
+	const next = [...messages]
+	next[lastToolIndex] = { ...target, content: target.content + formatSteeringNote(guidance) }
+	return next
+}

package/src/types/agent/manager.ts

@@ -30,10 +30,17 @@ export interface AgentManagerContract {
 	 *
 	 * Kept, and documented rather than deleted, because `drainMessages` is
 	 * the only way a host can pick these up at all — removing it would take
-	 * away the escape hatch and leave the trap. Two delivery routes that DO
-	 * work today: reject/modify feedback rides inside a tool result, and
-	 * `prepareStep`'s `system` string is appended to the next model call
-	 * from a hook that sees live history.
+	 * away the escape hatch and leave the trap.
+	 *
+	 * **For mid-run guidance, use `SteeringChannel` instead.** That is the
+	 * delivery handshake this queue was missing: text queued on it is
+	 * appended to the running batch's last `tool_result`, which is the only
+	 * slot a provider accepts mid-batch, and the loop drains it. Pass one as
+	 * `steering` on `drainQuery` params or on `SupervisorAgentConfig`.
+	 *
+	 * Two other routes also work: reject/modify feedback rides inside a tool
+	 * result, and `prepareStep`'s `system` string is appended to the next
+	 * model call from a hook that sees live history.
 	 */
 	continueTask(taskId: TaskId, message: string): Promise<void>
 	/** See {@link continueTask} — queued, not delivered. */

package/src/types/agent/supervisor.ts

@@ -1,4 +1,5 @@
 import type { CompactionConfig } from '../../config/runtime.js'
+import type { SteeringChannel } from '../../runtime/query/steering.js'
 import type { AdvisoryConfig } from '../advisory/index.js'
 import type { ResumeHandler } from '../hitl/index.js'
 import type { LLMProvider } from '../provider/index.js'
@@ -63,6 +64,15 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 */
 	resumeHandler?: ResumeHandler
 
+	/**
+	 * Channel a host uses to hand guidance to the supervisor's running turn.
+	 *
+	 * Present here for the same reason `resumeHandler` is: a capability the
+	 * kernel honours in `drainQuery` and not on the surface hosts actually
+	 * construct is a capability nobody can reach.
+	 */
+	steering?: SteeringChannel
+
 	/**
 	 * Optional declarative gate evaluated before tool execution. When
 	 * the gate marks all calls in a batch as `allow`, they execute

package/src/types/common/index.ts

@@ -10,6 +10,19 @@ export interface TokenUsage {
 	totalTokens: number
 	cachedTokens: number
 	cacheWriteTokens: number
+
+	/**
+	 * Output tokens the model spent on internal reasoning.
+	 *
+	 * A SUBSET of `completionTokens`, not an addition to it — reasoning is
+	 * billed as output, so adding these to a total would double-count. Present
+	 * so a caller can see what share of a turn went to thinking, which is the
+	 * question budgeting and cost attribution actually ask.
+	 *
+	 * Optional because most drivers do not report it. Absent means unknown,
+	 * not zero.
+	 */
+	reasoningTokens?: number
 }
 
 export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage): TokenUsage {
@@ -19,6 +32,13 @@ export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage):
 		totalTokens: current.totalTokens + addition.totalTokens,
 		cachedTokens: current.cachedTokens + addition.cachedTokens,
 		cacheWriteTokens: current.cacheWriteTokens + addition.cacheWriteTokens,
+		// Summed only when at least one side reported it. Coercing absent to
+		// zero would turn 'this driver does not tell us' into 'it spent none',
+		// and a run mixing a reporting driver with a silent one would read as
+		// though the silent turns did no thinking.
+		...(current.reasoningTokens !== undefined || addition.reasoningTokens !== undefined
+			? { reasoningTokens: (current.reasoningTokens ?? 0) + (addition.reasoningTokens ?? 0) }
+			: {}),
 	}
 }
 

package/src/types/provider/chat.ts

@@ -76,19 +76,75 @@ export interface ChatCompletionParams {
 	 * Drivers that do not support it ignore the field.
 	 */
 	thinking?: ThinkingConfig
+
+	/**
+	 * How much work to put into the response. See {@link ReasoningEffort}.
+	 *
+	 * Drivers that do not support it ignore the field.
+	 */
+	effort?: ReasoningEffort
 }
 
 export interface ThinkingConfig {
-	type: 'enabled' | 'disabled'
-	/** Token allowance for the thinking pass. */
+	/**
+	 * Which thinking mode to ask for.
+	 *
+	 * `'adaptive'` lets the model decide whether and how deeply to think per
+	 * request; depth is steered by {@link ChatCompletionParams.effort} rather
+	 * than a token budget. `'enabled'` is the older manual mode, where
+	 * {@link budgetTokens} fixes the depth and the model thinks on every
+	 * request.
+	 *
+	 * **These are not interchangeable, and a driver must not guess.** Vendors
+	 * reject the wrong one for a given model outright rather than degrading:
+	 * newer models refuse `'enabled'`, older ones refuse `'adaptive'`, and
+	 * some refuse `'disabled'` because they cannot stop thinking at all. A
+	 * driver that sends a mode the model does not accept produces a failed
+	 * request, not a worse answer — which is why this is a declared intent
+	 * that each driver resolves against the model it is about to call.
+	 */
+	type: 'adaptive' | 'enabled' | 'disabled'
+
+	/**
+	 * Token allowance for the thinking pass. Manual mode only — the adaptive
+	 * mode has no budget, and depth is set by `effort`.
+	 */
 	budgetTokens?: number
+
 	/**
-	 * Whether the provider should return full thinking text or a summary.
-	 * Purely a request hint; the runtime stores whatever comes back.
+	 * Whether the thinking text comes back or only its signature.
+	 *
+	 * `'omitted'` returns the blocks with an empty body and a signature, which
+	 * is enough to replay them on the next turn (see `replayReasoning`) while
+	 * keeping the text out of the response. `'summarized'` returns a summary
+	 * of the reasoning.
+	 *
+	 * Worth setting explicitly. This defaults to `'omitted'` on newer models,
+	 * so a caller that wants to show reasoning and does not ask for it gets
+	 * thinking blocks whose text is empty and no indication why.
+	 *
+	 * The values were `'full' | 'summarized'` here, and `'full'` was never a
+	 * value any vendor accepted — a declared option that could only ever have
+	 * been rejected, next to a real one that was missing.
 	 */
-	display?: 'full' | 'summarized'
+	display?: 'summarized' | 'omitted'
 }
 
+/**
+ * How much work the model should put into a response.
+ *
+ * A sibling of {@link ChatCompletionParams.thinking}, not a field inside it,
+ * because it is not exclusively a thinking control: it shapes the whole
+ * response, and at least one manual-mode model accepts it alongside a token
+ * budget, where effort shapes the answer and the budget sets thinking depth.
+ * Nesting it under `thinking` would have made that combination unsayable.
+ *
+ * In adaptive mode it is the primary depth lever — low effort may skip
+ * thinking entirely on easy input. In manual mode `budgetTokens` sets depth
+ * and effort does not move it.
+ */
+export type ReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+
 export interface ChatCompletionResponse {
 	id: string
 	model: string

package/src/types/provider/index.ts

@@ -4,6 +4,7 @@ export type {
 	CacheControl,
 	ChatCompletionParams,
 	ChatCompletionResponse,
+	ReasoningEffort,
 	ThinkingConfig,
 } from './chat.js'
 export type { StreamChunk } from './stream.js'