@namzu/sdk 45.1.0 → 48.0.0

package/src/toolsets/source-glob.ts

@@ -0,0 +1,22 @@
+/**
+ * Match a hierarchical source id against a glob pattern.
+ *
+ * Source ids are strings like `mcp:github`, `plugin:acme`,
+ * `plugin:acme/mcp:db` (plan.md §1) — no filesystem semantics, so this is
+ * not a path glob: `*` matches any run of characters, including `/` and
+ * `:`, so `plugin:acme/*` matches `plugin:acme/mcp:db` in one step. There
+ * is no `**`, `?` or character class — the id space does not need them, and
+ * a smaller matcher is one with no surprising cases to test.
+ *
+ * A pattern with no `*` is an exact match, so callers never have to special
+ * case "no wildcard" themselves.
+ */
+export function matchesSourceIdGlob(id: string, pattern: string): boolean {
+	if (!pattern.includes('*')) return id === pattern
+	const escaped = pattern.split('*').map(escapeRegExpLiteral).join('.*')
+	return new RegExp(`^${escaped}$`).test(id)
+}
+
+function escapeRegExpLiteral(literal: string): string {
+	return literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/src/toolsets/toolset.ts

@@ -0,0 +1,31 @@
+import type { ToolDefinition } from '../types/tool/index.js'
+import type { ToolSource, Toolset } from './types.js'
+
+/**
+ * The plain, static `Toolset`: a fixed list of tools from one source.
+ *
+ * A bare string source is shorthand for a `host_tool` source with that
+ * string as both `id` and `name` — the common case for a small, in-process
+ * bundle of tools ("builtin", "memory") that has no separate discovery
+ * metadata worth writing out. Anything that needs a real `kind`
+ * (`mcp_server`, `plugin`, …) passes a full {@link ToolSource}; string
+ * shorthand never guesses a kind from the text of the id.
+ *
+ * The tools array is snapshotted once, at construction, so a caller that
+ * mutates the array it passed in afterward cannot change what this toolset
+ * reports. There is no `onChange`: a plain toolset never changes on its
+ * own — wrap it with a live source (a future MCP toolset) or rebuild it
+ * with a new snapshot instead.
+ */
+export function toolset(source: ToolSource | string, tools: readonly ToolDefinition[]): Toolset {
+	const resolvedSource = typeof source === 'string' ? hostToolSource(source) : source
+	const snapshot = tools.slice()
+	return {
+		source: resolvedSource,
+		tools: () => snapshot,
+	}
+}
+
+function hostToolSource(id: string): ToolSource {
+	return { id, kind: 'host_tool', name: id }
+}

package/src/toolsets/types.ts

@@ -0,0 +1,154 @@
+import type { ToolDefinition } from '../types/tool/index.js'
+import type { ToolSource, ToolSourceKind } from '../types/toolset/index.js'
+
+// Re-exported so the rest of `toolsets/` can `import type { ToolSource }
+// from './types.js'` and never reach past this module's own boundary.
+// `public-types.ts` already exports these from `types/toolset/index.js`
+// directly, and lists this module's OWN new names explicitly (not `export
+// type *`), so this re-export does not create a duplicate public export.
+export type { ToolSource, ToolSourceKind }
+
+/**
+ * A toolset's own default for the tools it contributes.
+ *
+ * Deliberately narrower than {@link ToolAvailability} (`'active' |
+ * 'deferred' | 'suspended'`): `'suspended'` is derived from a host readiness
+ * check, not a static declaration. Absent means `'active'`.
+ */
+export type ToolsetAvailability = 'active' | 'deferred'
+
+/**
+ * The unit every tool comes from.
+ *
+ * A `Toolset` is a value, not a registration: `toolset()`, every wrapper
+ * below, and `combineToolsets` all return one without touching any shared
+ * state. The runtime resolves it through a `ToolManager` when a turn starts.
+ */
+export interface Toolset {
+	/** Where these tools come from. Ownership and trust stay with this. */
+	readonly source: ToolSource
+	/**
+	 * The current snapshot, in a deterministic order.
+	 *
+	 * Called fresh whenever a caller wants the current tools — a wrapper
+	 * re-derives its mapping/filtering on every call rather than caching,
+	 * so a live inner toolset's change is visible the moment `tools()` is
+	 * called again, with no separate invalidation step.
+	 */
+	tools(): readonly ToolDefinition[]
+	/**
+	 * This toolset's default for tools it contributes. Absent means
+	 * `'active'`. A wrapper composes this along with everything else: see
+	 * {@link deferred}.
+	 */
+	readonly availability?: ToolsetAvailability
+	/**
+	 * Host-owned readiness, independent of whether the model has loaded a
+	 * deferred schema. A false (or throwing) check keeps every tool in this
+	 * source out of discovery, prompts and execution. Read fresh on each use.
+	 */
+	readonly isReady?: () => boolean
+	/**
+	 * Subscribe to "the next `tools()` call may return something different"
+	 * — an MCP server's `list_changed`, for instance. Returns the
+	 * unsubscribe function. Absent means this toolset never changes on its
+	 * own (a plain {@link toolset} never does).
+	 *
+	 * A wrapper or {@link combineToolsets} that wraps a live toolset forwards
+	 * this by calling the inner `onChange` with the same listener, so a
+	 * change three layers down reaches a listener on the outermost toolset,
+	 * and unsubscribing at the outer layer unsubscribes at every inner one.
+	 */
+	onChange?(listener: () => void): () => void
+	/** Release whatever this toolset holds open (a connection, a watcher). */
+	close?(): Promise<void>
+}
+
+/** A broken readiness check must never expose the tools it guards. */
+export function toolsetIsReady(ts: Toolset): boolean {
+	try {
+		return ts.isReady?.() ?? true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * A lean reference to the toolset that contributed a tool.
+ * `ToolManager.sourceOf(name)` derives it from the owning toolset; no source
+ * pointer is stored on the `ToolDefinition` itself.
+ */
+export interface ToolSourceRef {
+	readonly id: string
+	readonly kind: ToolSourceKind
+	/** Only set when `kind` is `'mcp_server'`: the connected server's configured name. */
+	readonly server?: string
+	/**
+	 * Only set when `kind` is `'mcp_server'`. See `ToolProvenance.readOnlyHintTrusted`
+	 * (`types/tool/index.ts`) — same meaning, carried on the source instead of
+	 * duplicated onto every tool the source contributes.
+	 */
+	readonly readOnlyHintTrusted?: boolean
+}
+
+/**
+ * Project a `ToolSource` down to the lean reference returned by
+ * `ToolManager.sourceOf(name)`. Pure; reads nothing but its arguments.
+ *
+ * `readOnlyHintTrusted` defaults to `source.mcpServer?.readOnlyHintTrusted`
+ * — the operator's per-server trust decision, wired by whatever built this
+ * `ToolSource` (`mcpToolset`, plan.md §4). The `mcp` parameter overrides that
+ * default rather than being the only channel for it: a caller that already
+ * has the decision in hand some other way (a test, a wrapper) may still pass
+ * it explicitly, but `sourceOf` (`toolsets/manager.ts`) relies on the
+ * default so a trusted server's tools resolve as trusted with no extra
+ * wiring at the call site.
+ */
+export function toToolSourceRef(
+	source: ToolSource,
+	mcp?: { readonly readOnlyHintTrusted: boolean },
+): ToolSourceRef {
+	if (source.kind !== 'mcp_server') return { id: source.id, kind: source.kind }
+	return {
+		id: source.id,
+		kind: source.kind,
+		server: source.mcpServer?.name ?? source.name,
+		readOnlyHintTrusted: mcp?.readOnlyHintTrusted ?? source.mcpServer?.readOnlyHintTrusted ?? false,
+	}
+}
+
+/**
+ * A synchronous test over one tool, for {@link filtered} and
+ * {@link requireApproval}.
+ *
+ * `source` is the CONTRIBUTING TOOLSET's own source (`ts.source` projected
+ * through {@link toToolSourceRef}) — not a source declared by a tool
+ * definition (see {@link ToolFilterSelector}'s note on `sourceIdGlob`). A
+ * predicate that
+ * needs to tell a trusted MCP server's tool from an untrusted one's (the
+ * `isTrustedReadOnly` recipe in `tools/roster.ts`) reads this — which is
+ * correct for a plain, single-source toolset, and why that recipe must run
+ * on each contributing toolset before {@link combineToolsets} merges them:
+ * applied to an already-combined multi-source toolset, `source` is the
+ * COMBINED umbrella source, not any one contributor's, and a predicate that
+ * trusts it that far trusts every contributor equally.
+ */
+export type ToolPredicate = (tool: ToolDefinition, source: ToolSourceRef) => boolean
+
+/**
+ * What `filtered` (and `requireApproval`'s optional selector) may match on.
+ *
+ * `sourceIdGlob` matches the WHOLE toolset's own {@link ToolSource.id}
+ * (glob syntax: {@link matchesSourceIdGlob}) — not a per-tool source.
+ * A toolset is one source, so this keeps every tool the toolset contributes
+ * when the glob matches, and none when it does not.
+ *
+ * `metadata` is a deep-match against `ToolDefinition.metadata`: every key in
+ * the pattern must be present and equal (or, for a nested plain object,
+ * recursively matched) on the tool's own metadata. A tool with no metadata
+ * never matches a metadata selector.
+ */
+export type ToolFilterSelector =
+	| readonly string[]
+	| { readonly metadata: Readonly<Record<string, unknown>> }
+	| { readonly sourceIdGlob: string }

package/src/toolsets/wrappers.ts

@@ -0,0 +1,191 @@
+import { matchesToolSelector } from '../tools/roster.js'
+import type { ToolDefinition } from '../types/tool/index.js'
+import { matchesSourceIdGlob } from './source-glob.js'
+import {
+	type ToolFilterSelector,
+	type ToolPredicate,
+	type Toolset,
+	type ToolsetAvailability,
+	toToolSourceRef,
+} from './types.js'
+
+/**
+ * Build a derived `Toolset` that keeps the inner toolset's `source`,
+ * `availability` (unless overridden) and live-update wiring (`onChange`,
+ * `close`), forwarded rather than re-implemented.
+ *
+ * Every wrapper in this file goes through this one function, so "keep the
+ * inner source", "forward `onChange` through every layer" and "clean up
+ * `close`" are each written exactly once.
+ */
+function deriveToolset(
+	ts: Toolset,
+	overrides: {
+		tools?: () => readonly ToolDefinition[]
+		availability?: ToolsetAvailability
+		isReady?: () => boolean
+	},
+): Toolset {
+	const derived: Toolset = {
+		source: ts.source,
+		tools: overrides.tools ?? (() => ts.tools()),
+		availability: overrides.availability ?? ts.availability,
+		isReady: overrides.isReady ?? ts.isReady,
+	}
+	if (ts.onChange) {
+		// A direct forward: calling the derived toolset's `onChange` subscribes
+		// the inner one with the same listener and hands back ITS unsubscribe,
+		// so a change three layers down reaches the outermost listener, and
+		// unsubscribing at any layer tears down exactly that subscription.
+		const innerOnChange = ts.onChange
+		derived.onChange = (listener) => innerOnChange(listener)
+	}
+	if (ts.close) {
+		const innerClose = ts.close
+		derived.close = () => innerClose()
+	}
+	return derived
+}
+
+/**
+ * Apply `fn` to every tool this toolset contributes, recomputed on every
+ * `tools()` call (no caching) so a live inner toolset's change is visible
+ * immediately. Every other wrapper below is written in terms of this one.
+ */
+export function mapTools(ts: Toolset, fn: (tool: ToolDefinition) => ToolDefinition): Toolset {
+	return deriveToolset(ts, { tools: () => ts.tools().map(fn) })
+}
+
+/** Prepend `prefix` to every tool's name. `execute` and every other field are untouched. */
+export function prefixed(ts: Toolset, prefix: string): Toolset {
+	const cache = new WeakMap<ToolDefinition, ToolDefinition>()
+	return deriveToolset(ts, {
+		tools: () =>
+			ts.tools().map((tool) => {
+				let renamed = cache.get(tool)
+				if (!renamed) {
+					renamed = { ...tool, name: `${prefix}${tool.name}` }
+					cache.set(tool, renamed)
+				}
+				return renamed
+			}),
+	})
+}
+
+/**
+ * Rename the tools named as keys in `names` to their mapped value. A tool
+ * whose name is not a key keeps its name. `execute` and every other field
+ * are untouched — only `name` changes.
+ */
+export function renamed(ts: Toolset, names: Readonly<Record<string, string>>): Toolset {
+	return mapTools(ts, (tool) => {
+		const next = names[tool.name]
+		return next === undefined ? tool : { ...tool, name: next }
+	})
+}
+
+/**
+ * Keep only the tools `selector` (or `predicate`) admits.
+ *
+ * See {@link ToolFilterSelector} for what a non-function selector can match
+ * on. A `sourceIdGlob` selector is all-or-nothing per toolset — it tests
+ * this toolset's own `source.id`, not a per-tool source. A function
+ * `predicate` is handed `ts.source` (projected through
+ * {@link toToolSourceRef}) as its second argument for the same reason —
+ * see {@link ToolPredicate}'s note on what that source means, and does not
+ * mean, once toolsets have been combined.
+ */
+export function filtered(ts: Toolset, selector: ToolFilterSelector | ToolPredicate): Toolset {
+	const predicate = toPredicate(ts, selector)
+	const source = toToolSourceRef(ts.source)
+	return deriveToolset(ts, {
+		tools: () => ts.tools().filter((tool) => predicate(tool, source)),
+	})
+}
+
+function toPredicate(ts: Toolset, selector: ToolFilterSelector | ToolPredicate): ToolPredicate {
+	if (typeof selector === 'function') return selector
+	if (Array.isArray(selector)) {
+		const names = new Set<string>(selector as readonly string[])
+		return (tool) => names.has(tool.name)
+	}
+	// `Array.isArray`'s built-in guard narrows against a MUTABLE `any[]`, so
+	// TypeScript cannot use the negative case above to drop `readonly
+	// string[]` from the union — the cast is just naming what the runtime
+	// check already proved.
+	const objectSelector = selector as Exclude<ToolFilterSelector, readonly string[]>
+	if ('sourceIdGlob' in objectSelector) {
+		const keepEverything = matchesSourceIdGlob(ts.source.id, objectSelector.sourceIdGlob)
+		return () => keepEverything
+	}
+	// The deep-match itself (nested plain objects recursed, arrays compared
+	// elementwise) is `matchesToolSelector`'s (`tools/roster.ts`) — the same
+	// rule a permission `by_source`/metadata rule matches by, so a metadata
+	// selector means the same thing wherever it is written.
+	const pattern = objectSelector.metadata
+	return (tool) => matchesToolSelector(pattern, tool)
+}
+
+/**
+ * This toolset's tools default to `'deferred'` instead of `'active'` — the
+ * model has to ask for them by name (or a `search_tools`/reveal path) rather
+ * than seeing them offered up front.
+ */
+export function deferred(ts: Toolset): Toolset {
+	return deriveToolset(ts, { availability: 'deferred' })
+}
+
+/**
+ * Keep tools unavailable until the host confirms their prerequisite is ready.
+ * This guard is independent of `deferred`: search cannot grant readiness.
+ * The callback must read current host state and return synchronously.
+ */
+export function readyWhen(ts: Toolset, isReady: () => boolean): Toolset {
+	return deriveToolset(ts, {
+		isReady: () => (ts.isReady?.() ?? true) && isReady(),
+	})
+}
+
+/**
+ * Mark the tools `selector` admits (every tool, when omitted) as needing
+ * approval every time they are called.
+ *
+ * Sets `ToolDefinition.requiresApproval` to a predicate that always answers
+ * `true`, and nothing else — this wrapper does not enforce approval itself;
+ * that is `runtime/query/review-policy.ts`'s job, which reads the field this
+ * writes. `requiresApproval` is declared as `(input: TInput) => boolean`
+ * (method-shorthand, like `isReadOnly`), not a plain boolean, so every tool
+ * this wrapper marks gets the same always-true predicate rather than a
+ * second field shape to check for.
+ */
+export function requireApproval(
+	ts: Toolset,
+	selector?: ToolFilterSelector | ToolPredicate,
+): Toolset {
+	const predicate = selector ? toPredicate(ts, selector) : () => true
+	const source = toToolSourceRef(ts.source)
+	const mapped = new WeakMap<ToolDefinition, ToolDefinition>()
+	return deriveToolset(ts, {
+		tools: () =>
+			ts.tools().map((tool) => {
+				if (!predicate(tool, source)) return tool
+				let approved = mapped.get(tool)
+				if (!approved) {
+					approved = { ...tool, requiresApproval: () => true }
+					mapped.set(tool, approved)
+				}
+				return approved
+			}),
+	})
+}
+
+/**
+ * Merge `metadata` onto every tool this toolset contributes, keeping
+ * whatever metadata a tool already carries (last write wins per key).
+ */
+export function withMetadata(ts: Toolset, metadata: Readonly<Record<string, unknown>>): Toolset {
+	return mapTools(ts, (tool) => ({
+		...tool,
+		metadata: { ...tool.metadata, ...metadata },
+	}))
+}

package/src/types/agent/base.ts

@@ -16,7 +16,8 @@ import type { TurnExecutionStatus } from '../session/turn.js'
 import type { TaskStore } from '../task/index.js'
 import type { ToolAvailability } from '../tool/index.js'
 
-export type AgentType = 'reactive' | 'pipeline' | 'router' | 'supervisor'
+/** Application-owned agent kind; the SDK does not prescribe an agent taxonomy. */
+export type AgentType = string
 
 export type AgentContextLevel = 'full' | 'standard' | 'minimal'
 
@@ -225,30 +226,23 @@ export interface BaseAgentConfig {
 	idempotencyKey?: string
 
 	/**
-	 * Long-lived goal scope for the turn. Required at runtime — agents reject
-	 * configs missing this (`'X requires sessionId, projectId, and tenantId
-	 * in config'`).
-	 *
-	 * Kept optional at the TYPE level because {@link AgentManager} stamps
-	 * this field AFTER `configBuilder` returns (manager/agent/lifecycle.ts).
-	 * Tightening to required is a separate task alongside
-	 * `AgentFactoryOptions` carrying the triple.
+	 * Project scope for a store-backed turn. Optional on the general Agent
+	 * contract: {@link AgentManager} supplies the real project to delegated
+	 * agents after `configBuilder` returns. A standalone application agent need
+	 * not take its identity from a project store.
 	 */
 	projectId?: ProjectId
 
 	/**
-	 * Topic the turn belongs to. Optional at the TYPE level for the same
-	 * reason as `projectId` — {@link AgentManager} stamps this field after
-	 * `configBuilder` returns so `configBuilder` implementations do not
-	 * need to be updated before this tightens. Tightening to required
-	 * lands with the `AgentFactoryOptions` triple refactor.
+	 * Optional topic scope. A host with topics supplies it for its own session
+	 * and delegation records; it is not intrinsic to an Agent implementation.
 	 */
 	topicId?: TopicId
 
-	/** Session under which the turn executes. See `projectId` for the tightening plan. */
+	/** Session correlation for a persisted turn; a host may resolve it at invocation. */
 	sessionId?: SessionId
 
-	/** Isolation boundary (Convention #17). See `projectId` for the tightening plan. */
+	/** Host tenancy scope; store-backed delegation needs a real tenant owner. */
 	tenantId?: TenantId
 
 	/** Present on a child session: the session that delegated it. */
@@ -338,6 +332,15 @@ export interface AgentRuntimeContext {
 	notes?: readonly string[]
 }
 
+/** Host-owned scope for a managed invocation, separate from agent configuration. */
+export interface AgentInvocationScope {
+	readonly kind: 'managed'
+	readonly sessionId: SessionId
+	readonly topicId: TopicId
+	readonly projectId: ProjectId
+	readonly tenantId: TenantId
+}
+
 export interface AgentInput {
 	messages: Message[]
 	workingDirectory: string
@@ -352,6 +355,15 @@ export interface AgentInput {
 	runtimeContext?: AgentRuntimeContext
 }
 
+/** Input for an adapter that runs a managed session through the query kernel. */
+export type ManagedAgentInput = AgentInput & {
+	/**
+	 * Host-owned session attribution. `AgentManager` sets this from the admitted
+	 * child session, so the reusable agent config need not own its identity.
+	 */
+	readonly managedScope?: AgentInvocationScope
+}
+
 export interface BaseAgentResult {
 	/** Aggregate tree accounting, separate from this invocation's own usage. */
 	budget?: ReturnType<SessionTokenBudget['summary']>
@@ -389,6 +401,7 @@ export interface BaseAgentResult {
 	lastError?: string
 }
 
+/** Descriptive metadata. Access and concurrency are enforced by the host and runtime seams. */
 export interface AgentCapabilities {
 	supportsTools: boolean
 	supportsStreaming: boolean

package/src/types/agent/index.ts

@@ -1,5 +1,6 @@
 export * from './base.js'
 export * from './core.js'
+export * from './query.js'
 export * from './reactive.js'
 export * from './pipeline.js'
 export * from './router.js'

package/src/types/agent/pipeline.ts

@@ -24,6 +24,7 @@ export interface PipelineStep<TInput = unknown, TOutput = unknown> {
 	validate?(input: TInput): boolean
 }
 
+/** @deprecated Configuration for the pipeline example; define application orchestration as needed. */
 export interface PipelineAgentConfig extends BaseAgentConfig {
 	steps: PipelineStep[]
 	provider?: LLMProvider
@@ -38,6 +39,7 @@ export interface PipelineStepResult {
 	durationMs: number
 }
 
+/** @deprecated Result of the pipeline example. */
 export interface PipelineAgentResult extends BaseAgentResult {
 	stepResults: PipelineStepResult[]
 	completedSteps: number

package/src/types/agent/query.ts

@@ -0,0 +1,129 @@
+import type { CompactionConfig } from '../../config/runtime.js'
+import type { QueryParams } from '../../runtime/query/index.js'
+import type { SteeringChannel } from '../../runtime/query/steering.js'
+import type { Toolset } from '../../toolsets/types.js'
+import type { AdvisoryConfig } from '../advisory/index.js'
+import type { AuthorizationGateConfig } from '../authorization/index.js'
+import type { InputGuardrailSpec, OutputGuardrailSpec } from '../guardrail/index.js'
+import type { ResumeHandler } from '../hitl/index.js'
+import type { AgentPersona } from '../persona/index.js'
+import type { LLMProvider } from '../provider/index.js'
+import type { SandboxProvider } from '../sandbox/index.js'
+import type { BeforeStep, PrepareStepChain, StepResult, StopCondition } from '../session/index.js'
+import type { Skill } from '../skills/index.js'
+import type { StructuredOutputConfig } from '../structured-output/index.js'
+import type { RepairToolCall } from '../tool/repair.js'
+import type { BaseAgentConfig, BaseAgentResult } from './base.js'
+import type { WorkingMemoryProvider } from './working-memory.js'
+
+export interface QueryAgentConfig extends BaseAgentConfig {
+	systemPrompt?: string
+	/** Provider-hosted search for this turn; the selected driver must support it. */
+	webSearch?: { mode: 'live' | 'cached' }
+
+	persona?: AgentPersona
+
+	/**
+	 * Channel a host uses to hand guidance to this turn's current turn.
+	 *
+	 * Forwarded into `drainQuery` so a host using this adapter can steer the
+	 * same turn it could steer through a direct `query()` call.
+	 */
+	steering?: SteeringChannel
+
+	skills?: Skill[]
+
+	basePrompt?: string
+	provider: LLMProvider
+	/** Every tool this turn may see comes from one of these — see `toolsets/types.ts`. */
+	toolsets: readonly Toolset[]
+
+	advisory?: AdvisoryConfig
+
+	/**
+	 * Optional capability-aware deny/allow gate for tool calls.
+	 * When omitted,
+	 * `drainQuery` falls back to its `autoApproveHandler` default
+	 * (every tool call auto-approves, no policy applied). Hosts that
+	 * trust their sandbox should still pass at least
+	 * `{ enabled: true, denyDangerousPatterns: true, ... }` so the
+	 * canonical brick patterns hard-deny instead of executing
+	 * silently.
+	 */
+
+	authorizationGate?: AuthorizationGateConfig
+
+	/**
+	 * Optional ephemeral sandbox provider. When set, drainQuery creates
+	 * a sandbox via `provider.create()` before the iteration loop and
+	 * routes filesystem / shell tool calls through it; on turn end the
+	 * SDK calls `sandbox.destroy()`. Hosts that want related turns to share
+	 * one container pass the same caching provider instance to those turns.
+	 */
+	sandboxProvider?: SandboxProvider
+	/** See {@link QueryParams.sandboxTeardownTimeoutMs}. */
+	sandboxTeardownTimeoutMs?: number
+	/** See {@link QueryParams.outsideRootAccess}. Default `'refuse'`. */
+	outsideRootAccess?: 'refuse' | 'review'
+	/** See {@link QueryParams.sandboxEscape}. Default `'refuse'`. */
+	sandboxEscape?: 'refuse' | 'review'
+
+	/**
+	 * Optional structured-compaction config. Omitted ⇒ byte-identical run path
+	 * (no `WorkingStateManager`, compaction early-returns).
+	 */
+	compactionConfig?: CompactionConfig
+
+	/**
+	 * Optional neutral working-memory seam. Absent ⇒ no block injected.
+	 * Related turns can share one provider when the host wants shared memory.
+	 */
+	workingMemoryProvider?: WorkingMemoryProvider
+
+	/**
+	 * Loop-control and resilience seams, forwarded verbatim to `query()`.
+	 *
+	 * The optional `QueryAgent` adapter forwards these settings for hosts that
+	 * need an `AgentManager` shell. Hosts using `query()` configure them there.
+	 *
+	 * Every field is optional and absent means exactly what it meant
+	 * before, so no existing agent changes behavior.
+	 */
+	resumeHandler?: ResumeHandler
+	retry?: QueryParams['retry']
+	toolTimeoutMs?: number
+	toolRetryBackoff?: QueryParams['toolRetryBackoff']
+	maxToolConcurrency?: number
+	maxToolOutputChars?: number
+	retainedToolPreviewChars?: QueryParams['retainedToolPreviewChars']
+	/**
+	 * Cap on the RICH channel of a single tool result, in base64 characters.
+	 * `0` or absent disables it. Separate from {@link maxToolOutputChars}:
+	 * that one bounds characters the model reads, this one bounds the image
+	 * payload beside them, which no text budget ever touched.
+	 */
+	maxToolContentBytes?: number
+	repairToolCall?: RepairToolCall
+	stopWhen?: StopCondition
+	onStepFinish?: (step: StepResult) => void
+	prepareStep?: PrepareStepChain
+	/**
+	 * Refuse the next model call before it is made. See {@link BeforeStep}.
+	 * A throw fails CLOSED, opposite to `prepareStep` beside it.
+	 */
+	beforeStep?: BeforeStep
+
+	structuredOutput?: StructuredOutputConfig
+	inputGuardrails?: readonly InputGuardrailSpec[]
+	outputGuardrails?: readonly OutputGuardrailSpec[]
+
+	/**
+	 * Span this turn should hang off, when it is a delegated one. Absent for
+	 * a top-level turn, which correctly starts its own root trace.
+	 */
+	parentSpan?: import('@opentelemetry/api').Span
+}
+
+export interface QueryAgentResult extends BaseAgentResult {
+	toolCallCount: number
+}