@namzu/sdk 37.0.0 → 38.1.0

package/src/types/agent/scheduler.ts

@@ -54,6 +54,10 @@ export interface CreateTaskOptions {
 	 */
 	readonly parentSpan?: import('@opentelemetry/api').Span
 
+	/** Approved plan edge for live worker/progress correlation. */
+	readonly planId?: string
+	readonly planStepId?: string
+
 	agentId: string
 
 	/**

package/src/types/agent/task.ts

@@ -154,6 +154,10 @@ export interface SendMessageOptions {
 	/** See {@link import('./scheduler.js').CreateTaskOptions.personaOverride}. */
 	readonly personaOverride?: import('../persona/index.js').AgentPersona
 
+	/** Approved plan edge inherited from the delegation tool, when present. */
+	readonly planId?: string
+	readonly planStepId?: string
+
 	agentId: string
 
 	input: AgentInput

package/src/types/plugin/index.ts

@@ -8,6 +8,10 @@ import {
 	MAX_TOOLS_PER_PLUGIN,
 	PLUGIN_NAME_MAX_LENGTH,
 } from '../../constants/plugin/index.js'
+import type {
+	RequestContextChange,
+	RequestContextSnapshot,
+} from '../../runtime/query/request-context.js'
 import type { PluginId, RunId, SessionId } from '../ids/index.js'
 import type { Message, ToolResultContent } from '../message/index.js'
 import type { CancelCause } from '../run/cancel-cause.js'
@@ -142,6 +146,12 @@ export function assertPluginHookEvent(event: PluginHookEvent): void {
  * contract by accident.
  */
 export interface PluginModelRequest {
+	/** SDK provider-input content inventory; excludes adapter/server-private transformations. */
+	readonly context?: {
+		readonly snapshot: RequestContextSnapshot
+		/** Compared with the preceding pre_llm_call in this run; absent on the first. */
+		readonly change?: RequestContextChange
+	}
 	readonly model: string
 	readonly messages: readonly Message[]
 	/** Names only. A hook auditing tool exposure needs the set, not the schemas. */

package/src/types/provider/chat.ts

@@ -34,6 +34,8 @@ export interface ChatCompletionParams {
 	 * calls may omit it; a provider then uses its own id, `model`, and index 0.
 	 */
 	providerRoute?: ProviderRoute
+	/** Opt in to provider-hosted web search. Absent means no hosted search. */
+	webSearch?: { mode: 'cached' | 'live' }
 	tools?: LLMToolSchema[]
 	/**
 	 * Provider hint naming tools whose model-facing JSON Schema should be

package/src/types/provider/config.ts

@@ -121,6 +121,8 @@ export interface MockProviderConfig extends MockScript {
  * degradation is loud instead of silent.
  */
 export interface ProviderCapabilities {
+	/** Explicit provider-hosted web search support; absent means unsupported. */
+	supportsHostedWebSearch?: boolean
 	/** Native JSON Schema response-format mapping. Absent means unsupported. */
 	supportsNativeStructuredOutput?: boolean
 	supportsTools: boolean

package/src/types/provider/interface.ts

@@ -19,6 +19,9 @@ export interface LLMProvider {
 	 */
 	readonly capabilities?: ProviderCapabilities
 
+	/** Refine hosted search support for a model and mode. Absent uses the driver-wide declaration. */
+	supportsHostedWebSearchFor?(model: string, mode: 'live' | 'cached'): boolean
+
 	/**
 	 * Retry behaviour this DRIVER wants, when the generic default is wrong
 	 * for the vendor behind it.

package/src/types/provider/stream.ts

@@ -9,6 +9,13 @@ export interface StreamChunk {
 	 */
 	replayState?: unknown
 	delta: {
+		/** Activity executed by the provider, never a local function-call request. */
+		hostedTool?: {
+			id: string
+			name: 'web_search'
+			status: 'running' | 'completed' | 'failed'
+		}
+
 		content?: string
 		toolCalls?: Array<{
 			index: number

package/src/types/run/config.ts

@@ -65,6 +65,8 @@ export interface AgentRunConfig {
 	 * high-effort and silently was not is worse than a startup error.
 	 */
 	effort?: import('../provider/index.js').ReasoningEffort
+	/** Provider-hosted search for this run. Explicit opt-in; no local network permission. */
+	webSearch?: import('../provider/index.js').ChatCompletionParams['webSearch']
 	tokenBudget: number
 	costLimitUsd?: number
 	maxIterations?: number

package/src/types/run/events.ts

@@ -17,6 +17,7 @@ import type { Message } from '../message/index.js'
 import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
 import type { TaskStatus } from '../task/index.js'
+import type { ToolResultView } from '../tool/presentation.js'
 import type { CancelCause } from './cancel-cause.js'
 import type { FencingToken } from './checkpoint-store.js'
 import type { Lineage } from './lineage.js'
@@ -367,6 +368,13 @@ type CoreRunEvent =
 			/** Optional completion in [0,1] when the tool genuinely knows it. */
 			fraction?: number
 	  }
+	/** Provider-executed activity, retained as evidence rather than a local tool request. */
+	| {
+			type: 'hosted_tool'
+			runId: RunId
+			iteration: number
+			tool: NonNullable<import('../provider/index.js').StreamChunk['delta']['hostedTool']>
+	  }
 	/**
 	 * A model call failed transiently and is being retried after a backoff.
 	 *
@@ -426,6 +434,8 @@ type CoreRunEvent =
 	  }
 	| {
 			type: 'tool_completed'
+			/** Bounded result view; omitted when output was overridden or truncated. */
+			presentation?: ToolResultView
 			runId: RunId
 			toolUseId: ToolUseId
 			toolName: string
@@ -797,6 +807,9 @@ type CoreRunEvent =
 			parentAgentId: string
 			childAgentId: string
 			depth: number
+			/** Approved plan edge carried while the blocking tool is still live. */
+			planId?: string
+			planStepId?: string
 	  }
 	| {
 			type: 'agent_completed'

package/src/types/sandbox/index.ts

@@ -233,6 +233,34 @@ export interface SandboxSpawnOptions {
 	readonly env?: Record<string, string>
 }
 
+/**
+ * One host-side end of a TCP connection opened from inside the sandbox.
+ *
+ * The connection is intentionally narrower than general sandbox networking:
+ * callers may reach a loopback service already running in the sandbox, while
+ * the sandbox's egress policy remains unchanged. This is the primitive a
+ * development-workspace gateway uses to publish an HTTP/WebSocket preview
+ * without copying the checkout into a second container.
+ */
+export interface SandboxTcpConnection {
+	/** Queue bytes for the guest. False means pause the producer until onDrain. */
+	write(data: string | Uint8Array): boolean
+	end(): void
+	destroy(): void
+	/** Pause/resume bytes arriving from the guest without closing the stream. */
+	pause(): void
+	resume(): void
+	onData(listener: (chunk: Uint8Array) => void): () => void
+	onDrain(listener: () => void): () => void
+	readonly closed: Promise<void>
+}
+
+export interface SandboxTcpConnectOptions {
+	readonly port: number
+	/** Only guest loopback addresses are supported by the built-in backend. */
+	readonly host?: '127.0.0.1' | '::1'
+}
+
 export interface Sandbox {
 	readonly id: SandboxId
 	readonly status: SandboxStatus
@@ -281,11 +309,18 @@ export interface Sandbox {
 	 * with `rootDir` as its working directory does not satisfy either the
 	 * confinement or the ownership contract.
 	 *
-	 * @deprecated No built-in backend currently satisfies both guarantees.
-	 * Use a separately owned terminal backend; this member will be removed in
-	 * a future major release after the repository's deprecation window.
+	 * The Firecracker backend satisfies both guarantees by owning the PTY in the
+	 * guest and awaiting its exit before the microVM is released. Backends that
+	 * cannot provide that boundary omit the capability.
 	 */
 	openTerminal?(options: OpenTerminalOptions): Promise<TerminalSession>
+	/**
+	 * Connect to a loopback TCP service owned by this same sandbox.
+	 *
+	 * Optional. A backend that cannot preserve the same-workspace boundary must
+	 * omit this capability rather than proxying to a different filesystem.
+	 */
+	openTcpConnection?(options: SandboxTcpConnectOptions): Promise<SandboxTcpConnection>
 	writeFile(path: string, content: string | Buffer): Promise<void>
 	readFile(path: string): Promise<Buffer>
 	/**
@@ -310,6 +345,7 @@ export interface Sandbox {
 	listFiles(rootPath: string): Promise<readonly SandboxFileEntry[]>
 	/**
 	 * Lazily enumerate regular files as absolute paths, without following symlinks.
+	 * A regular-file root yields that file if its basename matches the pattern.
 	 * Cancellation and iterator return stop traversal. Exceeding the examined-entry
 	 * budget throws an error with code `ERR_FILE_WALK_LIMIT`; it is not an empty or
 	 * complete listing. Hosts requiring bounded search must refuse an absent method.
@@ -475,7 +511,10 @@ export interface ContainerSandboxLayout {
  * can inspect the post-default layout the model actually sees.
  */
 export interface ResolvedContainerSandboxLayout {
-	readonly outputs: { readonly source: ContainerSandboxMountSource; readonly containerPath: string }
+	readonly outputs: {
+		readonly source: ContainerSandboxMountSource
+		readonly containerPath: string
+	}
 	readonly uploads?: {
 		readonly source: ContainerSandboxMountSource
 		readonly containerPath: string

package/src/types/tool/presentation.ts

@@ -22,6 +22,8 @@ export type ToolCallView =
 			readonly label: string
 			/** Render this complete authored label without adding the registry name. */
 			readonly presentation?: 'activity'
+			/** Successful observations may be grouped by hosts without discarding output. */
+			readonly activity?: 'exploration'
 			/** A successful result may add no information beyond the completed call row. */
 			readonly visibility?: 'hidden'
 	  }
@@ -32,6 +34,8 @@ export type ToolCallView =
 	 */
 	| {
 			readonly kind: 'diff'
+			/** Optional operation summary, distinct from the file path. */
+			readonly label?: string
 			readonly path?: string
 			readonly before: string
 			readonly after: string