@namzu/sdk 0.6.0 → 1.1.0

package/src/types/agent/index.ts

@@ -9,3 +9,4 @@ export * from './gateway.js'
 export * from './task.js'
 export * from './lifecycle-event.js'
 export * from './manager.js'
+export * from './working-memory.js'

package/src/types/agent/reactive.ts

@@ -1,9 +1,13 @@
+import type { CompactionConfig } from '../../config/runtime.js'
 import type { AdvisoryConfig } from '../advisory/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 { Skill } from '../skills/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 { WorkingMemoryProvider } from './working-memory.js'
 
 export interface ReactiveAgentConfig extends BaseAgentConfig {
 	systemPrompt?: string
@@ -17,6 +21,44 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	tools: ToolRegistryContract
 
 	advisory?: AdvisoryConfig
+
+	/**
+	 * Optional capability-aware deny/allow gate for child tool calls.
+	 * Mirrors the same field on `SupervisorAgentConfig`; 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.
+	 */
+	verificationGate?: VerificationGateConfig
+
+	/**
+	 * 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 run end the
+	 * SDK calls `sandbox.destroy()`. Hosts that want a per-task
+	 * container shared across supervisor + every child specialist run
+	 * pass the SAME provider instance to all of them — caching layered
+	 * on top of the provider keeps the underlying container alive.
+	 */
+	sandboxProvider?: SandboxProvider
+
+	/**
+	 * Optional structured-compaction config. Omitted ⇒ byte-identical run path
+	 * (no `WorkingStateManager`, compaction early-returns). Mirrors the field
+	 * on `SupervisorAgentConfig` so a child specialist can share the
+	 * supervisor's compaction settings.
+	 */
+	compactionConfig?: CompactionConfig
+
+	/**
+	 * Optional neutral working-memory seam — same contract as the field on
+	 * `SupervisorAgentConfig`. Absent ⇒ no block injected. A child specialist
+	 * sharing the supervisor's output dir passes the same provider.
+	 */
+	workingMemoryProvider?: WorkingMemoryProvider
 }
 
 export interface ReactiveAgentResult extends BaseAgentResult {

package/src/types/agent/supervisor.ts

@@ -1,12 +1,17 @@
+import type { CompactionConfig } from '../../config/runtime.js'
 import type { AdvisoryConfig } from '../advisory/index.js'
 import type { ResumeHandler } from '../hitl/index.js'
 import type { LLMProvider } from '../provider/index.js'
 import type { TaskRouterConfig } from '../router/index.js'
+import type { SandboxProvider } from '../sandbox/index.js'
+import type { Skill } from '../skills/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 { TaskGateway } from './gateway.js'
 import type { AgentManagerContract } from './manager.js'
+import type { WorkingMemoryProvider } from './working-memory.js'
 
 export interface SupervisorAgentConfig extends BaseAgentConfig {
 	provider: LLMProvider
@@ -15,9 +20,12 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 
 	gateway?: TaskGateway
 	agentManager?: AgentManagerContract
+	tools?: ToolRegistryContract
 
 	systemPrompt: string
 
+	skills?: Skill[]
+
 	maxDepth?: number
 
 	taskRouter?: TaskRouterConfig
@@ -52,6 +60,34 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 * non-deterministic cases.
 	 */
 	verificationGate?: VerificationGateConfig
+
+	/**
+	 * Optional ephemeral sandbox provider. When set, drainQuery creates
+	 * a sandbox via `provider.create()` before the supervisor's own
+	 * iteration loop and routes filesystem / shell tool calls through
+	 * it. Multi-agent hosts thread the SAME provider instance into
+	 * every child `ReactiveAgentConfig.sandboxProvider` so supervisor
+	 * + children share one ephemeral container per task.
+	 */
+	sandboxProvider?: SandboxProvider
+
+	/**
+	 * Optional structured-compaction config. When omitted, `query()` never
+	 * builds a `WorkingStateManager` and compaction early-returns — the run
+	 * path is byte-identical to a non-compacting run. Hosts opt in (e.g. with
+	 * a `contextWindowTokens`) to keep a long single run alive instead of
+	 * silently truncating.
+	 */
+	compactionConfig?: CompactionConfig
+
+	/**
+	 * Optional neutral working-memory seam. When set, the SDK re-renders the
+	 * provider's string into a single pinned leading system message every
+	 * iteration (the primacy-edge, compaction-preserved slot). Absent ⇒ no
+	 * block is ever injected. The SDK only positions the string; the host owns
+	 * its content and trust framing.
+	 */
+	workingMemoryProvider?: WorkingMemoryProvider
 }
 
 export interface AgentTaskResult {

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

@@ -0,0 +1,29 @@
+/**
+ * Per-turn context the SDK is allowed to hand a working-memory provider.
+ *
+ * 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
+ * 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.
+ */
+export interface WorkingMemoryTurnContext {
+	/** The active run id (opaque). */
+	readonly runId: string
+	/** 1-based iteration counter for this run. */
+	readonly iteration: number
+}
+
+/**
+ * Returns a rendered, already-sanitized working-memory block to pin at the
+ * primacy edge (a single leading system message, refreshed every iteration).
+ *
+ * The SDK does no parsing of the returned string — it stores it verbatim under
+ * a sentinel header and re-pins it each turn. An empty/blank return ⇒ no block
+ * is injected (the byte-identical-when-empty property). Async so the host can
+ * `stat` the output dir / read the registry each turn. Failure-isolated by the
+ * SDK: a throwing/slow provider degrades to "no refresh this turn", never
+ * breaks the run.
+ */
+export type WorkingMemoryProvider = (ctx: WorkingMemoryTurnContext) => string | Promise<string>

package/src/types/common/index.ts

@@ -22,6 +22,25 @@ export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage):
 	}
 }
 
+/**
+ * Merge two usage snapshots seen WITHIN a single streamed turn. Provider usage
+ * frames over one stream are cumulative/monotonic (input set once early, output
+ * grows), but a late frame can OMIT a field (report 0) — e.g. Anthropic's
+ * `message_delta` may carry only output tokens. A naive last-write-wins
+ * (`usage = chunk.usage`) then drops the earlier prompt/cache counts and
+ * under-reports the turn. Taking the per-field high-water mark preserves every
+ * field. DISTINCT from {@link accumulateTokenUsage}, which SUMS across turns.
+ */
+export function mergeTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsage {
+	return {
+		promptTokens: Math.max(current.promptTokens, next.promptTokens),
+		completionTokens: Math.max(current.completionTokens, next.completionTokens),
+		totalTokens: Math.max(current.totalTokens, next.totalTokens),
+		cachedTokens: Math.max(current.cachedTokens, next.cachedTokens),
+		cacheWriteTokens: Math.max(current.cacheWriteTokens, next.cacheWriteTokens),
+	}
+}
+
 export interface CostInfo {
 	inputCostPer1M: number
 	outputCostPer1M: number

package/src/types/common/usage-merge.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+
+import { type TokenUsage, accumulateTokenUsage, mergeTokenUsage } from './index.js'
+
+const zero: TokenUsage = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+/**
+ * M7: within one streamed turn, usage frames are cumulative/monotonic but a
+ * late frame may omit fields. `mergeTokenUsage` keeps the per-field high-water
+ * mark so a trailing output-only frame does not zero the earlier prompt/cache
+ * counts (the under-report the audit flagged).
+ */
+describe('mergeTokenUsage (within-turn, per-field max)', () => {
+	it('preserves prompt/cache tokens when a later frame reports only output', () => {
+		// message_start-like frame: input + cache set, output still 0.
+		const early: TokenUsage = {
+			...zero,
+			promptTokens: 1200,
+			cachedTokens: 800,
+			cacheWriteTokens: 200,
+		}
+		// message_delta-like frame: only output tokens, input/cache dropped to 0.
+		const lateOutputOnly: TokenUsage = { ...zero, completionTokens: 350 }
+
+		const merged = mergeTokenUsage(early, lateOutputOnly)
+		expect(merged.promptTokens).toBe(1200) // NOT zeroed by the late frame
+		expect(merged.cachedTokens).toBe(800)
+		expect(merged.cacheWriteTokens).toBe(200)
+		expect(merged.completionTokens).toBe(350)
+	})
+
+	it('takes the growing (max) completion count across frames', () => {
+		const a: TokenUsage = { ...zero, promptTokens: 100, completionTokens: 10 }
+		const b: TokenUsage = { ...zero, promptTokens: 100, completionTokens: 42 }
+		expect(mergeTokenUsage(a, b).completionTokens).toBe(42)
+		// Order-independent (a late smaller frame never regresses the max).
+		expect(mergeTokenUsage(b, a).completionTokens).toBe(42)
+	})
+
+	it('is distinct from accumulateTokenUsage (which sums across turns)', () => {
+		const t1: TokenUsage = { ...zero, promptTokens: 100, completionTokens: 20 }
+		const t2: TokenUsage = { ...zero, promptTokens: 100, completionTokens: 30 }
+		// merge = max within a turn; accumulate = sum across turns.
+		expect(mergeTokenUsage(t1, t2).promptTokens).toBe(100)
+		expect(accumulateTokenUsage(t1, t2).promptTokens).toBe(200)
+	})
+})

package/src/types/connector/mcp.ts

@@ -6,7 +6,9 @@ import type {
 	ConnectorInstance,
 } from './definition.js'
 
-export type MCPTransportType = 'stdio' | 'http-sse'
+export type MCPStreamableHttpTransportType = 'streamable_http' | 'streamable-http'
+
+export type MCPTransportType = 'stdio' | 'http-sse' | MCPStreamableHttpTransportType
 
 export interface MCPTransportConfigBase {
 	type: MCPTransportType
@@ -27,7 +29,17 @@ export interface MCPHttpSseTransportConfig extends MCPTransportConfigBase {
 	timeoutMs?: number
 }
 
-export type MCPTransportUnion = MCPStdioTransportConfig | MCPHttpSseTransportConfig
+export interface MCPStreamableHttpTransportConfig extends MCPTransportConfigBase {
+	type: MCPStreamableHttpTransportType
+	url: string
+	headers?: Record<string, string>
+	timeoutMs?: number
+}
+
+export type MCPTransportUnion =
+	| MCPStdioTransportConfig
+	| MCPHttpSseTransportConfig
+	| MCPStreamableHttpTransportConfig
 
 export interface MCPJsonRpcError {
 	code: number

package/src/types/hitl/index.ts

@@ -7,11 +7,27 @@ export type { CheckpointId }
 
 export type HITLResumeDecision =
 	| { action: 'continue' }
-	| { action: 'approve_plan' }
+	| { action: 'approve_plan'; feedback?: string }
 	| { action: 'reject_plan'; feedback: string }
 	| { action: 'approve_tools' }
 	| { action: 'modify_tools'; modifications: ToolModification[] }
 	| { action: 'reject_tools'; feedback: string }
+	| {
+			action: 'answer_question'
+			selectedOptionIds: string[]
+			freeText?: string
+			/**
+			 * Echo of `UserQuestionData.questionId` — the misdirection
+			 * guard. The park/resolve registry on hosts is typically
+			 * keyed by run, so a stale client can answer question N
+			 * after question N+1 re-parked under the same run. When
+			 * present and it does not match the asking tool's own
+			 * questionId, the tool treats the decision as unanswered
+			 * instead of fabricating a selection against the wrong
+			 * question.
+			 */
+			questionId?: string
+	  }
 	| { action: 'pause'; reason: string }
 	| { action: 'abort'; reason: string }
 
@@ -24,6 +40,7 @@ export type HITLDecisionRequest =
 			checkpointId: CheckpointId
 			summary: CheckpointSummary
 	  }
+	| { type: 'user_question'; runId: RunId; checkpointId: CheckpointId; question: UserQuestionData }
 
 export type ResumeHandler = (request: HITLDecisionRequest) => Promise<HITLResumeDecision>
 
@@ -40,6 +57,29 @@ export interface ToolModification {
 	modifiedInput?: unknown
 }
 
+export interface UserQuestionOption {
+	id: string
+	label: string
+	description?: string
+}
+
+/**
+ * A model-authored question for the user, parked through the
+ * `ResumeHandler` exactly like a plan approval. `questionId` equals
+ * the asking `tool_use_id` so the host can mint stable, mergeable
+ * activity ids per question and so answers can be matched back to
+ * the question that asked them (see
+ * `HITLResumeDecision['answer_question'].questionId`).
+ */
+export interface UserQuestionData {
+	questionId: string
+	question: string
+	header?: string
+	options: UserQuestionOption[]
+	multiSelect: boolean
+	allowFreeText: boolean
+}
+
 export interface PlanApprovalData {
 	planId: PlanId
 	title: string
@@ -108,6 +148,17 @@ export function autoApproveHandler(request: HITLDecisionRequest): Promise<HITLRe
 			return Promise.resolve({ action: 'approve_tools' })
 		case 'iteration_checkpoint':
 			return Promise.resolve({ action: 'continue' })
+		case 'user_question':
+			// Headless runs must never deadlock on a question and must
+			// never fabricate a user choice: answer with an explicit
+			// no-selection sentinel so the asking tool renders "the user
+			// did not answer" rather than consent.
+			return Promise.resolve({
+				action: 'answer_question',
+				selectedOptionIds: [],
+				freeText: 'No user is available to answer. Proceed using your best judgment.',
+				questionId: request.question.questionId,
+			})
 		default: {
 			const _exhaustive: never = request
 			throw new Error(`Unhandled HITL request type: ${(_exhaustive as HITLDecisionRequest).type}`)

package/src/types/message/index.ts

@@ -2,6 +2,18 @@ export type MessageRole = 'system' | 'user' | 'assistant' | 'tool'
 
 export type CacheHint = 'cache' | 'ephemeral' | 'none'
 
+/**
+ * An image attached to a user message (vision input). Additive: providers
+ * that support vision (e.g. Anthropic) emit it as an image content block
+ * alongside the text; providers that don't simply ignore it.
+ */
+export interface ImageAttachment {
+	/** Base64-encoded image bytes (no `data:` URI prefix). */
+	readonly data: string
+	/** IANA media type, e.g. `image/png`, `image/jpeg`, `image/webp`. */
+	readonly mediaType: string
+}
+
 export interface ToolCall {
 	id: string
 	type: 'function'
@@ -9,6 +21,14 @@ export interface ToolCall {
 		name: string
 		arguments: string
 	}
+	/**
+	 * Runtime-only execution annotations. This is intentionally separate
+	 * from `function.arguments`: tool arguments remain the model-authored
+	 * JSON payload, while provider/runtime recovery state lives here.
+	 */
+	metadata?: {
+		inputTruncated?: boolean
+	}
 }
 
 export interface BaseMessage {
@@ -26,6 +46,8 @@ export interface SystemMessage extends BaseMessage {
 export interface UserMessage extends BaseMessage {
 	role: 'user'
 	content: string
+	/** Optional image attachments (vision input). */
+	attachments?: readonly ImageAttachment[]
 }
 
 export interface AssistantMessage extends BaseMessage {
@@ -51,8 +73,16 @@ export function createSystemMessage(content: string, cacheHint?: CacheHint): Sys
 	}
 }
 
-export function createUserMessage(content: string): UserMessage {
-	return { role: 'user', content, timestamp: Date.now() }
+export function createUserMessage(
+	content: string,
+	attachments?: readonly ImageAttachment[],
+): UserMessage {
+	return {
+		role: 'user',
+		content,
+		timestamp: Date.now(),
+		...(attachments && attachments.length > 0 ? { attachments } : {}),
+	}
 }
 
 export function createAssistantMessage(

package/src/types/provider/chat.ts

@@ -1,5 +1,5 @@
 import type { TokenUsage } from '../common/index.js'
-import type { Message } from '../message/index.js'
+import type { Message, ToolCall } from '../message/index.js'
 import type { LLMToolSchema } from '../tool/index.js'
 
 export type ToolChoice =
@@ -28,6 +28,16 @@ export interface ChatCompletionParams {
 	stream?: boolean
 	stop?: string[]
 
+	/**
+	 * Per-call cancellation. Aborting it tears down the in-flight model
+	 * request (the provider passes it to the underlying fetch / SDK) AND the
+	 * runtime races the stream consumer against it, so a Stop stops the
+	 * CURRENT turn mid-flight — not only between turns. Optional and inert
+	 * when unset: a non-aborted signal is behaviourally identical to omitting
+	 * it, so existing callers are unaffected.
+	 */
+	signal?: AbortSignal
+
 	toolChoice?: ToolChoice
 	parallelToolCalls?: boolean
 
@@ -48,14 +58,7 @@ export interface ChatCompletionResponse {
 	message: {
 		role: 'assistant'
 		content: string | null
-		toolCalls?: Array<{
-			id: string
-			type: 'function'
-			function: {
-				name: string
-				arguments: string
-			}
-		}>
+		toolCalls?: ToolCall[]
 	}
 	finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter'
 	usage: TokenUsage

package/src/types/run/events.ts

@@ -263,6 +263,12 @@ type CoreRunEvent =
 			runId: RunId
 			toolUseId: ToolUseId
 			input: unknown
+			/**
+			 * True when the provider stream ended before the tool JSON
+			 * arguments closed. `input` stays a sanitized object so public
+			 * consumers never receive internal recovery sentinels.
+			 */
+			inputTruncated?: boolean
 	  }
 
 /**