@namzu/sdk 30.2.0 → 31.0.0

package/src/tools/builtins/write-file.ts

@@ -1,10 +1,11 @@
-import { access, mkdir } from 'node:fs/promises'
+import { mkdir, readFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import { z } from 'zod'
 import type { ToolContext, ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinReal } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
+import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 
 const inputSchema = z
@@ -144,13 +145,16 @@ export const WriteFileTool = defineTool({
 
 		return withFileMutationLock(lockKey, async () => {
 			if (context.sandbox) {
-				const sandboxExists = await sandboxFileExists(context, valid.path)
-				if (sandboxExists) {
-					const guard = enforceReadBeforeOverwrite(context, valid.path)
+				const current = await readSandboxFileIfPresent(context, valid.path)
+				if (current !== undefined) {
+					const guard = enforceFreshOverwrite(context, valid.path, current.toString('utf-8'))
 					if (guard) return guard
 				}
 				await context.sandbox.writeFile(valid.path, content)
-				context.fileReadTracker?.recordRead(valid.path)
+				// This write is now the runtime's newest observation. Recording only
+				// the boolean would leave an older content fingerprint in place and
+				// make the next same-run write refuse its own predecessor as drift.
+				context.fileReadTracker?.recordRead(valid.path, content)
 				return {
 					success: true as const,
 					output: `File written successfully: ${valid.path} (${content.length} chars) [sandboxed]`,
@@ -159,9 +163,9 @@ export const WriteFileTool = defineTool({
 			}
 
 			const hostPath = filePath as string
-			const localExists = await pathExists(hostPath)
-			if (localExists) {
-				const guard = enforceReadBeforeOverwrite(context, hostPath)
+			const current = await readHostFileIfPresent(hostPath)
+			if (current !== undefined) {
+				const guard = enforceFreshOverwrite(context, hostPath, current)
 				if (guard) return guard
 			}
 
@@ -170,7 +174,7 @@ export const WriteFileTool = defineTool({
 			// leaves the destination truncated — and this tool overwrites a
 			// whole file, so the truncation is the user's previous work.
 			await atomicWriteFile(hostPath, content)
-			context.fileReadTracker?.recordRead(hostPath)
+			context.fileReadTracker?.recordRead(hostPath, content)
 
 			return {
 				success: true as const,
@@ -194,21 +198,53 @@ function enforceReadBeforeOverwrite(
 	}
 }
 
-async function pathExists(hostPath: string): Promise<boolean> {
+function enforceFreshOverwrite(
+	context: ToolContext,
+	key: string,
+	currentContent: string,
+): { success: false; output: ''; error: string } | null {
+	const unread = enforceReadBeforeOverwrite(context, key)
+	if (unread) return unread
+
+	// Optional forever: older hosts only tracked the boolean read-before-write
+	// fact. They retain their old behavior rather than being refused on a
+	// fingerprint the host never promised to capture.
+	const observed = context.fileReadTracker?.fingerprint?.(key)
+	if (observed !== undefined && observed !== fingerprintContent(currentContent)) {
+		return { success: false, output: '', error: staleFileError(key, 'write') }
+	}
+	return null
+}
+
+async function readHostFileIfPresent(hostPath: string): Promise<string | undefined> {
 	try {
-		await access(hostPath)
-		return true
-	} catch {
-		return false
+		return await readFile(hostPath, 'utf-8')
+	} catch (error) {
+		if (isMissingFileError(error)) return undefined
+		throw error
 	}
 }
 
-async function sandboxFileExists(context: ToolContext, path: string): Promise<boolean> {
-	if (!context.sandbox) return false
+function isMissingFileError(error: unknown): boolean {
+	return (
+		typeof error === 'object' &&
+		error !== null &&
+		'code' in error &&
+		(error as { code?: unknown }).code === 'ENOENT'
+	)
+}
+
+async function readSandboxFileIfPresent(
+	context: ToolContext,
+	path: string,
+): Promise<Buffer | undefined> {
+	if (!context.sandbox) return undefined
 	try {
-		await context.sandbox.readFile(path)
-		return true
+		return await context.sandbox.readFile(path)
 	} catch {
-		return false
+		// `Sandbox` currently has no typed missing-file result. Preserve the
+		// existing create behavior for all backends; when a read succeeds, the
+		// exact body above is still a real admission-time freshness check.
+		return undefined
 	}
 }

package/src/tools/command-arguments.ts

@@ -0,0 +1,54 @@
+/**
+ * Which argument of a tool holds a shell command line.
+ *
+ * ## Why a host needs this
+ *
+ * A host that compiles operator config into gate rules has a tool NAME and a
+ * pattern, and needs an argument to attach the pattern to. Without one it can
+ * only reach for `custom_pattern`, whose subject is `JSON.stringify(input)` —
+ * and matching a glob against a serialised object costs both halves of what an
+ * operator meant. The pattern can match the start of any argument's value
+ * rather than the one they had in mind, and it stays open on the right, so
+ * `bash = { "git status*" = "allow" }` compiled to a rule that also approved
+ * `git status && rm -rf ~`.
+ *
+ * `argument_pattern` has neither problem, and it reads the value as the
+ * commands it runs. Reaching it needs exactly one fact this function supplies.
+ *
+ * ## Why it is derived rather than written down
+ *
+ * A list of "tools whose first argument is a command" maintained beside the
+ * tools is a list that drifts from them, and this repository has now gated
+ * that same shape four times. So the fact lives on the tool as
+ * {@link ToolDefinition.commandArgument} and this reads it back.
+ *
+ * A host with its own tools should ask {@link commandArgumentOf} with the
+ * definition it already holds. {@link builtinCommandArguments} exists for the
+ * case where only the name is available — permission config is compiled before
+ * any tool is constructed — and answers for the builtin set alone. An unknown
+ * name gets `undefined`, which is a host falling back to what it did before
+ * rather than a wrong answer.
+ */
+
+import type { ToolDefinition } from '../types/tool/index.js'
+import { getBuiltinTools } from './builtins/index.js'
+
+/** The argument holding a command line, or undefined when the tool has none. */
+export function commandArgumentOf(tool: ToolDefinition): string | undefined {
+	return tool.commandArgument
+}
+
+/**
+ * The builtin tools that take a command line, by tool name.
+ *
+ * Computed on each call rather than cached at module load: a frozen snapshot
+ * taken at import time is a copy of the registry, and a copy is the thing this
+ * module exists to avoid.
+ */
+export function builtinCommandArguments(): ReadonlyMap<string, string> {
+	const byName = new Map<string, string>()
+	for (const tool of getBuiltinTools()) {
+		if (tool.commandArgument !== undefined) byName.set(tool.name, tool.commandArgument)
+	}
+	return byName
+}

package/src/tools/coordinator/index.ts

@@ -107,6 +107,9 @@ export interface CoordinatorToolsOptions {
 	pendingAnswers?: PendingAnswers
 }
 
+/** Internal identity shared by the builder and the agent authority boundary. */
+export const ASK_USER_QUESTION_TOOL_NAME = 'ask_user_question' as const
+
 const approvePlanStepSchema = z.object({
 	description: z.string().describe('What this step does'),
 	agent_id: z
@@ -1472,7 +1475,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		const parkRunId = runId
 		const parkHandler = resumeHandler
 		const askUserQuestion = defineTool({
-			name: 'ask_user_question',
+			name: ASK_USER_QUESTION_TOOL_NAME,
 			description:
 				'Ask the user ONE question ONLY when you are blocked on a decision that is genuinely theirs to make — one you cannot resolve from their request, your tools, the files you can read, or sensible defaults. The question must be the genuinely undecidable thing in THIS task. Never ask for information a tool can discover (do not ask what you can read, list, or search), never re-ask what the conversation already answers, and never ask meta-questions like "Shall I proceed?" — plan ratification goes through approve_plan. Provide 2-4 genuinely distinct options derived from the actual context — concrete paths, never generic placeholders (for example, asked to prepare a presentation, ask "Who is the audience?" with options like Board / Engineering team / Customer); keep labels short (1-5 words) and give each option a one-line description of what practically changes if it is chosen. Put your recommended option FIRST and append " (Recommended)" to its label. Set multiSelect: true only when several options can apply at once. A free-text "Something else" escape hatch is always shown automatically — do not add your own "Other" option. Ask ONE question per call and prefer at most one question per assistant turn; if several decisions block you, ask only the ones that materially change your next actions, in sequence — most work needs at most 2-3 questions, so prefer proceeding on stated defaults over interrogating the user. Never invent answers or synthetic content on the user\'s behalf unless they explicitly asked for a random/test scenario. The answer arrives as this tool\'s result; if the result says the user did not answer, do not ask this or any other question again — proceed on your best judgment without assuming consent.',
 			inputSchema: z

package/src/tools/defineTool.ts

@@ -48,6 +48,16 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	outputSchema?: Record<string, unknown>
 	/** Settle the run with this tool's output; see {@link ToolDefinition.terminal}. */
 	terminal?: boolean
+	/**
+	 * The argument holding a shell command line; see
+	 * {@link ToolDefinition.commandArgument}.
+	 *
+	 * Here as well as on the definition for the reason `maxRetries` and
+	 * `presentCall` are: this builder is the sanctioned way to author a tool,
+	 * and a field a host reads that the builder cannot set is a field only
+	 * hand-written definitions can use.
+	 */
+	commandArgument?: string
 	execute(input: z.infer<S>, context: ToolContext): Promise<ToolResult>
 }
 
@@ -66,6 +76,7 @@ export function defineTool<S extends z.ZodType>(
 		tier: options.tier,
 		...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
 		...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
+		...(options.commandArgument !== undefined ? { commandArgument: options.commandArgument } : {}),
 		...(options.presentCall ? { presentCall: options.presentCall } : {}),
 		...(options.presentResult ? { presentResult: options.presentResult } : {}),
 		...(options.outputSchema !== undefined ? { outputSchema: options.outputSchema } : {}),

package/src/tools/env-scrub.ts

@@ -20,11 +20,13 @@
  * still reach the command.
  *
  * The actual boundary is the sandbox, where the inherited set is an allowlist
- * (`SANDBOX_SAFE_ENV_KEYS`, seven keys) rather than a denylist. An allowlist
- * is correct there because a sandbox is a fresh environment; it is wrong on
- * the host path, where the same agent is expected to run `pnpm test`, `make`
- * and `docker build`, all of which need far more than seven variables. So the
- * host path gets the weaker control on purpose, and says so.
+ * (the local sandbox's bounded core-process keys) rather than a denylist. Its
+ * Windows branch includes the system-root, command-interpreter and profile
+ * plumbing a working Windows child needs; it still carries no ambient
+ * credential keys. An allowlist is correct there because a sandbox is a fresh
+ * environment; it is wrong on the host path, where the same agent is expected
+ * to run `pnpm test`, `make` and `docker build`, all of which need far more
+ * variables. So the host path gets the weaker control on purpose, and says so.
  *
  * ## Why this exists at all
  *

package/src/tools/goal/index.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod'
+
+import { GoalNotFoundError, type SessionGoalStore, StaleGoalError } from '../../store/goal/index.js'
+import type { GoalRoundAuthority, SessionGoal } from '../../types/goal/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { defineTool } from '../defineTool.js'
+
+export const SESSION_GOAL_TOOL_NAMES = ['get_goal', 'update_goal'] as const
+export const MIN_GOAL_BLOCK_ROUND = 3
+
+/** Resolve authority captured for one caller-reserved run id. */
+export type ResolveGoalRoundAuthority = (runId: RunId) => GoalRoundAuthority | null | undefined
+
+/** A goal tool was reached outside the one run whose admission authorized it. */
+export class GoalRoundAuthorityError extends Error {
+	constructor(runId: RunId) {
+		super(`Run ${runId} has no admitted goal-round authority.`)
+		this.name = 'GoalRoundAuthorityError'
+	}
+}
+
+async function currentGoal(
+	store: SessionGoalStore,
+	authority: GoalRoundAuthority,
+): Promise<SessionGoal> {
+	const goal = await store.getGoal(authority.sessionId, authority.tenantId)
+	if (!goal) throw new GoalNotFoundError(authority.sessionId)
+	if (goal.id !== authority.id || goal.revision !== authority.revision) {
+		throw new StaleGoalError({
+			sessionId: authority.sessionId,
+			expectedRevision: authority.revision,
+			actualRevision: goal.revision,
+		})
+	}
+	return goal
+}
+
+function authorityFor(
+	resolveAuthority: ResolveGoalRoundAuthority,
+	runId: RunId,
+): GoalRoundAuthority {
+	const authority = resolveAuthority(runId)
+	if (!authority) throw new GoalRoundAuthorityError(runId)
+	return authority
+}
+
+/**
+ * Run-scoped tools for an admitted SessionGoal round.
+ *
+ * Registration is not authorization. A host must also withhold these names
+ * from every non-goal provider request and executor allow-list.
+ */
+export function buildSessionGoalTools(
+	store: SessionGoalStore,
+	resolveAuthority: ResolveGoalRoundAuthority,
+): ToolDefinition[] {
+	const getGoal = defineTool({
+		name: 'get_goal',
+		description:
+			'Read the exact completion goal and admitted-round budget that authorized this automatic turn.',
+		inputSchema: z.object({}),
+		category: 'analysis',
+		permissions: [],
+		readOnly: true,
+		destructive: false,
+		concurrencySafe: true,
+		async execute(_input, context) {
+			const authority = authorityFor(resolveAuthority, context.runId)
+			const goal = await currentGoal(store, authority)
+			return {
+				success: true,
+				output: JSON.stringify({
+					id: goal.id,
+					objective: goal.objective,
+					phase: goal.phase,
+					round: authority.round,
+					maxGoalRounds: goal.maxGoalRounds,
+					roundsAdmitted: goal.roundsAdmitted,
+				}),
+				data: goal,
+			}
+		},
+	})
+
+	const updateGoal = defineTool({
+		name: 'update_goal',
+		description:
+			'Mark this admitted goal complete, or blocked after at least three admitted rounds. This does not end the turn; explain the final state to the operator afterward.',
+		inputSchema: z.object({
+			status: z.enum(['complete', 'blocked']),
+			reasonCode: z
+				.string()
+				.optional()
+				.describe('Lower-kebab-case reason code; required when status is blocked.'),
+			reason: z.string().optional().describe('Operator-readable reason; required when blocked.'),
+		}),
+		category: 'custom',
+		permissions: [],
+		readOnly: false,
+		destructive: false,
+		concurrencySafe: false,
+		async execute({ status, reasonCode, reason }, context) {
+			const authority = authorityFor(resolveAuthority, context.runId)
+			await currentGoal(store, authority)
+			const ref = { id: authority.id, revision: authority.revision }
+			if (status === 'complete') {
+				const goal = await store.completeGoal(authority.sessionId, authority.tenantId, ref)
+				return { success: true, output: 'Goal marked complete.', data: goal }
+			}
+
+			if (authority.round < MIN_GOAL_BLOCK_ROUND) {
+				throw new Error(
+					`A goal cannot be marked blocked before admitted round ${MIN_GOAL_BLOCK_ROUND}; this is round ${authority.round}.`,
+				)
+			}
+			if (!reasonCode || !reason) {
+				throw new TypeError('Blocked goal updates require reasonCode and reason.')
+			}
+			const goal = await store.blockGoal(authority.sessionId, authority.tenantId, ref, {
+				code: reasonCode,
+				message: reason,
+			})
+			return { success: true, output: 'Goal marked blocked.', data: goal }
+		},
+	})
+
+	return [getGoal, updateGoal]
+}

package/src/tools/memory/index.ts

@@ -2,10 +2,33 @@ import type { MemoryIndex, MemoryStore } from '../../types/memory/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { buildReadMemoryTool } from './read.js'
 import { buildSaveMemoryTool } from './save.js'
-import { buildSearchMemoryTool } from './search.js'
+import { buildSearchMemoryTool, buildStoreSearchMemoryTool } from './search.js'
 
-export function buildMemoryTools(store: MemoryStore, index: MemoryIndex): ToolDefinition[] {
-	return [buildSearchMemoryTool(index), buildReadMemoryTool(store), buildSaveMemoryTool(store)]
+/**
+ * Build memory tools over one authoritative store.
+ *
+ * This is the safe default for asynchronous or lazy stores: `search_memory`
+ * crosses the store's own `list()` boundary, so a fresh disk-backed instance
+ * loads its durable index before answering the first search.
+ */
+export function buildMemoryTools(store: MemoryStore): ToolDefinition[]
+
+/**
+ * Build memory tools with a caller-owned search index.
+ *
+ * The index is deliberately authoritative in this form. It may be remote,
+ * pre-populated or otherwise unrelated to the content store, so searching it
+ * must not first call `store.list()` and invent a readiness dependency that
+ * this contract never promised.
+ */
+export function buildMemoryTools(store: MemoryStore, index: MemoryIndex): ToolDefinition[]
+
+export function buildMemoryTools(store: MemoryStore, index?: MemoryIndex): ToolDefinition[] {
+	return [
+		index ? buildSearchMemoryTool(index) : buildStoreSearchMemoryTool(store),
+		buildReadMemoryTool(store),
+		buildSaveMemoryTool(store),
+	]
 }
 
 export { buildSearchMemoryTool } from './search.js'

package/src/tools/memory/search.ts

@@ -1,9 +1,16 @@
 import { z } from 'zod'
-import type { MemoryIndex } from '../../types/memory/index.js'
+import type {
+	MemoryIndex,
+	MemorySearchParams,
+	MemorySearchResult,
+	MemoryStore,
+} from '../../types/memory/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 
-export function buildSearchMemoryTool(index: MemoryIndex): ToolDefinition {
+type SearchMemory = (params: MemorySearchParams) => MemorySearchResult | Promise<MemorySearchResult>
+
+function defineSearchMemoryTool(search: SearchMemory): ToolDefinition {
 	return defineTool({
 		name: 'search_memory',
 		description:
@@ -19,7 +26,7 @@ export function buildSearchMemoryTool(index: MemoryIndex): ToolDefinition {
 		destructive: false,
 		concurrencySafe: true,
 		async execute({ query, tags, limit }) {
-			const result = index.search({ query, tags, limit })
+			const result = await search({ query, tags, limit })
 
 			if (result.entries.length === 0) {
 				return {
@@ -50,3 +57,13 @@ export function buildSearchMemoryTool(index: MemoryIndex): ToolDefinition {
 		},
 	})
 }
+
+/** Build search over a caller-owned, already-ready synchronous index. */
+export function buildSearchMemoryTool(index: MemoryIndex): ToolDefinition {
+	return defineSearchMemoryTool((params) => index.search(params))
+}
+
+/** Build search over the store's authoritative asynchronous read boundary. */
+export function buildStoreSearchMemoryTool(store: MemoryStore): ToolDefinition {
+	return defineSearchMemoryTool((params) => store.list(params))
+}

package/src/types/agent/base.ts

@@ -1,3 +1,4 @@
+import type { ProjectInstructionContext } from '../../runtime/query/project-instructions.js'
 import type { Logger } from '../../utils/logger.js'
 import type { CostInfo, RunExecutionStatus, TokenUsage } from '../common/index.js'
 import type { ResumeHandler } from '../hitl/index.js'
@@ -18,6 +19,10 @@ export interface BaseAgentConfig {
 	model: string
 	tokenBudget: number
 	timeoutMs: number
+	/** See {@link import('../run/config.js').AgentRunConfig.streamIdleTimeoutMs}. */
+	streamIdleTimeoutMs?: number
+	/** See {@link import('../run/config.js').AgentRunConfig.maxRequestRichContentBytes}. */
+	maxRequestRichContentBytes?: number
 	maxIterations?: number
 	temperature?: number
 	maxResponseTokens?: number
@@ -57,6 +62,9 @@ export interface BaseAgentConfig {
 	 */
 	inboundMessages?: () => import('../message/index.js').Message[]
 
+	/** Live project policy, flushed independently of human continuation text. */
+	projectInstructionContext?: ProjectInstructionContext
+
 	allowedTools?: readonly string[]
 
 	/**
@@ -184,7 +192,7 @@ export interface BaseAgentConfig {
 
 	/**
 	 * Where this agent takes a decision it cannot make alone — a tool that
-	 * needs approval, a question for a human, a plan to sign off.
+	 * needs approval, a root-agent question for a human, a plan to sign off.
 	 *
 	 * Declared HERE, on the base config, rather than only on the agent
 	 * shapes that happened to want it. `AgentManager` builds a child as a
@@ -203,8 +211,9 @@ export interface BaseAgentConfig {
 	 * had a human review `write` at the top level and never see the same
 	 * `write` issued one hop down.
 	 *
-	 * Absent still means auto-approve, so a host that never wired one is
-	 * unaffected.
+	 * A delegated agent inherits this channel for review but does not gain the
+	 * root-only `ask_user_question` tool. Absent still means auto-approve, so a
+	 * host that never wired one is unaffected.
 	 */
 	resumeHandler?: ResumeHandler
 }

package/src/types/agent/factory.ts

@@ -46,6 +46,8 @@ export interface AgentFactoryOptions {
 	workingDirectory?: string
 	tokenBudget?: number
 	timeoutMs?: number
+	streamIdleTimeoutMs?: number
+	maxRequestRichContentBytes?: number
 	temperature?: number
 	maxResponseTokens?: number
 	env?: Record<string, string>

package/src/types/agent/reactive.ts

@@ -64,6 +64,8 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	 * on top of the provider keeps the underlying container alive.
 	 */
 	sandboxProvider?: SandboxProvider
+	/** See {@link QueryParams.sandboxTeardownTimeoutMs}. */
+	sandboxTeardownTimeoutMs?: number
 
 	/**
 	 * Optional structured-compaction config. Omitted ⇒ byte-identical run path

package/src/types/agent/supervisor.ts

@@ -138,6 +138,10 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 * handler that surfaces the `tool_review_requested` RunEvent to
 	 * the user and resolves the returned promise once the user
 	 * approves, rejects, or modifies the call.
+	 *
+	 * The root supervisor also uses this channel for `ask_user_question`.
+	 * Delegated supervisors keep the review channel but do not publish that
+	 * interactive tool; their root owns operator questions.
 	 */
 	resumeHandler?: ResumeHandler
 
@@ -173,6 +177,8 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 * + children share one ephemeral container per task.
 	 */
 	sandboxProvider?: SandboxProvider
+	/** See {@link import('../../runtime/query/index.js').QueryParams.sandboxTeardownTimeoutMs}. */
+	sandboxTeardownTimeoutMs?: number
 
 	/**
 	 * Optional structured-compaction config. When omitted, `query()` never

package/src/types/agent/task.ts

@@ -42,8 +42,12 @@ export interface AgentTaskContext {
 	factoryOptions?: AgentFactoryOptions
 
 	/**
-	 * The parent's channel to whoever can answer a decision it cannot make
-	 * alone, handed down so a child asks the same person.
+	 * The parent's channel to whoever reviews decisions it cannot make alone,
+	 * handed down so a child's REVIEW-tier tool calls reach the same person.
+	 * This does not grant a delegated agent the `ask_user_question` tool:
+	 * interactive questions are a root-agent capability, while authorization
+	 * review must remain inherited to avoid unattended auto-approval below the
+	 * root.
 	 *
 	 * Passed as the function itself, which works because delegation is
 	 * in-process: `LocalTaskScheduler` is the only `TaskScheduler` in the tree.

package/src/types/connector/core.ts

@@ -29,14 +29,9 @@ export interface ConnectorMethod<TInput = unknown, TOutput = unknown> {
 	description: string
 	inputSchema: z.ZodType<TInput, z.ZodTypeDef, unknown>
 	/**
-	 * **Not consulted.** Neither in-tree connector declares one, and nothing
-	 * validates a result against it or shows it to a model.
-	 *
-	 * The tool layer solved the same problem already: a remote tool's output
-	 * schema is appended to its description by `describeWithOutput`, because
-	 * no provider's tool wire format has a slot for one. A connector method
-	 * that reaches a model through that bridge should take the same route
-	 * rather than growing a second mechanism.
+	 * Canonical output contract for this method. ConnectorManager validates a
+	 * successful implementation result before publishing it and exposes the
+	 * rendered schema to tool and MCP consumers.
 	 */
 	outputSchema?: z.ZodType<TOutput, z.ZodTypeDef, unknown>
 }
@@ -64,6 +59,11 @@ export interface ConnectorMethod<TInput = unknown, TOutput = unknown> {
  * in-process dedupe seam and names the cross-process half as its known
  * gap, and `EditOwnershipTracker.claim` is the claim/refuse shape with
  * same-owner idempotency already worked out.
+ *
+ * @deprecated The SDK does not subscribe to or dispatch connector triggers.
+ * Keep inbound subscription metadata in a host-owned type and store. This
+ * declaration remains for one migration release because a host may already
+ * use `ConnectorRegistry` as its own metadata table.
  */
 export interface ConnectorTrigger {
 	name: string
@@ -72,6 +72,11 @@ export interface ConnectorTrigger {
 	configSchema?: z.ZodType
 }
 
+/**
+ * @deprecated The SDK does not emit inbound connector events. Define the
+ * event envelope at the host boundary that owns subscription, de-duplication,
+ * delivery, and run admission.
+ */
 export interface ConnectorEvent {
 	connectorId: ConnectorId
 	instanceId: ConnectorInstanceId