@theokit/sdk 4.53.1 → 4.55.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.53.1",
-  "description": "TypeScript SDK for the Theo agent harness \u2014 same surface, local or cloud.",
+  "version": "4.55.0",
+  "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheokit/theokit-sdk#readme",
   "bugs": "https://github.com/usetheokit/theokit-sdk/issues",
@@ -88,6 +88,16 @@
         "default": "./dist/models.cjs"
       }
     },
+    "./providers": {
+      "import": {
+        "types": "./dist/providers.d.ts",
+        "default": "./dist/providers.js"
+      },
+      "require": {
+        "types": "./dist/providers.d.cts",
+        "default": "./dist/providers.cjs"
+      }
+    },
     "./skills": {
       "import": {
         "types": "./dist/skills.d.ts",
@@ -343,13 +353,12 @@
   "files": [
     "dist",
     "bin",
-    "claude-template",
+    "docs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "bin": {
-    "theokit-init-claude": "./bin/init-claude.mjs",
     "theokit-migrate-config": "./bin/theokit-migrate-config.mjs",
     "theokit-migrate-memory": "./bin/theokit-migrate-memory.mjs"
   },
@@ -358,19 +367,9 @@
     "**/agent.js",
     "**/agent.cjs"
   ],
-  "scripts": {
-    "build": "tsup && cp src/internal/providers/provider-catalog.json dist/provider-catalog.json",
-    "test": "vitest run --no-file-parallelism",
-    "test:watch": "vitest",
-    "eval": "vitest run --no-file-parallelism tests/eval/suites",
-    "test:contract": "vitest run --no-file-parallelism tests/theokit-consumer-contract.test.ts",
-    "prepublishOnly": "pnpm build && pnpm test:contract && node ../../tools/check-publish-no-workspace.mjs .",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "docs:json": "typedoc --options typedoc.json"
-  },
   "peerDependencies": {
     "@lancedb/lancedb": "^0.30.0",
+    "@opentelemetry/api": "^1.9.0",
     "@types/ws": ">=8.0.0",
     "better-sqlite3": "^12.0.0",
     "proper-lockfile": "^4.1.2",
@@ -382,6 +381,9 @@
     "@lancedb/lancedb": {
       "optional": true
     },
+    "@opentelemetry/api": {
+      "optional": true
+    },
     "@types/ws": {
       "optional": true
     },
@@ -402,6 +404,7 @@
     }
   },
   "publishConfig": {
+    "provenance": true,
     "access": "public"
   },
   "keywords": [
@@ -436,5 +439,15 @@
     "typedoc": "^0.28.19",
     "ws": "^8.18.0",
     "zod": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsup && cp src/internal/providers/provider-catalog.json dist/provider-catalog.json && node ../../tools/repair-dts-imports.mjs .",
+    "test": "vitest run --no-file-parallelism",
+    "test:watch": "vitest",
+    "eval": "vitest run --no-file-parallelism tests/eval/suites",
+    "test:contract": "vitest run --no-file-parallelism tests/theokit-consumer-contract.test.ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "docs:json": "typedoc --options typedoc.json"
   }
-}
+}

package/bin/init-claude.mjs

@@ -1,68 +0,0 @@
-#!/usr/bin/env node
-import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
-import { join } from "node:path";
-
-// EC-1: Node version guard (matches SDK engines.node)
-const [major, minor] = process.versions.node.split(".").map(Number);
-if (major < 22 || (major === 22 && minor < 12)) {
-  console.error(`@theokit/sdk requires Node >= 22.12.0. Current: ${process.version}`);
-  process.exit(1);
-}
-
-const templateDir = join(import.meta.dirname, "../claude-template");
-const cwd = process.cwd();
-const targetDir = join(cwd, ".claude");
-const force = process.argv.includes("--force");
-
-/**
- * Merge-copy: recursively copies src into dest, skipping files that already
- * exist in dest. With --force, overwrites everything.
- * Returns { added, skipped } counts.
- */
-function mergeCopy(src, dest) {
-  let added = 0;
-  let skipped = 0;
-  mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src, { withFileTypes: true })) {
-    const srcPath = join(src, entry.name);
-    const destPath = join(dest, entry.name);
-    if (entry.isDirectory()) {
-      const sub = mergeCopy(srcPath, destPath);
-      added += sub.added;
-      skipped += sub.skipped;
-    } else if (force || !existsSync(destPath)) {
-      cpSync(srcPath, destPath);
-      added++;
-    } else {
-      skipped++;
-    }
-  }
-  return { added, skipped };
-}
-
-// Merge .claude/ directory (skills, rules, settings)
-const dotClaude = mergeCopy(join(templateDir, "dot-claude"), targetDir);
-
-// Merge root files (AGENTS.md, CLAUDE.md)
-let rootAdded = 0;
-let rootSkipped = 0;
-for (const file of ["AGENTS.md", "CLAUDE.md"]) {
-  const dest = join(cwd, file);
-  if (force || !existsSync(dest)) {
-    cpSync(join(templateDir, file), dest);
-    rootAdded++;
-  } else {
-    rootSkipped++;
-  }
-}
-
-const totalAdded = dotClaude.added + rootAdded;
-const totalSkipped = dotClaude.skipped + rootSkipped;
-
-if (totalAdded === 0) {
-  console.log("All TheoKit SDK files already present. Nothing to add.");
-  console.log("Use --force to overwrite existing files.");
-} else {
-  console.log(`Added ${totalAdded} file(s). Skipped ${totalSkipped} existing file(s).`);
-  console.log("\nNext: open Claude Code and start building with TheoKit.");
-}

package/claude-template/AGENTS.md

@@ -1,157 +0,0 @@
-# @theokit/sdk — TypeScript SDK for AI Agents
-
-Build AI agents that run locally or in the cloud. Same code, same API, pick your runtime. The exported types are the canonical contract.
-
-## Setup
-
-```bash
-npm install @theokit/sdk
-```
-
-Set your API key:
-```bash
-export THEOKIT_API_KEY="your-key"
-```
-
-Node 22.12+ required.
-
-## Import Map (verified subpaths)
-
-```typescript
-import { Agent, Cron, Tool } from "@theokit/sdk";              // core: Agent, Run, Cron, Tool, SDKMessage
-import { TheokitAgentError } from "@theokit/sdk/errors";       // error hierarchy
-import { Workflow } from "@theokit/sdk/workflow";              // multi-step workflows
-import { Eval } from "@theokit/sdk/eval";                      // evaluation suite
-import { Subscription } from "@theokit/sdk/subscription";      // SSE / WebSocket subscriptions
-import { SubAgent } from "@theokit/sdk/a2a";                   // agent-to-agent delegation
-import { Auth } from "@theokit/sdk/server/auth";              // authentication
-import { TaskStore } from "@theokit/sdk/task-store";           // task persistence
-```
-
-Other public subpaths: `/messages`, `/models`, `/skills`, `/project`, `/subagents`, `/sandbox`, `/client`, `/persistence`, `/retry`, `/concurrency`, `/sanitize`. There is **no** `@theokit/sdk/rag` subpath. Never import from `@theokit/sdk/internal/*` or `@theokit/sdk/dist/*`.
-
-## Quick Start
-
-```typescript
-const agent = await Agent.create({
-  apiKey: process.env.THEOKIT_API_KEY!,
-  model: { id: "google/gemini-2.0-flash-001" },
-  local: { cwd: process.cwd() },
-});
-
-const run = await agent.send("Summarize this repository");
-for await (const event of run.stream()) {
-  if (event.type === "assistant") {
-    for (const block of event.message.content) {
-      if (block.type === "text") process.stdout.write(block.text);
-    }
-  }
-}
-
-await agent[Symbol.asyncDispose](); // or: await using agent = await Agent.create(...)
-```
-
-## Core Patterns
-
-### Agent lifecycle
-- `Agent.create(options)` — create an agent (local or cloud); returns immediately, `agent.agentId` is `agent-<uuid>` (local) or `bc-<uuid>` (cloud).
-- `agent.send(prompt)` — send a message, get a `Run` (context is retained across sends).
-- `run.stream()` — `AsyncGenerator` of `SDKMessage` events.
-- `run.wait()` — resolve to `{ status, result, model, durationMs, git? }` after the run ends.
-- `Agent.prompt(prompt, options)` — one-shot (create + send + dispose). **Prompt is the first argument.**
-- `Agent.resume(agentId, { apiKey })` — reattach; runtime auto-detected from the ID prefix.
-- Dispose with `await using`, `await agent[Symbol.asyncDispose]()`, or `agent.close()` (fire-and-forget).
-
-### Tool definition — `Tool.create` with a Zod schema
-```typescript
-import { z } from "zod";
-import { Tool } from "@theokit/sdk";
-
-const searchTool = Tool.create({
-  name: "search",
-  description: "Search the web",
-  inputSchema: z.object({ query: z.string() }),
-  handler: async ({ query }) => JSON.stringify({ results: await search(query) }),
-});
-```
-
-The tool spec field is `handler` (returns a string, or a typed value when you set `outputSchema`). Built-in coding tools (`createReadFileTool`, …) live in the separate `@theokit/sdk-tools` package, not a `@theokit/sdk/tools` subpath.
-
-`Tool.create` is the canonical factory (uniform `X.create()` API since v3.0). Every public factory follows it: `Provider.create`, `Plugin.create`, `Subscription.create`, `Auth.create`, `SubAgent.create`, `Squad.create`, `Retry.create`. There is **no** `defineTool` / `define*` export — those were removed at v3.0.
-
-### Streaming events (`SDKMessage`)
-Discriminate on `type`. All events carry `agent_id` and `run_id`.
-- `{ type: "system" }` — init metadata, once at start (`model?`, `tools?`)
-- `{ type: "user", message: { content } }` — echo of the prompt
-- `{ type: "assistant", message: { content } }` — model output; `content` is a `(TextBlock | ToolUseBlock)[]`
-- `{ type: "thinking", text }` — reasoning content
-- `{ type: "tool_call", call_id, name, status, args?, result? }` — tool lifecycle
-- `{ type: "status", status }` — cloud run lifecycle
-- `{ type: "task" }` / `{ type: "request", request_id }` — task milestones / awaiting input
-
-There is no `tool_use` / `tool_result` / `usage` / `error` event. Read assistant text from `event.message.content` (a block array), not `event.content`. Treat `tool_call` `args`/`result` as `unknown`.
-
-### Error handling
-```typescript
-import { TheokitAgentError } from "@theokit/sdk/errors";
-
-try {
-  await agent.send("...");
-} catch (e) {
-  if (e instanceof TheokitAgentError) console.error(e.code, e.isRetryable, e.message);
-}
-```
-Subclasses: `AuthenticationError`, `RateLimitError`, `ConfigurationError`, `IntegrationNotConnectedError`, `NetworkError`, `UnknownAgentError`, `UnsupportedRunOperationError`.
-
-### Optional: DI decorators (`@theokit/di` + `@theokit/di-agent`)
-Decorators are an **optional** convenience layer in separate packages — the factory API above is canonical and never requires them.
-```typescript
-import { Injectable } from "@theokit/di";
-import { Tool as ToolDecorator, Cron as CronDecorator } from "@theokit/di-agent";
-
-@Injectable()
-class MyService {
-  @ToolDecorator({ name: "search", description: "Search" })
-  searchTool!: unknown;
-
-  @CronDecorator({ schedule: "*/5 * * * *" })
-  cleanup() { /* runs every 5 min */ }
-}
-```
-
-### Optional: Gateways
-```typescript
-import { defineGateway } from "@theokit/gateway-telegram"; // or -slack, -discord, etc.
-const gateway = defineGateway({ token: process.env.BOT_TOKEN });
-```
-
-## Anti-patterns
-
-- NEVER `new Agent()` — always `await Agent.create()`.
-- NEVER author `defineTool` / `defineSubscription` / `defineAuth` / `defineSubAgent` — use `Tool.create` / `Subscription.create` / `Auth.create` / `SubAgent.create`.
-- NEVER switch on `tool_use` / `tool_result` / `usage` / `error` stream events — they don't exist; use `tool_call` / `assistant` / `thinking` / `status`.
-- NEVER read assistant text as `event.content` — it's `event.message.content`.
-- NEVER import from `@theokit/sdk/internal/*`, `@theokit/sdk/dist/*`, or `@theokit/sdk/rag` (no such subpath).
-- NEVER forget disposal (`await using` / `Symbol.asyncDispose` / `close()`) — it leaks the runtime.
-- NEVER use `any` for tool input schemas — use Zod schemas.
-
-## Packages
-
-| Package | Purpose |
-|---------|---------|
-| `@theokit/sdk` | Core SDK (Agent, Run, Tool, Cron, streaming, memory, workflows, eval, subscriptions) |
-| `@theokit/di` | Dependency injection container (optional) |
-| `@theokit/di-agent` | Agentic decorators for DI (optional) |
-| `@theokit/gateway-*` | Platform gateways — telegram, slack, discord, etc. (optional) |
-| `@theokit/react` | React hooks for agent UIs (optional) |
-
-## Configuration
-
-Project config lives in `.theokit/`:
-- `.theokit/mcp.json` — MCP server configuration
-- `.theokit/hooks.json` — lifecycle hooks
-- `.theokit/agents/*.md` — agent instruction files
-
-Environment variables:
-- `THEOKIT_API_KEY` — API key (required)
-- `THEOKIT_MODEL_ID` — default model override

package/claude-template/CLAUDE.md

@@ -1,66 +0,0 @@
-@AGENTS.md
-
-## Claude Code — TheoKit SDK Extensions
-
-This project uses `@theokit/sdk`. The AGENTS.md above contains the full API reference. Below are Claude Code-specific extensions.
-
-### Available Skills (auto-loaded by domain)
-
-These skills inject TheoKit knowledge automatically when you edit files matching their domain:
-
-| Skill | Triggers on files matching |
-|-------|---------------------------|
-| `theokit-agent-core` | `*agent*`, `*Agent*`, `sdk.*` |
-| `theokit-tools` | `*tool*`, `*Tool*` |
-| `theokit-memory` | `*memory*`, `*Memory*`, `*embed*` |
-| `theokit-di` | `*container*`, `*inject*`, `*provider*`, `*module*` |
-| `theokit-di-agent` | `*decorator*`, `*Decorator*`, `di-agent*` |
-| `theokit-gateways` | `*gateway*`, `*telegram*`, `*slack*`, `*discord*` |
-| `theokit-workflows` | `*workflow*`, `*Workflow*`, `*step*` |
-| `theokit-eval` | `*eval*`, `*Eval*`, `*scorer*` |
-| `theokit-cron` | `*cron*`, `*Cron*`, `*job*`, `*schedule*` |
-| `theokit-subscriptions` | `*subscri*`, `*sse*`, `*websocket*`, `*ws.*` |
-| `theokit-errors` | `*error*`, `*Error*`, `*exception*` |
-| `theokit-config` | `.theokit/**`, `config.*`, `theo.config.*` |
-| `theokit-streaming` | `*stream*`, `*Stream*`, `*SDKMessage*` |
-| `theokit-budget` | `*budget*`, `*Budget*`, `*cost*`, `*token*` |
-| `theokit-models` | `*model*`, `*Model*` |
-| `theokit-subagents` | `*subagent*`, `*a2a*`, `*delegat*` |
-| `theokit-retry` | `*retry*`, `*Retry*` |
-| `theokit-task-store` | `*task-store*`, `*taskstore*`, `*TaskStore*` |
-| `theokit-sandbox` | `*sandbox*`, `*Sandbox*` |
-| `theokit-compaction` | `*compact*`, `*Compact*` |
-| `theokit-messages` | `*message*`, `*Message*` |
-| `theokit-auth` | `*auth*`, `*Auth*`, `*envelope*` |
-| `theokit-sanitize` | `*sanitize*`, `*Sanitize*` |
-| `theokit-skills` | `*skill*`, `*Skill*` |
-| `theokit-path-safety` | `*path-safety*`, `*pathsafety*` |
-| `theokit-concurrency` | `*concurren*`, `*semaphore*`, `*Semaphore*` |
-| `theokit-persistence` | `*persist*`, `*Persist*` |
-| `theokit-client` | `*client*`, `*Client*` |
-| `theokit-filesystem` | `*filesystem*`, `*Filesystem*` |
-| `theokit-project` | `*project*`, `*Project*` |
-
-### Settings
-
-`.claude/settings.json` is pre-configured with safe defaults:
-- Allows: `npm run *`, `pnpm *`, `git status`, `git diff`, reading `src/` and `docs/`
-- Denies: `.env*` file reads, `sudo`, `rm -rf`
-- Override locally: create `.claude/settings.local.json` (add to `.gitignore`)
-
-### Customization
-
-Add your project-specific instructions below this line. The SDK knowledge above stays current with your installed `@theokit/sdk` version.
-
-```markdown
-## My Project
-
-Build: `npm run build`
-Test: `npm test`
-Lint: `npm run lint`
-
-## Architecture
-- `src/agents/` — agent definitions
-- `src/tools/` — tool implementations
-- `src/services/` — business logic
-```

package/claude-template/dot-claude/rules/theokit-conventions.md

@@ -1,32 +0,0 @@
-# TheoKit SDK Conventions
-
-## Agent lifecycle
-- Always use `Agent.create()` to create agents — NEVER `new Agent()`
-- Always call `agent.dispose()` or use `await using` when done
-- Use `Agent.prompt()` for one-shot operations (auto-disposes)
-
-## Imports
-- Use `@theokit/sdk` for core (Agent, Tool, Cron, Memory)
-- Use `@theokit/sdk/errors` for error types
-- Use `@theokit/sdk/subscription` for SSE/WebSocket
-- Use `@theokit/sdk/cron` for scheduled jobs
-- Use `@theokit/sdk/eval` for evaluation
-- Use `@theokit/sdk/workflow` for workflows
-- NEVER import from `@theokit/sdk/internal/...`
-- NEVER import from `@theokit/sdk/dist/...`
-
-## Tools
-- Tool `inputSchema` MUST use Zod schemas — NEVER `any` or untyped objects
-- Tool `handler` MUST return a string (or a value matching `outputSchema` when set)
-
-## DI
-- Use `@Injectable()` + `@Inject()` from `@theokit/di`
-- NEVER manually `new` a service — let the container resolve it
-
-## Error handling
-- Catch `TheokitAgentError` (base class) and check `error.code`
-- NEVER silently swallow errors — log with context or rethrow
-
-## Gateways
-- One gateway per agent instance
-- Configure via `defineGateway()` from the specific gateway package

package/claude-template/dot-claude/settings.json

@@ -1,16 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm run *)",
-      "Bash(pnpm *)",
-      "Bash(npx *)",
-      "Read(./src/**)",
-      "Read(./docs/**)",
-      "Read(./tests/**)",
-      "Bash(git status)",
-      "Bash(git diff)",
-      "Bash(git log *)"
-    ],
-    "deny": ["Read(.env*)", "Read(**/.env*)", "Bash(sudo *)", "Bash(rm -rf *)"]
-  }
-}

package/claude-template/dot-claude/skills/theokit-agent-core/SKILL.md

@@ -1,209 +0,0 @@
----
-user-invocable: false
-description: Agent lifecycle, sending messages, streaming, and disposal patterns for @theokit/sdk.
-paths:
-  - "**/*agent*"
-  - "**/*Agent*"
-  - "**/sdk.*"
----
-
-# TheoKit SDK -- Agent Core
-
-Quick reference for Agent lifecycle, Run streaming, and disposal.
-
-## Agent.create
-
-```typescript
-import { Agent } from "@theokit/sdk";
-
-const agent = await Agent.create({
-  apiKey: process.env.THEOKIT_API_KEY!,
-  model: { id: "google/gemini-2.0-flash-001" },
-  local: { cwd: process.cwd() },
-});
-```
-
-Returns an `SDKAgent`. Local agents get `agent-<uuid>` IDs; cloud agents get `bc-<uuid>`.
-
-### AgentOptions (key fields)
-
-| Property | Type | Notes |
-|---|---|---|
-| `model` | `ModelSelection` | Required for local; `{ id, params? }`. |
-| `apiKey` | `string` | Falls back to `THEOKIT_API_KEY` env. |
-| `local` | `{ cwd, settingSources?, sandboxOptions? }` | Local runtime config. |
-| `cloud` | `CloudOptions` | Cloud runtime config (repos, autoCreatePR, envVars). |
-| `systemPrompt` | `string \| (ctx: SystemPromptContext) => string` | Static string or async resolver. |
-| `mcpServers` | `Record<string, McpServerConfig>` | Inline MCP server definitions. |
-| `agents` | `Record<string, AgentDefinition>` | Subagent definitions. |
-| `tools` | `CustomTool[]` | Inline custom tools (local only). |
-| `memory` | `MemoryOptions` | Durable memory config. |
-| `handoffs` | `Array<SDKAgent \| Handoff>` | Peer-to-peer agent handoffs. |
-| `conversationStorage` | `ConversationStorageAdapter` | Pluggable persistence. |
-
-## Agent.prompt (one-shot)
-
-```typescript
-const result = await Agent.prompt("What does the auth middleware do?", {
-  apiKey: process.env.THEOKIT_API_KEY!,
-  model: { id: "google/gemini-2.0-flash-001" },
-  local: { cwd: process.cwd() },
-});
-// result: { id, status, result?, model?, durationMs?, git? }
-```
-
-Pass `throwOnError: true` to reject with `AgentRunError` instead of resolving with `status: 'error'`.
-
-## agent.send and Run
-
-```typescript
-const run = await agent.send("Find the bug in src/auth.ts");
-```
-
-### Run interface
-
-| Member | Type | Description |
-|---|---|---|
-| `id` | `string` | Run identifier. |
-| `status` | `RunStatus` | `"running" \| "finished" \| "error" \| "cancelled"` |
-| `stream()` | `AsyncGenerator<SDKMessage>` | Normalized event stream. |
-| `wait()` | `Promise<RunResult>` | Block until finished. |
-| `cancel()` | `Promise<void>` | Cancel the run. |
-| `conversation()` | `Promise<ConversationTurn[]>` | Structured turn history. |
-| `onDidChangeStatus(fn)` | `() => void` | Status change listener; returns unsubscribe. |
-
-### Streaming SDKMessage types
-
-```typescript
-for await (const event of run.stream()) {
-  switch (event.type) {
-    case "assistant": /* event.message.content: (TextBlock | ToolUseBlock)[] */ break;
-    case "thinking":  /* event.text, event.thinking_duration_ms? */ break;
-    case "tool_call": /* event.name, event.status, event.args?, event.result? */ break;
-    case "status":    /* event.status: cloud lifecycle transitions */ break;
-    case "task":      /* event.text: task milestones */ break;
-    case "request":   /* event.request_id: awaiting user input */ break;
-  }
-}
-```
-
-### Per-send options
-
-```typescript
-await agent.send("Plan the refactor", {
-  model: { id: "claude-sonnet-4-6", params: [{ id: "thinking", value: "high" }] },
-  systemPrompt: "Focus on performance.",
-  signal: abortController.signal,
-  onDelta: ({ update }) => { /* InteractionUpdate */ },
-  onStep: ({ step }) => { /* ConversationStep */ },
-});
-```
-
-## Agent.resume
-
-```typescript
-const agent = await Agent.resume("bc-abc123", {
-  apiKey: process.env.THEOKIT_API_KEY!,
-});
-```
-
-Runtime auto-detected from ID prefix. Inline `mcpServers` and `tools` are NOT persisted -- re-pass on resume.
-
-## Agent.getOrCreate
-
-```typescript
-const agent = await Agent.getOrCreate(`tg-user-${userId}`, {
-  apiKey: process.env.THEOKIT_API_KEY!,
-  model: { id: "claude-sonnet-4-6" },
-  local: { cwd: process.cwd() },
-});
-```
-
-Tries resume first; on `UnknownAgentError` falls through to create.
-
-## Agent.get / Agent.list / Agent.listRuns
-
-```typescript
-const info = await Agent.get(agentId);
-const { items, nextCursor } = await Agent.list({ runtime: "local", cwd: process.cwd() });
-const { items: runs } = await Agent.listRuns(agentId);
-```
-
-## AgentFactory.create
-
-```typescript
-import { AgentFactory } from "@theokit/sdk";
-
-const factory = AgentFactory.create({
-  apiKey: process.env.THEOKIT_API_KEY!,
-  model: { id: "claude-sonnet-4-6" },
-  local: { cwd: process.cwd() },
-  systemPrompt: "You are a helpful assistant.",
-});
-const agent = await factory.getOrCreate(`user-${userId}`);
-```
-
-## Agent.builder (fluent API)
-
-```typescript
-const agent = await Agent.builder()
-  .apiKey(process.env.THEOKIT_API_KEY!)
-  .model({ id: "claude-sonnet-4-6" })
-  .local({ cwd: process.cwd() })
-  .tools([myTool])
-  .getOrCreate(`user-${userId}`);
-```
-
-## Agent.generateObject / Agent.streamObject
-
-```typescript
-import { z } from "zod";
-
-const { object } = await Agent.generateObject({
-  schema: z.object({ title: z.string(), year: z.number().nullable() }),
-  prompt: "Fact card about jazz.",
-  model: { id: "google/gemini-2.0-flash-001" },
-  local: { cwd: process.cwd() },
-});
-
-for await (const evt of Agent.streamObject({ schema, prompt, model, local })) {
-  if (evt.type === "partial") render(evt.partial);
-  if (evt.type === "complete") finalize(evt.object);
-}
-```
-
-## Disposal patterns
-
-```typescript
-// Preferred: await using (auto-dispose on block exit)
-await using agent = await Agent.create({ /* ... */ });
-
-// Explicit dispose
-await agent[Symbol.asyncDispose]();
-
-// Fire-and-forget close
-agent.close();
-
-// Reload config without disposing
-await agent.reload();
-```
-
-## Agent.registry (production)
-
-```typescript
-Agent.registry.configure({ maxAgents: 1000, idleTimeoutMs: 15 * 60 * 1000 });
-Agent.registry.size();
-Agent.registry.evict("agent-42");
-await Agent.registry.evictAll(); // graceful shutdown
-```
-
-## Cancellation
-
-```typescript
-const run = await agent.send(message, { signal: request.signal });
-// On abort: AgentRunError with code "aborted"
-
-// Compose with timeout:
-const composed = AbortSignal.any([request.signal, AbortSignal.timeout(30_000)]);
-await agent.send(message, { signal: composed });
-```