@namzu/sdk 0.1.4 → 0.1.5-rc.1-fix

package/src/tools/builtins/__tests__/structuredOutput.example.ts

@@ -0,0 +1,221 @@
+/**
+ * Real-world examples of using createStructuredOutputTool
+ *
+ * These examples demonstrate how to use the structured output tool
+ * to force agents to produce validated, typed output.
+ */
+
+import { z } from 'zod'
+import { createStructuredOutputTool } from '../structuredOutput.js'
+
+// ============================================================================
+// Example 1: Code Review Analysis
+// ============================================================================
+
+const CodeReviewSchema = z.object({
+	status: z.enum(['approved', 'changes_requested', 'rejected']),
+	summary: z.string().describe('Overall summary of the review'),
+	issues: z.array(
+		z.object({
+			file: z.string(),
+			line: z.number().int().positive(),
+			severity: z.enum(['critical', 'major', 'minor']),
+			message: z.string(),
+			suggestion: z.string().optional(),
+		}),
+	),
+	strengths: z.array(z.string()).describe('What was done well'),
+	suggestions: z.array(z.string()).describe('Actionable improvements'),
+})
+
+export const createCodeReviewTool = () => createStructuredOutputTool(CodeReviewSchema)
+
+// Usage example:
+// const tool = createCodeReviewTool()
+// await toolRegistry.register(tool)
+// // Model analyzes code...
+// const review = extractToolResult(messages, 'structured_output')
+// const typedReview: z.infer<typeof CodeReviewSchema> = JSON.parse(review.output)
+
+// ============================================================================
+// Example 2: Document Summarization
+// ============================================================================
+
+const DocumentSummarySchema = z.object({
+	title: z.string(),
+	category: z.enum(['technical', 'business', 'legal', 'other']),
+	summary: z.string().min(100).max(500),
+	key_points: z.array(z.string()).min(3).max(10),
+	metadata: z.object({
+		source: z.string().optional(),
+		date: z.string().datetime().optional(),
+		language: z.string().default('en'),
+	}),
+})
+
+export const createDocumentSummaryTool = () => createStructuredOutputTool(DocumentSummarySchema)
+
+// ============================================================================
+// Example 3: Data Extraction
+// ============================================================================
+
+const ExtractedDataSchema = z.object({
+	entities: z.array(
+		z.object({
+			type: z.enum(['person', 'organization', 'location', 'date', 'amount']),
+			text: z.string(),
+			confidence: z.number().min(0).max(1),
+		}),
+	),
+	relationships: z.array(
+		z.object({
+			subject: z.string(),
+			predicate: z.string(),
+			object: z.string(),
+		}),
+	),
+})
+
+export const createDataExtractionTool = () => createStructuredOutputTool(ExtractedDataSchema)
+
+// ============================================================================
+// Example 4: Task Execution Status
+// ============================================================================
+
+const TaskResultSchema = z.object({
+	task_id: z.string(),
+	status: z.enum(['success', 'partial', 'failed']),
+	result: z.record(z.unknown()).describe('Task-specific result data'),
+	errors: z
+		.array(
+			z.object({
+				code: z.string(),
+				message: z.string(),
+				details: z.string().optional(),
+			}),
+		)
+		.default([]),
+	metadata: z.object({
+		duration_ms: z.number().int().positive().optional(),
+		attempts: z.number().int().min(1),
+		timestamp: z.string().datetime(),
+	}),
+})
+
+export const createTaskResultTool = () => createStructuredOutputTool(TaskResultSchema)
+
+// ============================================================================
+// Example 5: Diagnosis/Decision Making
+// ============================================================================
+
+const DiagnosisSchema = z.object({
+	diagnosis: z.string(),
+	confidence: z.number().min(0).max(1),
+	differential: z.array(
+		z.object({
+			diagnosis: z.string(),
+			probability: z.number().min(0).max(1),
+		}),
+	),
+	recommended_actions: z.array(z.string()),
+	urgency: z.enum(['low', 'medium', 'high', 'critical']),
+})
+
+export const createDiagnosisTool = () => createStructuredOutputTool(DiagnosisSchema)
+
+// ============================================================================
+// Example 6: Multi-language Translation
+// ============================================================================
+
+const TranslationSchema = z.object({
+	source_text: z.string(),
+	source_language: z.string(),
+	target_language: z.string(),
+	translation: z.string(),
+	confidence: z.number().min(0).max(1),
+	notes: z.string().optional(),
+	alternatives: z
+		.array(
+			z.object({
+				text: z.string(),
+				note: z.string(),
+			}),
+		)
+		.optional(),
+})
+
+export const createTranslationTool = () => createStructuredOutputTool(TranslationSchema)
+
+// ============================================================================
+// Example 7: Test Report Generation
+// ============================================================================
+
+const TestReportSchema = z.object({
+	total_tests: z.number().int().nonnegative(),
+	passed: z.number().int().nonnegative(),
+	failed: z.number().int().nonnegative(),
+	skipped: z.number().int().nonnegative(),
+	coverage_percent: z.number().min(0).max(100),
+	failures: z.array(
+		z.object({
+			test_name: z.string(),
+			error_message: z.string(),
+			stack_trace: z.string().optional(),
+		}),
+	),
+	summary: z.string(),
+})
+
+export const createTestReportTool = () => createStructuredOutputTool(TestReportSchema)
+
+// ============================================================================
+// Integration Pattern
+// ============================================================================
+
+/**
+ * Example of how to integrate structured output into an agent iteration:
+ *
+ * ```typescript
+ * async function queryWithStructuredOutput(
+ *   toolRegistry: ToolRegistry,
+ *   schema: z.ZodType,
+ *   messages: Message[]
+ * ): Promise<any> {
+ *   const tool = createStructuredOutputTool(schema)
+ *
+ *   try {
+ *     // Register the tool
+ *     toolRegistry.register(tool)
+ *
+ *     // Run the iteration with this tool available
+ *     // (in real usage, this would be integrated with the iteration loop)
+ *     const response = await provider.chat({
+ *       messages,
+ *       tools: toolRegistry.toLLMTools(),
+ *       toolChoice: {
+ *         type: 'function',
+ *         function: { name: 'structured_output' }
+ *       }
+ *     })
+ *
+ *     // Extract the result
+ *     const toolCall = response.message.toolCalls?.find(
+ *       tc => tc.function.name === 'structured_output'
+ *     )
+ *
+ *     if (toolCall) {
+ *       const args = JSON.parse(toolCall.function.arguments)
+ *       return {
+ *         success: true,
+ *         data: args
+ *       }
+ *     }
+ *
+ *     return { success: false, error: 'Tool was not called' }
+ *   } finally {
+ *     // Clean up
+ *     toolRegistry.unregister('structured_output')
+ *   }
+ * }
+ * ```
+ */

package/src/tools/builtins/__tests__/structuredOutput.test.ts

@@ -0,0 +1,275 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import type { ToolContext } from '../../../types/tool/index.js'
+import { STRUCTURED_OUTPUT_TOOL_NAME, createStructuredOutputTool } from '../structuredOutput.js'
+
+describe('structuredOutput', () => {
+	describe('STRUCTURED_OUTPUT_TOOL_NAME', () => {
+		it('should export the constant with correct value', () => {
+			expect(STRUCTURED_OUTPUT_TOOL_NAME).toBe('structured_output')
+		})
+	})
+
+	describe('createStructuredOutputTool', () => {
+		it('should create a tool with correct name and description', () => {
+			const schema = z.object({ result: z.string() })
+			const tool = createStructuredOutputTool(schema)
+
+			expect(tool.name).toBe('structured_output')
+			expect(tool.description).toContain('MUST call this tool')
+		})
+
+		it('should have correct tool properties', () => {
+			const schema = z.object({ result: z.string() })
+			const tool = createStructuredOutputTool(schema)
+
+			expect(tool.category).toBe('analysis')
+			expect(tool.isReadOnly?.({} as any)).toBe(true)
+			expect(tool.isDestructive?.({} as any)).toBe(false)
+			expect(tool.isConcurrencySafe?.({} as any)).toBe(true)
+			expect(tool.permissions).toEqual([])
+		})
+
+		it('should use the provided schema as input schema', () => {
+			const schema = z.object({
+				title: z.string(),
+				count: z.number(),
+			})
+			const tool = createStructuredOutputTool(schema)
+
+			expect(tool.inputSchema).toBe(schema)
+		})
+
+		it('should execute successfully with valid input', async () => {
+			const schema = z.object({
+				title: z.string(),
+				summary: z.string(),
+			})
+			const tool = createStructuredOutputTool(schema)
+
+			const input = {
+				title: 'Test Title',
+				summary: 'Test Summary',
+			}
+
+			const mockContext: ToolContext = {
+				runId: 'run_test' as any,
+				workingDirectory: '/tmp',
+				abortSignal: new AbortController().signal,
+				env: {},
+				log: () => {},
+			}
+
+			const result = await tool.execute(input, mockContext)
+
+			expect(result.success).toBe(true)
+			expect(result.data).toEqual(input)
+			expect(result.output).toBe(JSON.stringify(input))
+			expect(result.error).toBeUndefined()
+		})
+
+		it('should handle complex nested schemas', async () => {
+			const schema = z.object({
+				name: z.string(),
+				metadata: z.object({
+					tags: z.array(z.string()),
+					settings: z.record(z.unknown()),
+				}),
+			})
+			const tool = createStructuredOutputTool(schema)
+
+			const input = {
+				name: 'Complex Object',
+				metadata: {
+					tags: ['tag1', 'tag2'],
+					settings: { timeout: 5000, retries: 3 },
+				},
+			}
+
+			const mockContext: ToolContext = {
+				runId: 'run_test' as any,
+				workingDirectory: '/tmp',
+				abortSignal: new AbortController().signal,
+				env: {},
+				log: () => {},
+			}
+
+			const result = await tool.execute(input, mockContext)
+
+			expect(result.success).toBe(true)
+			expect(result.data).toEqual(input)
+			const parsed = JSON.parse(result.output)
+			expect(parsed).toEqual(input)
+		})
+
+		it('should handle arrays in schema', async () => {
+			const schema = z.object({
+				items: z.array(
+					z.object({
+						id: z.number(),
+						value: z.string(),
+					}),
+				),
+			})
+			const tool = createStructuredOutputTool(schema)
+
+			const input = {
+				items: [
+					{ id: 1, value: 'first' },
+					{ id: 2, value: 'second' },
+				],
+			}
+
+			const mockContext: ToolContext = {
+				runId: 'run_test' as any,
+				workingDirectory: '/tmp',
+				abortSignal: new AbortController().signal,
+				env: {},
+				log: () => {},
+			}
+
+			const result = await tool.execute(input, mockContext)
+
+			expect(result.success).toBe(true)
+			expect(result.data).toEqual(input)
+			expect(JSON.parse(result.output)).toEqual(input)
+		})
+
+		it('should handle optional fields', async () => {
+			const schema = z.object({
+				required: z.string(),
+				optional: z.string().optional(),
+			})
+			const tool = createStructuredOutputTool(schema)
+
+			const input = {
+				required: 'value',
+				optional: undefined,
+			}
+
+			const mockContext: ToolContext = {
+				runId: 'run_test' as any,
+				workingDirectory: '/tmp',
+				abortSignal: new AbortController().signal,
+				env: {},
+				log: () => {},
+			}
+
+			const result = await tool.execute(input, mockContext)
+
+			expect(result.success).toBe(true)
+			expect((result.data as typeof input)?.required).toBe('value')
+		})
+
+		it('should handle boolean and number values', async () => {
+			const schema = z.object({
+				active: z.boolean(),
+				count: z.number(),
+				rate: z.number(),
+			})
+			const tool = createStructuredOutputTool(schema)
+
+			const input = {
+				active: true,
+				count: 42,
+				rate: 3.14,
+			}
+
+			const mockContext: ToolContext = {
+				runId: 'run_test' as any,
+				workingDirectory: '/tmp',
+				abortSignal: new AbortController().signal,
+				env: {},
+				log: () => {},
+			}
+
+			const result = await tool.execute(input, mockContext)
+
+			expect(result.success).toBe(true)
+			expect(result.data).toEqual(input)
+		})
+
+		it('should support union types', async () => {
+			const schema = z.object({
+				status: z.enum(['pending', 'completed', 'failed']),
+				result: z.union([z.string(), z.number()]),
+			})
+			const tool = createStructuredOutputTool(schema)
+
+			const input = {
+				status: 'completed' as const,
+				result: 'success',
+			}
+
+			const mockContext: ToolContext = {
+				runId: 'run_test' as any,
+				workingDirectory: '/tmp',
+				abortSignal: new AbortController().signal,
+				env: {},
+				log: () => {},
+			}
+
+			const result = await tool.execute(input, mockContext)
+
+			expect(result.success).toBe(true)
+			expect((result.data as typeof input)?.status).toBe('completed')
+			expect((result.data as typeof input)?.result).toBe('success')
+		})
+
+		it('should create multiple independent tools', () => {
+			const schema1 = z.object({ type: z.literal('type1'), data: z.string() })
+			const schema2 = z.object({ type: z.literal('type2'), count: z.number() })
+
+			const tool1 = createStructuredOutputTool(schema1)
+			const tool2 = createStructuredOutputTool(schema2)
+
+			// Both should have the same name (that's the point - it's a special tool)
+			expect(tool1.name).toBe(tool2.name)
+			expect(tool1.name).toBe('structured_output')
+
+			// But their input schemas should be different
+			expect(tool1.inputSchema).not.toBe(tool2.inputSchema)
+		})
+
+		it('should not throw on execute', async () => {
+			const schema = z.object({ value: z.string() })
+			const tool = createStructuredOutputTool(schema)
+
+			const mockContext: ToolContext = {
+				runId: 'run_test' as any,
+				workingDirectory: '/tmp',
+				abortSignal: new AbortController().signal,
+				env: {},
+				log: () => {},
+			}
+
+			await expect(tool.execute({ value: 'test' }, mockContext)).resolves.toBeDefined()
+		})
+
+		it('should handle null values in nullable fields', async () => {
+			const schema = z.object({
+				required: z.string(),
+				nullable: z.string().nullable(),
+			})
+			const tool = createStructuredOutputTool(schema)
+
+			const input = {
+				required: 'value',
+				nullable: null,
+			}
+
+			const mockContext: ToolContext = {
+				runId: 'run_test' as any,
+				workingDirectory: '/tmp',
+				abortSignal: new AbortController().signal,
+				env: {},
+				log: () => {},
+			}
+
+			const result = await tool.execute(input, mockContext)
+
+			expect(result.success).toBe(true)
+			expect((result.data as typeof input)?.nullable).toBeNull()
+		})
+	})
+})

package/src/tools/builtins/grep.ts

@@ -1,5 +1,4 @@
-import { readFile } from 'node:fs/promises'
-import { glob } from 'node:fs/promises'
+import { glob, readFile } from 'node:fs/promises'
 import { relative, resolve } from 'node:path'
 import { z } from 'zod'
 import { defineTool } from '../defineTool.js'

package/src/tools/builtins/index.ts

@@ -6,6 +6,7 @@ export { GlobTool } from './glob.js'
 export { GrepTool } from './grep.js'
 export { LsTool } from './ls.js'
 export { SearchToolsTool } from './search-tools.js'
+export { createStructuredOutputTool, STRUCTURED_OUTPUT_TOOL_NAME } from './structuredOutput.js'
 
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { BashTool } from './bash.js'
@@ -16,6 +17,8 @@ import { LsTool } from './ls.js'
 import { ReadFileTool } from './read-file.js'
 import { SearchToolsTool } from './search-tools.js'
 import { WriteFileTool } from './write-file.js'
+// Note: createStructuredOutputTool is not included in getBuiltinTools()
+// because it requires a schema parameter and is created per-use case
 
 export function getBuiltinTools(): ToolDefinition[] {
 	return [

package/src/tools/builtins/structuredOutput.ts

@@ -0,0 +1,55 @@
+import type { z } from 'zod'
+import type { ToolContext, ToolResult } from '../../types/tool/index.js'
+import { defineTool } from '../defineTool.js'
+
+export const STRUCTURED_OUTPUT_TOOL_NAME = 'structured_output' as const
+
+/**
+ * Creates a structured output tool that wraps a Zod schema.
+ *
+ * This tool is used to force the model to produce validated output by presenting
+ * the output schema as a special tool that must be called. The tool executes
+ * immediately upon invocation (validation happens via Zod schema).
+ *
+ * @param schema - A Zod schema that defines the output structure
+ * @returns A ToolDefinition that validates and returns the structured output
+ *
+ * @example
+ * ```typescript
+ * const outputSchema = z.object({
+ *   title: z.string(),
+ *   summary: z.string(),
+ * })
+ *
+ * const tool = createStructuredOutputTool(outputSchema)
+ * // Model calls: structured_output({ title: "...", summary: "..." })
+ * // Tool returns: { success: true, output: JSON.stringify({...}) }
+ * ```
+ */
+export function createStructuredOutputTool<TSchema extends z.ZodType>(
+	schema: TSchema,
+): ReturnType<typeof defineTool<TSchema>> {
+	type TInput = z.infer<TSchema>
+
+	return defineTool({
+		name: STRUCTURED_OUTPUT_TOOL_NAME,
+		description:
+			'Use this tool to provide your final structured response. You MUST call this tool with your answer.',
+		inputSchema: schema,
+		category: 'analysis',
+		permissions: [],
+		readOnly: true,
+		destructive: false,
+		concurrencySafe: true,
+
+		async execute(input: TInput, _context: ToolContext): Promise<ToolResult> {
+			// Input is already validated by Zod schema before this function is called.
+			// Simply return the validated output.
+			return {
+				success: true,
+				output: JSON.stringify(input),
+				data: input,
+			}
+		},
+	})
+}

package/src/tools/task/list.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod'
 import type { RunId } from '../../types/ids/index.js'
-import type { TaskStore } from '../../types/task/index.js'
-import { isTerminalTaskStatus } from '../../types/task/index.js'
+import { type TaskStore, isTerminalTaskStatus } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 

package/src/types/agent/base.ts

@@ -1,8 +1,9 @@
 import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
 import type { RunId, ThreadId } from '../ids/index.js'
+import type { InvocationState } from '../invocation/index.js'
 import type { Message } from '../message/index.js'
 import type { PermissionMode } from '../permission/index.js'
-import type { StopReason } from '../run/index.js'
+import type { StopReason } from '../run/stop-reason.js'
 import type { TaskStore } from '../task/index.js'
 import type { ToolAvailability } from '../tool/index.js'
 
@@ -28,6 +29,9 @@ export interface BaseAgentConfig {
 	depth?: number
 
 	contextLevel?: AgentContextLevel
+
+	/** Shared invocation state passed through agent hierarchies */
+	invocationState?: InvocationState
 }
 
 export type RuntimeToolOverrides = Record<string, ToolAvailability | 'disabled'>

package/src/types/agent/index.ts

@@ -8,3 +8,4 @@ export * from './factory.js'
 export * from './gateway.js'
 export * from './task.js'
 export * from './lifecycle-event.js'
+export * from './manager.js'

package/src/types/agent/manager.ts

@@ -0,0 +1,36 @@
+import type { RunId, TaskId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
+import type { RunEventListener } from '../run/events.js'
+import type { AgentLifecycleListener } from './lifecycle-event.js'
+import type { AgentTask, AgentTaskContext, AgentTaskState, SendMessageOptions } from './task.js'
+
+/**
+ * Agent task lifecycle contract — task creation, cancellation, messaging, and completion tracking.
+ * Concrete implementation: `AgentManager` in `manager/agent/lifecycle.ts`.
+ */
+export interface AgentManagerContract {
+	sendMessage(
+		options: SendMessageOptions,
+		context: AgentTaskContext,
+		listener?: RunEventListener,
+	): Promise<AgentTask>
+
+	cancel(taskId: TaskId): void
+	cancelAll(parentRunId: RunId): void
+
+	continueTask(taskId: TaskId, message: string): Promise<void>
+	queueMessage(taskId: TaskId, message: Message): void
+	drainMessages(taskId: TaskId): Message[]
+
+	waitForCompletion(taskId: TaskId): Promise<void>
+	getInstance(taskId: TaskId): AgentTask | undefined
+	listByParent(parentRunId: RunId): AgentTask[]
+	listActive(): AgentTask[]
+	getState(taskId: TaskId): AgentTaskState | undefined
+
+	on(listener: AgentLifecycleListener): void
+	off(listener: AgentLifecycleListener): void
+
+	cleanup(): void
+	dispose(): void
+}

package/src/types/agent/reactive.ts

@@ -1,8 +1,8 @@
-import type { ToolRegistry } from '../../registry/tool/execute.js'
 import type { AdvisoryConfig } from '../advisory/index.js'
 import type { AgentPersona } from '../persona/index.js'
 import type { LLMProvider } from '../provider/index.js'
 import type { Skill } from '../skills/index.js'
+import type { ToolRegistryContract } from '../tool/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 
 export interface ReactiveAgentConfig extends BaseAgentConfig {
@@ -14,7 +14,7 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 
 	basePrompt?: string
 	provider: LLMProvider
-	tools: ToolRegistry
+	tools: ToolRegistryContract
 
 	advisory?: AdvisoryConfig
 }

package/src/types/agent/supervisor.ts

@@ -1,10 +1,10 @@
-import type { AgentManager } from '../../manager/agent/lifecycle.js'
 import type { AdvisoryConfig } from '../advisory/index.js'
 import type { LLMProvider } from '../provider/index.js'
 import type { TaskRouterConfig } from '../router/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'
 
 export interface SupervisorAgentConfig extends BaseAgentConfig {
 	provider: LLMProvider
@@ -12,7 +12,7 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	agentIds: string[]
 
 	gateway?: TaskGateway
-	agentManager?: AgentManager
+	agentManager?: AgentManagerContract
 
 	systemPrompt: string