@theokit/sdk 1.7.0 → 1.8.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [1.8.1] - 2026-06-12
+
+### Changed
+
+- `theokit-init-claude` now merges into existing `.claude/` directories instead of refusing. Adds only missing files, preserves user customizations. Use `--force` to overwrite all files.
+
+## [1.8.0] - 2026-06-12
+
+### Added
+
+- `.claude/` consumer template with 15 domain-specific passive skills, convention rules, AGENTS.md (cross-agent), and CLAUDE.md for AI coding tool integration. Scaffold via `npx theokit-init-claude`. Skills auto-inject TheoKit API knowledge when editing files matching each domain (Agent Core, Tools, Memory, DI, DI-Agent, Gateways, RAG, Workflows, Eval, Cron, Subscriptions, Errors, Config, Streaming, Budget). 33 tests.
+
 ## [1.7.0] - 2026-06-11
 
 ### Changed

package/bin/init-claude.mjs

@@ -0,0 +1,68 @@
+#!/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

@@ -0,0 +1,139 @@
+# @theokit/sdk — TypeScript SDK for AI Agents
+
+Build AI agents that run locally or in the cloud. Same code, same API, pick your runtime.
+
+## Setup
+
+```bash
+npm install @theokit/sdk
+```
+
+Set your API key:
+```bash
+export THEOKIT_API_KEY="your-key"
+```
+
+## Import Map
+
+```typescript
+import { Agent } from "@theokit/sdk";                         // Core: Agent, Run, SDKMessage
+import { defineTool } from "@theokit/sdk";                     // Tool definitions
+import { TheokitAgentError } from "@theokit/sdk/errors";       // Error hierarchy
+import { Cron } from "@theokit/sdk/cron";                      // Scheduled jobs
+import { Eval } from "@theokit/sdk/eval";                      // Evaluation suite
+import { Workflow } from "@theokit/sdk/workflow";               // Multi-step workflows
+import { defineSubscription } from "@theokit/sdk/subscription"; // SSE/WebSocket subscriptions
+import { VectorRetriever } from "@theokit/sdk/rag";            // RAG: retrievers, rerankers, splitters
+import { defineSubAgent } from "@theokit/sdk/a2a";             // Agent-to-agent delegation
+import { SandboxBackend } from "@theokit/sdk/sandbox";         // Sandbox backends
+import { defineAuth } from "@theokit/sdk/server/auth";         // Authentication
+import { TaskStore } from "@theokit/sdk/task-store";           // Task persistence
+import { createClient } from "@theokit/sdk/client";            // HTTP client
+```
+
+## 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") console.log(event.content);
+}
+
+agent.dispose(); // Always clean up
+```
+
+## Core Patterns
+
+### Agent lifecycle
+- `Agent.create(options)` — create an agent (local or cloud)
+- `agent.send(prompt)` — send a message, get a Run
+- `run.stream()` — AsyncGenerator of SDKMessage events
+- `agent.dispose()` — clean up resources (or use `await using`)
+- `Agent.prompt(options, prompt)` — one-shot: create, send, dispose
+
+### Tool definition
+```typescript
+const searchTool = defineTool({
+  name: "search",
+  description: "Search the web",
+  inputSchema: z.object({ query: z.string() }),
+  execute: async ({ query }) => ({ results: await search(query) }),
+});
+```
+
+### Streaming events (SDKMessage)
+- `{ type: "assistant", content }` — text from the model
+- `{ type: "tool_use", name, input }` — tool call
+- `{ type: "tool_result", name, output }` — tool response
+- `{ type: "status", status }` — run status change
+- `{ type: "error", error }` — error event
+- `{ type: "usage", tokens }` — token usage update
+
+### Error handling
+```typescript
+try {
+  await agent.send("...");
+} catch (e) {
+  if (e instanceof TheokitAgentError) {
+    console.error(e.code, e.message); // typed error with code
+  }
+}
+```
+
+### DI decorators (`@theokit/di` + `@theokit/di-agent`)
+```typescript
+import { Injectable, Container } from "@theokit/di";
+import { Tool, Workflow, Cron, InjectAgent } from "@theokit/di-agent";
+
+@Injectable()
+class MyService {
+  @Tool({ name: "search", description: "Search" })
+  searchTool!: ToolOptions;
+
+  @Cron({ schedule: "*/5 * * * *" })
+  cleanup() { /* runs every 5 min */ }
+}
+```
+
+### Gateways
+```typescript
+import { defineGateway } from "@theokit/gateway-telegram"; // or -slack, -discord, etc.
+const gateway = defineGateway({ token: process.env.BOT_TOKEN });
+```
+
+Available: telegram, slack, discord, whatsapp, teams, email, sms, mattermost, line, matrix.
+
+## Anti-patterns
+
+- NEVER import from `@theokit/sdk/internal/...` — internal paths are not public API
+- NEVER import from `@theokit/sdk/dist/...` — use the exports map above
+- NEVER forget `agent.dispose()` — causes resource leaks
+- NEVER use `new Agent()` — always use `Agent.create()`
+- NEVER use `any` for tool input schemas — use Zod schemas
+
+## Packages
+
+| Package | Purpose |
+|---------|---------|
+| `@theokit/sdk` | Core SDK (Agent, Run, Tools, Memory, Streaming) |
+| `@theokit/di` | Dependency injection container |
+| `@theokit/di-agent` | 15 agentic decorators for DI |
+| `@theokit/gateway-*` | Platform gateways (Telegram, Slack, etc.) |
+| `@theokit/react` | React hooks for agent UIs |
+
+## 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

@@ -0,0 +1,51 @@
+@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-rag` | `*retriev*`, `*rerank*`, `*splitter*`, `*rag*` |
+| `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*` |
+
+### 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

@@ -0,0 +1,33 @@
+# 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, defineTool, Memory)
+- Use `@theokit/sdk/errors` for error types
+- Use `@theokit/sdk/subscription` for SSE/WebSocket
+- Use `@theokit/sdk/rag` for retrievers, rerankers, splitters
+- 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 `execute` MUST return a serializable value
+
+## 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

@@ -0,0 +1,16 @@
+{
+  "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

@@ -0,0 +1,209 @@
+---
+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);
+```
+
+## createAgentFactory
+
+```typescript
+import { createAgentFactory } from "@theokit/sdk";
+
+const factory = createAgentFactory({
+  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 });
+```