@namzu/sdk 0.1.4 → 0.1.5-rc.1

package/src/types/agent/task.ts

@@ -66,8 +66,6 @@ export interface AgentTaskProgress {
 	recentActivities: string[]
 }
 
-export { MAX_RECENT_ACTIVITIES } from '../../constants/agent/index.js'
-
 export interface SendMessageOptions {
 	agentId: string
 
@@ -88,5 +86,3 @@ export interface AgentManagerConfig {
 
 	maxBudgetFraction: number
 }
-
-export { AGENT_MANAGER_DEFAULTS } from '../../constants/agent/index.js'

package/src/types/common/index.ts

@@ -12,8 +12,6 @@ export interface TokenUsage {
 	cacheWriteTokens: number
 }
 
-export { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
-
 export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage): TokenUsage {
 	return {
 		promptTokens: current.promptTokens + addition.promptTokens,

package/src/types/hitl/index.ts

@@ -1,9 +1,8 @@
 import type { CostInfo, TokenUsage } from '../common/index.js'
-import type { PlanId, RunId } from '../ids/index.js'
+import type { CheckpointId, PlanId, RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
 import type { PlanStatus } from '../plan/index.js'
 
-import type { CheckpointId } from '../ids/index.js'
 export type { CheckpointId }
 
 export type HITLResumeDecision =

package/src/types/invocation/__tests__/state.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from 'vitest'
+import type { TenantId } from '../../ids/index.js'
+import { deriveChildState } from '../index.js'
+import type { InvocationState } from '../index.js'
+
+describe('InvocationState', () => {
+	describe('deriveChildState', () => {
+		it('should create child state with single agent in parentChain when parent is undefined', () => {
+			const childState = deriveChildState(undefined, 'agent-123')
+
+			expect(childState.parentChain).toEqual(['agent-123'])
+			expect(childState.tenantId).toBeUndefined()
+			expect(childState.metadata).toBeUndefined()
+			expect(childState.services).toBeUndefined()
+		})
+
+		it('should create child state with single agent in parentChain when parent has no parentChain', () => {
+			const parent: InvocationState = {
+				tenantId: 'ten_abc' as TenantId,
+				metadata: { userId: 'user-123' },
+			}
+
+			const childState = deriveChildState(parent, 'agent-456')
+
+			expect(childState.parentChain).toEqual(['agent-456'])
+			expect(childState.tenantId).toBe(parent.tenantId)
+			expect(childState.metadata).toBe(parent.metadata)
+		})
+
+		it('should extend parentChain with current agent', () => {
+			const parent: InvocationState = {
+				parentChain: ['supervisor', 'router'],
+				tenantId: 'ten_xyz' as TenantId,
+			}
+
+			const childState = deriveChildState(parent, 'worker-agent')
+
+			expect(childState.parentChain).toEqual(['supervisor', 'router', 'worker-agent'])
+		})
+
+		it('should preserve tenantId through derivation', () => {
+			const tenantId = 'ten_tenant123' as TenantId
+			const parent: InvocationState = {
+				tenantId,
+				parentChain: ['agent-1'],
+			}
+
+			const childState = deriveChildState(parent, 'agent-2')
+
+			expect(childState.tenantId).toBe(tenantId)
+		})
+
+		it('should preserve metadata through derivation', () => {
+			const metadata = {
+				userId: 'user-456',
+				sessionId: 'sess_789',
+				correlationId: 'corr_abc',
+			}
+			const parent: InvocationState = {
+				metadata,
+				parentChain: ['agent-1'],
+			}
+
+			const childState = deriveChildState(parent, 'agent-2')
+
+			expect(childState.metadata).toBe(metadata)
+			expect(childState.metadata?.userId).toBe('user-456')
+		})
+
+		it('should preserve services through derivation', () => {
+			const services = {
+				db: { pool: 'mock-pool' },
+				cache: { client: 'mock-redis' },
+			}
+			const parent: InvocationState = {
+				services,
+				parentChain: ['agent-1'],
+			}
+
+			const childState = deriveChildState(parent, 'agent-2')
+
+			expect(childState.services).toBe(services)
+		})
+
+		it('should preserve all fields through multi-level derivation', () => {
+			const tenantId = 'ten_multi' as TenantId
+			const metadata = { userId: 'user-multi' }
+			const services = { db: 'postgres' }
+
+			const level1 = deriveChildState(undefined, 'supervisor')
+			expect(level1.parentChain).toEqual(['supervisor'])
+
+			const parent: InvocationState = {
+				tenantId,
+				metadata,
+				services,
+				parentChain: level1.parentChain,
+			}
+
+			const level2 = deriveChildState(parent, 'router')
+			expect(level2.parentChain).toEqual(['supervisor', 'router'])
+			expect(level2.tenantId).toBe(tenantId)
+			expect(level2.metadata).toBe(metadata)
+			expect(level2.services).toBe(services)
+
+			const level3 = deriveChildState(level2, 'worker')
+			expect(level3.parentChain).toEqual(['supervisor', 'router', 'worker'])
+			expect(level3.tenantId).toBe(tenantId)
+			expect(level3.metadata).toBe(metadata)
+			expect(level3.services).toBe(services)
+		})
+
+		it('should create immutable parentChain', () => {
+			const parent: InvocationState = {
+				parentChain: ['agent-1'],
+			}
+
+			const childState = deriveChildState(parent, 'agent-2')
+
+			// Ensure the parentChain is a new array, not mutated
+			expect(parent.parentChain).toEqual(['agent-1'])
+			expect(childState.parentChain).toEqual(['agent-1', 'agent-2'])
+		})
+
+		it('should handle empty parentChain in parent', () => {
+			const parent: InvocationState = {
+				parentChain: [],
+			}
+
+			const childState = deriveChildState(parent, 'agent-first')
+
+			expect(childState.parentChain).toEqual(['agent-first'])
+		})
+
+		it('should allow complex agent IDs in parentChain', () => {
+			const agentIds = ['supervisor-agent-123', 'router-multi-path', 'worker-task-handler']
+
+			let state: InvocationState | undefined
+			for (const agentId of agentIds) {
+				state = deriveChildState(state, agentId)
+			}
+
+			expect(state?.parentChain).toEqual(agentIds)
+		})
+
+		it('should not mutate parent state', () => {
+			const parent: InvocationState = {
+				parentChain: ['original'],
+				tenantId: 'ten_orig' as TenantId,
+				metadata: { key: 'value' },
+			}
+
+			const originalParentChain = [...parent.parentChain!]
+
+			deriveChildState(parent, 'child')
+
+			// Parent state should remain unchanged
+			expect(parent.parentChain).toEqual(originalParentChain)
+			expect(parent.parentChain).toEqual(['original'])
+		})
+	})
+
+	describe('InvocationState immutability', () => {
+		it('should have readonly fields', () => {
+			const state: InvocationState = {
+				tenantId: 'ten_test' as TenantId,
+				metadata: { key: 'value' },
+				services: { db: 'postgres' },
+				parentChain: ['agent-1'],
+			}
+
+			// Type system enforces immutability, so these assertions verify the type definitions
+			expect(state.tenantId).toBe('ten_test')
+			expect(state.metadata).toBeDefined()
+			expect(state.services).toBeDefined()
+			expect(state.parentChain).toBeDefined()
+		})
+
+		it('should support undefined optional fields', () => {
+			const minimalState: InvocationState = {
+				parentChain: ['agent-1'],
+			}
+
+			expect(minimalState.tenantId).toBeUndefined()
+			expect(minimalState.metadata).toBeUndefined()
+			expect(minimalState.services).toBeUndefined()
+			expect(minimalState.parentChain).toEqual(['agent-1'])
+		})
+
+		it('should handle metadata with various types', () => {
+			const metadata = {
+				userId: 'user-123',
+				count: 42,
+				enabled: true,
+				nested: { key: 'value' },
+				array: [1, 2, 3],
+			}
+
+			const state: InvocationState = {
+				metadata,
+			}
+
+			expect(state.metadata?.userId).toBe('user-123')
+			expect(state.metadata?.count).toBe(42)
+			expect(state.metadata?.enabled).toBe(true)
+			expect(state.metadata?.nested).toEqual({ key: 'value' })
+			expect(state.metadata?.array).toEqual([1, 2, 3])
+		})
+	})
+})

package/src/types/invocation/index.ts

@@ -0,0 +1,55 @@
+import type { TenantId } from '../ids/index.js'
+
+/**
+ * Shared state passed through agent hierarchies.
+ *
+ * This state is NOT visible to the LLM — it carries runtime context
+ * like DB clients, tenant info, session metadata, etc. that sub-agents
+ * need to access but should not expose to the LLM.
+ *
+ * The invocation state flows through the entire agent call chain:
+ * - Top-level caller creates or provides initial state
+ * - SupervisorAgent/RouterAgent derives child state with extended parentChain
+ * - Child agents receive the state in their config
+ * - Tools can access state via ToolContext.invocationState
+ */
+export interface InvocationState {
+	/** Tenant context for multi-tenant isolation (if applicable) */
+	readonly tenantId?: TenantId
+
+	/** Request-scoped metadata (user info, session, correlation IDs, etc.) */
+	readonly metadata?: Readonly<Record<string, unknown>>
+
+	/** Shared services (DB clients, external APIs, cache, etc.) */
+	readonly services?: Readonly<Record<string, unknown>>
+
+	/** Parent agent chain for debugging/tracing (agent IDs in order) */
+	readonly parentChain?: readonly string[]
+}
+
+/**
+ * Create a child invocation state with the current agent appended to parentChain.
+ *
+ * This function is called by SupervisorAgent and RouterAgent when delegating
+ * to sub-agents. It ensures the full agent hierarchy is tracked for debugging,
+ * logging, and tenant isolation validation.
+ *
+ * @param parent The parent invocation state (may be undefined for top-level agents)
+ * @param currentAgentId The ID of the agent making the delegation
+ * @returns A new InvocationState with currentAgentId appended to parentChain
+ */
+export function deriveChildState(
+	parent: InvocationState | undefined,
+	currentAgentId: string,
+): InvocationState {
+	const parentChain = parent?.parentChain
+		? [...parent.parentChain, currentAgentId]
+		: [currentAgentId]
+
+	return {
+		tenantId: parent?.tenantId,
+		metadata: parent?.metadata,
+		services: parent?.services,
+		parentChain,
+	}
+}

package/src/types/plugin/index.ts

@@ -125,6 +125,25 @@ export type PluginHookResult =
 	| { action: 'skip'; reason: string }
 	| { action: 'modify'; input: unknown }
 	| { action: 'error'; message: string }
+	| { action: 'resume'; input: string }
+	| { action: 'retry' }
+
+export function assertPluginHookResult(result: PluginHookResult): asserts result {
+	const action = result.action
+	switch (action) {
+		case 'continue':
+		case 'skip':
+		case 'modify':
+		case 'error':
+		case 'resume':
+		case 'retry':
+			break
+		default: {
+			const _exhaustive: never = action
+			throw new Error(`Unknown PluginHookResult action: ${_exhaustive}`)
+		}
+	}
+}
 
 export interface PluginHookDefinition {
 	readonly event: PluginHookEvent

package/src/types/run/events.ts

@@ -7,16 +7,7 @@ import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
 import type { TaskStatus } from '../task/index.js'
 
-export type StopReason =
-	| 'end_turn'
-	| 'token_budget'
-	| 'cost_limit'
-	| 'timeout'
-	| 'max_iterations'
-	| 'cancelled'
-	| 'plan_rejected'
-	| 'paused'
-	| 'error'
+export type { StopReason } from './stop-reason.js'
 
 export type RunEvent =
 	| { type: 'run_started'; runId: RunId; systemPrompt?: string }

package/src/types/run/index.ts

@@ -1,3 +1,4 @@
+export * from './stop-reason.js'
 export * from './config.js'
 export * from './state.js'
 export * from './events.js'

package/src/types/run/metadata.ts

@@ -1,6 +1,6 @@
 import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
 import type { RunId, TaskId, ThreadId } from '../ids/index.js'
-import type { StopReason } from './events.js'
+import type { StopReason } from './stop-reason.js'
 
 export interface RunMetadata {
 	id: RunId

package/src/types/run/state.ts

@@ -2,7 +2,7 @@ import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
 import type { RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
 import type { AgentRunConfig } from './config.js'
-import type { StopReason } from './events.js'
+import type { StopReason } from './stop-reason.js'
 
 export interface RunStateMetadata {
 	agentId: string

package/src/types/run/stop-reason.ts

@@ -0,0 +1,10 @@
+export type StopReason =
+	| 'end_turn'
+	| 'token_budget'
+	| 'cost_limit'
+	| 'timeout'
+	| 'max_iterations'
+	| 'cancelled'
+	| 'plan_rejected'
+	| 'paused'
+	| 'error'

package/src/types/structured-output/index.ts

@@ -0,0 +1,56 @@
+import type { z } from 'zod'
+
+/**
+ * Configuration for structured output via tool constraint.
+ *
+ * This configuration allows an agent to produce validated, typed output by
+ * presenting the output schema as a special tool that the model must call.
+ */
+export interface StructuredOutputConfig<TSchema extends z.ZodType = z.ZodType> {
+	/**
+	 * The Zod schema that defines the output structure.
+	 * Used for both validation and LLM tool schema generation.
+	 */
+	schema: TSchema
+
+	/**
+	 * Whether to force the model to use the structured_output tool.
+	 * When true, sets tool_choice to force the tool.
+	 * When false, the model may choose to call it or not.
+	 * Default: true
+	 */
+	enforceToolChoice?: boolean
+}
+
+/**
+ * Result from structured output tool execution.
+ *
+ * The structured_output tool returns this result after validating
+ * the input against the provided schema.
+ */
+export interface StructuredOutputResult<T = unknown> {
+	/**
+	 * Whether the structured output was successfully produced.
+	 * Always true for successful tool execution (validation happens at schema level).
+	 */
+	success: boolean
+
+	/**
+	 * The parsed and validated output data.
+	 * Type is inferred from the Zod schema.
+	 */
+	data?: T
+
+	/**
+	 * Error message if structured output failed.
+	 * This would typically come from schema validation errors
+	 * that occur before tool execution.
+	 */
+	error?: string
+
+	/**
+	 * The raw JSON string representation of the output.
+	 * Useful for logging or debugging.
+	 */
+	rawOutput?: string
+}

package/src/types/tool/index.ts

@@ -1,6 +1,7 @@
 import type { z } from 'zod'
 import type { Logger } from '../../utils/logger.js'
 import type { RunId } from '../ids/index.js'
+import type { InvocationState } from '../invocation/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { Sandbox } from '../sandbox/index.js'
 
@@ -22,6 +23,8 @@ export interface ToolContext {
 		workingDirectory: string
 	}
 
+	invocationState?: InvocationState
+
 	toolRegistry?: ToolRegistryRef
 	sandbox?: Sandbox
 }
@@ -84,3 +87,45 @@ export interface ToolRegistryConfig {
 	logger?: Logger
 	tierConfig?: ToolTierConfig
 }
+
+export interface ToolExecutionResult extends ToolResult {
+	permissionDenied?: boolean
+	permissionMessage?: string
+}
+
+/**
+ * Full tool registry contract — registration, lookup, execution, prompt generation.
+ * Concrete implementation: `ToolRegistry` in `registry/tool/execute.ts`.
+ */
+export interface ToolRegistryContract {
+	register(id: string, tool: ToolDefinition): void
+	register(tool: ToolDefinition, initialState?: ToolAvailability): void
+	register(tools: ToolDefinition[], initialState?: ToolAvailability): void
+
+	unregister(id: string): boolean
+	clear(): void
+
+	get(name: string): ToolDefinition | undefined
+	getOrThrow(name: string): ToolDefinition
+	has(name: string): boolean
+	getAll(): ToolDefinition[]
+	listIds(): string[]
+	listNames(): string[]
+
+	getAvailability(name: string): ToolAvailability
+	activate(names: string[]): void
+	defer(names: string[]): void
+	suspendAll(): void
+	hasSuspended(): boolean
+	searchDeferred(query: string): ToolDefinition[]
+	getCallableTools(toolNames?: string[]): ToolDefinition[]
+
+	execute(toolName: string, rawInput: unknown, context: ToolContext): Promise<ToolExecutionResult>
+
+	size(): number
+
+	toLLMTools(toolNames?: string[]): LLMToolSchema[]
+	toPromptSection(toolNames?: string[]): string
+	toTierGuidance(): string | null
+	assignTiers(mapping: Record<string, string>): void
+}