@namzu/sdk 4.0.0 → 5.0.0

package/dist/types/provider/chat.d.ts

@@ -67,17 +67,69 @@ 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/dist/types/provider/chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../src/types/provider/chat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,MAAM,MAAM,UAAU,GACnB,MAAM,GACN,MAAM,GACN,UAAU,GACV;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAA;AAEnD,MAAM,MAAM,cAAc,GACvB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IACA,IAAI,EAAE,aAAa,CAAA;IACnB,WAAW,EAAE;QACZ,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC/B,MAAM,CAAC,EAAE,OAAO,CAAA;KAChB,CAAA;CACA,CAAA;AAEJ,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,KAAK,CAAC,EAAE,aAAa,EAAE,CAAA;IACvB;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IAEf;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IAEpB,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAE3B,YAAY,CAAC,EAAE,YAAY,CAAA;IAE3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B,cAAc,CAAC,EAAE,cAAc,CAAA;IAE/B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAA;CACzB;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,SAAS,GAAG,UAAU,CAAA;IAC5B,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACtC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QACR,IAAI,EAAE,WAAW,CAAA;QACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;QACtB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;QACtB,mEAAmE;QACnE,SAAS,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;QACrC,kEAAkE;QAClE,SAAS,CAAC,EAAE,SAAS,OAAO,qBAAqB,EAAE,QAAQ,EAAE,CAAA;KAC7D,CAAA;IACD,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,gBAAgB,CAAA;IACjE,KAAK,EAAE,UAAU,CAAA;CACjB"}
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../src/types/provider/chat.ts"],"names":[],"mappings":"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"}

package/dist/types/provider/index.d.ts

@@ -1,4 +1,4 @@
-export type { ToolChoice, ResponseFormat, CacheControl, ChatCompletionParams, ChatCompletionResponse, ThinkingConfig, } from './chat.js';
+export type { ToolChoice, ResponseFormat, CacheControl, ChatCompletionParams, ChatCompletionResponse, ReasoningEffort, ThinkingConfig, } from './chat.js';
 export type { StreamChunk } from './stream.js';
 export type { ModelInfo } from './model.js';
 export type { LLMProvider } from './interface.js';

package/dist/types/provider/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/provider/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,UAAU,EACV,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,GACd,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,YAAY,EACX,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,GACxB,MAAM,YAAY,CAAA;AACnB,YAAY,EACX,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,GACtB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/provider/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,UAAU,EACV,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,cAAc,GACd,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,YAAY,EACX,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,GACxB,MAAM,YAAY,CAAA;AACnB,YAAY,EACX,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,GACtB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "4.0.0",
+  "version": "5.0.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/agents/SupervisorAgent.ts

@@ -300,6 +300,12 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 				// auto-approve. drainQuery falls back to autoApproveHandler
 				// when resumeHandler is omitted (= same behaviour as before).
 				...(config.resumeHandler ? { resumeHandler: config.resumeHandler } : {}),
+				// Forwarded for the same reason the handler is. A capability the
+				// kernel honours in `drainQuery` but that never reaches the
+				// surface a host actually constructs is a capability nobody can
+				// use — which is the shape of defect this file has already been
+				// corrected for twice.
+				...(config.steering ? { steering: config.steering } : {}),
 				...(config.verificationGate ? { verificationGate: config.verificationGate } : {}),
 				...(config.sandboxProvider ? { sandboxProvider: config.sandboxProvider } : {}),
 				// Working-memory / compaction seam (optional; absent => unchanged

package/src/agents/__tests__/run-agent.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { MockLLMProvider, registerMock } from '../../provider/index.js'
+import { ToolRegistry } from '../../registry/index.js'
+import { runAgent } from '../runAgent.js'
+
+/**
+ * `drainQuery` takes eleven required parameters, four of which throw when
+ * missing. That is right for a kernel and wrong for the first thing anybody
+ * writes — and the proof was in this repo, where the eval suites, the test
+ * files and the CLI each hand-assembled the same block.
+ *
+ * These pin the two things a front door has to get right: that the short form
+ * works at all, and that the identity it invents comes back, because a
+ * generated session that a caller cannot recover is a conversation that
+ * silently restarts on turn two.
+ */
+
+registerMock()
+
+describe('running an agent through the front door', () => {
+	it('runs from a provider, a model and a prompt', async () => {
+		const { output, run } = await runAgent({
+			provider: new MockLLMProvider({ turns: [{ text: 'four' }] }),
+			model: 'mock-model',
+			prompt: 'What is 2 + 2?',
+		})
+
+		expect(output).toBe('four')
+		expect(run.status).toBe('completed')
+		expect(run.stopReason).toBe('end_turn')
+	})
+
+	it('hands back the identity it generated, so a second turn can continue', async () => {
+		const first = await runAgent({
+			provider: new MockLLMProvider({ turns: [{ text: 'noted' }] }),
+			model: 'mock-model',
+			prompt: 'My name is Ada.',
+		})
+
+		expect(first.identity.sessionId).toBeTruthy()
+		expect(first.identity.tenantId).toBeTruthy()
+
+		const second = await runAgent({
+			provider: new MockLLMProvider({ turns: [{ text: 'Ada' }] }),
+			model: 'mock-model',
+			prompt: 'What is my name?',
+			...first.identity,
+		})
+
+		// The same session, not a new one that happens to work.
+		expect(second.identity).toEqual(first.identity)
+	})
+
+	it('generates a distinct identity per run when none is given', async () => {
+		const a = await runAgent({
+			provider: new MockLLMProvider({ turns: [{ text: 'a' }] }),
+			model: 'mock-model',
+			prompt: 'x',
+		})
+		const b = await runAgent({
+			provider: new MockLLMProvider({ turns: [{ text: 'b' }] }),
+			model: 'mock-model',
+			prompt: 'y',
+		})
+
+		expect(a.identity.sessionId).not.toBe(b.identity.sessionId)
+	})
+
+	it('carries prior messages when the prompt is a history', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'Ada' }] })
+
+		await runAgent({
+			provider,
+			model: 'mock-model',
+			prompt: [
+				{ role: 'user', content: 'My name is Ada.' },
+				{ role: 'assistant', content: 'Noted.' },
+				{ role: 'user', content: 'What is my name?' },
+			] as never,
+		})
+
+		const sent = provider.requests[0]?.messages.map((m) => m.content) ?? []
+		expect(sent).toContain('My name is Ada.')
+		expect(sent).toContain('What is my name?')
+	})
+
+	it('passes instructions through as the system prompt', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'ok' }] })
+
+		await runAgent({
+			provider,
+			model: 'mock-model',
+			prompt: 'hello',
+			instructions: 'You only answer in haiku.',
+		})
+
+		const system = JSON.stringify(provider.requests[0]?.messages ?? [])
+		expect(system).toContain('You only answer in haiku.')
+	})
+
+	it('runs tools when given a registry', async () => {
+		const tools = new ToolRegistry()
+		let ran = false
+		tools.register({
+			name: 'ping',
+			description: 'pings',
+			inputSchema: z.object({}),
+			category: 'custom',
+			permissions: [],
+			readOnly: true,
+			destructive: false,
+			concurrencySafe: true,
+			execute: async () => {
+				ran = true
+				return { success: true, output: 'pong' }
+			},
+		} as never)
+
+		const { output } = await runAgent({
+			provider: new MockLLMProvider({
+				turns: [{ toolCalls: [{ id: 'c1', name: 'ping', rawArguments: '{}' }] }, { text: 'done' }],
+			}),
+			model: 'mock-model',
+			prompt: 'ping it',
+			tools,
+		})
+
+		expect(ran).toBe(true)
+		expect(output).toBe('done')
+	})
+
+	it('caps a runaway loop on its own default', async () => {
+		const tools = new ToolRegistry()
+		tools.register({
+			name: 'again',
+			description: 'always asks for more',
+			inputSchema: z.object({}),
+			category: 'custom',
+			permissions: [],
+			readOnly: true,
+			destructive: false,
+			concurrencySafe: true,
+			execute: async () => ({ success: true, output: 'and again' }),
+		} as never)
+
+		// The point of a default budget is that a caller who set none is still
+		// protected. Two iterations here rather than the default sixteen, so
+		// the test pins the mechanism without paying for it.
+		const { run } = await runAgent({
+			provider: new MockLLMProvider({
+				turns: Array.from({ length: 10 }, () => ({
+					toolCalls: [{ id: 'c', name: 'again', rawArguments: '{}' }],
+				})),
+			}),
+			model: 'mock-model',
+			prompt: 'loop',
+			tools,
+			maxIterations: 2,
+		})
+
+		expect(run.currentIteration).toBeLessThanOrEqual(2)
+	})
+})

package/src/agents/index.ts

@@ -7,3 +7,5 @@ export { defineAgent } from './defineAgent.js'
 export type { DefineAgentOptions } from './defineAgent.js'
 export { InvocationLock, ConcurrentInvocationError } from './lock.js'
 export type { Disposable } from './lock.js'
+export { runAgent } from './runAgent.js'
+export type { AgentIdentity, RunAgentOptions, RunAgentResult } from './runAgent.js'

package/src/agents/runAgent.ts

@@ -0,0 +1,179 @@
+import { ToolRegistry } from '../registry/tool/execute.js'
+import { drainQuery } from '../runtime/query/index.js'
+import type { ProjectId, SessionId, TenantId, ThreadId } from '../types/ids/index.js'
+import type { Message } from '../types/message/index.js'
+import type { LLMProvider } from '../types/provider/index.js'
+import type { Run, RunEventListener } from '../types/run/index.js'
+import type { ToolRegistryContract } from '../types/tool/index.js'
+import {
+	generateProjectId,
+	generateSessionId,
+	generateTenantId,
+	generateThreadId,
+} from '../utils/id.js'
+
+/**
+ * The session a run belongs to.
+ *
+ * Every field is generated when absent, and the generated values come back on
+ * the result so a second turn can be handed the same ones. That pairing is the
+ * point: auto-generating alone would make each call its own session, which is
+ * right for a one-shot and silently wrong for a conversation — the second turn
+ * would start with no history and no shared budget, and nothing would say so.
+ */
+export interface AgentIdentity {
+	sessionId?: SessionId
+	threadId?: ThreadId
+	projectId?: ProjectId
+	tenantId?: TenantId
+}
+
+export interface RunAgentOptions extends AgentIdentity {
+	/** The model driver. The one thing with no sensible default. */
+	provider: LLMProvider
+
+	/** What to ask. A string is turned into a single user message. */
+	prompt: string | Message[]
+
+	/** The system prompt. */
+	instructions?: string
+
+	/**
+	 * Model id.
+	 *
+	 * Required, and not defaulted from the provider, because `LLMProvider`
+	 * carries no model — a driver may have been constructed with one, but the
+	 * interface does not expose it, so anything this function picked would be
+	 * a guess billed to the caller. Two required options is a shape someone
+	 * can hold in their head; a wrong model quietly used is not.
+	 */
+	model: string
+
+	tools?: ToolRegistryContract
+
+	/** Defaults to the current working directory. */
+	workingDirectory?: string
+
+	maxIterations?: number
+	tokenBudget?: number
+	timeoutMs?: number
+	temperature?: number
+
+	/** Names the agent in traces and events. Defaults to `Agent`. */
+	name?: string
+
+	signal?: AbortSignal
+	listener?: RunEventListener
+}
+
+export interface RunAgentResult {
+	/** The model's final text, or `undefined` if it produced none. */
+	readonly output: string | undefined
+
+	/** The full run — usage, cost, steps, stop reason, every message. */
+	readonly run: Run
+
+	/**
+	 * The identity this run used, with anything generated filled in.
+	 *
+	 * Pass it straight back into the next call to continue the same session.
+	 */
+	readonly identity: Required<AgentIdentity>
+}
+
+/**
+ * Defaults chosen to be safe rather than generous.
+ *
+ * A front door exists so a first run works without a decision, and the cost of
+ * that convenience is that nobody reads these numbers before their first
+ * runaway loop. So: a budget that ends a stuck run in seconds rather than
+ * dollars, and an iteration cap that stops a tool-calling loop well before a
+ * context window does. Every one is overridable and named on the option.
+ */
+const DEFAULT_MAX_ITERATIONS = 16
+const DEFAULT_TOKEN_BUDGET = 200_000
+const DEFAULT_TIMEOUT_MS = 300_000
+
+/**
+ * Run an agent, without assembling a kernel by hand.
+ *
+ * `drainQuery` is the kernel's real entry point and takes eleven required
+ * parameters, four of which are identity fields that throw when missing. That
+ * is the correct shape for a kernel — a run with no tenant is a run no auditor
+ * can attribute — and it is the wrong shape for the first thing anybody
+ * writes. The proof was in this repo: the eval suites, the test files and the
+ * CLI each hand-assemble the same block, which is what a missing front door
+ * looks like from the inside.
+ *
+ * So this supplies an environment rather than a new engine. It generates the
+ * identity a single-tenant local run has no opinion about, defaults the
+ * budgets, points the working directory at the process's own, and hands back
+ * both the answer and the identity it used. Everything it fills in is a normal
+ * `drainQuery` parameter; there is no second code path, and a caller who
+ * outgrows it passes more options until they are calling `drainQuery` in all
+ * but name.
+ *
+ * ```ts
+ * const { output } = await runAgent({
+ *   provider,
+ *   model: 'claude-sonnet-4-5',
+ *   prompt: 'What is 2 + 2?',
+ * })
+ * ```
+ *
+ * A second turn in the same session is the identity handed back, and the
+ * previous messages carried forward:
+ *
+ * ```ts
+ * const first = await runAgent({ provider, model, prompt: 'My name is Ada.' })
+ *
+ * const second = await runAgent({
+ *   provider,
+ *   model,
+ *   ...first.identity,
+ *   prompt: [...first.run.messages, createUserMessage('What is my name?')],
+ * })
+ * ```
+ */
+export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult> {
+	const identity: Required<AgentIdentity> = {
+		sessionId: options.sessionId ?? generateSessionId(),
+		threadId: options.threadId ?? generateThreadId(),
+		projectId: options.projectId ?? generateProjectId(),
+		tenantId: options.tenantId ?? generateTenantId(),
+	}
+
+	const messages: Message[] =
+		typeof options.prompt === 'string'
+			? [{ role: 'user', content: options.prompt, timestamp: Date.now() } as Message]
+			: options.prompt
+
+	const run = await drainQuery(
+		{
+			provider: options.provider,
+			tools: options.tools ?? new ToolRegistry(),
+			messages,
+			workingDirectory: options.workingDirectory ?? process.cwd(),
+			runConfig: {
+				model: options.model,
+				maxIterations: options.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+				tokenBudget: options.tokenBudget ?? DEFAULT_TOKEN_BUDGET,
+				timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+				...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+			},
+			// One option covers both. `drainQuery` separates the id from the
+			// display name because a fleet needs a stable key and a readable
+			// label; a single agent has no such tension, and asking for two
+			// strings that will always be the same is the kind of ceremony this
+			// function exists to remove.
+			agentId: options.name ?? 'agent',
+			agentName: options.name ?? 'Agent',
+			...(options.instructions ? { systemPrompt: options.instructions } : {}),
+			...(options.signal ? { signal: options.signal } : {}),
+			...identity,
+		} as never,
+		options.listener,
+	)
+
+	return { output: run.result, run, identity }
+}

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'
 

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,