@qodo/sdk 0.13.3 → 2.0.0-next.0

package/LICENSE

@@ -1,118 +1,31 @@
-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.
+The Qodo SDK License
+
+Copyright (c) 2024-2026 Qodo Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+EXCEPTION: Notwithstanding the permissions above, the Software may not be used,
+in whole or substantial part, to develop, host, or operate any product or
+service whose primary purpose is to provide AI agent runtime, agent
+orchestration, agent lifecycle management, or substantially similar
+capabilities to third parties on a commercial basis. This Exception does not
+restrict: (a) building software agents that consume the Qodo Agent Runtime or
+interoperate with services of Qodo Ltd.; (b) internal use of the Software
+within a single organization; or (c) modification of the Software for any of
+the foregoing permitted purposes.
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,91 +2,134 @@
 
 Official TypeScript SDK for building AI-powered agents with Qodo.
 
+> **Migrating from 1.x?** The full 1.x → 2.0 upgrade guide is at [`docs/sdk2/migration-from-1x.md`](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/migration-from-1x.md), with paired side-by-side examples in [`examples/migration-rosetta/`](https://github.com/qodo-ai/qodo-ts-sdk/tree/main/examples/migration-rosetta).
+>
+> **1.x users (legacy line, published as `0.13.x`):** the SDK is moving to a 2.0 trunk that targets the new Qodo Agent Runtime (QAR). The legacy line continues on the `release/1.x` branch with security and critical-bug patches only, on a calendar tied to command-backend's Sept 2026 EOL.
+
 ## Installation
 
 ```bash
-npm install @qodo/sdk zod
+# 2.0 (alpha — the canonical advertised API)
+npm install @qodo/sdk@next
+
+# 1.x (legacy, command-backend-native — published as 0.13.x)
+npm install @qodo/sdk
 ```
 
-**Requirements:** Node.js >= 18, ESM only
+`@qodo/sdk@latest` resolves to the 1.x line until 2.0 GA flips the dist-tag (Sept 2026). Until then, install 2.0 explicitly with `@next`.
 
-## Quick Start
+**Requirements:** Node.js >= 20, ESM only
 
-```typescript
-import { QodoSDK } from '@qodo/sdk';
+## Quick Start (2.0)
 
-const sdk = new QodoSDK();
+```typescript
+import { QodoClient } from '@qodo/sdk';
 
-// Simple prompt
-const result = await sdk.prompt('Analyze this codebase and summarize the main components.');
-console.log(result.result.final_output);
+const client = new QodoClient({
+  baseUrl: 'https://qar.qodo.ai',
+  auth: 'env',     // reads QODO_API_KEY; ~/.qodo/auth.key fallback
+});
+await client.connect();
+
+for await (const ev of client.tasks.start({
+  agent_id: 'my-agent',
+  input: { user_query: 'Analyze this codebase and summarize the main components.' },
+})) {
+  switch (ev.kind) {
+    case 'task.delta':
+      process.stdout.write(JSON.stringify(ev.payload.delta) + '\n');
+      break;
+    case 'task.done':
+      console.log(`\n[done status=${ev.payload.status}]`);
+      break;
+    case 'error':
+      console.error(`[error ${ev.payload.code}] ${ev.payload.message}`);
+      break;
+  }
+}
 
-await sdk.dispose();
+await client.disconnect();
 ```
 
-### Streaming
+`for await` is the canonical streaming primitive — there's no separate `run()` / `stream()` / `prompt()`. The full vocabulary of envelope kinds plus `qar.client.*` lifecycle events for reconnect/replay is documented in the [Public API reference](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/public-api.md).
+
+### Cross-pod session identity (opt-in)
+
+For consumers that need cross-pod serialization of "the same logical work-unit" — Slack thread, GitHub PR, customer issue — pass `idempotencyKey` to opt into QAR's deterministic session-id derivation. Two pods receiving the same `(tenant_id, idempotencyKey)` derive the same `session_id` and serialize through QAR's lease table; without the field, every call gets a fresh `session_id` (DX default — right for one-shot scripts and single-process consumers).
 
 ```typescript
-import { QodoSDK, SdkEventType, matchSdkEvent } from '@qodo/sdk';
+const stream = client.tasks.startWithAgent(
+  { agent: myAgent, input: { user_query: 'review this PR' } },
+  // Encode your fine scope into the key — two-layer scoping principle:
+  // tenant_id is added server-side; the consumer-supplied key carries
+  // the finer subject (PR number, thread id, issue id).
+  { idempotencyKey: `${owner}/${repo}:pr:${prNumber}` },
+);
+
+// `stream.taskId` is synchronous and equals the FIRST outbound
+// task.start.message_id. Use it for the pre-admission cancel race —
+// `client.tasks.cancel(stream.taskId)` immediately after the start call.
+console.log('taskId:', stream.taskId);
+
+// `stream.admittedTaskId` is a Promise that resolves to the SERVER's
+// canonical task_id once `task.started` arrives. On the omitted-key
+// path it equals `taskId`. On the opt-in deterministic-key path with
+// admission_in_progress retries it MAY DIFFER from `taskId` — the SDK
+// rotates message_ids per retry while the canonical id is whatever
+// the winning attempt's `task.started` reports. Use this id for
+// cancel / continue / resubscribe AFTER admission completes.
+const admittedTaskId = await stream.admittedTaskId;
+
+// `stream.sessionId` resolves on the same admission ack. Await it
+// before any cross-pod operation (e.g. forwarding to another pod via
+// Bulletin for `task.resubscribe`).
+const sessionId = await stream.sessionId;
+
+for await (const ev of stream) { /* … */ }
+```
 
-const sdk = new QodoSDK();
+Both `admittedTaskId` and `sessionId` settle independently of consumer iteration — the SDK's internal admission driver advances the retry loop and resolves/rejects both Promises within `PENDING_ADMISSION_TIMEOUT` (5 min default). `await stream.sessionId` BEFORE the first `for await` cannot hang.
 
-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: () => {},
-  });
-}
+**Validation**: keys must be 1–512 **Unicode code points** with no NUL byte. Invalid keys throw `QodoIdempotencyKeyValidationError` synchronously, before the wire round-trip.
 
-await sdk.dispose();
-```
+**Don't pass `Date.now()` or a fresh `randomUUID()` per call** — the first collides on rapid-fire calls within clock resolution; the second works but defeats the purpose. Omit the field instead and let the server mint.
 
-### Interactive Mode
+**Lost-ack retry semantics**: the omitted-key path is intentionally non-idempotent across `task.start` retries. The SDK does NOT silently retry transport-failed `task.start` envelopes when `idempotencyKey` is absent — a retry without a sticky key starts a SECOND fresh session. Consumers requiring lost-ack idempotency MUST pass a deterministic key (domain-derived or a sticky per-attempt UUIDv7).
 
-Enable `interactiveMode` for chat applications where the agent should ask clarifying questions:
+**`admission_in_progress` retry**: when two pods race the same `(tenant_id, idempotencyKey)`, QAR returns the retryable `admission_in_progress` error. The SDK honors the server's `retry_after_ms` hint when present and falls back to exponential backoff with jitter (initial 100 ms, doubling, capped at 5 min) otherwise. After the cap the SDK throws `QodoAdmissionTimeoutError` carrying the scoped `session_id` so the caller can `task.resubscribe` if recovery is possible. The terminal `admission_stalled` server emission surfaces immediately as `QodoAdmissionStalledError` (same `sessionId` field).
 
-```typescript
-const sdk = new QodoSDK({
-  interactiveMode: true,  // Agent can ask clarifying questions
-});
-```
+Full design rationale and worked examples: [QAR D-16 ADR](https://github.com/qodo-ai/qodo-agent-runtime/blob/ec7705f96ecadf728d27ea022c51923a75ec93f8/knowledge/decisions/D-16-session-identity.md).
 
-By default, the SDK operates non-interactively (ideal for CI/CD and automation).
+### Tools
 
-### Structured Output with Zod
+Register a handler for inbound `tool.request` envelopes. The wire is parallel-batched: `req.payload.calls: ToolCall[]` (always a list, even for a single call) plus a required `req.payload.node_name`. Return one `ToolResponseResult` per call (positional array) or — when you know every request is single-call — a single result that the SDK auto-batches.
 
 ```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'),
-      }),
-    }),
-  },
-});
+import { ToolDeniedError } from '@qodo/sdk';
+
+const sub = client.tools.onRequest((req) =>
+  req.payload.calls.map((call) => {
+    if (call.name === 'echo') {
+      return { outcome: 'success', result: { echoed: call.arguments } };
+    }
+    if (call.name.startsWith('forbidden_')) {
+      // Return-style denial keeps per-call attribution; a `throw new
+      // ToolDeniedError(...)` would deny the whole batch.
+      return { outcome: 'denied', error: 'blocked by policy' };
+    }
+    return { outcome: 'error', error: `unknown tool: ${call.name}` };
+  }),
+);
+// later: sub.unsubscribe();
+```
 
-const sdk = QodoSDK.fromAgent(agent);
-const result = await sdk.run('analyze', { args: { file: 'src/main.ts' } });
-console.log(result.result.structured_output);
+Stacking handlers compose approval middleware (policy first, dispatcher second). Deep dive in the [Tools guide](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/tools.md).
 
-await sdk.dispose();
-```
+### Migrating from 1.x
+
+TL;DR: `QodoSDK` → `QodoClient`, `sdk.run/stream/prompt` → `for await client.tasks.start({...})`, `sdkAgent`/`sdkCommand` removed (agents are server-side now), `IDERetrievalRequest` → `ToolRequestEnvelope`, `Resume`/`ResumeAck` machinery removed (server-driven replay), `onTransportEvent` removed (lifecycle events on the same iterator). Auth is unchanged.
+
+Full guide with per-export migration table: [`docs/sdk2/migration-from-1x.md`](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/migration-from-1x.md). Paired side-by-side examples: [`examples/migration-rosetta/`](https://github.com/qodo-ai/qodo-ts-sdk/tree/main/examples/migration-rosetta).
 
 ## Authentication
 
@@ -98,87 +141,56 @@ export QODO_API_KEY=your_api_key_here
 mkdir -p ~/.qodo && echo "your_api_key_here" > ~/.qodo/auth.key
 ```
 
-## Optional Dependencies
-
-The SDK includes built-in tool servers that work out of the box. Some tools have optional system dependencies for enhanced functionality:
-
-| Tool | Dependency | Purpose | Install |
-|------|------------|---------|---------|
-| `ripgrep_search` | [ripgrep](https://github.com/BurntSushi/ripgrep) | Fast code/text search | See below |
-| `git_*` | git | Git operations | Usually pre-installed |
-| `shell_execute` | shell | Command execution | Built-in |
-
-### Ripgrep
-
-For the `ripgrep_search` tool, you have two options:
-
-**Option 1: Install `@vscode/ripgrep` (Recommended)**
-
-```bash
-npm install @vscode/ripgrep
-```
-
-This bundles ripgrep binaries for all platforms - no system installation needed. The SDK auto-detects it.
-
-**Option 2: System ripgrep**
-
-```bash
-# macOS
-brew install ripgrep
-
-# Ubuntu/Debian
-apt install ripgrep
+In code, `auth: 'env'` reads `QODO_API_KEY` first and falls back to `~/.qodo/auth.key`. Pass `auth: { apiKey: '...' }` to supply the token directly, or `auth: { provider: () => Promise<string> }` to plug in a custom token source.
 
-# Windows
-choco install ripgrep
-```
+## TypeScript / Node
 
-If ripgrep is not available, the `ripgrep_search` tool will be unavailable and the SDK will log a warning. All other functionality works normally.
+Full type definitions ship in the package. The SDK targets ES2022 + NodeNext modules, requires Node.js >= 20, and is ESM only — `require()` is not supported. See the [Public API reference](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/public-api.md) for the canonical exported surface.
 
-## Claude Code Skill
+## Documentation
 
-The SDK ships with a Claude Code skill that provides context-aware assistance when building Qodo agents. Install it with:
+> Full documentation lives in the repository. Repository access is currently restricted to Qodo organization members — if you need a deep reference link to resolve, contact [support@qodo.ai](mailto:support@qodo.ai).
 
-```bash
-# Install to your project
-npx @qodo/sdk install-skill
+### 2.0 (canonical)
 
-# Or install globally (available in all projects)
-npx @qodo/sdk install-skill --global
-```
+**Learn the SDK** (in order):
 
-Once installed, use `/qodo-agent` in Claude Code to get help with agent configuration, SDK APIs, and common patterns.
+| Track | Description |
+|-------|-------------|
+| [Tutorial](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/tutorial/00-overview.md) | 8 chapters: `npm install` → first task → tools → MCP → HITL → multi-agent → OTel → production checklist |
+| [Concept guides](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/concepts/00-index.md) | Mental model behind each primitive: agent spec, tools, HITL, skills, sessions, observability, error handling |
+| [Use cases](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/usecases.md) | Three flagship reference implementations: doc-qa, slack-bot, agentic-docs-updater |
+| [Cookbook](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/cookbook/00-index.md) | Lookup-shaped recipes: cancel, resume, reconnect, MCP subset, HITL, multi-agent, OTel, errors, testing, auth |
 
-## Documentation
+**Reference** (every field, every error):
 
 | 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 |
+| [Migration from 1.x](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/migration-from-1x.md) | Canonical 1.x → 2.0 upgrade guide; per-export table, recipes, FAQ |
+| [Public API](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/public-api.md) | `QodoClient`, connect, `tasks.start/continue/cancel`, errors, backpressure |
+| [Tools](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/tools.md) | `client.tools.onRequest` / `respond`, stacking, error mapping |
+| [MCP tools](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/mcp-tools.md) | `mcpTools` projection, auto-discovery, fallback bridge |
+| [Reconnect + replay](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/reconnect-replay.md) | Auto-reconnect, `tasks.resubscribe`, `replay_anchor_missing` |
+| [Observability](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/observability.md) | OTel attribute taxonomy, span boundaries, skip-list, cardinality |
+| [Event surfaces](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/sdk2/event-surfaces.md) | `bulletin` / `artifacts` / `state` / `agents` observers |
+| [Release policy](https://github.com/qodo-ai/qodo-ts-sdk/blob/main/docs/release-policy.md) | Versioning, branch rules, backport policy, EOL calendar |
 
 ## Examples
 
-See the [`examples/`](examples/) directory:
+End-to-end runnable scripts live in [`examples/`](https://github.com/qodo-ai/qodo-ts-sdk/tree/main/examples). Most are env-gated on `QAR_BASE_URL` and exit cleanly when unset — safe to clone and run.
 
-- `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
+- [`examples/sdk2/`](https://github.com/qodo-ai/qodo-ts-sdk/tree/main/examples/sdk2) — `hello-task`, `tool-roundtrip`, `multi-agent-observer`, MCP auto-discovery, end-to-end live-cluster smoke.
+- [`examples/tutorial/`](https://github.com/qodo-ai/qodo-ts-sdk/tree/main/examples/tutorial) — companion code for the tutorial chapters (HITL, MCP, OTel, multi-agent).
+- [`examples/usecases/`](https://github.com/qodo-ai/qodo-ts-sdk/tree/main/examples/usecases) — three flagship reference implementations: doc-qa, slack-bot, agentic-docs-updater.
+- [`examples/migration-rosetta/`](https://github.com/qodo-ai/qodo-ts-sdk/tree/main/examples/migration-rosetta) — paired 1.x/2.0 files for every common upgrade pattern.
 
 ```bash
+export QAR_BASE_URL=https://qar.dev.qodo.ai
 export QODO_API_KEY=your_key
-node examples/run-chat.mjs
+export QAR_AGENT_ID=health
+npx tsx examples/sdk2/hello-task.ts
 ```
 
-## TypeScript
-
-Full type definitions included. See [API Reference](docs/api-reference.md#typescript-exports) for all exports.
-
 ## License
 
-See [LICENSE](LICENSE) file.
+See [LICENSE](LICENSE). The SDK ships under an MIT-style license with a protective exception that bars re-use to build competing AI agent runtimes; consumer agents that interoperate with the Qodo Agent Runtime are unaffected.

package/bin/qodo-skills.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * `qodo-skills` CLI binary entrypoint (T-0011).
+ *
+ * Defers to `dist/skills/cli/index.js#runSkillsCli`; the bin shim is
+ * intentionally tiny so the published artifact stays minimal and the
+ * implementation can grow inside `src/skills/cli/`.
+ */
+
+import { runSkillsCli, defaultCliIo } from '../dist/skills/cli/index.js';
+
+const code = await runSkillsCli(process.argv.slice(2), defaultCliIo());
+process.exit(code);

package/bundled-skills/code-review/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: code-review
+description: Review a pull request diff for security issues, performance regressions, correctness bugs, and adherence to the project's conventions. Trigger keywords — review, PR review, code review, audit code, look at this change, what's wrong with this diff, check my pull request.
+when_to_use: When the user asks for feedback on a diff, a pull request URL, a changeset, a commit, or a series of files they have just edited. Especially useful before merging or when the user explicitly invites criticism.
+vendor: qodo
+version: 1.0.0
+---
+
+# Code review
+
+You are reviewing a code change. Be specific, actionable, and concise.
+
+## What to check
+
+Walk the diff once per dimension and only report findings you'd defend in a PR review:
+
+- **Correctness**: logic errors, off-by-one, null handling, race conditions, exception swallowing, control-flow gaps. Match the change against the intent the author stated (commit message, PR description).
+- **Security**: injection (SQL, command, prompt), insecure deserialisation, secrets in code, weak crypto, broken auth, IDOR, SSRF. Where the diff touches I/O boundaries, check input validation. Where it touches identity, check authorisation.
+- **Performance**: N+1 queries, accidental quadratic loops, unbounded buffers, missing cancellation in long-running async work. Don't speculate; cite the loop or the call site.
+- **Style and conventions**: only call out drift from patterns visible elsewhere in the codebase. Project-specific conventions trump general best practice — read the surrounding code before judging.
+
+## Output format
+
+Group findings by severity: **Blocker**, **High**, **Medium**, **Low**, **Nit**. For each, write one line:
+
+```
+[Severity] path/to/file.ext:Lstart-Lend — finding. Suggested fix or "consider <X>".
+```
+
+Skip the dimension entirely if you have nothing for it. A short review is a confidence signal; padding with low-value nits is noise. If the change is clean, say so explicitly.
+
+## What NOT to do
+
+- Don't restate what the diff does. The reviewer can read it.
+- Don't suggest renames or formatting unless they'd land in the next style commit anyway.
+- Don't propose refactors outside the diff's scope unless they're load-bearing for the change.
+- Don't quote large blocks of code back; cite line ranges.
+
+## Calibration
+
+If the change is genuinely good, say `LGTM — <one-line why>` and stop. Reviewers who never approve cleanly become noise the author learns to ignore.

package/bundled-skills/pr-summary/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: pr-summary
+description: Generate a pull-request summary from a diff or list of files. Produces a short title, a 2-3 bullet "what changed", and a test-plan checklist. Trigger keywords — summarize PR, write a PR description, draft pull request, describe this diff, what does this change do, generate pr summary.
+when_to_use: When the user is preparing to open or update a pull request and asks for a summary, description, or release-note-style writeup of a diff. Especially useful when the diff spans multiple files and the author wants the framing extracted before they edit it.
+vendor: qodo
+version: 1.0.0
+---
+
+# PR summary
+
+Generate a pull-request description that a reviewer can act on in under a minute.
+
+## Output template
+
+```markdown
+## Title
+
+<one short imperative line, ≤70 chars, no trailing punctuation>
+
+## Summary
+
+- <what changed, one bullet>
+- <why it changed, one bullet>
+- <any caller-facing impact, one bullet — skip if none>
+
+## Test plan
+
+- [ ] <how the change was verified locally>
+- [ ] <regression scope the reviewer should re-check>
+- [ ] <any manual steps for staging / production>
+```
+
+## Style rules
+
+- **Title is imperative present**: "Add X", "Fix Y", "Remove Z". Not "Added", "Fixes".
+- **Summary explains the why, not the what**. The diff already shows the what. The reviewer needs the motivation: bug context, design decision, ticket goal.
+- **Test plan is the reviewer's checklist**, not a confession of what you did. Frame each item as something someone else could run.
+- **No marketing language**. No "improved", "enhanced", "simplified" without specifics. Either cite a metric or describe the concrete change.
+- **No co-author trailers** unless explicitly requested. The user controls attribution.
+
+## When the diff is large
+
+If you're summarising more than ~500 lines or 10+ files, group the summary by sub-system rather than flat-listing every change. Each subsection gets one bullet:
+
+```markdown
+### `src/auth/`
+- <one bullet>
+
+### `tests/`
+- <one bullet>
+```
+
+## When the diff is trivial
+
+A one-line summary is appropriate. Don't pad to fit the template — concise descriptions beat templated boilerplate. Output the title plus one bullet.
+
+## See also
+
+When the author also wants line-by-line review notes, suggest `qodo/code-review` instead. PR summary is the framing; code review is the gate.

package/bundled-skills/test-gen/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: test-gen
+description: Generate unit or integration tests for a target file or function. Picks the project's existing test framework, mirrors the surrounding test style, and covers the happy path plus the edge cases the implementation guards against. Trigger keywords — write tests, generate tests, add coverage, test this function, missing tests, what cases am I missing.
+when_to_use: When the user has just written, modified, or pointed at code that lacks coverage and asks for tests. Especially useful when the test framework + style are already established in the project — this skill mirrors the existing tests rather than imposing a generic template.
+arguments:
+  - name: target
+    description: Path to the file (or function within a file) that needs tests. Optional — defaults to the file the user is currently discussing.
+vendor: qodo
+version: 1.0.0
+---
+
+# Test generation
+
+Generate tests that match how the project already writes them.
+
+## Before writing anything
+
+Read these in order so the generated tests fit:
+
+1. **The target file.** Identify the public surface, the failure modes the implementation explicitly guards against, and any nontrivial invariants.
+2. **The nearest existing test file** in the project (same directory, sibling `tests/` directory, or `__tests__/`). Mirror its imports, naming convention, fixture pattern, assertion style. If the project uses `describe/it`, don't switch to `test()`. If the project uses `assert`, don't switch to `expect`.
+3. **The project's test runner config** (`vitest.config`, `jest.config`, `package.json` scripts). Confirm the runner before assuming.
+
+If no existing tests are present, fall back to the framework the package.json declares, in this priority: `vitest` → `jest` → `mocha` → `node:test`. Output the chosen runner in a one-line preamble so the user can redirect.
+
+## What to cover
+
+For each public function or class method exposed by the target:
+
+- **Happy path**: the documented contract, single test.
+- **Boundary cases**: empty input, single-element input, the largest input the implementation explicitly handles. Skip unbounded "what if N=10^9" speculation.
+- **Documented error paths**: each `throw`, each `return null/undefined`, each `if (!X)` early return. One test per branch.
+- **Side effects**: if the function writes to disk, the network, or shared state, assert the effect — not just the return value.
+
+## What NOT to do
+
+- Don't write tests for trivial getters/setters, pure pass-throughs, or generated code.
+- Don't mock the system under test. Mock its collaborators.
+- Don't assert on log output unless the log is part of the documented contract.
+- Don't add `test.todo` placeholders; either write the test or omit it.
+- Don't pad the suite. A focused 6-test file beats a 30-test file padded with permutations.
+
+## Output
+
+Write the test file. If the project uses a `tests/` mirror tree, place it there. If it uses sibling `*.test.ts` files, place it next to the target. Match the existing convention — don't introduce a new layout.
+
+After writing, run the test command (if known) and report the result. If any test fails, fix the test (not the implementation) unless you've found a genuine bug — in which case, flag it explicitly.