@qodo/sdk 0.13.4 → 2.0.0-next.1

package/.claude/skills/qodo-agent/SKILL.md

@@ -1,974 +0,0 @@
----
-name: qodo-agent
-description: Development companion for building AI-powered agents with @qodo/sdk. Use when working with QodoSDK, sdkAgent(), sdkCommand(), agent.toml, or any Qodo agent development tasks.
-compatibility: Requires Node.js >= 18, npm, and zod package for schema definitions.
-metadata:
-  author: qodo
-  version: "1.0"
----
-
-# Qodo SDK Development Companion
-
-Use this skill when working with `@qodo/sdk` to build AI-powered agents. This skill helps you:
-
-- **Create** agent configurations (TypeScript and TOML)
-- **Scaffold** Zod schemas with proper patterns and descriptions
-- **Extend** existing agents with new commands, tools, and capabilities
-- **Debug** streaming events, schema validation, and tool execution issues
-- **Refactor** between config formats and improve type safety
-
-## Quick Reference
-
-### Core Exports
-
-| Export | Purpose |
-|--------|---------|
-| `QodoSDK` | Main SDK class - initialize and run agents |
-| `sdkAgent()` | Build agent config programmatically |
-| `sdkCommand()` | Build command config with Zod schemas |
-| `sdkArgs()` | Convenience wrapper for `z.object()` |
-
-### Schema Helpers
-
-| Export | Purpose |
-|--------|---------|
-| `zodOutputSchema()` | Convert Zod to JSON Schema for output |
-| `zJsonValue()` | Flexible primitive type (string \| number \| boolean \| null) |
-| `zJsonAny()` | Flexible any type (primitives + arrays + objects) |
-| `zCoerce` | CLI-style input coercion (boolean, number, jsonArray, jsonObject) |
-| `parseArgsWithSchema()` | Validate args with Zod, get typed result |
-| `QodoSchemaError` | Schema validation error class |
-
-### Pipeline DSL
-
-| Export | Purpose |
-|--------|---------|
-| `sdkPipeline()` | Build multi-step agent workflows |
-| `runPipeline()` | Execute a pipeline with an SDK instance |
-| `PipelineExecutionError` | Pipeline step failure error |
-| `.step()` | Add a sequential step with typed state threading |
-| `.parallel()` | Add a group of steps that execute concurrently |
-| `.gate()` | Pipeline-level barrier — halts subsequent entries when false |
-| `.branch()` | Pipeline-level if/else fork with sub-pipeline paths |
-
-### Tool Middleware
-
-| Export | Purpose |
-|--------|---------|
-| `ToolMiddleware` (type) | Pre/post execution hook interface |
-| `ToolMiddlewareError` | Middleware failure error |
-| `MIDDLEWARE_TIMEOUT_MS` | Default hook timeout (10s) |
-| `PROTECTED_TOOL_FIELDS` | Fields middleware cannot overwrite |
-
-### Tool Approval Policies
-
-| Export | Purpose |
-|--------|---------|
-| `sdkPolicy()` | Fluent builder for declarative tool approval rules |
-| `policyFromRules()` | Build a policy from a rule array |
-| `globMatch()` | Glob pattern matching utility |
-
-### Artifacts
-
-| Export | Purpose |
-|--------|---------|
-| `ArtifactStore` | Store/persist intermediate pipeline results |
-| `withArtifacts()` | Wrap a pipeline step to auto-store output |
-| `jsonSerializer` | Default JSON serializer |
-
-### OpenTelemetry Tracing
-
-| Export | Purpose |
-|--------|---------|
-| `createSdkTracer()` | Create event-to-span tracer (duck-typed OTel API) |
-| `tracePipeline()` | Trace pipeline execution with nested spans |
-| `SdkTracer` | Tracer class for manual usage |
-
-### Event Handling
-
-| Export | Purpose |
-|--------|---------|
-| `SdkEventType` | Event type constants (Init, MessageDelta, Final, etc.) |
-| `matchSdkEvent()` | Type-safe event router |
-
-### Clients
-
-| Export | Purpose |
-|--------|---------|
-| `QodoInfoClient` | Backend info (models, capabilities, rate limits) |
-| `QodoSessionsClient` | Session history management |
-| `QodoToolsClient` | Tool discovery (built-in + backend tools) |
-
-### Errors
-
-| Export | Purpose |
-|--------|---------|
-| `QodoSchemaError` | Schema validation failures |
-| `QodoAuthError` | Authentication failures |
-| `QodoBackendBootstrapError` | Backend initialization failures |
-| `QodoOutputValidationError` | Structured output didn't match Zod schema |
-| `ToolMiddlewareError` | Tool middleware hook failure |
-| `PipelineExecutionError` | Pipeline step failure |
-
-### Built-in Tools
-
-Use these in `available_tools` to give your agent capabilities:
-
-| Tool | Purpose | Common Use Cases |
-|------|---------|------------------|
-| `filesystem` | File operations | Read/write files, navigate directories, edit code |
-| `git` | Version control | Check status, view diffs, commit changes |
-| `ripgrep` | Code search | Find patterns, locate definitions, search codebase |
-| `shell` | Run commands | Build tools, scripts, system commands |
-
-**Example:**
-```typescript
-sdkCommand({
-  name: 'analyze',
-  available_tools: ['filesystem', 'ripgrep'],  // Read files + search
-  // ...
-});
-```
-
-**Common Combinations:**
-- **Code analysis**: `['filesystem', 'ripgrep']`
-- **Code review**: `['git', 'filesystem']`
-- **Full development**: `['filesystem', 'git', 'ripgrep', 'shell']`
-
-See [references/builtin-tools.md](references/builtin-tools.md) for detailed documentation on each tool.
-
----
-
-## Critical Rules
-
-### For SDK Users (Building Apps)
-
-1. **Every output property needs `.describe()`**
-   ```typescript
-   // WRONG - will throw QodoSchemaError
-   const output = z.object({
-     summary: z.string(),
-     score: z.number(),
-   });
-
-   // CORRECT
-   const output = z.object({
-     summary: z.string().describe('Brief summary of the analysis'),
-     score: z.number().describe('Quality score from 0-100'),
-   });
-   ```
-
-2. **Never use `z.any()` in output schemas**
-   ```typescript
-   // WRONG - produces invalid JSON Schema
-   const output = z.object({
-     data: z.any().describe('The data'),
-   });
-
-   // CORRECT - use zJsonValue() or zJsonAny()
-   import { zJsonValue, zJsonAny } from '@qodo/sdk';
-
-   const output = z.object({
-     // For primitives only:
-     value: zJsonValue().describe('A primitive value'),
-     // For any JSON (including objects/arrays):
-     data: zJsonAny().describe('Any JSON data'),
-   });
-   ```
-
-3. **Always call `sdk.dispose()`**
-   ```typescript
-   const sdk = new QodoSDK({ ... });
-   try {
-     const result = await sdk.run('analyze', { args: { path: './src' } });
-     console.log(result.structured_output);
-   } finally {
-     await sdk.dispose(); // Cleanup MCP servers and connections
-   }
-   ```
-
-4. **Handle errors appropriately**
-   ```typescript
-   import { QodoSchemaError, QodoAuthError } from '@qodo/sdk';
-
-   try {
-     const result = await sdk.run('analyze');
-   } catch (e) {
-     if (e instanceof QodoSchemaError) {
-       console.error('Schema validation failed:', e.message);
-     } else if (e instanceof QodoAuthError) {
-       console.error('Authentication failed:', e.message);
-     } else {
-       throw e;
-     }
-   }
-   ```
-
-### For SDK Contributors (Modifying @qodo/sdk)
-
-1. **Never use `process.exit()`** - throw errors instead (library code)
-2. **Use `.js` extensions** in imports - ESM requirement
-3. **Export types separately** - TypeScript best practice
-
----
-
-## Usage Patterns
-
-### Pattern 1: Simple Prompt (No Config)
-
-```typescript
-import { QodoSDK } from '@qodo/sdk';
-
-const sdk = new QodoSDK();
-try {
-  const result = await sdk.prompt('Explain how async/await works in JavaScript');
-  console.log(result.final_output);
-} finally {
-  await sdk.dispose();
-}
-```
-
-### Pattern 2: Programmatic Agent with Zod
-
-```typescript
-import { QodoSDK, sdkAgent, sdkCommand, sdkArgs, z } from '@qodo/sdk';
-// Note: Import `z` from '@qodo/sdk' for guaranteed compatibility with SDK schema functions
-// Alternatively, Zod 3 users can use: import { z } from 'zod';
-// Zod 4 users should use: import { z } from 'zod/v3';
-
-const agent = sdkAgent({
-  instructions: 'You are a code analysis assistant.',
-  commands: {
-    analyze: sdkCommand({
-      name: 'analyze',
-      description: 'Analyze code quality',
-      instructions: 'Analyze the code and provide a quality assessment.',
-      available_tools: ['filesystem', 'ripgrep'],
-      args: sdkArgs({
-        path: z.string().describe('Path to analyze'),
-        depth: z.number().optional().default(3).describe('Max directory depth'),
-      }),
-      output: z.object({
-        summary: z.string().describe('Overall assessment'),
-        issues: z.array(z.object({
-          file: z.string().describe('File path'),
-          line: z.number().describe('Line number'),
-          severity: z.enum(['low', 'medium', 'high']).describe('Issue severity'),
-          message: z.string().describe('Issue description'),
-        })).describe('List of issues found'),
-        score: z.number().describe('Quality score 0-100'),
-      }),
-    }),
-  },
-});
-
-const sdk = QodoSDK.fromAgent(agent);
-try {
-  const result = await sdk.run('analyze', {
-    args: { path: './src', depth: 5 },
-  });
-  console.log('Score:', result.structured_output?.score);
-  console.log('Issues:', result.structured_output?.issues);
-} finally {
-  await sdk.dispose();
-}
-```
-
-### Pattern 3: TOML Configuration
-
-Create `agent.toml`:
-```toml
-version = "1.0"
-instructions = "You are a helpful coding assistant."
-
-[commands.review]
-name = "review"
-description = "Review code changes"
-instructions = "Review the provided code changes and suggest improvements."
-available_tools = ["filesystem", "git", "ripgrep"]
-
-[commands.review.output_schema]
-type = "json_schema"
-
-[commands.review.output_schema.json_schema]
-name = "review_output"
-strict = true
-
-[commands.review.output_schema.json_schema.schema]
-type = "object"
-required = ["summary", "suggestions"]
-
-[commands.review.output_schema.json_schema.schema.properties.summary]
-type = "string"
-description = "Overall review summary"
-
-[commands.review.output_schema.json_schema.schema.properties.suggestions]
-type = "array"
-description = "List of improvement suggestions"
-
-[commands.review.output_schema.json_schema.schema.properties.suggestions.items]
-type = "object"
-required = ["file", "suggestion"]
-
-[commands.review.output_schema.json_schema.schema.properties.suggestions.items.properties.file]
-type = "string"
-description = "File path"
-
-[commands.review.output_schema.json_schema.schema.properties.suggestions.items.properties.suggestion]
-type = "string"
-description = "The suggestion"
-```
-
-Then use it:
-```typescript
-import { QodoSDK } from '@qodo/sdk';
-
-const sdk = new QodoSDK({
-  agentFile: './agent.toml',
-});
-try {
-  const result = await sdk.run('review');
-  console.log(result.structured_output);
-} finally {
-  await sdk.dispose();
-}
-```
-
-### Pattern 4: Streaming Events
-
-```typescript
-import { QodoSDK, SdkEventType, matchSdkEvent } from '@qodo/sdk';
-
-const sdk = new QodoSDK();
-try {
-  for await (const event of sdk.streamPrompt('Write a haiku about coding')) {
-    matchSdkEvent(event, {
-      [SdkEventType.MessageDelta]: (e) => {
-        process.stdout.write(e.data.delta);
-      },
-      [SdkEventType.ToolRequested]: (e) => {
-        console.log(`\nTool: ${e.data.server_name}.${e.data.tool_name}`);
-      },
-      [SdkEventType.ToolExecuted]: (e) => {
-        console.log(`Tool result: ${e.data.result.isError ? 'error' : 'success'}`);
-      },
-      [SdkEventType.Error]: (e) => {
-        console.error('Error:', e.data.message);
-      },
-      [SdkEventType.Final]: (e) => {
-        console.log('\n\nDone! Success:', e.data.success);
-      },
-      default: () => {}, // Ignore other events
-    });
-  }
-} finally {
-  await sdk.dispose();
-}
-```
-
-### Pattern 5: Custom Tool Approval
-
-```typescript
-import { QodoSDK } from '@qodo/sdk';
-import * as readline from 'readline';
-
-const sdk = new QodoSDK({
-  autoApproveTools: false,
-  toolApproval: async ({ tool_name, server_name, tool_args }) => {
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-
-    return new Promise((resolve) => {
-      rl.question(
-        `Allow ${server_name}.${tool_name}(${JSON.stringify(tool_args)})? [y/N] `,
-        (answer) => {
-          rl.close();
-          resolve(answer.toLowerCase() === 'y');
-        }
-      );
-    });
-  },
-});
-
-try {
-  const result = await sdk.prompt('List files in current directory');
-  console.log(result.final_output);
-} finally {
-  await sdk.dispose();
-}
-```
-
-### Pattern 6: Session Continuity
-
-```typescript
-import { QodoSDK } from '@qodo/sdk';
-
-// First conversation
-const sdk1 = new QodoSDK();
-let sessionId: string;
-
-try {
-  for await (const event of sdk1.streamPrompt('Remember: my favorite color is blue')) {
-    if (event.type === 'sdk.run.started') {
-      sessionId = event.data.session_id;
-    }
-  }
-} finally {
-  await sdk1.dispose();
-}
-
-// Continue the conversation
-const sdk2 = new QodoSDK().withSession(sessionId!);
-try {
-  const result = await sdk2.prompt('What is my favorite color?');
-  console.log(result.final_output); // Should mention "blue"
-} finally {
-  await sdk2.dispose();
-}
-```
-
-### Pattern 7: Multi-Agent Orchestration
-
-```typescript
-import { QodoSDK, sdkAgent, sdkCommand, sdkArgs, z } from '@qodo/sdk';
-
-// Agent 1: Code analyzer
-const analyzerAgent = sdkAgent({
-  instructions: 'You analyze code and identify issues.',
-  commands: {
-    analyze: sdkCommand({
-      name: 'analyze',
-      description: 'Analyze code',
-      available_tools: ['filesystem', 'ripgrep'],
-      output: z.object({
-        issues: z.array(z.string().describe('Issue description')).describe('Issues found'),
-      }),
-    }),
-  },
-});
-
-// Agent 2: Code fixer
-const fixerAgent = sdkAgent({
-  instructions: 'You fix code issues.',
-  commands: {
-    fix: sdkCommand({
-      name: 'fix',
-      description: 'Fix code issues',
-      available_tools: ['filesystem'],
-      args: sdkArgs({
-        issues: z.array(z.string()).describe('Issues to fix'),
-      }),
-      output: z.object({
-        fixed: z.array(z.string().describe('Fixed issue')).describe('Issues that were fixed'),
-      }),
-    }),
-  },
-});
-
-// Orchestrate
-const analyzer = QodoSDK.fromAgent(analyzerAgent);
-const fixer = QodoSDK.fromAgent(fixerAgent);
-
-try {
-  // Step 1: Analyze
-  const analysis = await analyzer.run('analyze');
-  const issues = analysis.structured_output?.issues || [];
-
-  // Step 2: Fix
-  if (issues.length > 0) {
-    const fixes = await fixer.run('fix', { args: { issues } });
-    console.log('Fixed:', fixes.structured_output?.fixed);
-  }
-} finally {
-  await Promise.all([analyzer.dispose(), fixer.dispose()]);
-}
-```
-
-### Pattern 8: Pipeline DSL (Multi-Step Workflows)
-
-```typescript
-import { QodoSDK, sdkPipeline, runPipeline } from '@qodo/sdk';
-
-const sdk = new QodoSDK({ autoApproveTools: true });
-
-const pipeline = sdkPipeline<{ repo: string }>()
-  .step('lint', async ({ state, run }) => {
-    const r = await run('lint', { args: { path: state.repo } });
-    return { lintOutput: r.result.final_output };
-  })
-  // Gate: only continue review if lint produced output
-  .gate((state) => !!state.lintOutput)
-  .step('review', async ({ state, run }) => {
-    const r = await run('review', {
-      extraInstructions: `Lint results:\n${state.lintOutput}`,
-    });
-    return { reviewOutput: r.result.final_output };
-  })
-  .build();
-
-const result = await runPipeline(sdk, pipeline, { repo: './src' });
-console.log(result.state.reviewOutput);
-console.log(result.steps); // Step logs with timing
-
-await sdk.dispose();
-```
-
-Features: typed state threading, `.parallel([...])`, `.gate()` (pipeline barriers), `.branch()` (if/else forks), error strategies (`'skip'`, `'throw'`, custom recovery).
-
-### Pattern 8b: Pipeline Branches
-
-```typescript
-import { QodoSDK, sdkPipeline, runPipeline } from '@qodo/sdk';
-
-const sdk = new QodoSDK({ autoApproveTools: true });
-
-const pipeline = sdkPipeline<{ fileCount: number }>()
-  .branch(
-    (state) => state.fileCount > 20,
-    {
-      true: (b) => b.step('deep', async ({ run }) => {
-        const r = await run('analyze-deep');
-        return { analysis: r.result.final_output };
-      }),
-      false: (b) => b.step('quick', async ({ run }) => {
-        const r = await run('summarize');
-        return { analysis: r.result.final_output };
-      }),
-    },
-    { name: 'size-check' },
-  )
-  .step('report', async ({ state }) => ({
-    report: `${state.fileCount} files: ${state.analysis}`,
-  }))
-  .build();
-
-await sdk.dispose();
-```
-
-### Pattern 9: Dry Run Mode
-
-```typescript
-import { QodoSDK } from '@qodo/sdk';
-
-const sdk = new QodoSDK({ autoApproveTools: true });
-
-// Preview what the agent would do without executing tools
-const result = await sdk.run('review', {
-  args: { path: './src' },
-  dryRun: true,
-});
-
-console.log(result.result.final_output); // Agent describes planned actions
-console.log(result.meta.dry_run);        // true
-
-await sdk.dispose();
-```
-
-### Pattern 10: Tool Middleware (Auditing & Control)
-
-```typescript
-import { QodoSDK, type ToolMiddleware } from '@qodo/sdk';
-
-const auditLogger: ToolMiddleware = {
-  name: 'audit-logger',
-  preExecute(toolData) {
-    console.log(`[AUDIT] ${toolData.server_name}.${toolData.tool_name}`);
-  },
-  postExecute(toolData, result) {
-    console.log(`[AUDIT] Result: ${result.isError ? 'ERROR' : 'OK'}`);
-  },
-};
-
-const readOnly: ToolMiddleware = {
-  name: 'read-only',
-  preExecute(toolData) {
-    if (['write_file', 'edit_file', 'delete_files'].includes(toolData.tool_name)) {
-      throw new Error(`Blocked: ${toolData.tool_name}`);
-    }
-  },
-};
-
-const sdk = new QodoSDK({
-  autoApproveTools: true,
-  toolMiddleware: [auditLogger, readOnly],
-});
-```
-
-### Pattern 11: Tool Approval Policy DSL
-
-```typescript
-import { QodoSDK, sdkPolicy } from '@qodo/sdk';
-
-const policy = sdkPolicy()
-  .approve({ tools: ['read_*', 'list_*', 'git_status', 'git_log'] }, 'allow-reads')
-  .deny({ servers: ['shell'] }, 'block-shell')
-  .deny({ tools: ['write_file', 'edit_file', 'delete_files'] }, 'block-writes')
-  .requireHuman({ tools: ['git_commit'] }, 'review-commits')
-  .default('deny')
-  .build();
-
-const sdk = new QodoSDK({
-  autoApproveTools: false,
-  toolApproval: policy.evaluate,
-});
-
-// Inspect policy decisions:
-const result = policy.evaluateDetailed({
-  tool_name: 'read_files', server_name: 'filesystem', tool_args: {},
-});
-console.log(result.decision, result.matchedRule?.name); // 'approve', 'allow-reads'
-```
-
-### Pattern 12: Execution Timeouts and Retries
-
-```typescript
-import { QodoSDK } from '@qodo/sdk';
-
-const sdk = new QodoSDK({ autoApproveTools: true });
-
-const result = await sdk.run('review', {
-  args: { path: './src' },
-  timeout: 30000,     // 30 second limit per attempt
-  maxRetries: 2,      // Retry up to 2 times on failure
-});
-
-if (result.meta.timed_out) {
-  console.warn('Run timed out');
-}
-
-await sdk.dispose();
-```
-
-### Pattern 13: Artifacts (Pipeline Intermediate Results)
-
-```typescript
-import { QodoSDK, sdkPipeline, runPipeline, ArtifactStore, withArtifacts } from '@qodo/sdk';
-import fs from 'fs/promises';
-
-const store = new ArtifactStore({
-  onPersist: async (artifact) => {
-    await fs.writeFile(`./out/${artifact.stepName}.json`, artifact.serialized);
-  },
-});
-
-const pipeline = sdkPipeline<{ repo: string }>()
-  .step('lint', withArtifacts(store, async ({ state, run }) => {
-    const r = await run('lint', { args: { path: state.repo } });
-    return { lintOutput: r.result.final_output };
-  }))
-  .build();
-
-const result = await runPipeline(sdk, pipeline, { repo: './src' });
-console.log(store.all());       // All artifacts
-console.log(store.getErrors()); // Persistence failures (non-fatal)
-```
-
-### Pattern 14: OpenTelemetry Tracing
-
-```typescript
-import * as otel from '@opentelemetry/api';
-import { QodoSDK, createSdkTracer, SdkEventType, matchSdkEvent } from '@qodo/sdk';
-
-const sdk = new QodoSDK({ autoApproveTools: true });
-const tracer = createSdkTracer(otel, { tracerName: 'my-service' });
-
-// Events flow through unchanged, spans created automatically
-for await (const ev of tracer.wrapStream(sdk.stream('review'))) {
-  matchSdkEvent(ev, {
-    [SdkEventType.MessageDelta]: (e) => process.stdout.write(e.data.delta),
-    [SdkEventType.Final]: (e) => console.log('Done:', e.data.success),
-    default: () => {},
-  });
-}
-
-tracer.flush();
-await sdk.dispose();
-```
-
-No compile-time OTel dependency — install `@opentelemetry/api` as optional peer dep.
-
-### Pattern 15: Backend Info Client (Standalone)
-
-```typescript
-import { QodoInfoClient } from '@qodo/sdk';
-
-// Standalone — no run/stream needed
-const info = new QodoInfoClient();
-const things = await info.getThings();
-console.log(things.available_models);  // ['gpt-4', 'gpt-4o', ...]
-console.log(things.default_model);     // 'gpt-4o'
-console.log(things.session_id);        // new backend session ID
-console.log(things.rate_limit);        // { remaining, reset, limit }
-
-// Convenience
-const models = await info.getAvailableModels();
-
-// Via SDK instance
-const sdk = new QodoSDK();
-const defaultModel = await sdk.info.getDefaultModel();
-```
-
-### Pattern 16: Tool Discovery Client (Standalone)
-
-```typescript
-import { QodoToolsClient } from '@qodo/sdk';
-
-// Standalone — no run/stream needed
-const client = new QodoToolsClient();
-
-// List all tools (built-in + backend)
-const tools = await client.getTools();
-for (const tool of tools) {
-  console.log(`${tool.server}.${tool.name} (${tool.serverType})`);
-  // e.g. "filesystem.read_files (builtin)"
-  // e.g. "sequential_thinking.sequential_thinking (backend)"
-}
-
-// Group by server
-const byServer = await client.getToolsByServer();
-console.log(Object.keys(byServer));
-// ['filesystem', 'git', 'ripgrep', 'shell', 'sequential_thinking', ...]
-
-// Filter by type
-const backendOnly = tools.filter(t => t.serverType === 'backend');
-const builtinOnly = tools.filter(t => t.serverType === 'builtin');
-
-// Via SDK instance
-const sdk = new QodoSDK();
-const allTools = await sdk.tools.getTools();
-```
-
----
-
-## Zod Schema Patterns
-
-### Basic Types with Descriptions
-
-```typescript
-import { z } from '@qodo/sdk'; // Recommended for type compatibility
-
-const output = z.object({
-  // Primitives
-  name: z.string().describe('The name'),
-  count: z.number().describe('Total count'),
-  enabled: z.boolean().describe('Whether enabled'),
-
-  // Optional fields
-  notes: z.string().optional().describe('Optional notes'),
-
-  // With defaults
-  priority: z.number().default(5).describe('Priority level 1-10'),
-
-  // Enums
-  status: z.enum(['pending', 'done', 'failed']).describe('Current status'),
-
-  // Arrays
-  tags: z.array(z.string().describe('Tag name')).describe('List of tags'),
-
-  // Nested objects
-  metadata: z.object({
-    created: z.string().describe('Creation date'),
-    author: z.string().describe('Author name'),
-  }).describe('Metadata information'),
-});
-```
-
-### Flexible Types with zJsonValue and zJsonAny
-
-```typescript
-import { z, zJsonValue, zJsonAny } from '@qodo/sdk';
-
-const output = z.object({
-  // When you need a primitive but don't know which type
-  // Allows: string | number | boolean | null
-  dynamicValue: zJsonValue().describe('A dynamic primitive value'),
-
-  // When you need truly flexible data (including objects/arrays)
-  // Allows: primitives + arrays of primitives + objects with primitive values
-  rawData: zJsonAny().describe('Raw data in any JSON format'),
-
-  // Array of mixed primitives
-  mixedArray: z.array(zJsonValue()).describe('Array of mixed primitive values'),
-});
-```
-
-### Coerced Input Types
-
-```typescript
-import { z, zCoerce } from '@qodo/sdk';
-
-// For CLI-style string inputs that need type conversion
-const args = z.object({
-  // "true"/"false" strings -> boolean
-  verbose: zCoerce.boolean().describe('Enable verbose output'),
-
-  // "123" string -> number
-  limit: zCoerce.number().describe('Result limit'),
-
-  // '["a","b"]' string -> string[]
-  files: zCoerce.jsonArray(z.string()).describe('Files to process'),
-
-  // '{"key":"value"}' string -> object
-  config: zCoerce.jsonObject({ key: z.string() }).describe('Configuration'),
-});
-```
-
----
-
-## Event Types Reference
-
-| Event Type | When Emitted | Key Data Fields |
-|------------|--------------|-----------------|
-| `sdk.init` | SDK initialized | `sdk_version`, `backend.base_url`, `model` |
-| `sdk.run.started` | Run begins | `session_id`, `command`, `prompt_mode`, `cwd`, `dry_run?` |
-| `sdk.message.delta` | Streaming text | `delta`, `message_id`, `role` |
-| `sdk.message.full` | Full message update | `messages.langchain`, `messages.openai` |
-| `sdk.progress` | Progress update | `title`, `status`, `percent` |
-| `sdk.tool.requested` | Tool call requested | `tool_call_id`, `server_name`, `tool_name`, `tool_args`, `pending_approval` |
-| `sdk.tool.approved` | Tool approved/denied | `tool_call_id`, `approved`, `reason` |
-| `sdk.tool.executed` | Tool finished | `tool_call_id`, `result.isError`, `result.content`, `dry_run?` |
-| `sdk.error` | Error occurred | `message`, `cause` |
-| `sdk.final` | Run completed | `success`, `result.structured_output`, `result.final_output`, `meta.dry_run?`, `meta.timed_out?` |
-
----
-
-## QodoSDK Options Reference
-
-```typescript
-interface QodoSDKOptions {
-  // Agent configuration (mutually exclusive)
-  agentFile?: string;           // Path to agent.toml/yaml
-  agentContent?: string;        // Raw TOML/YAML content
-  agentObject?: AIAssistantConfig; // Programmatic config
-
-  // MCP servers
-  mcpFile?: string;             // Path to mcp.json
-  mcpServers?: Record<string, MCPConfig>; // Inline server configs
-
-  // Execution settings
-  model?: string;               // Model override
-  projectPath?: string;         // Working directory
-  additionalPaths?: string[];   // Extra accessible paths
-
-  // Tool handling
-  autoApproveTools?: boolean;   // Auto-approve tools (default: true)
-  toolApproval?: (req) => Promise<boolean> | boolean; // Custom approval
-  toolMiddleware?: ToolMiddleware[]; // Pre/post execution hooks
-
-  // Session
-  contextSessionIds?: string[]; // Previous sessions for context
-
-  // Backend
-  backend?: { baseUrl?: string }; // Backend URL override
-
-  // Debugging
-  debug?: boolean;              // Enable debug logging
-  logger?: QodoSDKLogger;       // Custom logger
-
-  // Mode
-  interactiveMode?: boolean;    // Enable interactive clarifications
-}
-```
-
----
-
-## Common Tasks
-
-### Adding a New Command to an Existing Agent
-
-1. Define the command with `sdkCommand()`:
-   ```typescript
-   const newCommand = sdkCommand({
-     name: 'newCommand',
-     description: 'What this command does',
-     instructions: 'Detailed instructions for the AI',
-     available_tools: ['filesystem', 'ripgrep'],
-     args: sdkArgs({
-       // Define your args
-     }),
-     output: z.object({
-       // Define your output with .describe() on every field
-     }),
-   });
-   ```
-
-2. Add to agent's commands:
-   ```typescript
-   const agent = sdkAgent({
-     commands: {
-       existingCommand,
-       newCommand, // Add here
-     },
-   });
-   ```
-
-### Converting TOML to Programmatic TypeScript
-
-Read the TOML and translate each section:
-
-```typescript
-// From TOML:
-// [commands.analyze]
-// name = "analyze"
-// description = "Analyze code"
-// available_tools = ["filesystem"]
-
-// To TypeScript:
-import { sdkCommand, sdkArgs, z } from '@qodo/sdk';
-
-const analyze = sdkCommand({
-  name: 'analyze',
-  description: 'Analyze code',
-  available_tools: ['filesystem'],
-  args: sdkArgs({ /* from [commands.analyze.arguments] */ }),
-  output: z.object({ /* from [commands.analyze.output_schema] */ }),
-});
-```
-
-### Debugging Schema Validation Errors
-
-When you see `QodoSchemaError: output schema is missing description for: fieldName`:
-
-1. Find the field in your Zod schema
-2. Add `.describe('...')` to it
-3. Check nested objects - all properties need descriptions
-
-```typescript
-// Before (error)
-z.object({
-  items: z.array(z.object({
-    name: z.string(), // Missing description!
-  })),
-})
-
-// After (fixed)
-z.object({
-  items: z.array(z.object({
-    name: z.string().describe('Item name'),
-  })).describe('List of items'),
-})
-```
-
----
-
-## Additional Resources
-
-- [assets/programmatic-agent.ts](assets/programmatic-agent.ts) - Complete working TypeScript agent template
-- [references/builtin-tools.md](references/builtin-tools.md) - Detailed guide to filesystem, git, ripgrep, and shell tools
-- [references/common-issues.md](references/common-issues.md) - Troubleshooting guide for common problems
-
-### Documentation (in `docs/`)
-
-| Feature | Doc |
-|---------|-----|
-| API Reference (Clients, Options, Types) | [docs/api-reference.md](../../../docs/api-reference.md) |
-| Pipeline DSL | [docs/pipeline.md](../../../docs/pipeline.md) |
-| Dry Run Mode | [docs/dry-run.md](../../../docs/dry-run.md) |
-| Tool Middleware | [docs/tool-middleware.md](../../../docs/tool-middleware.md) |
-| Structured Output | [docs/structured-output.md](../../../docs/structured-output.md) |
-| Execution Timeouts | [docs/execution-timeouts.md](../../../docs/execution-timeouts.md) |
-| OpenTelemetry | [docs/opentelemetry.md](../../../docs/opentelemetry.md) |
-| Approval Policies | [docs/approval-policies.md](../../../docs/approval-policies.md) |
-| Artifacts | [docs/artifacts.md](../../../docs/artifacts.md) |