@qodo/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,118 @@
+Qodo SDK Software License Agreement
+
+Copyright (c) 2024-2025 Qodo Ltd. All Rights Reserved.
+
+IMPORTANT: READ THIS LICENSE AGREEMENT CAREFULLY BEFORE USING THIS SOFTWARE.
+
+1. DEFINITIONS
+
+"Software" means the Qodo SDK, including all source code, object code, documentation,
+and any updates or modifications provided by Qodo Ltd.
+
+"Licensee" means the individual or entity that has agreed to this License.
+
+"Authorized Use" means use of the Software solely in connection with Qodo's services
+and with a valid API key or subscription obtained from Qodo Ltd.
+
+2. LICENSE GRANT
+
+Subject to the terms of this Agreement, Qodo Ltd. grants Licensee a limited,
+non-exclusive, non-transferable, revocable license to use the Software solely for
+Authorized Use in connection with Qodo's services.
+
+3. RESTRICTIONS
+
+Licensee shall NOT:
+
+(a) Copy, reproduce, or duplicate the Software except as necessary for Authorized Use;
+
+(b) Modify, adapt, translate, reverse engineer, decompile, disassemble, or create
+    derivative works based on the Software;
+
+(c) Distribute, sublicense, lease, rent, loan, or otherwise transfer the Software
+    to any third party;
+
+(d) Remove, alter, or obscure any proprietary notices, labels, or marks on the Software;
+
+(e) Use the Software to build a competing product or service;
+
+(f) Use the Software without a valid API key or subscription from Qodo Ltd.;
+
+(g) Circumvent any technical limitations or access controls in the Software;
+
+(h) Use the Software in any manner that violates applicable laws or regulations.
+
+4. INTELLECTUAL PROPERTY
+
+The Software is proprietary to Qodo Ltd. and is protected by copyright, trade secret,
+and other intellectual property laws. Qodo Ltd. retains all right, title, and interest
+in and to the Software, including all intellectual property rights therein. No title
+to or ownership of the Software is transferred to Licensee.
+
+5. CONFIDENTIALITY
+
+Licensee acknowledges that the Software contains trade secrets and confidential
+information of Qodo Ltd. Licensee agrees to maintain the confidentiality of the
+Software and not to disclose it to any third party without Qodo's prior written consent.
+
+6. NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, AND NONINFRINGEMENT. QODO LTD. DOES NOT WARRANT THAT THE
+SOFTWARE WILL BE ERROR-FREE OR UNINTERRUPTED.
+
+7. LIMITATION OF LIABILITY
+
+IN NO EVENT SHALL QODO LTD. BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
+CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS, REVENUE, DATA, OR
+USE, ARISING OUT OF OR RELATED TO THIS AGREEMENT OR THE SOFTWARE, EVEN IF QODO
+LTD. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. QODO LTD.'S TOTAL
+LIABILITY SHALL NOT EXCEED THE AMOUNTS PAID BY LICENSEE FOR THE SOFTWARE IN THE
+TWELVE (12) MONTHS PRECEDING THE CLAIM.
+
+8. TERMINATION
+
+This license is effective until terminated. Qodo Ltd. may terminate this license
+immediately upon written notice if Licensee breaches any term of this Agreement.
+Upon termination, Licensee must cease all use of the Software and destroy all
+copies in Licensee's possession or control.
+
+9. AUDIT RIGHTS
+
+Qodo Ltd. reserves the right to audit Licensee's use of the Software to verify
+compliance with this Agreement. Licensee agrees to cooperate with such audits
+and provide reasonable access to relevant records.
+
+10. EXPORT COMPLIANCE
+
+Licensee agrees to comply with all applicable export and import laws and regulations
+in connection with the use of the Software.
+
+11. GOVERNING LAW
+
+This Agreement shall be governed by and construed in accordance with the laws of
+the State of Israel, without regard to its conflict of laws principles. Any disputes
+arising under this Agreement shall be subject to the exclusive jurisdiction of the
+courts located in Tel Aviv, Israel.
+
+12. ENTIRE AGREEMENT
+
+This Agreement constitutes the entire agreement between the parties concerning the
+subject matter hereof and supersedes all prior or contemporaneous agreements,
+representations, warranties, and understandings.
+
+13. SEVERABILITY
+
+If any provision of this Agreement is held to be unenforceable, the remaining
+provisions shall continue in full force and effect.
+
+14. CONTACT
+
+For licensing inquiries or permissions, contact:
+Qodo Ltd.
+Email: support@qodo.ai
+Website: https://www.qodo.ai
+
+BY USING THIS SOFTWARE, YOU ACKNOWLEDGE THAT YOU HAVE READ THIS AGREEMENT,
+UNDERSTAND IT, AND AGREE TO BE BOUND BY ITS TERMS AND CONDITIONS.

package/README.md

@@ -0,0 +1,121 @@
+# @qodo/sdk
+
+Official TypeScript SDK for building AI-powered agents with Qodo.
+
+## Installation
+
+```bash
+npm install @qodo/sdk zod
+```
+
+**Requirements:** Node.js >= 18, ESM only
+
+## Quick Start
+
+```typescript
+import { QodoSDK } from '@qodo/sdk';
+
+const sdk = new QodoSDK();
+
+// Simple prompt
+const result = await sdk.prompt('Analyze this codebase and summarize the main components.');
+console.log(result.result.final_output);
+
+await sdk.dispose();
+```
+
+### Streaming
+
+```typescript
+import { QodoSDK, SdkEventType, matchSdkEvent } from '@qodo/sdk';
+
+const sdk = new QodoSDK();
+
+for await (const ev of sdk.streamPrompt('Explain this repository structure.')) {
+  matchSdkEvent(ev, {
+    [SdkEventType.MessageDelta]: (e) => process.stdout.write(e.data.delta),
+    [SdkEventType.Final]: (e) => console.log('\n--- Done ---'),
+    default: () => {},
+  });
+}
+
+await sdk.dispose();
+```
+
+### Structured Output with Zod
+
+```typescript
+import { QodoSDK, sdkAgent, sdkCommand } from '@qodo/sdk';
+import { z } from 'zod';
+
+const agent = sdkAgent({
+  commands: {
+    analyze: sdkCommand({
+      name: 'analyze',
+      description: 'Analyze code quality',
+      instructions: 'Analyze the provided code and return structured feedback.',
+      args: z.object({
+        file: z.string().describe('Path to the file to analyze'),
+      }),
+      output: z.object({
+        issues: z.array(z.object({
+          line: z.number().describe('Line number'),
+          severity: z.enum(['info', 'warning', 'error']).describe('Issue severity'),
+          message: z.string().describe('Issue description'),
+        })).describe('List of issues found'),
+        summary: z.string().describe('Brief summary of code quality'),
+      }),
+    }),
+  },
+});
+
+const sdk = QodoSDK.fromAgent(agent);
+const result = await sdk.run('analyze', { args: { file: 'src/main.ts' } });
+console.log(result.result.structured_output);
+
+await sdk.dispose();
+```
+
+## Authentication
+
+```bash
+# Option 1: Environment variable (recommended)
+export QODO_API_KEY=your_api_key_here
+
+# Option 2: Auth file
+mkdir -p ~/.qodo && echo "your_api_key_here" > ~/.qodo/auth.key
+```
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](docs/getting-started.md) | Installation, setup, core concepts |
+| [API Reference](docs/api-reference.md) | QodoSDK class, methods, options |
+| [Agent Configuration](docs/agent-configuration.md) | Commands, modes, triggers, TOML/YAML |
+| [Event Streaming](docs/event-streaming.md) | All events, handlers, patterns |
+| [Tool Servers](docs/tool-servers.md) | Filesystem, git, shell, ripgrep tools |
+| [Schema Builders](docs/schema-builders.md) | sdkAgent, sdkCommand, Zod integration |
+| [Utilities](docs/utilities.md) | InfoClient, SessionsClient, Tracker |
+
+## Examples
+
+See the [`examples/`](examples/) directory:
+
+- `run-chat.mjs` - Simple blocking execution
+- `stream-chat.mjs` - Streaming with event handling
+- `agent-object.mjs` - Code-defined agent with Zod schemas
+- `approval-policy.mjs` - Custom tool approval policies
+
+```bash
+export QODO_API_KEY=your_key
+node examples/run-chat.mjs
+```
+
+## TypeScript
+
+Full type definitions included. See [API Reference](docs/api-reference.md#typescript-exports) for all exports.
+
+## License
+
+See [LICENSE](LICENSE) file.

package/dist/api/agent.d.ts

@@ -0,0 +1,69 @@
+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 latestSessionId;
+    private lastToolId;
+    private readonly mcpManager?;
+    private readonly taskTracker;
+    private pendingResumeError;
+    private hotStartInProgress;
+    private userHasControl;
+    private ipcBridge;
+    constructor(sessionContext?: SessionContext | undefined);
+    private ensureConnected;
+    private setupWebSocketHandlers;
+    private setupNetworkListeners;
+    private handleNetworkOnline;
+    private handleNetworkOffline;
+    getConnectionState(): ConnectionState;
+    onConnectionStateChange(callback: (state: ConnectionState) => 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>;
+    startHotTask(agentSession: AgentSession): Promise<void>;
+    sendHotStartUserRequest(userRequest: string, images?: string[]): 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

@@ -0,0 +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;IAiC5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAhC5C,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,kBAAkB,CAAS;IACnC,OAAO,CAAC,cAAc,CAAS;IAE/B,OAAO,CAAC,SAAS,CAAoB;gBAER,cAAc,CAAC,EAAE,cAAc,YAAA;YAkC9C,eAAe;IAyB7B,OAAO,CAAC,sBAAsB;IAqE9B,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;YASd,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;IAmBpD,YAAY,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBvD,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCvE,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;YAgFb,sBAAsB;YAStB,cAAc;YAsCd,uBAAuB;YA+CvB,kBAAkB;IA4ChC,OAAO,CAAC,mBAAmB;YAIb,gBAAgB;YAWhB,aAAa;YAuCb,mBAAmB;YAiEnB,iBAAiB;YAajB,QAAQ;YAuGR,gBAAgB;IAmD9B,OAAO,CAAC,kBAAkB;YAwBZ,oBAAoB;YAgBpB,mBAAmB;YAUnB,WAAW;IAwDlB,kBAAkB,IAAI,IAAI;IAK1B,OAAO,IAAI,IAAI;IAYf,cAAc,IAAI,WAAW;CAGrC"}