@namzu/sdk 27.0.0 → 28.0.0

package/src/types/agent/{gateway.ts → scheduler.ts}

@@ -1,4 +1,5 @@
 import type { TaskId } from '../ids/index.js'
+import type { AgentPersona } from '../persona/index.js'
 import type { AgentRuntimeContext, BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { AgentTaskState } from './task.js'
 
@@ -34,6 +35,31 @@ export interface CreateTaskOptions {
 
 	agentId: string
 
+	/**
+	 * Tools this ONE delegation may not use, on top of whatever the child
+	 * would otherwise have.
+	 *
+	 * Deny-only, and the shape is the point: a per-call scope that could
+	 * ADD a tool is a privilege-escalation surface wearing the word
+	 * "scope". Widening has to be unexpressible, not merely discouraged —
+	 * a caller who wants a child to have more tools changes the agent's
+	 * definition, where somebody can see it.
+	 *
+	 * Naming a tool the child never had is a no-op, not an error: the
+	 * result is still narrower, and refusing would make a caller's deny
+	 * list depend on which agent it happened to be talking to.
+	 */
+	readonly toolScope?: { readonly deny: readonly string[] }
+
+	/**
+	 * Replace the child's assembled persona for this delegation only.
+	 *
+	 * Scoped to the call rather than the agent, so a supervisor can hand
+	 * one subtask a narrower brief without redefining an agent every other
+	 * delegation shares.
+	 */
+	readonly personaOverride?: AgentPersona
+
 	prompt: string
 
 	workingDirectory: string
@@ -45,7 +71,7 @@ export interface CreateTaskOptions {
 	 * agent's own definition supplies — the model it runs on, its iteration
 	 * ceiling, its thinking or effort settings.
 	 *
-	 * **This was accepted and dropped.** `LocalTaskGateway.createTask` built
+	 * **This was accepted and dropped.** `LocalTaskScheduler.createTask` built
 	 * its own `configOverrides` object out of `parentSpan` alone and never
 	 * read this field, so a caller pinning a delegated run to a cheaper model
 	 * got the agent's default model and no indication otherwise. It is
@@ -60,7 +86,7 @@ export interface CreateTaskOptions {
 	configOverrides?: Partial<BaseAgentConfig>
 }
 
-export interface TaskGateway {
+export interface TaskScheduler {
 	createTask(options: CreateTaskOptions): Promise<TaskHandle>
 
 	waitForTask(taskId: TaskId): Promise<TaskHandle>
@@ -84,7 +110,7 @@ export interface TaskGateway {
 	 * This is a request, not a requirement, and the cost of not meeting it is
 	 * yours: a gateway that forgets a task the instant it completes still
 	 * works, but under a burst large enough to overflow the buffer a fast
-	 * worker's result can go unannounced. `LocalTaskGateway` meets it for as
+	 * worker's result can go unannounced. `LocalTaskScheduler` meets it for as
 	 * long as the manager holds the record.
 	 */
 	getTask(taskId: TaskId): TaskHandle | undefined
@@ -106,7 +132,7 @@ export interface TaskGateway {
 	 * OPTIONAL, and the absence is meaningful rather than an oversight: a
 	 * gateway that cannot observe its children still works, and its waits
 	 * are bounded by the wall clock alone — which is exactly the behaviour
-	 * before this existed. It is optional because `TaskGateway` is
+	 * before this existed. It is optional because `TaskScheduler` is
 	 * implemented by hosts, and a required method would break every one of
 	 * them for a capability not all of them can provide.
 	 *
@@ -117,3 +143,14 @@ export interface TaskGateway {
 	 */
 	onTaskProgress?(callback: (taskId: TaskId) => void): () => void
 }
+
+/**
+ * @deprecated Renamed to {@link TaskScheduler}. Removed in the next major.
+ *
+ * "Gateway" names an object that sits at a system boundary and faces
+ * outward — Fowler's POEAA Gateway, an API gateway, a payment gateway. This
+ * one faces inward: it creates, waits on, continues, cancels and lists
+ * in-process agent tasks. A reader who trusted the name expected a facade
+ * over something external and found a scheduler.
+ */
+export type TaskGateway = TaskScheduler

package/src/types/agent/supervisor.ts

@@ -1,6 +1,7 @@
 import type { CompactionConfig } from '../../config/runtime.js'
 import type { SteeringChannel } from '../../runtime/query/steering.js'
 import type { AdvisoryConfig } from '../advisory/index.js'
+import type { AuthorizationGateConfig } from '../authorization/index.js'
 import type { ResumeHandler } from '../hitl/index.js'
 import type { LLMProvider } from '../provider/index.js'
 import type { TaskRouterConfig } from '../router/index.js'
@@ -8,11 +9,10 @@ import type { SandboxProvider } from '../sandbox/index.js'
 import type { Skill } from '../skills/index.js'
 import type { StructuredOutputConfig } from '../structured-output/index.js'
 import type { ToolRegistryContract } from '../tool/index.js'
-import type { VerificationGateConfig } from '../verification/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { AgentFactoryOptions } from './factory.js'
-import type { SiblingFailurePolicy, TaskGateway } from './gateway.js'
 import type { AgentManagerContract } from './manager.js'
+import type { SiblingFailurePolicy, TaskScheduler } from './scheduler.js'
 import type { WorkingMemoryProvider } from './working-memory.js'
 
 export interface SupervisorAgentConfig extends BaseAgentConfig {
@@ -48,7 +48,22 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 */
 	allowDelegation?: boolean
 
-	gateway?: TaskGateway
+	/**
+	 * @deprecated Renamed to {@link SupervisorAgentConfig.scheduler}. Removed
+	 * in the next major. Setting both to different instances throws.
+	 */
+	gateway?: TaskScheduler
+
+	scheduler?: TaskScheduler
+
+	/**
+	 * Called when the operator approves a plan.
+	 *
+	 * The hook a host uses to leave plan mode without ending the run — which
+	 * is what the mode's per-run lifetime used to force, discarding the
+	 * in-flight step and the tool-schema context to change one enum.
+	 */
+	onPlanApproved?: () => Promise<void> | void
 	agentManager?: AgentManagerContract
 	tools?: ToolRegistryContract
 
@@ -94,7 +109,7 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 * What a failed child means for the siblings still running. Defaults to
 	 * `'continue'`.
 	 *
-	 * `LocalTaskGateway` has honoured this since it was written, and the
+	 * `LocalTaskScheduler` has honoured this since it was written, and the
 	 * cancellation machinery behind `'cancel-siblings'` is complete — but the
 	 * policy was a constructor argument on a gateway the supervisor builds
 	 * itself, and the supervisor passed nothing. So every host in existence
@@ -152,7 +167,13 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 * review") so the resumeHandler only fires for the truly
 	 * non-deterministic cases.
 	 */
-	verificationGate?: VerificationGateConfig
+	/**
+	 * @deprecated Renamed to `authorizationGate`. Removed in the next major.
+	 * Setting both to different configs throws.
+	 */
+	verificationGate?: AuthorizationGateConfig
+
+	authorizationGate?: AuthorizationGateConfig
 
 	/**
 	 * Optional ephemeral sandbox provider. When set, drainQuery creates

package/src/types/agent/task.ts

@@ -4,7 +4,7 @@ import type { ResumeHandler } from '../hitl/index.js'
 import type { RunId, SessionId, TaskId, TenantId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
 import type { RunEventListener } from '../run/events.js'
-import type { ProjectId, ThreadId } from '../session/ids.js'
+import type { ProjectId, TopicId } from '../session/ids.js'
 import type { AgentInput, BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { Agent } from './core.js'
 import type { AgentFactoryOptions } from './factory.js'
@@ -24,7 +24,7 @@ export function isTerminalAgentTaskState(state: AgentTaskState): boolean {
 
 /**
  * Context carried into {@link AgentManager.sendMessage}. `tenantId`,
- * `threadId`, `sessionId`, `projectId`, and `parentActor` are required —
+ * `topicId`, `sessionId`, `projectId`, and `parentActor` are required —
  * the spawn path is the ingress point for the session hierarchy; callers
  * must provide the full scoping set.
  */
@@ -46,7 +46,7 @@ export interface AgentTaskContext {
 	 * alone, handed down so a child asks the same person.
 	 *
 	 * Passed as the function itself, which works because delegation is
-	 * in-process: `LocalTaskGateway` is the only `TaskGateway` in the tree.
+	 * in-process: `LocalTaskScheduler` is the only `TaskScheduler` in the tree.
 	 * A gateway that dispatched across a process boundary could not carry a
 	 * closure and would have to proxy the request onto the parent's event
 	 * stream and route the answer back by request id — the upward half of
@@ -58,17 +58,34 @@ export interface AgentTaskContext {
 	 */
 	resumeHandler?: ResumeHandler
 
+	/**
+	 * The tool denies in force for the actor that owns this context — the
+	 * union of every `toolScope.deny` recorded along its actor chain.
+	 *
+	 * Threaded, not re-derived from the chain, because `ActorRef` identifies
+	 * an AGENT and not a spawn: two children of one parent running the same
+	 * agent id have identical chains, so a lookup keyed on one could not
+	 * tell their scopes apart.
+	 *
+	 * Absent means nothing was denied above here, which is what a top-level
+	 * run has. It is only ever added to. A spawn's own denies union with
+	 * this; nothing checks a spawn's denies AGAINST it, because a descendant
+	 * narrowing further is the whole point and a descendant widening is what
+	 * this exists to prevent.
+	 */
+	readonly toolDenies?: readonly string[]
+
 	/** Isolation boundary. Required per session-hierarchy.md §12.1. */
 	tenantId: TenantId
 
 	/**
-	 * Topic the current task belongs to. Required in 0.3.0 — spawn copies
-	 * this onto the child session without a second ThreadStore round-trip,
-	 * and gates creation on {@link ThreadManager.requireOpen}. Children
-	 * inherit the parent's `threadId` verbatim; cross-thread spawn is
-	 * forbidden by design (a delegated sub-agent stays on the same topic).
+	 * Topic the current task belongs to. Required — spawn copies this onto
+	 * the child session without a second TopicStore round-trip, and gates
+	 * creation on {@link TopicManager.requireOpen}. Children inherit the
+	 * parent's `topicId` verbatim; cross-topic spawn is forbidden by design
+	 * (a delegated sub-agent stays on the same topic).
 	 */
-	threadId: ThreadId
+	topicId: TopicId
 
 	/**
 	 * Parent session under which any sub-agent spawn is recorded. Required
@@ -134,6 +151,11 @@ export interface AgentTask {
  * WorkspaceRef triple atomically on every spawn.
  */
 export interface SendMessageOptions {
+	/** See {@link import('./scheduler.js').CreateTaskOptions.toolScope}. Deny-only. */
+	readonly toolScope?: { readonly deny: readonly string[] }
+	/** See {@link import('./scheduler.js').CreateTaskOptions.personaOverride}. */
+	readonly personaOverride?: import('../persona/index.js').AgentPersona
+
 	agentId: string
 
 	input: AgentInput

package/src/types/agent/working-memory.ts

@@ -4,7 +4,7 @@
  * NEUTRAL by construction: opaque strings + a number, NO host/Postgres/disk
  * types. It mirrors `AgentRuntimeContext.notes: readonly string[]` and the
  * `web-search` seam discipline — the host closes over everything else
- * (threadId, output dir, tenancy) when it builds the provider, so the SDK
+ * (topicId, output dir, tenancy) when it builds the provider, so the SDK
  * never learns a domain type. The SDK only POSITIONS the returned string at
  * the primacy edge; the host OWNS the content and its authority framing.
  */

package/src/types/{verification → authorization}/index.ts

@@ -1,16 +1,27 @@
 import { z } from 'zod'
-import { MAX_CUSTOM_PATTERN_LENGTH } from '../../constants/verification/index.js'
+import { MAX_CUSTOM_PATTERN_LENGTH } from '../../constants/authorization/index.js'
 
 export type GateDecision = 'allow' | 'deny' | 'review'
 
 export interface GateEvaluationResult {
 	readonly decision: GateDecision
-	readonly matchedRule: VerificationRule | null
+	readonly matchedRule: AuthorizationRule | null
 	readonly reason: string
 }
 
-export type VerificationRule =
-	| { type: 'allow_read_only' }
+export type AuthorizationRule =
+	| {
+			/**
+			 * Categories this allowance does not reach, even when
+			 * `isTrustedReadOnly` says the read-only CLAIM is trustworthy.
+			 * `isTrustedReadOnly` has no notion of category — it answers
+			 * whether the claim can be believed, never what channel the call
+			 * travelled over. See `evaluateRule`'s `allow_read_only` case for
+			 * the category that actually needs this.
+			 */
+			type: 'allow_read_only'
+			excludeCategories?: string[]
+	  }
 	| { type: 'deny_dangerous_patterns' }
 	| { type: 'allow_by_category'; categories: string[] }
 	| { type: 'allow_by_name'; toolNames: string[] }
@@ -32,7 +43,7 @@ export type VerificationRule =
 			 * other tool's arguments.
 			 *
 			 * When you mean "this tool, this argument", use
-			 * {@link VerificationRule} `argument_pattern` instead. This one
+			 * {@link AuthorizationRule} `argument_pattern` instead. This one
 			 * stays for the case it is actually good at: matching anywhere in
 			 * the serialised input without caring where.
 			 */
@@ -74,7 +85,16 @@ export type VerificationRule =
 	  }
 	| { type: 'allow_by_tier'; tiers: string[] }
 
-const AllowReadOnlySchema = z.object({ type: z.literal('allow_read_only') })
+const AllowReadOnlySchema = z.object({
+	type: z.literal('allow_read_only'),
+	// Optional, no default: a rule written before this field existed still
+	// parses and still means what it always meant. `.default([])` would make
+	// `AuthorizationGateConfig` — which is `z.infer` of the schema below, i.e.
+	// the zod OUTPUT type — require the field on every hand-authored literal
+	// in this repo and in every consumer, for no behavioural gain: `undefined`
+	// and `[]` are read identically.
+	excludeCategories: z.array(z.string()).optional(),
+})
 const DenyDangerousPatternsSchema = z.object({ type: z.literal('deny_dangerous_patterns') })
 const AllowByCategorySchema = z.object({
 	type: z.literal('allow_by_category'),
@@ -108,7 +128,7 @@ const AllowByTierSchema = z.object({
 	tiers: z.array(z.string()),
 })
 
-export const VerificationRuleSchema = z.discriminatedUnion('type', [
+export const AuthorizationRuleSchema = z.discriminatedUnion('type', [
 	AllowReadOnlySchema,
 	DenyDangerousPatternsSchema,
 	AllowByCategorySchema,
@@ -119,12 +139,61 @@ export const VerificationRuleSchema = z.discriminatedUnion('type', [
 	AllowByTierSchema,
 ])
 
-export const VerificationGateConfigSchema = z.object({
+export const AuthorizationGateConfigSchema = z.object({
 	enabled: z.boolean().default(false),
-	rules: z.array(VerificationRuleSchema).default([]),
+	rules: z.array(AuthorizationRuleSchema).default([]),
 	allowReadOnlyTools: z.boolean().default(false),
+	/**
+	 * Narrows the LAST-resort `allow_read_only` rule the gate appends for
+	 * {@link allowReadOnlyTools}. A category listed here falls through to
+	 * whatever comes next — another rule, or review — even for a call
+	 * `isTrustedReadOnly` would otherwise allow.
+	 *
+	 * `.optional()` for the reason `AllowReadOnlySchema.excludeCategories` is.
+	 */
+	allowReadOnlyExcludeCategories: z.array(z.string()).optional(),
 	denyDangerousPatterns: z.boolean().default(false),
 	logDecisions: z.boolean().default(true),
 })
 
-export type VerificationGateConfig = z.infer<typeof VerificationGateConfigSchema>
+export type AuthorizationGateConfig = z.infer<typeof AuthorizationGateConfigSchema>
+
+/**
+ * Old spellings, live for one deprecation window.
+ *
+ * A reader who saw `VerificationGate` expected something that verifies a
+ * claim — checks a signature, confirms an output matches a schema. This is
+ * a rule engine that decides, BEFORE a tool runs, whether the call is
+ * permitted: allow / deny / review, by name, category, tier or a pattern
+ * over the arguments. Every rule variant says so.
+ *
+ * The misreading was not academic. The module sat beside real guardrail and
+ * HITL neighbours, where "verification" actively suggests the post-hoc
+ * double-check the guardrails do.
+ */
+
+/**
+ * The two schemas below carry aliases too, and the task that specified this
+ * rename said they would not need any: `public-runtime.ts` records that they
+ * are deliberately not re-exported, so they looked unreachable.
+ *
+ * They were not. `public-types.ts` re-exports this module with
+ * `export type *`, which exports every name in TYPE position — including a
+ * `const`. So `import type { VerificationRuleSchema } from '@namzu/sdk'`
+ * compiled and `typeof VerificationRuleSchema` was a usable type, while
+ * importing it as a value failed with TS1362. Checked by compiling both
+ * forms against the built package rather than reading the barrel.
+ *
+ * Declared as `const` rather than `type` on purpose: a `type` alias would
+ * break `typeof`, which is the only way these were ever usable.
+ */
+
+/** @deprecated Renamed to {@link AuthorizationRuleSchema}. Removed in the next major. */
+export const VerificationRuleSchema = AuthorizationRuleSchema
+/** @deprecated Renamed to {@link AuthorizationGateConfigSchema}. Removed in the next major. */
+export const VerificationGateConfigSchema = AuthorizationGateConfigSchema
+
+/** @deprecated Renamed to {@link AuthorizationRule}. Removed in the next major. */
+export type VerificationRule = AuthorizationRule
+/** @deprecated Renamed to {@link AuthorizationGateConfig}. Removed in the next major. */
+export type VerificationGateConfig = AuthorizationGateConfig

package/src/types/bus/index.ts

@@ -25,7 +25,13 @@ export interface FileLock {
 
 export type LockAcquireResult =
 	| { acquired: true; lock: FileLock }
-	| { acquired: false; holder: RunId; filePath: string }
+	// `holder` is OPTIONAL, and its absence is the honest answer to "who holds
+	// it". The failure branch is also reached when the lock was released
+	// between the attempt and the read, and this used to report `'' as RunId`
+	// for that — an empty string wearing an id type, which the nominal ids of
+	// NZ-SURF-11 will not express and which no caller could have distinguished
+	// from a real holder anyway.
+	| { acquired: false; holder?: RunId; filePath: string }
 
 export interface FileOwnership {
 	readonly filePath: string
@@ -85,6 +91,29 @@ export type AgentBusEvent =
 			durationMs: number
 			error: string
 	  }
+	/**
+	 * A credential was written, removed, or replaced.
+	 *
+	 * Rotation was invisible: a lapsed OAuth token was refreshed straight
+	 * into a host's file store, and this union carried a LOOKUP event and no
+	 * change event — so no probe subscriber could see a credential turn
+	 * over, and nothing could answer "when did this last rotate".
+	 *
+	 * Carries no secret and never will. The whole value of a change event is
+	 * that it can be logged, forwarded and retained, which is exactly what a
+	 * credential must not be. `source` names where it lives; the value stays
+	 * where it lives.
+	 */
+	| {
+			type: 'vault_credential_changed'
+			/** `rotated` is a set that REPLACED a value, not a first write. */
+			kind: 'set' | 'unset' | 'rotated'
+			/** Which backing store changed — `env`, a file path's label, a KMS id. */
+			source: string
+			ref: string
+			tenantId?: TenantId
+			runId?: RunId
+	  }
 	| {
 			type: 'vault_lookup'
 			vaultId: string

package/src/types/code-navigation/index.ts

@@ -0,0 +1,99 @@
+/**
+ * The seam a language server arrives on.
+ *
+ * Declared in the SDK and implemented in `@namzu/lsp`, the same split
+ * `Sandbox` uses: the kernel owns the shape a tool programs against, and the
+ * optional package owns the process that answers. A host constructs one and
+ * puts it on the tool context — there is no `registerProvider()` discovery
+ * step, because a capability a host cannot see it wired up is one it cannot
+ * debug either.
+ *
+ * Kept here rather than imported from `@namzu/lsp` because the dependency
+ * direction forbids it: `sdk ← lsp`, never the other way. A duplicated
+ * declaration would be a second definition that can drift, so `@namzu/lsp`
+ * imports THESE types and implements them.
+ */
+
+/** A place in a file, zero-based, matching the language-server wire. */
+export interface SourceLocation {
+	/** Absolute path. Callers get back something they can open. */
+	readonly path: string
+	readonly line: number
+	readonly character: number
+	readonly endLine?: number
+	readonly endCharacter?: number
+}
+
+/**
+ * What a navigation query answers.
+ *
+ * Three cases, closed, and the last two are separate on purpose.
+ * `unsupported` is "this server does not do that" — a caller can fall back
+ * to `grep` and say the answer is textual. `failed` is "something broke" —
+ * a caller must not present the absence of an answer as a complete one.
+ *
+ * Neither is `{ kind: 'locations', locations: [] }`. An empty list means "I
+ * looked, and there are none", which is a real answer and the one a
+ * deletion depends on; conflating it with a failure is how an agent
+ * concludes a symbol has no callers because the server never started.
+ */
+export type CodeNavigationResult =
+	| { readonly kind: 'locations'; readonly locations: readonly SourceLocation[] }
+	| { readonly kind: 'unsupported'; readonly reason: string }
+	| { readonly kind: 'failed'; readonly error: string }
+
+/** A symbol found by name rather than by position. */
+export interface SymbolLocation extends SourceLocation {
+	readonly name: string
+	/** The wire's own symbol-kind number, when the server gave one. */
+	readonly symbolKind?: number
+	/** The class, module or namespace it sits in, when the server gave one. */
+	readonly containerName?: string
+}
+
+/**
+ * What hovering over a position says.
+ *
+ * `contents` may be EMPTY, and that is a real answer: hovering over
+ * whitespace or a comment resolves to nothing, and a caller must be able to
+ * tell that from a server that failed. Same reason `locations: []` is not a
+ * failure.
+ */
+export type HoverResult =
+	| { readonly kind: 'hover'; readonly contents: string }
+	| { readonly kind: 'unsupported'; readonly reason: string }
+	| { readonly kind: 'failed'; readonly error: string }
+
+export type SymbolSearchResult =
+	| { readonly kind: 'symbols'; readonly symbols: readonly SymbolLocation[] }
+	| { readonly kind: 'unsupported'; readonly reason: string }
+	| { readonly kind: 'failed'; readonly error: string }
+
+export interface CodeNavigationProvider {
+	/** Where the symbol under this position is declared. */
+	definition(file: string, line: number, character: number): Promise<CodeNavigationResult>
+	/** Everywhere the symbol under this position is used. */
+	references(file: string, line: number, character: number): Promise<CodeNavigationResult>
+	/** The symbol's type and documentation, without opening the file. */
+	hover(file: string, line: number, character: number): Promise<HoverResult>
+	/**
+	 * Find a declaration by NAME, with no position.
+	 *
+	 * The operation an agent reaches for first, and the one whose absence
+	 * made the rest unreachable: `definition` and `references` both need a
+	 * line and a character, and an agent starting from a name has neither.
+	 * Without this, every navigation began with a grep — which is the text
+	 * path this package exists to replace.
+	 *
+	 * `scope` is a file path or an extension that picks which language's
+	 * server answers. Absent means every configured language.
+	 */
+	symbols(query: string, scope?: string): Promise<SymbolSearchResult>
+	/**
+	 * Stop whatever backs it.
+	 *
+	 * Not optional. An implementation spawns a process, and a provider that
+	 * could not be told to stop leaves one behind per run.
+	 */
+	dispose(): Promise<void>
+}

package/src/types/command/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Commands a HOST offers its operator — not tools a model can call.
+ *
+ * There was no seam at all. The whole vocabulary was a literal array in one
+ * host's TUI module, over a union shaped by that TUI's own concerns
+ * (`repick`, `expand`, `login`, `clear`), and the coupling had already
+ * escaped: two non-TUI commands import that array from React-adjacent code
+ * to build a name list, for facts the kernel owns.
+ *
+ * **Never model-visible.** No descriptor is handed to a provider, no
+ * dispatch path reaches the LLM, and nothing here is a `ToolDefinition`.
+ * That separation is the whole point: a `/tasks` readout is a question the
+ * operator asked, and turning it into a tool would let the model call it,
+ * spend a turn on it, and put its output in the transcript as if the model
+ * had discovered something.
+ */
+
+/**
+ * What a command produces, structured rather than rendered.
+ *
+ * The SDK formats nothing. A TUI draws a table, a JSON command prints a
+ * document, a web host renders a component — and a pre-rendered string
+ * would force all three to parse prose back into the fields it was built
+ * from. Returning the fields is the only shape that serves a host the
+ * kernel has never seen.
+ */
+export type HostCommandOutcome =
+	| { readonly kind: 'report'; readonly title: string; readonly rows: readonly HostCommandRow[] }
+	| { readonly kind: 'prompt'; readonly text: string }
+	| { readonly kind: 'ack'; readonly message: string }
+	/**
+	 * The command exists and cannot answer right now.
+	 *
+	 * Different from an empty `report`, and different from `undefined`. An
+	 * empty report says "I looked and there are none"; this says "I could
+	 * not look", and a host that conflates them shows an operator a
+	 * confident zero for a question nobody answered.
+	 */
+	| { readonly kind: 'refused'; readonly reason: string }
+
+/** One line of a report. Keys are column names; a host decides the order. */
+export type HostCommandRow = Readonly<Record<string, string | number | boolean | null>>
+
+export interface HostCommandContext {
+	/** Whatever followed the command name, unparsed. */
+	readonly args: readonly string[]
+}
+
+/**
+ * A command as it is registered, handler included.
+ *
+ * `args` is JSON Schema rather than Zod, for the same reason
+ * `ToolDefinition.modelInputSchema` is: a descriptor has to survive being
+ * sent to a host that is not this process, and a Zod schema does not
+ * serialize.
+ */
+export interface HostCommandDescriptor {
+	readonly name: string
+	readonly description: string
+	/** One line a host can show beside the name. */
+	readonly hint?: string
+	/** JSON Schema for the arguments, when the command takes any. */
+	readonly args?: Record<string, unknown>
+	handler(ctx: HostCommandContext): Promise<HostCommandOutcome> | HostCommandOutcome
+}
+
+/** The same descriptor with the handler removed, safe to serialize. */
+export type SerializableHostCommand = Omit<HostCommandDescriptor, 'handler'>

package/src/types/common/index.ts

@@ -1,6 +1,30 @@
-export type AgentStatus = 'idle' | 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+/**
+ * The lifecycle of one RUN.
+ *
+ * Named for what it types. Every one of its uses in this package is a
+ * run's status, a run's audit outcome, or the status field of a run's
+ * result -- none of them describe an `AbstractAgent` or a
+ * `ReactiveAgent`, which have no status of their own. The old name sent a
+ * reader looking for an agent's lifecycle to the type that governs a run.
+ */
+export type RunExecutionStatus =
+	| 'idle'
+	| 'pending'
+	| 'running'
+	| 'completed'
+	| 'failed'
+	| 'cancelled'
+
+/**
+ * @deprecated Use {@link RunExecutionStatus}. Removal is a later major.
+ *
+ * The union is unchanged -- this is a rename, and the alias is here so
+ * code written against the old name still compiles and warns for one
+ * release, per SemVer's deprecate-before-remove.
+ */
+export type AgentStatus = RunExecutionStatus
 
-export function isTerminalStatus(status: AgentStatus): boolean {
+export function isTerminalStatus(status: RunExecutionStatus): boolean {
 	return status === 'completed' || status === 'failed' || status === 'cancelled'
 }
 

package/src/types/connector/mcp.ts

@@ -1,3 +1,4 @@
+import type { Logger } from '../../utils/logger.js'
 import type { ConnectorId, ConnectorInstanceId, MCPClientId, MCPServerId } from '../ids/index.js'
 import type {
 	ConnectorDefinition,
@@ -218,6 +219,13 @@ export interface MCPClientConfig {
 	 * forever — no error, no failure, just a run that stopped.
 	 */
 	requestTimeoutMs?: number
+	/**
+	 * A pre-built logger. Threaded into the transport `MCPClient` constructs
+	 * internally (`createTransport`), so a caller that supplies this gets a
+	 * correlated client AND a correlated transport from one field, rather
+	 * than each reaching for its own process-default child.
+	 */
+	logger?: Logger
 }
 
 export interface MCPClientState {