@theokit/sdk 4.2.6 → 4.2.7

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 4.2.7
+
+### Patch Changes
+
+- fix(init-claude): the scaffolded `.claude/` template (`npx theokit-init-claude`) now teaches the current `X.create()` API instead of the pre-3.0 surface removed by SE36 (#139). `AGENTS.md` + the affected skills/rules were corrected: `defineTool`→`Tool.create`, `defineSubscription`→`Subscription.create`, `createAgentFactory`→`AgentFactory.create`; the tool spec field is `handler` (not `execute`); streaming events are `system`/`user`/`assistant`/`thinking`/`tool_call`/`status`/`task`/`request` (there is no `tool_use`/`tool_result`/`usage`/`error`); assistant text is `event.message.content`; `Agent.prompt(prompt, options)` (prompt first); built-in coding tools import from `@theokit/sdk-tools` (not a `@theokit/sdk/tools` subpath). The phantom `theokit-rag` skill and the non-existent `@theokit/sdk/rag` import were removed. A `tests/lint/claude-template-no-drift.test.ts` gate now fails CI if the scaffold teaches a removed factory, phantom subpath, or non-existent stream event.
+
 ## 4.2.6
 
 ### Patch Changes

package/claude-template/AGENTS.md

@@ -1,6 +1,6 @@
 # @theokit/sdk — TypeScript SDK for AI Agents
 
-Build AI agents that run locally or in the cloud. Same code, same API, pick your runtime.
+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
 
@@ -13,24 +13,23 @@ Set your API key:
 export THEOKIT_API_KEY="your-key"
 ```
 
-## Import Map
+Node 22.12+ required.
+
+## Import Map (verified subpaths)
 
 ```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
+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
@@ -42,90 +41,109 @@ const agent = await Agent.create({
 
 const run = await agent.send("Summarize this repository");
 for await (const event of run.stream()) {
-  if (event.type === "assistant") console.log(event.content);
+  if (event.type === "assistant") {
+    for (const block of event.message.content) {
+      if (block.type === "text") process.stdout.write(block.text);
+    }
+  }
 }
 
-agent.dispose(); // Always clean up
+await agent[Symbol.asyncDispose](); // or: await using agent = await Agent.create(...)
 ```
 
 ## 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
+- `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
-const searchTool = defineTool({
+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() }),
-  execute: async ({ query }) => ({ results: await search(query) }),
+  handler: async ({ query }) => JSON.stringify({ 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
+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.message); // typed error with code
-  }
+  if (e instanceof TheokitAgentError) console.error(e.code, e.isRetryable, e.message);
 }
 ```
+Subclasses: `AuthenticationError`, `RateLimitError`, `ConfigurationError`, `IntegrationNotConnectedError`, `NetworkError`, `UnknownAgentError`, `UnsupportedRunOperationError`.
 
-### DI decorators (`@theokit/di` + `@theokit/di-agent`)
+### 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, Container } from "@theokit/di";
-import { Tool, Workflow, Cron, InjectAgent } from "@theokit/di-agent";
+import { Injectable } from "@theokit/di";
+import { Tool as ToolDecorator, Cron as CronDecorator } from "@theokit/di-agent";
 
 @Injectable()
 class MyService {
-  @Tool({ name: "search", description: "Search" })
-  searchTool!: ToolOptions;
+  @ToolDecorator({ name: "search", description: "Search" })
+  searchTool!: unknown;
 
-  @Cron({ schedule: "*/5 * * * *" })
+  @CronDecorator({ schedule: "*/5 * * * *" })
   cleanup() { /* runs every 5 min */ }
 }
 ```
 
-### Gateways
+### Optional: 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
+- 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, 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 |
+| `@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
 

package/claude-template/CLAUDE.md

@@ -16,7 +16,6 @@ These skills inject TheoKit knowledge automatically when you edit files matching
 | `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*` |

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

@@ -6,10 +6,9 @@
 - Use `Agent.prompt()` for one-shot operations (auto-disposes)
 
 ## Imports
-- Use `@theokit/sdk` for core (Agent, defineTool, Memory)
+- 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/rag` for retrievers, rerankers, splitters
 - Use `@theokit/sdk/cron` for scheduled jobs
 - Use `@theokit/sdk/eval` for evaluation
 - Use `@theokit/sdk/workflow` for workflows
@@ -18,7 +17,7 @@
 
 ## Tools
 - Tool `inputSchema` MUST use Zod schemas — NEVER `any` or untyped objects
-- Tool `execute` MUST return a serializable value
+- Tool `handler` MUST return a string (or a value matching `outputSchema` when set)
 
 ## DI
 - Use `@Injectable()` + `@Inject()` from `@theokit/di`

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

@@ -129,12 +129,12 @@ const { items, nextCursor } = await Agent.list({ runtime: "local", cwd: process.
 const { items: runs } = await Agent.listRuns(agentId);
 ```
 
-## createAgentFactory
+## AgentFactory.create
 
 ```typescript
-import { createAgentFactory } from "@theokit/sdk";
+import { AgentFactory } from "@theokit/sdk";
 
-const factory = createAgentFactory({
+const factory = AgentFactory.create({
   apiKey: process.env.THEOKIT_API_KEY!,
   model: { id: "claude-sonnet-4-6" },
   local: { cwd: process.cwd() },

package/claude-template/dot-claude/skills/theokit-subscriptions/SKILL.md

@@ -5,7 +5,7 @@ paths:
   - "**/*sse*"
   - "**/*websocket*"
   - "**/*ws.*"
-description: TheoKit SDK Subscriptions API — defineSubscription, SSE/WebSocket transport, subscribe, tracked, resume tokens
+description: TheoKit SDK Subscriptions API — Subscription.create, SSE/WebSocket transport, subscribe, tracked, resume tokens
 ---
 
 # TheoKit Subscriptions
@@ -13,13 +13,13 @@ description: TheoKit SDK Subscriptions API — defineSubscription, SSE/WebSocket
 Typed WebSocket + W3C SSE subscriptions with opaque resume tokens. Available
 via the `@theokit/sdk/subscription` sub-path import (not on the main barrel).
 
-## Server side — `defineSubscription`
+## Server side — `Subscription.create`
 
 ```typescript
-import { defineSubscription } from "@theokit/sdk/subscription";
+import { Subscription } from "@theokit/sdk/subscription";
 import { z } from "zod";
 
-export default defineSubscription({
+export default Subscription.create({
   input: z.object({
     room: z.string(),
     lastEventId: z.string().optional(),
@@ -91,11 +91,11 @@ for await (const msg of subscribe<
 
 ## Composing with LLM streaming
 
-`Agent.streamObject` and `defineSubscription` are independent surfaces. Call
+`Agent.streamObject` and `Subscription.create` are independent surfaces. Call
 `Agent.streamObject` inside a subscription handler:
 
 ```typescript
-export default defineSubscription({
+export default Subscription.create({
   input: z.object({ topic: z.string() }),
   output: z.object({ kind: z.enum(["partial", "complete"]), text: z.string() }),
   async *handler(input, ctx) {

package/claude-template/dot-claude/skills/theokit-tools/SKILL.md

@@ -1,6 +1,6 @@
 ---
 user-invocable: false
-description: Custom tools, defineTool with Zod schemas, and built-in coding tools for @theokit/sdk.
+description: Custom tools, Tool.create with Zod schemas, and built-in coding tools for @theokit/sdk.
 paths:
   - "**/*tool*"
   - "**/*Tool*"
@@ -10,13 +10,13 @@ paths:
 
 Quick reference for custom inline tools and built-in coding tools.
 
-## defineTool (type-safe builder)
+## Tool.create (type-safe builder)
 
 ```typescript
 import { z } from "zod";
-import { defineTool } from "@theokit/sdk";
+import { Tool } from "@theokit/sdk";
 
-const rollTool = defineTool({
+const rollTool = Tool.create({
   name: "roll",
   description: "Roll N dice with S sides each.",
   inputSchema: z.object({
@@ -84,22 +84,22 @@ await agent.send("Use only the calculator.", {
 // tools: []        -> no custom tools for this run
 ```
 
-## Built-in coding tools (`@theokit/sdk/tools`)
+## Built-in coding tools (`@theokit/sdk-tools`)
 
-Drop-in toolkit for coding agents. All tools are project-scoped and refuse sensitive files.
+Drop-in toolkit for coding agents, shipped as the separate `@theokit/sdk-tools` package (not a `@theokit/sdk/tools` subpath). All tools are project-scoped and refuse sensitive files.
 
 ```typescript
-import { createAgentFactory } from "@theokit/sdk";
+import { AgentFactory } from "@theokit/sdk";
 import {
   createReadFileTool,
   createListDirTool,
   createSearchTextTool,
   createGitDiffTool,
   createRunVitestTool,
-} from "@theokit/sdk/tools";
+} from "@theokit/sdk-tools";
 
 const projectRoot = process.cwd();
-const factory = createAgentFactory({
+const factory = AgentFactory.create({
   apiKey: process.env.ANTHROPIC_API_KEY!,
   model: { id: "claude-sonnet-4-6" },
   tools: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.2.6",
+  "version": "4.2.7",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheodev/theokit-sdk#readme",

package/claude-template/dot-claude/skills/theokit-rag/SKILL.md

@@ -1,226 +0,0 @@
----
-user-invocable: false
-description: RAG primitives -- VectorRetriever, CohereReranker, text splitters from @theokit/sdk/rag.
-paths:
-  - "**/*retriev*"
-  - "**/*rerank*"
-  - "**/*splitter*"
-  - "**/*rag*"
----
-
-# TheoKit SDK -- RAG
-
-Quick reference for the RAG (Retrieval-Augmented Generation) sub-path at `@theokit/sdk/rag`.
-
-## Installation
-
-The RAG module ships with `@theokit/sdk` -- no additional install needed.
-
-```typescript
-import {
-  VectorRetriever,
-  CohereReranker,
-  NoopReranker,
-  splitByCharacter,
-  splitBySentence,
-  splitRecursive,
-} from "@theokit/sdk/rag";
-```
-
-## Types
-
-```typescript
-interface Document {
-  id: string;
-  text: string;
-  metadata?: Record<string, unknown>;
-}
-
-interface Chunk {
-  text: string;
-  index: number;
-  metadata?: Record<string, unknown>;
-}
-
-interface RetrievalResult {
-  text: string;
-  score: number;
-  metadata?: Record<string, unknown>;
-}
-
-interface RankedChunk {
-  text: string;
-  score: number;
-  originalIndex: number;
-  metadata?: Record<string, unknown>;
-}
-
-interface SplitOptions {
-  chunkSize: number;
-  overlap?: number;
-}
-```
-
-## Interfaces
-
-### Retriever
-
-```typescript
-interface Retriever {
-  retrieve(query: string, options?: { topK?: number }): Promise<RetrievalResult[]>;
-}
-```
-
-### Reranker
-
-```typescript
-interface Reranker {
-  rerank(query: string, chunks: RetrievalResult[]): Promise<RankedChunk[]>;
-}
-```
-
-## VectorRetriever
-
-Wraps any index that implements `search(query, topK)`.
-
-```typescript
-interface VectorIndex {
-  search(query: string, topK: number): Promise<RetrievalResult[]>;
-}
-
-interface VectorRetrieverOptions {
-  index: VectorIndex;
-  topK?: number; // default 5
-}
-```
-
-Usage:
-
-```typescript
-import { VectorRetriever } from "@theokit/sdk/rag";
-
-const retriever = new VectorRetriever({
-  index: myVectorIndex,
-  topK: 10,
-});
-
-const results = await retriever.retrieve("How does auth work?");
-// results: RetrievalResult[] sorted by relevance
-```
-
-The `VectorIndex` interface is the DI boundary. Consumers depend on the interface; implementations (e.g., backed by Memory's SQLite-vec or LanceDB index) depend on the index adapter.
-
-## CohereReranker
-
-Calls the Cohere Rerank v2 API to re-score retrieval results by relevance.
-
-```typescript
-interface CohereRerankerOptions {
-  apiKey: string;
-  model?: string; // default "rerank-v3.5"
-}
-```
-
-Usage:
-
-```typescript
-import { CohereReranker } from "@theokit/sdk/rag";
-
-const reranker = new CohereReranker({
-  apiKey: process.env.COHERE_API_KEY!,
-  model: "rerank-v3.5",
-});
-
-const ranked = await reranker.rerank("auth middleware", retrievalResults);
-// ranked: RankedChunk[] re-scored by Cohere
-```
-
-## NoopReranker
-
-Passes through results unchanged. Useful as a baseline or when reranking is not needed.
-
-```typescript
-import { NoopReranker } from "@theokit/sdk/rag";
-
-const reranker = new NoopReranker();
-const ranked = await reranker.rerank(query, results);
-// ranked === results (with originalIndex added)
-```
-
-## Text splitters
-
-Three strategies for splitting documents into chunks. All return `Chunk[]` with `text` and `index`. Empty input returns an empty array.
-
-### splitByCharacter
-
-Fixed-size character windows with optional overlap.
-
-```typescript
-import { splitByCharacter } from "@theokit/sdk/rag";
-
-const chunks = splitByCharacter(longText, { chunkSize: 500, overlap: 50 });
-```
-
-### splitBySentence
-
-Groups sentences into chunks up to `chunkSize` characters.
-
-```typescript
-import { splitBySentence } from "@theokit/sdk/rag";
-
-const chunks = splitBySentence(longText, { chunkSize: 500 });
-```
-
-Splits on sentence boundaries (`.`, `!`, `?` followed by whitespace). Sentences are never broken mid-sentence.
-
-### splitRecursive
-
-Three-level cascading split: paragraph, then sentence, then character.
-
-```typescript
-import { splitRecursive } from "@theokit/sdk/rag";
-
-const chunks = splitRecursive(longText, { chunkSize: 500, overlap: 50 });
-```
-
-Algorithm:
-1. Split by double newlines (paragraphs).
-2. Paragraphs that exceed `chunkSize` are split by sentence.
-3. Sentences that still exceed `chunkSize` are split by character.
-
-This is the recommended default for most RAG use cases.
-
-## Full RAG pipeline example
-
-```typescript
-import { VectorRetriever, CohereReranker, splitRecursive } from "@theokit/sdk/rag";
-
-// 1. Split documents
-const chunks = splitRecursive(documentText, { chunkSize: 500, overlap: 50 });
-
-// 2. Index chunks (your vector store)
-await vectorStore.upsert(chunks.map((c, i) => ({
-  id: `doc-${i}`,
-  text: c.text,
-  embedding: await embed(c.text),
-})));
-
-// 3. Retrieve
-const retriever = new VectorRetriever({ index: vectorStore, topK: 20 });
-const results = await retriever.retrieve(userQuery);
-
-// 4. Rerank
-const reranker = new CohereReranker({ apiKey: process.env.COHERE_API_KEY! });
-const ranked = await reranker.rerank(userQuery, results);
-
-// 5. Use top results as agent context
-const context = ranked.slice(0, 5).map((r) => r.text).join("\n\n");
-const agent = await Agent.create({
-  systemPrompt: `Use this context:\n${context}`,
-  // ...
-});
-```
-
-## DI integration
-
-Use `@Retriever` and `@Reranker` decorators from `@theokit/di-agent` to register RAG components in the DI container. See the theokit-di-agent skill for details.