@namzu/sdk 3.3.0 → 5.0.0

package/src/provider/__tests__/thinking-support.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+
+import { assertThinkingUnsupported } from '../thinking-support.js'
+
+/**
+ * `thinking` sits on `ChatCompletionParams`, so every driver accepts it. Six
+ * of the seven in this repo did not implement it, and five of those six simply
+ * dropped the field: the caller got an ordinary completion with an empty
+ * `reasoning` array, indistinguishable from a model that chose not to reason.
+ *
+ * One driver already refused instead, with the reasoning written out. The rule
+ * was decided once and applied once — so it moved here, where a new driver
+ * inherits it rather than re-deciding it.
+ */
+describe('a driver that cannot think says so', () => {
+	it('refuses a manual thinking request', () => {
+		expect(() =>
+			assertThinkingUnsupported('TestProvider', { thinking: { type: 'enabled' } }),
+		).toThrow(/TestProvider does not implement thinking/)
+	})
+
+	it('refuses an adaptive one too', () => {
+		// Both are a request to think. Refusing one and dropping the other
+		// would leave exactly the silence this exists to remove.
+		expect(() =>
+			assertThinkingUnsupported('TestProvider', { thinking: { type: 'adaptive' } }),
+		).toThrow(/does not implement thinking/)
+	})
+
+	it('names the driver, not just the problem', () => {
+		// In a multi-provider setup this is the difference between a bug
+		// report about the model and a one-line config fix.
+		expect(() =>
+			assertThinkingUnsupported('BedrockProvider', { thinking: { type: 'adaptive' } }),
+		).toThrow(/BedrockProvider/)
+	})
+
+	it('says what silence would have looked like', () => {
+		let message = ''
+		try {
+			assertThinkingUnsupported('TestProvider', { thinking: { type: 'enabled' } })
+		} catch (err) {
+			message = (err as Error).message
+		}
+		expect(message).toContain('empty reasoning list')
+		expect(message).toContain('Drop `thinking`')
+	})
+
+	it('honours an explicit disable as a no-op', () => {
+		// A config shared across providers that says "do not think" should not
+		// fail on the ones that were never going to.
+		expect(() =>
+			assertThinkingUnsupported('TestProvider', { thinking: { type: 'disabled' } }),
+		).not.toThrow()
+	})
+
+	it('does nothing when the caller said nothing', () => {
+		expect(() => assertThinkingUnsupported('TestProvider', {})).not.toThrow()
+	})
+})

package/src/provider/thinking-support.ts

@@ -0,0 +1,37 @@
+import type { ThinkingConfig } from '../types/provider/index.js'
+
+/**
+ * Refuse a thinking request a driver does not implement.
+ *
+ * The failure this prevents is silence. `thinking` sits on
+ * `ChatCompletionParams`, so every driver accepts it; a driver that does not
+ * implement it drops the field and returns an ordinary completion with an
+ * empty `reasoning` array. The caller cannot tell that apart from a model that
+ * simply chose not to reason — the request looks honoured and the answer looks
+ * like an answer.
+ *
+ * Refusing names the driver instead, which is the difference between a bug
+ * report about the model and a one-line configuration fix.
+ *
+ * **Turning thinking OFF is honoured as a no-op**, because that is the state a
+ * driver without thinking is already in. A config shared across providers that
+ * says `{type: 'disabled'}` should not fail on the ones that were never going
+ * to think.
+ *
+ * This lived as a private copy inside one driver while five others dropped the
+ * field silently. It is here so a new driver inherits the rule instead of
+ * re-deciding it.
+ *
+ * @param driverName Named in the error, so the reader knows which provider in
+ *   a multi-provider setup refused.
+ */
+export function assertThinkingUnsupported(
+	driverName: string,
+	params: { thinking?: ThinkingConfig },
+): void {
+	const type = params.thinking?.type
+	if (type !== 'enabled' && type !== 'adaptive') return
+	throw new Error(
+		`${driverName} does not implement thinking. Silently ignoring the request would return an ordinary completion with an empty reasoning list, which reads as "the model did not reason" rather than "this driver cannot ask it to". Drop \`thinking\`, or use a driver that implements it.`,
+	)
+}

package/src/public-runtime.ts

@@ -67,7 +67,14 @@ export { extractFinalResponse } from './utils/conversation.js'
 // ─── router, runtime, run ────────────────────────────────────────────────
 
 export { resolveTaskModel } from './router/task-router.js'
+// Every driver accepts `thinking`; one that does not implement it must
+// refuse rather than drop it. Shared so a new driver inherits the rule.
+export { assertThinkingUnsupported } from './provider/thinking-support.js'
 export { drainQuery, query } from './runtime/query/index.js'
+// Mid-run guidance. A host holds the channel and the loop drains it at the
+// tool-result boundary; see the module for why that is the only legal slot.
+export { SteeringBinding, attachSteering, formatSteeringNote } from './runtime/query/steering.js'
+export type { SteeringChannel } from './runtime/query/steering.js'
 export { createMockBidiProvider, startBidiRun } from './runtime/bidi/index.js'
 export { ContextCache } from './runtime/query/context-cache.js'
 export {
@@ -135,6 +142,9 @@ export {
 	PipelineAgent,
 	ReactiveAgent,
 	RouterAgent,
+	// The short path: provider + model + prompt. Assembles the identity and
+	// budgets `drainQuery` requires and hands the generated identity back.
+	runAgent,
 	SupervisorAgent,
 } from './agents/index.js'
 
@@ -158,6 +168,7 @@ export {
 	PluginRegistry,
 	Registry,
 	ToolCatalog,
+	ToolNameCollisionError,
 	ToolRegistry,
 	createToolCatalogFromRegistry,
 	loadingFromAvailability,

package/src/public-tools.ts

@@ -12,6 +12,10 @@
 // ─── Tool definition primitive ───────────────────────────────────────────
 
 export { defineTool } from './tools/defineTool.js'
+// A host that surfaces its own untrusted content to a model needs the same
+// framing the kernel applies to connector prompts and delegated results.
+export { neutralizeEnvelopeDelimiter, wrapUntrusted } from './tools/untrusted-envelope.js'
+export type { UntrustedEnvelope } from './tools/untrusted-envelope.js'
 
 // ─── Built-in tools ──────────────────────────────────────────────────────
 

package/src/public-types.ts

@@ -99,7 +99,13 @@ export type { ContextCacheConfig, PromptCacheInput } from './runtime/query/conte
 
 export type { LimitCheckResult, LimitCheckerState, RunReporter } from './run/index.js'
 
-export type { DefineAgentOptions, Disposable } from './agents/index.js'
+export type {
+	AgentIdentity,
+	DefineAgentOptions,
+	Disposable,
+	RunAgentOptions,
+	RunAgentResult,
+} from './agents/index.js'
 
 export type {
 	ActivityEvent,

package/src/registry/index.ts

@@ -2,7 +2,7 @@ export { Registry } from './Registry.js'
 export { ManagedRegistry } from './ManagedRegistry.js'
 export type { ManagedRegistryConfig } from './ManagedRegistry.js'
 
-export { ToolRegistry } from './tool/execute.js'
+export { ToolNameCollisionError, ToolRegistry } from './tool/execute.js'
 export type { ToolExecutionResult } from './tool/execute.js'
 export {
 	ToolCatalog,

package/src/registry/tool/execute.ts

@@ -83,6 +83,29 @@ export function assertToolName(name: string): void {
 	)
 }
 
+/**
+ * Two sources contributed the same tool name and neither may take it.
+ *
+ * Named, and carrying the name, for the reason `DuplicateProviderError` is:
+ * a host that wants to handle this — fall back to its own tool, log and
+ * continue, surface it in a config error — has to be able to catch it
+ * narrowly rather than match on message text. It also names both remedies,
+ * because a hard collision policy without a way to decline would make
+ * shadowing-by-name the only way to say "I do not want this tool", which is
+ * precisely what now throws.
+ */
+export class ToolNameCollisionError extends Error {
+	readonly toolName: string
+
+	constructor(toolName: string, context: string) {
+		super(
+			`Tool name "${toolName}" is already registered by this host, and ${context} will not replace it. Rename the host tool, or decline the one being mounted with runtimeToolOverrides: { "${toolName}": "disabled" }.`,
+		)
+		this.name = 'ToolNameCollisionError'
+		this.toolName = toolName
+	}
+}
+
 /**
  * Append a tool's declared return shape to its description.
  *

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
+}