@namzu/sdk 4.0.0 → 5.1.0

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/errors.ts

@@ -362,6 +362,62 @@ function codeFromStructure(err: unknown): ProviderErrorCode | undefined {
  *
  * Aborts are passed through untouched — see {@link isAbortError}.
  */
+/**
+ * Every `ProviderErrorKind`, mapped to what the runtime acts on.
+ *
+ * Read structurally rather than with `instanceof`: a driver in one package
+ * throws this and the runtime in another reads it, and two copies of the SDK
+ * in one process make `instanceof` unreliable — the same reason
+ * `isProviderRequestError` exists.
+ *
+ * `retryable` here is about whether resending the SAME request could succeed.
+ * `context_overflow` is correctly false — an identical prompt overflows
+ * identically — and it maps to `context_length_exceeded` so the loop can reach
+ * for compaction, which is a different remedy than a retry.
+ */
+const KIND_TO_CODE: Readonly<Record<string, { code: ProviderErrorCode; retryable: boolean }>> = {
+	throttle: { code: 'rate_limit', retryable: true },
+	network: { code: 'network', retryable: true },
+	server: { code: 'server_error', retryable: true },
+	auth: { code: 'auth', retryable: false },
+	context_overflow: { code: 'context_length_exceeded', retryable: false },
+	bad_request: { code: 'invalid_request', retryable: false },
+}
+
+function classifyFromProviderRequestError(
+	err: unknown,
+	providerId: string | undefined,
+	now: number,
+): ProviderError | undefined {
+	if (!(err instanceof Error) || err.name !== 'ProviderRequestError') return undefined
+	const candidate = err as Error & {
+		kind?: unknown
+		providerId?: unknown
+		status?: unknown
+		retryAfterMs?: unknown
+	}
+	if (typeof candidate.kind !== 'string') return undefined
+	const mapped = KIND_TO_CODE[candidate.kind]
+	if (!mapped) return undefined
+
+	const retryAfterMs =
+		typeof candidate.retryAfterMs === 'number' ? candidate.retryAfterMs : readRetryAfterMs(err, now)
+
+	return new ProviderError({
+		code: mapped.code,
+		message: err.message,
+		retryable: mapped.retryable,
+		cause: err,
+		...(typeof candidate.providerId === 'string'
+			? { providerId: candidate.providerId }
+			: providerId !== undefined
+				? { providerId }
+				: {}),
+		...(typeof candidate.status === 'number' ? { status: candidate.status } : {}),
+		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+	})
+}
+
 export function classifyProviderError(
 	err: unknown,
 	providerId?: string,
@@ -369,6 +425,21 @@ export function classifyProviderError(
 ): ProviderError {
 	if (isProviderError(err)) return err
 
+	// A driver that already classified its own failure is read FIRST, and by
+	// its `kind` — the field it set on purpose.
+	//
+	// Without this the classifier fell through to the status heuristics, where
+	// a `ProviderRequestError` carrying `kind: 'context_overflow'` and a 400
+	// became `invalid_request`, non-retryable. Three of the six kinds landed
+	// wrong that way, and the consequences were not cosmetic: the loop's
+	// overflow branch tests for `context_length_exceeded`, so compaction relief
+	// — the one provider failure this kernel can actually do something about —
+	// was unreachable for exactly the drivers that had diagnosed it correctly.
+	// A driver that classified its own error came out worse than one that did
+	// not, which is the opposite of the incentive the type was created for.
+	const fromKind = classifyFromProviderRequestError(err, providerId, now)
+	if (fromKind) return fromKind
+
 	const message = err instanceof Error ? err.message : String(err)
 	const status = readStatus(err)
 	const errno = readErrnoCode(err)

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'