@qodo/sdk 0.13.4 → 2.0.0-next.0

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

@@ -1,537 +0,0 @@
-# Common Issues and Solutions
-
-This guide covers frequent problems when working with `@qodo/sdk` and how to resolve them.
-
-## Table of Contents
-
-1. [Schema Validation Errors](#schema-validation-errors)
-2. [Import and Module Errors](#import-and-module-errors)
-3. [Tool Configuration Issues](#tool-configuration-issues)
-4. [Session Management](#session-management)
-5. [Streaming and Events](#streaming-and-events)
-6. [Authentication](#authentication)
-
----
-
-## Schema Validation Errors
-
-### Missing `.describe()` on Output Properties
-
-**Error:**
-```
-QodoSchemaError: output schema is missing description for: fieldName
-```
-
-**Cause:** Every property in output schemas must have a description for the LLM to understand what to generate.
-
-**Solution:** Add `.describe()` to every property, including nested ones:
-
-```typescript
-// WRONG
-const output = z.object({
-  name: z.string(),
-  items: z.array(z.object({
-    id: z.number(),
-  })),
-});
-
-// CORRECT
-const output = z.object({
-  name: z.string().describe('The name of the entity'),
-  items: z.array(z.object({
-    id: z.number().describe('Unique identifier'),
-  })).describe('List of items'),
-});
-```
-
-**Tip:** For nested objects, every level needs descriptions.
-
----
-
-### Using `z.any()` in Output Schemas
-
-**Error:**
-```
-QodoSchemaError: Output schema contains z.any() or z.unknown() at: fieldName.
-These types produce incomplete JSON schemas that OpenAI rejects...
-```
-
-**Cause:** `z.any()` and `z.unknown()` produce JSON Schema without proper type definitions, which structured output APIs reject.
-
-**Solution:** Use `zJsonValue()` or `zJsonAny()` instead:
-
-```typescript
-import { zJsonValue, zJsonAny } from '@qodo/sdk';
-
-// WRONG
-const output = z.object({
-  data: z.any().describe('Dynamic data'),
-});
-
-// CORRECT - for primitives (string | number | boolean | null)
-const output = z.object({
-  value: zJsonValue().describe('A primitive value'),
-});
-
-// CORRECT - for any JSON (primitives + arrays + objects)
-const output = z.object({
-  data: zJsonAny().describe('Any JSON data'),
-});
-```
-
-**When to use which:**
-- `zJsonValue()` - When you expect a single primitive value
-- `zJsonAny()` - When you need maximum flexibility (objects, arrays, etc.)
-- Specific types - When you know the structure (preferred for type safety)
-
----
-
-### Invalid Args Schema
-
-**Error:**
-```
-QodoSchemaError: Args schema must be an object with properties
-```
-
-**Cause:** The args schema must be a `z.object()`.
-
-**Solution:** Wrap your args in `z.object()` or use `sdkArgs()`:
-
-```typescript
-// WRONG
-const args = z.string();
-
-// CORRECT
-const args = sdkArgs({
-  path: z.string().describe('Path to process'),
-});
-
-// Also correct
-const args = z.object({
-  path: z.string().describe('Path to process'),
-});
-```
-
----
-
-## Import and Module Errors
-
-### Zod 4 Type Compatibility
-
-**Error (TypeScript):**
-```
-Type 'ZodObject<any, $strip>' is not assignable to parameter of type 'ZodType<any, ZodTypeDef, any>'
-```
-
-**Cause:** The SDK uses `zod-to-json-schema` internally which expects Zod 3 compatible types. When using Zod 4, importing from `'zod'` gives you Zod 4 types that aren't type-compatible.
-
-**Solution:** Import `z` from `@qodo/sdk` for guaranteed compatibility:
-
-```typescript
-// RECOMMENDED - works with both Zod 3 and Zod 4
-import { z, sdkCommand, sdkArgs } from '@qodo/sdk';
-
-// ALSO WORKS for Zod 3 users
-import { z } from 'zod';
-
-// FOR ZOD 4 USERS (if not importing from @qodo/sdk)
-import { z } from 'zod/v3';
-```
-
-**Note:** The SDK supports both Zod 3 (`^3.25`) and Zod 4 (`^4.0`) as peer dependencies.
-
----
-
-### Missing `.js` Extension (SDK Contributors Only)
-
-**Error:**
-```
-Error [ERR_MODULE_NOT_FOUND]: Cannot find module './schemas' imported from...
-```
-
-**Cause:** ESM requires explicit file extensions in imports.
-
-**Note:** This only applies when modifying the SDK source code, not when using `@qodo/sdk` as a dependency.
-
-**Solution:** Add `.js` extensions to relative imports:
-
-```typescript
-// WRONG (in SDK source code)
-import { zodOutputSchema } from './schemas';
-
-// CORRECT
-import { zodOutputSchema } from './schemas.js';
-```
-
----
-
-### CommonJS vs ESM
-
-**Error:**
-```
-require() of ES Module ... not supported
-```
-
-**Cause:** `@qodo/sdk` is ESM-only.
-
-**Solution:** Either:
-
-1. Set `"type": "module"` in your `package.json`
-2. Use `.mjs` extension for your files
-3. Use dynamic import:
-
-```typescript
-// In CommonJS context
-const { QodoSDK } = await import('@qodo/sdk');
-```
-
----
-
-## Tool Configuration Issues
-
-### Tools Not Available
-
-**Symptom:** Agent doesn't use expected tools, or tools fail.
-
-**Possible causes:**
-
-1. **Tool not in `available_tools`:**
-   ```typescript
-   sdkCommand({
-     name: 'analyze',
-     // Make sure needed tools are listed
-     available_tools: ['filesystem', 'ripgrep', 'git'],
-   });
-   ```
-
-2. **Tool in `ignore_tools`:**
-   ```typescript
-   // Check if tool is accidentally ignored
-   sdkCommand({
-     ignore_tools: ['shell'], // Don't include tools you need
-   });
-   ```
-
-3. **MCP server not configured:**
-   ```typescript
-   const sdk = new QodoSDK({
-     mcpServers: {
-       'custom-server': {
-         command: 'npx',
-         args: ['my-mcp-server'],
-       },
-     },
-   });
-   ```
-
----
-
-### Tool Approval Issues
-
-**Symptom:** Tools hang or are silently rejected.
-
-**Solution:** Check your approval configuration:
-
-```typescript
-// Default: all tools auto-approved
-const sdk = new QodoSDK();
-
-// Require explicit approval
-const sdk = new QodoSDK({
-  autoApproveTools: false,
-  toolApproval: async ({ tool_name, tool_args }) => {
-    // Must return true to approve, false to deny
-    console.log(`Approving: ${tool_name}`);
-    return true;
-  },
-});
-```
-
-**Common mistake:** Setting `autoApproveTools: false` without providing `toolApproval` callback - tools will be denied.
-
----
-
-## Session Management
-
-### Session Not Persisting
-
-**Symptom:** Agent doesn't remember previous conversation.
-
-**Cause:** Each `QodoSDK` instance starts a new session by default.
-
-**Solution:** Use `withSession()` to continue a session:
-
-```typescript
-// First run - capture session ID
-let sessionId: string;
-for await (const event of sdk.stream('analyze')) {
-  if (event.type === 'sdk.run.started') {
-    sessionId = event.data.session_id;
-  }
-}
-
-// Later - continue the session
-const sdk2 = new QodoSDK().withSession(sessionId);
-```
-
----
-
-### Multiple Concurrent Runs
-
-**Symptom:** Unexpected behavior when running multiple commands simultaneously.
-
-**Cause:** Single SDK instance handles concurrent runs by creating internal delegates.
-
-**Solution:** For explicit isolation, create separate SDK instances:
-
-```typescript
-// Option 1: Let SDK handle it (creates internal delegate)
-const results = await Promise.all([
-  sdk.run('analyze', { args: { path: './src' } }),
-  sdk.run('analyze', { args: { path: './tests' } }),
-]);
-
-// Option 2: Explicit separate instances (recommended for clarity)
-const sdk1 = QodoSDK.fromAgent(agent);
-const sdk2 = QodoSDK.fromAgent(agent);
-try {
-  const results = await Promise.all([
-    sdk1.run('analyze', { args: { path: './src' } }),
-    sdk2.run('analyze', { args: { path: './tests' } }),
-  ]);
-} finally {
-  await Promise.all([sdk1.dispose(), sdk2.dispose()]);
-}
-```
-
----
-
-## Streaming and Events
-
-### Events Not Firing
-
-**Symptom:** `matchSdkEvent` handlers not being called.
-
-**Possible causes:**
-
-1. **Not iterating the stream:**
-   ```typescript
-   // WRONG - stream not consumed
-   sdk.stream('analyze');
-
-   // CORRECT - must iterate
-   for await (const event of sdk.stream('analyze')) {
-     // handle events
-   }
-   ```
-
-2. **Missing event type in handler:**
-   ```typescript
-   matchSdkEvent(event, {
-     [SdkEventType.Final]: (e) => { /* ... */ },
-     // Add handler for events you care about
-     // Use 'default' to catch unhandled events
-     default: (e) => console.log('Unhandled:', e.type),
-   });
-   ```
-
----
-
-### Stream Ends Without Final Event
-
-**Symptom:** Stream completes but `sdk.final` never fires.
-
-**Possible causes:**
-
-1. **Error during initialization** - Check for `sdk.error` events
-2. **Network issues** - The backend connection may have dropped
-
-**Solution:** Always handle error events:
-
-```typescript
-for await (const event of sdk.stream('analyze')) {
-  matchSdkEvent(event, {
-    [SdkEventType.Error]: (e) => {
-      console.error('Error occurred:', e.data.message);
-    },
-    [SdkEventType.Final]: (e) => {
-      if (!e.data.success) {
-        console.error('Run failed:', e.data.error);
-      }
-    },
-  });
-}
-```
-
----
-
-## Authentication
-
-### Authentication Failed
-
-**Error:**
-```
-QodoAuthError: Authentication failed
-```
-
-**Causes and solutions:**
-
-1. **Missing API key:**
-   ```bash
-   export QODO_API_KEY=your-api-key
-   ```
-
-2. **Invalid API key:**
-   - Verify the key is correct
-   - Check if the key has expired
-
-3. **Backend URL issues:**
-   ```typescript
-   const sdk = new QodoSDK({
-     backend: {
-       baseUrl: 'https://api.qodo.ai', // Ensure correct URL
-     },
-   });
-   ```
-
----
-
-### Backend Bootstrap Failed
-
-**Error:**
-```
-QodoBackendBootstrapError: Failed to initialize backend
-```
-
-**Causes:**
-- Network connectivity issues
-- Backend service unavailable
-- Incorrect backend URL
-
-**Solution:**
-1. Check network connectivity
-2. Verify backend URL is correct
-3. Check if backend service is running (for self-hosted)
-
-```typescript
-// Enable debug to see more details
-const sdk = new QodoSDK({
-  debug: true,
-});
-```
-
----
-
-## 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, or use gates to guard steps:
-
-```typescript
-sdkPipeline()
-  .step('lint', lintFn, { onError: 'skip' })        // Skip on failure
-  .gate((state) => !!state.lintOutput)               // Gate: halt if no lint output
-  .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:
-
-1. **Enable debug mode:**
-   ```typescript
-   const sdk = new QodoSDK({ debug: true });
-   ```
-
-2. **Check all events, not just Final:**
-   ```typescript
-   for await (const event of sdk.stream('cmd')) {
-     console.log(event.type, JSON.stringify(event.data, null, 2));
-   }
-   ```
-
-3. **Verify schema descriptions:**
-   - Every output property has `.describe()`
-   - No `z.any()` or `z.unknown()` in outputs
-
-4. **Check tool configuration:**
-   - Required tools in `available_tools`
-   - No needed tools in `ignore_tools`
-
-5. **Verify cleanup:**
-   - `await sdk.dispose()` is called
-   - Use `try/finally` pattern
-
-6. **Check environment:**
-   - `QODO_API_KEY` is set
-   - Node.js >= 18
-   - Package has `"type": "module"` for ESM
-   - Import `z` from `@qodo/sdk` (not `'zod'`) for Zod 4 compatibility

package/dist/api/agent.d.ts

@@ -1,105 +0,0 @@
-import { EventEmitter } from "events";
-import { AgentSession } from "./types.js";
-import { SessionContext } from "../session/index.js";
-import { TaskTracker } from "./taskTracking.js";
-import { ConnectionState } from "./websocket.js";
-export declare class AgentAPI extends EventEmitter {
-    private readonly sessionContext?;
-    private wsClient;
-    private shouldDebugLog;
-    private debug;
-    private currentSession?;
-    private readonly pendingToolRequests;
-    private readonly inFlightToolCalls;
-    private readonly answeredToolCalls;
-    private latestSessionId;
-    private lastToolId;
-    private readonly mcpManager?;
-    private readonly taskTracker;
-    private pendingResumeError;
-    private userHasControl;
-    private currentMessageProcessing;
-    constructor(sessionContext?: SessionContext | undefined);
-    private ensureConnected;
-    private setupWebSocketHandlers;
-    private setupNetworkListeners;
-    private handleNetworkOnline;
-    private handleNetworkOffline;
-    getConnectionState(): ConnectionState;
-    onConnectionStateChange(callback: (state: ConnectionState) => void): () => void;
-    /**
-     * Protocol-v2 transport metrics. Delegates to the underlying WebSocket client.
-     * Safe to call at any time; values are a point-in-time snapshot.
-     */
-    getTransportMetrics(): Record<string, number>;
-    /**
-     * Subscribe to protocol-v2 transport lifecycle events.
-     *
-     * The SDK's own stream layer uses this to surface `Reconnecting`,
-     * `Reconnected`, `ResumeReconciled`, `ReconcileFailed`, and `StallDetected`
-     * events with proper envelopes. External callers can also subscribe for
-     * fine-grained observability without touching the WebSocketClient directly.
-     */
-    onTransportEvent(handlers: {
-        reconnecting?: (info: {
-            attempt: number;
-        }) => void;
-        reconnected?: (info: {
-            downtime_ms?: number;
-        }) => void;
-        resumeAck?: (info: {
-            current_checkpoint?: string | null;
-            last_consumed_turn_id?: string | null;
-            awaiting: {
-                type: 'prompt' | 'tool_result' | 'none';
-                tool_call_id?: string;
-            };
-            outbox_size: number;
-        }) => void;
-        reconcileFailed?: (info: {
-            reason: string;
-            awaiting?: any;
-        }) => void;
-        stallDetected?: (info: {
-            stage: string;
-            outboxSize: number;
-        }) => void;
-    }): () => void;
-    private handleWebSocketError;
-    private handleUnexpectedDisconnection;
-    setUserHasControl(hasControl: boolean): void;
-    resetActivityTimer(): void;
-    toolApproval(identifier: string, approved: boolean): Promise<void>;
-    private cleanupOldestPendingTools;
-    tryPrefetchSummarization(sessionIds: string[], taskFocus?: string): Promise<Record<string, string>>;
-    resumeTask(agentSession: AgentSession): Promise<void>;
-    startTask(agentSession: AgentSession): Promise<void>;
-    finishCurrentTask(isError?: boolean): Promise<void>;
-    private collectBaseData;
-    private initializeTask;
-    cancelCurrentSession(): void;
-    private requestCancellation;
-    private disconnectAndReconnect;
-    private checkCancellation;
-    private handleCancellation;
-    private sendUserQuery;
-    private handleWebSocketMessage;
-    private processMessage;
-    private handleTaskResponseError;
-    private handleTaskResponse;
-    private isValidTaskResponse;
-    private responseCallback;
-    private handleEndNode;
-    private handleToolExecution;
-    private handleToolDecline;
-    private callTool;
-    private sendToolResponse;
-    private convertToolsForIDE;
-    private processToolReasoning;
-    private processToolResponse;
-    private handleError;
-    cleanupConnections(): void;
-    cleanup(): void;
-    getTaskTracker(): TaskTracker;
-}
-//# sourceMappingURL=agent.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/api/agent.ts"],"names":[],"mappings":"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"}