@qodo/sdk 0.7.0 → 0.8.0

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

@@ -39,6 +39,47 @@ Use this skill when working with `@qodo/sdk` to build AI-powered agents. This sk
 | `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 |
+
+### 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 |
@@ -60,6 +101,9 @@ Use this skill when working with `@qodo/sdk` to build AI-powered agents. This sk
 | `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
 
@@ -437,6 +481,178 @@ try {
 }
 ```
 
+### 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 };
+  })
+  .step('review', async ({ state, run }) => {
+    // TypeScript knows state has `repo` + `lintOutput`
+    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([...])`, gates, error strategies (`'skip'`, `'throw'`, custom recovery).
+
+### 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.
+
 ---
 
 ## Zod Schema Patterns
@@ -519,15 +735,15 @@ const args = z.object({
 | 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.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` |
+| `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`, `messages` |
+| `sdk.final` | Run completed | `success`, `result.structured_output`, `result.final_output`, `meta.dry_run?`, `meta.timed_out?` |
 
 ---
 
@@ -552,6 +768,7 @@ interface QodoSDKOptions {
   // 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
@@ -654,3 +871,16 @@ z.object({
 - [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 |
+|---------|-----|
+| 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) |

package/.claude/skills/qodo-agent/assets/programmatic-agent.ts

@@ -5,6 +5,10 @@
  * - sdkAgent() and sdkCommand() builders
  * - Zod schemas with proper descriptions
  * - Event streaming with matchSdkEvent()
+ * - Pipeline DSL with typed state threading
+ * - Tool middleware for auditing
+ * - Dry run mode
+ * - Execution timeouts
  * - Error handling
  * - Proper cleanup with dispose()
  *
@@ -23,7 +27,11 @@ import {
   zJsonAny,
   QodoSchemaError,
   QodoAuthError,
-  z
+  QodoOutputValidationError,
+  sdkPipeline,
+  runPipeline,
+  z,
+  type ToolMiddleware,
 } from '@qodo/sdk';
 
 // =============================================================================
@@ -180,6 +188,17 @@ Guidelines:
 // =============================================================================
 
 async function main() {
+  // Optional: create tool middleware for auditing
+  const auditMiddleware: ToolMiddleware = {
+    name: 'audit',
+    preExecute(toolData) {
+      console.log(`  [audit] >>> ${toolData.server_name}.${toolData.tool_name}`);
+    },
+    postExecute(toolData, result) {
+      console.log(`  [audit] <<< ${result.isError ? 'ERROR' : 'OK'}`);
+    },
+  };
+
   // Create SDK from the agent configuration
   const sdk = QodoSDK.fromAgent(codeAssistantAgent, {
     // Optional: override project path (defaults to cwd)
@@ -188,6 +207,9 @@ async function main() {
     // Optional: enable debug logging
     // debug: true,
 
+    // Optional: tool middleware for auditing, rate limiting, etc.
+    toolMiddleware: [auditMiddleware],
+
     // Optional: custom tool approval (default: auto-approve)
     // autoApproveTools: false,
     // toolApproval: async ({ tool_name, tool_args }) => {
@@ -296,6 +318,54 @@ async function main() {
     );
     // @ts-ignore
     console.log('Response:', promptResult.final_output);
+    // -------------------------------------------------------------------------
+    // Example 4: Pipeline (multi-step workflow)
+    // -------------------------------------------------------------------------
+    console.log('\n\n--- Pipeline example ---\n');
+
+    const pipeline = sdkPipeline<{ path: string }>()
+      .step('analyze', async ({ state, run }) => {
+        const r = await run('analyze', { args: { path: state.path } });
+        return { analysis: r.result.structured_output };
+      })
+      .step('summarize', async ({ state, run }) => {
+        const r = await run('', {
+          extraInstructions: `Summarize these findings in one paragraph: ${JSON.stringify(state.analysis)}`,
+        });
+        return { summary: r.result.final_output };
+      })
+      .build();
+
+    const pipelineResult = await runPipeline(sdk, pipeline, { path: './src' });
+    console.log('Pipeline summary:', pipelineResult.state.summary);
+    for (const log of pipelineResult.steps) {
+      console.log(`  ${log.name}: ${log.status} (${log.durationMs}ms)`);
+    }
+
+    // -------------------------------------------------------------------------
+    // Example 5: Dry run mode (preview without side effects)
+    // -------------------------------------------------------------------------
+    console.log('\n\n--- Dry run example ---\n');
+
+    const dryResult = await sdk.run('analyze', {
+      args: { path: './src' },
+      dryRun: true,
+    });
+    console.log('Dry run output:', dryResult.result.final_output?.slice(0, 200));
+    console.log('Was dry run:', dryResult.meta.dry_run);
+
+    // -------------------------------------------------------------------------
+    // Example 6: Execution timeout with retry
+    // -------------------------------------------------------------------------
+    console.log('\n\n--- Timeout example ---\n');
+
+    const timedResult = await sdk.run('analyze', {
+      args: { path: './src' },
+      timeout: 60000,     // 60 second limit
+      maxRetries: 1,      // Retry once on failure
+    });
+    console.log('Timed out:', timedResult.meta.timed_out ?? false);
+
   } catch (error) {
     // Handle specific error types
     if (error instanceof QodoSchemaError) {
@@ -304,6 +374,9 @@ async function main() {
     } else if (error instanceof QodoAuthError) {
       console.error('Authentication error:', error.message);
       console.error('Check your QODO_API_KEY environment variable');
+    } else if (error instanceof QodoOutputValidationError) {
+      console.error('Output validation error:', error.issues);
+      console.error('Raw output:', error.rawOutput);
     } else {
       throw error;
     }

package/.claude/skills/qodo-agent/references/common-issues.md

@@ -422,6 +422,85 @@ const sdk = new QodoSDK({
 
 ---
 
+## Pipeline and Middleware Errors
+
+### Pipeline Step Failed
+
+**Error:**
+```
+PipelineExecutionError: Step "lint" failed: ...
+```
+
+**Cause:** A pipeline step threw an error and no error strategy was set.
+
+**Solution:** Add error handling per step:
+
+```typescript
+sdkPipeline()
+  .step('lint', lintFn, { onError: 'skip' })        // Skip on failure
+  .step('review', reviewFn, {
+    onError: (error, state) => ({ fallback: true }),  // Custom recovery
+  })
+  .build();
+```
+
+---
+
+### Structured Output Validation Failed
+
+**Error:**
+```
+QodoOutputValidationError: Structured output validation failed
+```
+
+**Cause:** The agent returned data that doesn't match the Zod output schema.
+
+**Solution:** Check `error.issues` for details and `error.rawOutput` for what the agent actually returned:
+
+```typescript
+import { QodoOutputValidationError } from '@qodo/sdk';
+
+try {
+  await sdk.run('analyze');
+} catch (e) {
+  if (e instanceof QodoOutputValidationError) {
+    console.error('Issues:', e.issues);    // [{ path: ['score'], message: '...' }]
+    console.error('Raw:', e.rawOutput);    // What the agent returned
+  }
+}
+```
+
+---
+
+### Tool Middleware Error
+
+**Error:**
+```
+ToolMiddlewareError: Middleware "my-middleware" failed in preExecute
+```
+
+**Cause:** A tool middleware hook threw or timed out (default: 10s).
+
+**Solution:** Check the middleware implementation and handle errors gracefully:
+
+```typescript
+import { ToolMiddlewareError, MIDDLEWARE_TIMEOUT_MS } from '@qodo/sdk';
+
+// Middleware hooks should be fast and defensive
+const safeMiddleware = {
+  name: 'safe-mw',
+  preExecute(toolData) {
+    try {
+      // Your logic here
+    } catch {
+      // Don't throw — return void to pass through
+    }
+  },
+};
+```
+
+---
+
 ## Quick Debugging Checklist
 
 When something isn't working:

package/dist/api/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/api/agent.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,YAAY,EAAC,MAAM,QAAQ,CAAC;AAGpC,OAAO,EAGL,YAAY,EAEb,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAK9C,OAAO,EAAkB,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAuBhE,qBAAa,QAAS,SAAQ,YAAY;IAkC5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAjC5C,OAAO,CAAC,QAAQ,CAAkB;IAElC,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,cAAc,CAAC,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsC;IAI1E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IACvD,OAAO,CAAC,eAAe,CAAM;IAC7B,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,kBAAkB,CAAsB;IAChD,OAAO,CAAC,cAAc,CAAS;IAI/B,OAAO,CAAC,wBAAwB,CAA8B;gBAEjC,cAAc,CAAC,EAAE,cAAc,YAAA;YAuB9C,eAAe;IAyB7B,OAAO,CAAC,sBAAsB;IAkF9B,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,oBAAoB;IAKrB,kBAAkB,IAAI,eAAe;IAIrC,uBAAuB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAKtF,OAAO,CAAC,oBAAoB;YAUd,6BAA6B;IAkBpC,iBAAiB,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI;IAgB5C,kBAAkB,IAAI,IAAI;IAK3B,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBxE,OAAO,CAAC,yBAAyB;IAUpB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAmC1G,UAAU,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAarD,SAAS,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB7C,iBAAiB,CAAC,OAAO,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvE,OAAO,CAAC,eAAe;YA4BT,cAAc;IAKrB,oBAAoB,IAAI,IAAI;IAInC,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,sBAAsB;YAUhB,iBAAiB;YASjB,kBAAkB;YAWlB,aAAa;YAqEb,sBAAsB;YAStB,cAAc;YAsCd,uBAAuB;YA0CvB,kBAAkB;IA4ChC,OAAO,CAAC,mBAAmB;YAIb,gBAAgB;YAWhB,aAAa;YAab,mBAAmB;YAqDnB,iBAAiB;YAajB,QAAQ;YAiGR,gBAAgB;IAmD9B,OAAO,CAAC,kBAAkB;YAwBZ,oBAAoB;YAgBpB,mBAAmB;YAUnB,WAAW;IAkClB,kBAAkB,IAAI,IAAI;IAK1B,OAAO,IAAI,IAAI;IAUf,cAAc,IAAI,WAAW;CAGrC"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/api/agent.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,YAAY,EAAC,MAAM,QAAQ,CAAC;AAGpC,OAAO,EAGL,YAAY,EAEb,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAK9C,OAAO,EAAkB,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAuBhE,qBAAa,QAAS,SAAQ,YAAY;IAkC5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAjC5C,OAAO,CAAC,QAAQ,CAAkB;IAElC,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,cAAc,CAAC,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsC;IAI1E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IACvD,OAAO,CAAC,eAAe,CAAM;IAC7B,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,kBAAkB,CAAsB;IAChD,OAAO,CAAC,cAAc,CAAS;IAI/B,OAAO,CAAC,wBAAwB,CAA8B;gBAEjC,cAAc,CAAC,EAAE,cAAc,YAAA;YAuB9C,eAAe;IAyB7B,OAAO,CAAC,sBAAsB;IAkF9B,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,oBAAoB;IAKrB,kBAAkB,IAAI,eAAe;IAIrC,uBAAuB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAKtF,OAAO,CAAC,oBAAoB;YAUd,6BAA6B;IAkBpC,iBAAiB,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI;IAgB5C,kBAAkB,IAAI,IAAI;IAK3B,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBxE,OAAO,CAAC,yBAAyB;IAUpB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAmC1G,UAAU,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAarD,SAAS,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB7C,iBAAiB,CAAC,OAAO,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvE,OAAO,CAAC,eAAe;YA4BT,cAAc;IAKrB,oBAAoB,IAAI,IAAI;IAInC,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,sBAAsB;YAUhB,iBAAiB;YASjB,kBAAkB;YAWlB,aAAa;YAqEb,sBAAsB;YAStB,cAAc;YAsCd,uBAAuB;YA0CvB,kBAAkB;IA4ChC,OAAO,CAAC,mBAAmB;YAIb,gBAAgB;YAWhB,aAAa;YAab,mBAAmB;YA0DnB,iBAAiB;YAajB,QAAQ;YAiGR,gBAAgB;IAmD9B,OAAO,CAAC,kBAAkB;YAwBZ,oBAAoB;YAgBpB,mBAAmB;YAUnB,WAAW;IAkClB,kBAAkB,IAAI,IAAI;IAK1B,OAAO,IAAI,IAAI;IAUf,cAAc,IAAI,WAAW;CAGrC"}

package/dist/api/agent.js

@@ -6,7 +6,7 @@ import { getUserData, getCurrentGitSha1 } from "./utils.js";
 import { EndNode, UserResponse } from "../constants/tools.js";
 import { SessionContext } from "../session/index.js";
 import { TaskTracker } from "./taskTracking.js";
-import { toolProcessorManager } from "../mcp/index.js";
+import { ToolProcessorManager } from "../mcp/index.js";
 import process from "node:process";
 import { ServerData } from "../session/index.js";
 import { httpRequest } from "./http.js";
@@ -166,7 +166,7 @@ export class AgentAPI extends EventEmitter {
                     await this.responseCallback({ forceStop: true });
                 }
             }
-            catch { }
+            catch { /* best-effort: forceStop on reconnect should not crash the WS listener */ }
         });
         this.wsClient.on('checkpointRecovery', (info) => {
             this.debug('[AgentAPI] Checkpoint recovery initiated', `| Reason: ${info.reason}`, info.checkpoint ? `| Checkpoint: ${info.checkpoint.substring(0, 8)}` : '');
@@ -639,10 +639,15 @@ export class AgentAPI extends EventEmitter {
                 return;
             }
             const isAutoApprovedTool = this.mcpManager.isAutoApprovedTool(toolData.server_name, toolData.tool, toolData.tool_args);
-            // Dry run tools if configured
-            const processedToolData = await toolProcessorManager.preProcessTool(toolData, this.sessionContext);
+            const processedToolData = await ToolProcessorManager.getInstance().preProcessTool(toolData, this.sessionContext);
             await this.processToolReasoning(processedToolData, isAutoApprovedTool);
-            if (isAutoApprovedTool) {
+            // Dry run: simulate tool execution without side effects
+            if (this.sessionContext?.isDryRun()) {
+                const dryResult = await ToolProcessorManager.getInstance().dryRunTool(processedToolData, this.sessionContext);
+                await this.processToolResponse(processedToolData, dryResult);
+                await this.sendToolResponse(processedToolData, dryResult);
+            }
+            else if (isAutoApprovedTool) {
                 await this.callTool(processedToolData);
             }
             else {
@@ -701,7 +706,7 @@ export class AgentAPI extends EventEmitter {
                     }
                 }
             }
-            catch { }
+            catch { /* best-effort: tool arg patching should not block tool execution */ }
             if (!this.mcpManager) {
                 // Should not be reachable because we guard earlier, but keep a safe fallback
                 // that gracefully declines the tool call instead of throwing.
@@ -723,7 +728,7 @@ export class AgentAPI extends EventEmitter {
                         return;
                     }
                     // Post-process the tool result
-                    const processedResponse = await toolProcessorManager.postProcessTool(toolData, response);
+                    const processedResponse = await ToolProcessorManager.getInstance().postProcessTool(toolData, response);
                     await this.processToolResponse(toolData, processedResponse);
                     // Send tool response via WebSocket
                     await this.sendToolResponse(toolData, processedResponse);
@@ -870,7 +875,7 @@ export class AgentAPI extends EventEmitter {
         try {
             this.cleanupConnections();
         }
-        catch { }
+        catch { /* cleanup: connection teardown must not throw */ }
         this.pendingToolRequests.clear();
         this.currentSession = undefined;
         this.latestSessionId = "";