@qodo/sdk 0.4.0 → 0.6.0

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

@@ -0,0 +1,656 @@
+---
+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 |
+
+### 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) |
+| `QodoSessionsClient` | Session history management |
+
+### Errors
+
+| Export | Purpose |
+|--------|---------|
+| `QodoSchemaError` | Schema validation failures |
+| `QodoAuthError` | Authentication failures |
+| `QodoBackendBootstrapError` | Backend initialization failures |
+
+### 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()]);
+}
+```
+
+---
+
+## 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` |
+| `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` |
+| `sdk.error` | Error occurred | `message`, `cause` |
+| `sdk.final` | Run completed | `success`, `result.structured_output`, `result.final_output`, `messages` |
+
+---
+
+## 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
+
+  // 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