ql-agent-sdk 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,849 @@
-# Temporary Holding Version
+# ql-agent-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript SDK for the **Quanton Labs** agent platform API (v1). Integrate your application with 8 specialized AI agents, capabilities, workflows, and background tasks.
+
+- **Zero runtime dependencies** — built on native `fetch` and Web Streams
+- **Full TypeScript** — all request/response types exported
+- **ESM + CJS** — works in Node, Bun, Deno, Next.js, and edge runtimes
+
+> Base URL defaults to `https://app.quantonlabs.com`. Override with `baseUrl` option or the `QL_BASE_URL` environment variable.
+
+---
+
+## Install
+
+```bash
+npm install ql-agent-sdk
+# or
+pnpm add ql-agent-sdk
+# or
+yarn add ql-agent-sdk
+```
+
+Requires **Node.js 18+** (native `fetch`).
+
+---
+
+## Quick Start
+
+```ts
+import { QLClient } from "ql-agent-sdk";
+
+const ql = new QLClient({ apiKey: process.env.QL_API_KEY! });
+
+// Discover available agents
+const { agents } = await ql.agents.list();
+console.log(agents.map((a) => a.id));
+// → ["governing", "finance", "marketing", "inventory", "customer", "developer", "operations", "research"]
+
+// Chat with an agent (non-streaming)
+const reply = await ql.agents.chat({
+  agentId: "governing",
+  messages: [{ role: "user", content: "Summarize this quarter's revenue." }],
+});
+console.log(reply.content);
+```
+
+---
+
+## Configuration
+
+```ts
+const ql = new QLClient({
+  apiKey,               // required — your Bearer API key (ql_live_...)
+  baseUrl,              // optional — defaults to QL_BASE_URL or https://app.quantonlabs.com
+  fetch: customFetch,   // optional — override for tests/proxies/custom runtimes
+});
+```
+
+The `apiKey` is held in a private field. It is **never** returned by the client, included in error messages, or logged.
+
+---
+
+## Authentication
+
+All API calls use **Bearer token authentication** with your API key:
+
+```
+Authorization: Bearer ql_live_your_key_here
+```
+
+Create keys in your Quanton Labs dashboard → **API Keys** page. Each key is scoped to a single workspace.
+
+### Scope Requirements
+
+| Scope | Grants access to |
+|-------|-----------------|
+| `workspace` | `ql.workspace.get()` |
+| `agents` | `ql.agents.list()`, `ql.agents.get()` |
+| `capabilities` | `ql.agents.capabilities()`, `ql.agents.runCapability()` |
+| `chat` | `ql.agents.chat()`, `ql.agents.chatStream()` |
+| `messages` | `ql.agents.history()` |
+| `workflows` | `ql.workflows.run()`, `ql.workflows.getRun()` |
+| `tasks` | `ql.tasks.create()`, `ql.tasks.get()` |
+| `*` | All of the above (default for new keys) |
+
+---
+
+## API Reference
+
+### Response Envelope
+
+All non-streaming endpoints return a consistent envelope:
+
+**Success:**
+```json
+{ "ok": true, "data": { ... } }
+```
+
+**Error:**
+```json
+{ "ok": false, "error": { "code": "not_found", "message": "Agent not found: foo" } }
+```
+
+The SDK unwraps `data` for you and throws a typed `QLError` on errors. You never see the envelope directly.
+
+---
+
+### Workspace
+
+#### `ql.workspace.get()` → `Promise<Workspace>`
+
+**Scope:** `workspace`
+
+Returns the workspace bound to your API key.
+
+**Response (200):**
+```json
+{
+  "_id": "6adf926f6f87c9ab86f32c0e",
+  "name": "Robin",
+  "plan": "standard",
+  "createdAt": "2026-10-26T17:48:31.038Z",
+  "updatedAt": "2026-10-27T11:56:44.074Z"
+}
+```
+
+**TypeScript:**
+```ts
+const ws = await ql.workspace.get();
+ws._id;      // string
+ws.name;     // string
+ws.plan;     // "standard" | "premium" | "enterprise" | undefined
+ws.createdAt; // string (ISO 8601)
+```
+
+---
+
+### Agents
+
+#### `ql.agents.list()` → `Promise<AgentListResult>`
+
+**Scope:** `agents`
+
+Lists all 8 available agents with their capability counts.
+
+**Response (200):**
+```json
+{
+  "agents": [
+    {
+      "id": "governing",
+      "name": "Governing Agent",
+      "domain": "orchestration",
+      "description": "Coordinates all other agents...",
+      "icon": "brain",
+      "tags": ["coordination", "reasoning"],
+      "capabilityCount": 20
+    }
+  ]
+}
+```
+
+#### `ql.agents.get(agentId)` → `Promise<AgentDetail>`
+
+**Scope:** `agents`
+
+Returns an agent's details and full capability list.
+
+**Parameters:**
+- `agentId: string` — agent slug (e.g. `"finance"`, `"governing"`) or ObjectId
+
+**Response (200):**
+```json
+{
+  "agent": {
+    "id": "finance",
+    "name": "Finance Agent",
+    "domain": "finance",
+    "description": "Handles financial analysis...",
+    "icon": "dollar-sign",
+    "tags": ["accounting", "budgeting"]
+  },
+  "capabilities": [
+    {
+      "id": "invoice",
+      "name": "Invoice Generator",
+      "description": "Generate formatted invoices from data",
+      "category": "documents",
+      "params": [
+        { "key": "data", "label": "Data", "kind": "textarea", "required": true }
+      ],
+      "templates": [
+        { "label": "Monthly Report", "values": { "data": "Revenue | 12000\nCosts | 4000" } }
+      ]
+    }
+  ]
+}
+```
+
+**Errors:**
+- `404 not_found` — agent slug doesn't exist
+
+#### `ql.agents.capabilities(agentId)` → `Promise<CapabilitiesResult>`
+
+**Scope:** `capabilities`
+
+Returns just the capability list for an agent (lighter than `get`).
+
+**Response (200):**
+```json
+{
+  "agentId": "finance",
+  "capabilities": [ ... ]
+}
+```
+
+#### `ql.agents.runCapability(agentId, input)` → `Promise<RunCapabilityResult>`
+
+**Scope:** `capabilities`
+
+Executes a specific capability (feature) on an agent.
+
+**Parameters:**
+- `agentId: string` — agent slug
+- `input.capId: string` — capability ID (from the capabilities list)
+- `input.params?: Record<string, unknown>` — capability-specific parameters
+
+**Response (200):**
+```json
+{
+  "result": {
+    "type": "html",
+    "html": "<div class=\"invoice\">...</div>"
+  }
+}
+```
+
+The `result` is a **discriminated union** — check `result.type`:
+
+| `type` | Fields | When |
+|--------|--------|------|
+| `"text"` | `content: string` | Plain text output |
+| `"json"` | `data: unknown` | Structured JSON |
+| `"html"` | `html: string` | HTML content (renderable) |
+| `"file"` | `url, filename, mime` | Generated file (image, PDF, etc.) |
+
+**Example:**
+```ts
+const { result } = await ql.agents.runCapability("finance", {
+  capId: "invoice",
+  params: { data: "Revenue | 12000\nCosts | 4000" },
+});
+
+if (result.type === "html") {
+  document.body.innerHTML = result.html;
+} else if (result.type === "json") {
+  console.log(result.data);
+} else if (result.type === "text") {
+  console.log(result.content);
+} else if (result.type === "file") {
+  window.open(result.url); // download
+}
+```
+
+---
+
+### Chat
+
+#### `ql.agents.chat(input)` → `Promise<ChatResult>`
+
+**Scope:** `chat`
+
+Non-streaming chat with an agent. Waits for the full response.
+
+**Parameters:**
+- `agentId: string` — agent slug
+- `messages: ChatMessage[]` — conversation history (newest last)
+- `userId?: string` — optional internal user ID (defaults to workspace)
+- `response_format?: object` — optional OpenRouter format hint
+
+**Response (200):**
+```json
+{
+  "content": "Based on your data, Q3 revenue was $120K...",
+  "toolCalls": 2,
+  "iterations": 3,
+  "duration": "4.21s"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `content` | `string` | The agent's full text response |
+| `toolCalls` | `number` | How many tool calls were made during reasoning |
+| `iterations` | `number` | Tool loop iterations |
+| `duration` | `string` | Human-readable execution time |
+
+**Example:**
+```ts
+const reply = await ql.agents.chat({
+  agentId: "finance",
+  messages: [
+    { role: "user", content: "What was our profit margin last month?" },
+  ],
+});
+console.log(reply.content);
+```
+
+---
+
+#### `ql.agents.chatStream(input, opts?)` → `AsyncIterable<ChatStreamEvent>`
+
+**Scope:** `chat`
+
+Streaming chat — yields incremental events as the agent responds.
+
+**Parameters:**
+- Same as `chat()` above
+- `opts.signal?: AbortSignal` — abort the stream at any time
+
+**Yielded events:**
+```ts
+type ChatStreamEvent =
+  | { type: "delta"; content?: string; reasoning?: string }  // incremental piece
+  | { type: "done"; content: string; reasoning?: string };   // final accumulated text
+```
+
+| Event | When | Fields |
+|-------|------|--------|
+| `delta` | For each token/chunk from the model | `content` (text delta), `reasoning` (thinking delta, if model supports it) |
+| `done` | Once at the end | `content` (full accumulated text), `reasoning` (full reasoning, if any) |
+
+**Example:**
+```ts
+import { QLClient } from "ql-agent-sdk";
+
+const ql = new QLClient({ apiKey: process.env.QL_API_KEY! });
+const controller = new AbortController();
+
+// Optional: auto-abort after 30s
+const timer = setTimeout(() => controller.abort(), 30_000);
+
+let full = "";
+try {
+  for await (const ev of ql.agents.chatStream(
+    { agentId: "governing", messages: [{ role: "user", content: "Explain quantum computing" }] },
+    { signal: controller.signal },
+  )) {
+    if (ev.type === "delta") {
+      process.stdout.write(ev.content ?? ""); // print incrementally
+      full += ev.content ?? "";
+    } else if (ev.type === "done") {
+      full = ev.content; // final text (replaces accumulated)
+    }
+  }
+} catch (err) {
+  if ((err as any)?.code === "aborted") console.log("\n[stopped by user]");
+} finally {
+  clearTimeout(timer);
+}
+```
+
+**SSE wire format** (if you ever need to parse it manually):
+```
+data: {"id":"gen-...","choices":[{"delta":{"content":"Hel"}}]}
+
+data: {"id":"gen-...","choices":[{"delta":{"content":"lo"}}]}
+
+data: [DONE]
+
+```
+Events are separated by blank lines. `data: [DONE]` signals the end.
+
+---
+
+### History / Messages
+
+#### `ql.agents.history(agentId, opts?)` → `Promise<HistoryPage>`
+
+**Scope:** `messages`
+
+Returns paginated conversation history for an agent (newest first).
+
+**Parameters:**
+- `agentId: string` — agent slug
+- `opts.limit?: number` — page size, 1–100 (default 20)
+- `opts.before?: string` — cursor from previous page's `nextBefore`
+- `opts.userId?: string` — optional filter by user
+
+**Response (200):**
+```json
+{
+  "agentId": "finance",
+  "limit": 20,
+  "nextBefore": "6ae0d96274f1cf895ef06e0c",
+  "items": [
+    {
+      "id": "6ae0d963...",
+      "role": "user",
+      "content": "What was our profit margin?",
+      "toolCalls": [],
+      "status": "completed",
+      "timestamp": "2026-10-27T14:32:00.000Z"
+    },
+    {
+      "id": "6ae0d962...",
+      "role": "assistant",
+      "content": "Based on your records...",
+      "reasoning": "Let me check the financial data...",
+      "toolCalls": [{ "name": "db_query", ... }],
+      "status": "completed",
+      "timestamp": "2026-10-27T14:32:05.000Z"
+    }
+  ]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `nextBefore` | Cursor for next page. `null` when no more pages. |
+| `items[].role` | `"user"` or `"assistant"` |
+| `items[].content` | Message text (may be null for tool-only messages) |
+| `items[].reasoning` | Model's thinking (if supported by the model) |
+| `items[].toolCalls` | Array of tool invocations made during this message |
+| `items[].status` | `"completed"`, `"processing"`, or `"failed"` |
+
+**Walking all pages:**
+```ts
+const allMessages = [];
+let before: string | undefined;
+
+do {
+  const page = await ql.agents.history("finance", { limit: 50, before });
+  allMessages.push(...page.items);
+  before = page.nextBefore ?? undefined; // null when exhausted
+} while (before);
+
+console.log(`${allMessages.length} total messages`);
+```
+
+---
+
+### Workflows
+
+#### `ql.workflows.run(workflowId, input?)` → `Promise<WorkflowRunStart>`
+
+**Scope:** `workflows`
+
+Triggers a workflow execution. Returns immediately with a run ID (HTTP 202).
+
+**Parameters:**
+- `workflowId: string` — the workflow's ObjectId
+- `input?: { input?: Record<string, unknown> }` — optional input payload for the workflow
+
+**Response (202):**
+```json
+{
+  "runId": "6ae101c8...",
+  "status": "running"
+}
+```
+
+**Errors:**
+- `400 validation_error` — invalid workflow ID format
+- `404 not_found` — workflow doesn't exist in this workspace
+
+#### `ql.workflows.getRun(runId)` → `Promise<WorkflowRun>`
+
+**Scope:** `workflows`
+
+Polls a workflow run's status.
+
+**Response (200):**
+```json
+{
+  "runId": "6ae101c8...",
+  "status": "completed",
+  "output": { "result": "..." },
+  "error": null,
+  "durationMs": 4523,
+  "startedAt": "2026-10-27T14:32:00.000Z",
+  "finishedAt": "2026-10-27T14:32:04.523Z"
+}
+```
+
+| `status` value | Meaning |
+|----------------|---------|
+| `"queued"` | Waiting to start |
+| `"running"` | Currently executing |
+| `"completed"` | Finished successfully — check `output` |
+| `"failed"` | Execution error — check `error` |
+| `"cancelled"` | Was cancelled |
+
+**Polling example:**
+```ts
+const start = await ql.workflows.run("6adf929d6f87c9ab86f32c19", { input: { a: 1 } });
+
+// Poll until done
+let run;
+do {
+  await new Promise((r) => setTimeout(r, 2000));
+  run = await ql.workflows.getRun(start.runId);
+} while (run.status === "running" || run.status === "queued");
+
+if (run.status === "completed") console.log(run.output);
+else if (run.status === "failed") console.error(run.error);
+```
+
+---
+
+### Tasks (Background)
+
+#### `ql.tasks.create(input)` → `Promise<TaskCreated>`
+
+**Scope:** `tasks`
+
+Creates a background task. The task **starts executing immediately** on the server — you don't need to call another endpoint.
+
+**Parameters:**
+- `agentId: string` — which agent handles this task
+- `title: string` — human-readable name
+- `description?: string` — optional longer description
+- `input?: unknown` — payload for the agent (string, or `{ message }`, or `{ prompt }`)
+- `priority?: "low" | "medium" | "high" | "urgent"` — scheduling priority
+
+**Response (201):**
+```json
+{
+  "taskId": "6ae101b7...",
+  "status": "queued"
+}
+```
+
+**Errors:**
+- `400 validation_error` — missing `agentId` or `title`
+- `404 not_found` — unknown agent slug
+
+#### `ql.tasks.get(taskId)` → `Promise<Task>`
+
+**Scope:** `tasks`
+
+Single poll of a task's current state.
+
+**Response (200):**
+```json
+{
+  "taskId": "6ae101b7...",
+  "status": "completed",
+  "title": "Monthly Report",
+  "progress": {
+    "current": 100,
+    "total": 100,
+    "message": "Completed",
+    "updatedAt": "2026-10-27T19:53:23.117Z"
+  },
+  "result": "Here is your monthly report...",
+  "output": "Here is your monthly report...",
+  "error": null,
+  "createdAt": "2026-10-27T19:53:16.756Z",
+  "completedAt": "2026-10-27T19:53:23.117Z"
+}
+```
+
+| `status` value | Meaning | Check field |
+|----------------|---------|-------------|
+| `"queued"` | Waiting to start | — |
+| `"running"` | In progress | `progress.message` for current step |
+| `"retrying"` | Failed, will retry automatically | `error` for what went wrong |
+| `"completed"` | Done successfully | `result` / `output` for the answer |
+| `"failed"` | Permanently failed (max retries) | `error` for the reason |
+| `"cancelled"` | Was cancelled | — |
+
+#### `ql.tasks.handle(taskId)` → `TaskHandle`
+
+Returns a handle with `poll()` and `wait()` methods.
+
+**`handle.poll(signal?)`** — single fetch, returns current `Task` snapshot.
+
+**`handle.wait(opts?)`** — polls until terminal status with backoff.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `intervalMs` | 2000 | Initial delay between polls (ms) |
+| `maxIntervalMs` | 15000 | Backoff cap (grows 1.5× per poll) |
+| `timeoutMs` | undefined (wait forever) | Throw after this many ms total |
+| `signal` | undefined | AbortSignal for cancellation |
+| `onTick` | undefined | Callback after each poll with latest snapshot |
+
+**Terminal states returned by `wait()`:**
+- `task.status === "completed"` → check `task.result`
+- `task.status === "failed"` → check `task.error`
+- `task.status === "cancelled"` → task was cancelled server-side
+
+**Non-terminal exits (throws QLError):**
+- `err.code === "timeout"` → exceeded `timeoutMs`
+- `err.code === "aborted"` → `signal` was aborted
+
+**Example:**
+```ts
+const created = await ql.tasks.create({
+  agentId: "finance",
+  title: "Quarterly Report",
+  input: { message: "Generate a Q3 financial summary from our database." },
+  priority: "high",
+});
+
+const handle = ql.tasks.handle(created.taskId);
+
+try {
+  const done = await handle.wait({
+    intervalMs: 2000,
+    maxIntervalMs: 10000,
+    timeoutMs: 5 * 60_000, // 5 minute timeout
+    onTick: (task) => {
+      if (task.status === "running" && task.progress?.message) {
+        process.stdout.write(`\r${task.progress.message}`);
+      }
+    },
+  });
+
+  if (done.status === "completed") {
+    console.log("\n✓ Done:", done.result);
+  } else if (done.status === "failed") {
+    console.error("✗ Failed:", done.error);
+  }
+} catch (err) {
+  if ((err as any).code === "timeout") console.error("Timed out after 5 min");
+  if ((err as any).code === "aborted") console.log("Cancelled by user");
+}
+```
+
+> **Note on execution:** Tasks execute in the server's process. If the server restarts mid-execution, the task will be recovered and retried on next startup (up to `maxRetries` times). For mission-critical workloads with strict durability requirements, consider a persistent queue backend.
+
+---
+
+## Error Handling
+
+All API failures throw a typed **`QLError`**:
+
+```ts
+import { QLClient, QLError } from "ql-agent-sdk";
+
+try {
+  await ql.agents.chat({ agentId: "finance", messages: [...] });
+} catch (err) {
+  if (err instanceof QLError) {
+    console.error(err.status);   // HTTP status code (401, 403, 404, etc.)
+    console.error(err.code);     // stable string code (see table below)
+    console.error(err.message);  // human-readable (never includes API key)
+
+    // Convenience booleans:
+    err.isAuthError;      // true for 401/403
+    err.isAborted;        // true for abort
+    err.isTimeout;        // true for wait() timeout
+    err.isNetworkError;   // true for connection failures
+  }
+}
+```
+
+### Error Code Reference
+
+| HTTP Status | `code` | When it happens |
+|-------------|--------|-----------------|
+| 401 | `unauthorized` | Missing, invalid, or revoked API key |
+| 403 | `forbidden` | Key lacks the required scope for this endpoint |
+| 404 | `not_found` | Resource doesn't exist in your workspace (agent, workflow, task) |
+| 409 | `conflict` | Conflict (e.g. duplicate resource) |
+| 400 | `validation_error` | Malformed request body, missing required fields, invalid params |
+| 500 | `internal_error` | Server-side error (AI provider failure, DB issue, etc.) |
+| — | `network` | No HTTP response received (connection refused, DNS failure, timeout) |
+| — | `aborted` | Caller aborted via `AbortSignal` |
+| — | `timeout` | `wait()` exceeded its `timeoutMs` budget |
+
+### Common Error Scenarios
+
+```ts
+// 1. Expired/revoked key
+try {
+  await ql.workspace.get();
+} catch (e) {
+  if (e instanceof QLError && e.code === "unauthorized") {
+    console.log("API key is invalid or revoked. Generate a new one in your dashboard.");
+  }
+}
+
+// 2. Key doesn't have chat scope
+try {
+  await ql.agents.chat({ agentId: "finance", messages: [...] });
+} catch (e) {
+  if (e instanceof QLError && e.code === "forbidden") {
+    console.log("This key needs the 'chat' scope. Create a new key with broader scopes.");
+  }
+}
+
+// 3. AI provider error (transient)
+try {
+  await ql.agents.chat({ agentId: "governing", messages: [...] });
+} catch (e) {
+  if (e instanceof QLError && e.status === 500) {
+    console.log("AI service temporarily unavailable. Retry later.");
+  }
+}
+```
+
+---
+
+## TypeScript
+
+Full type declarations are included. All public types are exported:
+
+```ts
+import type {
+  QLClient,
+  QLClientOptions,
+  QLError,
+  // Request types
+  ChatInput,
+  RunCapabilityInput,
+  TaskCreateInput,
+  WaitOptions,
+  HistoryParams,
+  WorkflowRunInput,
+  // Response types
+  Workspace,
+  AgentSummary,
+  AgentDetail,
+  CapabilityInfo,
+  CapabilityResult,
+  ChatResult,
+  ChatStreamEvent,
+  HistoryPage,
+  MessageItem,
+  WorkflowRun,
+  Task,
+  TaskCreated,
+  // Constants
+  API_ERROR_CODES,
+} from "ql-agent-sdk";
+```
+
+---
+
+## Using in Next.js App Router
+
+The SDK is safe to use **server-side** in Route Handlers or Server Components:
+
+```ts
+// app/api/agent/route.ts
+import { QLClient, QLError } from "ql-agent-sdk";
+
+export const runtime = "nodejs"; // uses native fetch + Web Streams
+
+const ql = new QLClient({ apiKey: process.env.QL_API_KEY! });
+
+export async function POST(req: Request) {
+  const { message } = await req.json();
+
+  try {
+    const reply = await ql.agents.chat({
+      agentId: "governing",
+      messages: [{ role: "user", content: message }],
+    });
+    return Response.json({ text: reply.content });
+  } catch (err) {
+    if (err instanceof QLError) {
+      return Response.json({ error: err.message }, { status: err.status ?? 500 });
+    }
+    throw err;
+  }
+}
+```
+
+For **streaming** in a Route Handler:
+```ts
+export async function POST(req: Request) {
+  const { message } = await req.json();
+  const ql = new QLClient({ apiKey: process.env.QL_API_KEY! });
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const ev of ql.agents.chatStream({
+          agentId: "governing",
+          messages: [{ role: "user", content: message }],
+        })) {
+          if (ev.type === "delta" && ev.content) {
+            controller.enqueue(new TextEncoder().encode(ev.content));
+          }
+        }
+      } finally {
+        controller.close();
+      }
+    },
+  });
+
+  return new Response(stream, { headers: { "Content-Type": "text/plain" } });
+}
+```
+
+---
+
+## Agent Reference
+
+The platform includes 8 specialized agents. Each has 20 capabilities in its domain:
+
+| ID | Domain | Examples |
+|----|--------|----------|
+| `governing` | Orchestration | Coordinates other agents, complex multi-step reasoning |
+| `finance` | Finance | Invoices, P&L, budgeting, cash flow, tax estimates |
+| `marketing` | Marketing | Social media content, ad copy, SEO, campaign planning |
+| `inventory` | Supply Chain | Stock levels, reorder points, supplier management |
+| `customer` | Customer Success | Support drafts, onboarding sequences, churn analysis |
+| `developer` | Engineering | Code generation, API docs, bug triage, test writing |
+| `operations` | Operations | SOPs, process mapping, KPI dashboards, compliance |
+| `research` | Research | Market analysis, competitor intel, literature reviews |
+
+Discover available capabilities at runtime:
+```ts
+const detail = await ql.agents.get("finance");
+console.log(detail.capabilities.map((c) => c.id));
+```
+
+---
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `QL_API_KEY` | Your API key (convention — the SDK reads it from the `apiKey` option, not env directly) |
+| `QL_BASE_URL` | Override the base URL (useful for staging/self-hosted) |
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `QLError: unauthorized` | Key is invalid, revoked, or expired | Generate a new key in your dashboard |
+| `QLError: forbidden` | Key scope doesn't cover the endpoint | Create a key with the required scope or `*` |
+| `QLError: not_found` (agent) | Typo in agent slug | Use `ql.agents.list()` to see valid IDs |
+| `QLError: network` | Can't reach the API | Check your network / base URL / firewall |
+| Task stuck in `"running"` | Server restarted mid-execution | Wait for stale recovery (≤5 min) or poll again later |
+| Stream produces no output | Model returned empty response | Check `reasoning` field or try a different agent |
+
+---
+
+## License
+
+MIT