@theokit/sdk 1.6.2 → 1.8.0

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

@@ -0,0 +1,226 @@
+---
+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.

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

@@ -0,0 +1,156 @@
+---
+user-invocable: false
+paths:
+  - "**/*stream*"
+  - "**/*Stream*"
+  - "**/*SDKMessage*"
+description: TheoKit SDK streaming reference — Run.stream(), SDKMessage union, streamObject, generateObject
+---
+
+# TheoKit Streaming
+
+## `Run.stream()` — SDKMessage events
+
+```typescript
+const run = await agent.send("Find the bug in src/auth.ts");
+for await (const event of run.stream()) {
+  switch (event.type) {
+    case "assistant":
+      for (const block of event.message.content) {
+        if (block.type === "text") process.stdout.write(block.text);
+      }
+      break;
+    case "thinking":
+      process.stdout.write(event.text);
+      break;
+    case "tool_call":
+      console.log(`[tool] ${event.name}: ${event.status}`);
+      break;
+    case "status":
+      console.log(`[status] ${event.status}`);
+      break;
+  }
+}
+```
+
+## SDKMessage discriminated union
+
+```typescript
+type SDKMessage =
+  | SDKSystemMessage        // "system" — init metadata, emitted once
+  | SDKUserMessageEvent     // "user"   — echo of user prompt
+  | SDKAssistantMessage     // "assistant" — model text output
+  | SDKThinkingMessage      // "thinking"  — reasoning content
+  | SDKToolUseMessage       // "tool_call" — tool invocation lifecycle
+  | SDKStatusMessage        // "status" — cloud run transitions
+  | SDKTaskMessage          // "task"   — task milestones/summaries
+  | SDKRequestMessage;      // "request" — awaiting user input
+```
+
+All events include `agent_id` and `run_id`.
+
+### Key message types
+
+| Type | Key fields |
+|---|---|
+| `"system"` | `subtype?: "init"`, `model?`, `tools?` |
+| `"assistant"` | `message.content: (TextBlock \| ToolUseBlock)[]` |
+| `"thinking"` | `text`, `thinking_duration_ms?` |
+| `"tool_call"` | `call_id`, `name`, `status`, `args?`, `result?`, `truncated?` |
+| `"status"` | `status: "CREATING" \| "RUNNING" \| "FINISHED" \| ...` |
+
+`tool_call` is emitted twice: once with `status: "running"` + `args`, then
+again on completion with `status: "completed"` or `"error"` + `result`.
+
+## Raw deltas — `onDelta` callback
+
+For per-token streaming, pass `onDelta` to `agent.send()`:
+
+```typescript
+const run = await agent.send("Refactor the utils module", {
+  onDelta: ({ update }) => {
+    if (update.type === "text-delta") process.stdout.write(update.text);
+    if (update.type === "thinking-delta") process.stdout.write(update.text);
+  },
+  onStep: ({ step }) => {
+    console.log(`[step] ${step.type}`);
+  },
+});
+```
+
+### InteractionUpdate types
+
+`text-delta`, `thinking-delta`, `thinking-completed`, `tool-call-started`,
+`tool-call-completed`, `partial-tool-call`, `token-delta`, `step-started`,
+`step-completed`, `turn-ended`, `summary`, `shell-output-delta`.
+
+`turn-ended` includes token usage:
+```typescript
+{ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens }
+```
+
+## `Agent.generateObject()` — structured output
+
+```typescript
+import { z } from "zod";
+import { Agent } from "@theokit/sdk";
+
+const { object, raw, usage, finishReason } = await Agent.generateObject({
+  schema: z.object({
+    title: z.string().min(1),
+    summary: z.string(),
+    year: z.number().nullable(),
+  }),
+  prompt: "Produce a fact card about: Brazilian samba.",
+  model: { id: "google/gemini-2.0-flash-001" },
+  local: { cwd: process.cwd(), sandboxOptions: { enabled: false } },
+  apiKey: process.env.THEOKIT_API_KEY,
+  maxRetries: 1,
+});
+// object is fully typed: z.infer<typeof schema>
+```
+
+Throws `GenerateObjectError` with `code: "no_tool_call" | "parse_failed"`.
+
+## `Agent.streamObject()` — streaming structured output (v1.2+)
+
+```typescript
+for await (const evt of Agent.streamObject({
+  schema: FactCard,
+  prompt: "Produce a fact card about: jazz music.",
+  model: { id: "google/gemini-2.0-flash-001" },
+  apiKey: process.env.THEOKIT_API_KEY,
+  local: { cwd: process.cwd() },
+})) {
+  if (evt.type === "partial") render(evt.partial);
+  if (evt.type === "complete") finalize(evt.object);
+}
+```
+
+### StreamObjectEvent
+
+```typescript
+type StreamObjectEvent<T> =
+  | { type: "partial"; partial: DeepPartial<T>; attempt: number }
+  | { type: "complete"; object: T; raw: unknown; usage; finishReason };
+```
+
+The `complete` event always fires (or the iterator throws `StreamObjectError`).
+Partials are best-effort.
+
+## Waiting without streaming
+
+```typescript
+const result = await run.wait();
+console.log(result.status);     // "finished" | "error" | "cancelled"
+console.log(result.result);     // final assistant text
+console.log(result.durationMs);
+console.log(result.git);        // cloud: { branches: [{ repoUrl, branch?, prUrl? }] }
+```
+
+## Cancelling
+
+```typescript
+await run.cancel();
+// status moves to "cancelled", partial output preserved
+```

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

@@ -0,0 +1,148 @@
+---
+user-invocable: false
+paths:
+  - "**/*subscri*"
+  - "**/*sse*"
+  - "**/*websocket*"
+  - "**/*ws.*"
+description: TheoKit SDK Subscriptions API — defineSubscription, SSE/WebSocket transport, subscribe, tracked, resume tokens
+---
+
+# TheoKit Subscriptions
+
+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`
+
+```typescript
+import { defineSubscription } from "@theokit/sdk/subscription";
+import { z } from "zod";
+
+export default defineSubscription({
+  input: z.object({
+    room: z.string(),
+    lastEventId: z.string().optional(),
+  }),
+  output: z.object({
+    id: z.string(),
+    text: z.string(),
+    sender: z.string(),
+    ts: z.number(),
+  }),
+  async *handler(input, ctx) {
+    let cursor = input.lastEventId ?? "0";
+    while (!ctx.signal.aborted) {
+      const msgs = await fetchNewMessages(input.room, cursor);
+      for (const m of msgs) {
+        cursor = m.id;
+        yield ctx.tracked(m.id, {
+          id: m.id,
+          text: m.text,
+          sender: m.sender,
+          ts: m.ts,
+        });
+      }
+      await sleep(1000);
+    }
+  },
+});
+```
+
+### `ctx.tracked(id, payload)`
+
+Advertises a resume token alongside the payload. The client receives the token
+and echoes it back on reconnect via `lastEventId`. The token is **opaque to
+the SDK** — the server handler decides its semantics:
+
+- Monotonic int: `"42"` — resume after event 42
+- ULID: `"01H9X..."` — resume after that ULID
+- Encrypted cursor: consumer decrypts + decodes
+- Timestamp: `"2026-06-04T15:00:00Z"` — resume after that moment
+
+## Client side — `subscribe`
+
+```typescript
+import { subscribe } from "@theokit/sdk/subscription";
+
+for await (const msg of subscribe<
+  { room: string },
+  { id: string; text: string; sender: string; ts: number }
+>(
+  "chat",
+  { room: "lobby" },
+  {
+    baseUrl: "http://localhost:3000",
+    transport: "auto",             // 'ws' | 'sse' | 'auto' (default)
+    maxReconnectAttempts: 10,      // 0 disables reconnect
+  },
+)) {
+  console.log(`[${msg.sender}] ${msg.text}`);
+}
+```
+
+## Transport selection
+
+| Mode | When to use |
+|---|---|
+| `'auto'` (default) | Prefer WS, fall back to SSE — works everywhere |
+| `'ws'` | Strict bidirectional — error if WS unavailable |
+| `'sse'` | Browser-native EventSource, no upgrade required |
+
+## Composing with LLM streaming
+
+`Agent.streamObject` and `defineSubscription` are independent surfaces. Call
+`Agent.streamObject` inside a subscription handler:
+
+```typescript
+export default defineSubscription({
+  input: z.object({ topic: z.string() }),
+  output: z.object({ kind: z.enum(["partial", "complete"]), text: z.string() }),
+  async *handler(input, ctx) {
+    let counter = 0;
+    const iter = Agent.streamObject({
+      schema: z.object({ text: z.string() }),
+      prompt: `Write a haiku about ${input.topic}`,
+      model: { id: "openrouter/openai/gpt-4o-mini" },
+      apiKey: process.env.OPENROUTER_API_KEY,
+      local: { settingSources: [] },
+    });
+    for await (const evt of iter) {
+      if (evt.type === "partial") {
+        yield ctx.tracked(String(++counter), {
+          kind: "partial",
+          text: JSON.stringify(evt.partial),
+        });
+      } else if (evt.type === "complete") {
+        yield ctx.tracked(String(++counter), {
+          kind: "complete",
+          text: evt.object.text,
+        });
+      }
+    }
+  },
+});
+```
+
+## Multi-runtime support
+
+| Runtime | v1.7.0 | v1.8.x (planned) |
+|---|---|---|
+| Node 22+ | Yes (`ws` optional peer) | Yes |
+| Cloudflare Workers | Consumer-supplied `WsAdapter` only | `@theokit/sdk-ws-cloudflare` |
+| Bun | Consumer-supplied `WsAdapter` only | `@theokit/sdk-ws-bun` |
+| Deno | Consumer-supplied `WsAdapter` only | `@theokit/sdk-ws-deno` |
+
+## Security checklist
+
+1. Authenticate WS upgrade via the request object — auth runs BEFORE upgrade
+2. Validate input via Zod schema (done by SDK automatically)
+3. Bind resume tokens to session when token leakage allows replay
+4. Force-close on session revocation via `ctx.disconnect(code, reason)`
+5. Never log payloads — telemetry captures `{subscriptionName, lastEventId}` only
+
+## Why sub-path import?
+
+`@theokit/sdk/subscription` is a dedicated entry point to isolate the
+subscription module from the main `index.ts` DTS bundle. Once the internal
+rollup-dts cycle is resolved, `Theokit.subscribe` can be promoted additively.

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

@@ -0,0 +1,170 @@
+---
+user-invocable: false
+description: Custom tools, defineTool with Zod schemas, and built-in coding tools for @theokit/sdk.
+paths:
+  - "**/*tool*"
+  - "**/*Tool*"
+---
+
+# TheoKit SDK -- Tools
+
+Quick reference for custom inline tools and built-in coding tools.
+
+## defineTool (type-safe builder)
+
+```typescript
+import { z } from "zod";
+import { defineTool } from "@theokit/sdk";
+
+const rollTool = defineTool({
+  name: "roll",
+  description: "Roll N dice with S sides each.",
+  inputSchema: z.object({
+    count: z.number().int().min(1).max(100),
+    sides: z.number().int().min(2).max(1000),
+  }),
+  handler: ({ count, sides }) => {
+    const rolls = Array.from({ length: count }, () => 1 + Math.floor(Math.random() * sides));
+    return JSON.stringify({ rolls, total: rolls.reduce((a, b) => a + b, 0) });
+  },
+});
+```
+
+Requires `zod` as a peer dependency. Converts Zod schema to JSON Schema for the LLM. Runtime `schema.parse` validates input before the handler runs. Invalid input becomes `tool_result(isError)` with a Zod message.
+
+### DefineToolSpec
+
+```typescript
+interface DefineToolSpec<T extends ZodType> {
+  name: string;
+  description: string;
+  inputSchema: T;
+  handler: (input: z.infer<T>) => string | Promise<string>;
+}
+```
+
+## CustomTool (raw interface)
+
+```typescript
+interface CustomTool {
+  name: string;          // /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/
+  description: string;
+  inputSchema: Record<string, unknown>; // JSON Schema, type: "object"
+  handler: (input: Record<string, unknown>) => string | Promise<string>;
+}
+```
+
+### Reserved names (rejected at create time)
+
+`shell`, `memory_search`, `memory_get`, anything prefixed with `mcp_`.
+
+### Constraints
+
+- **Local runtime only.** Cloud agents throw `ConfigurationError(code: "cloud_custom_tools_rejected")` when `tools.length > 0`.
+- **Not persisted.** Handlers are in-memory closures. Re-pass tools on `Agent.resume`.
+
+## Registering tools with agents
+
+```typescript
+const agent = await Agent.create({
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "google/gemini-2.0-flash-001" },
+  local: { cwd: process.cwd() },
+  tools: [rollTool, lookupTool],
+});
+```
+
+### Per-send tool override
+
+```typescript
+await agent.send("Use only the calculator.", {
+  tools: [calculatorTool], // fully replaces agent-level tools for this run
+});
+// tools: undefined -> fall back to agent tools
+// tools: []        -> no custom tools for this run
+```
+
+## Built-in coding tools (`@theokit/sdk/tools`)
+
+Drop-in toolkit for coding agents. All tools are project-scoped and refuse sensitive files.
+
+```typescript
+import { createAgentFactory } from "@theokit/sdk";
+import {
+  createReadFileTool,
+  createListDirTool,
+  createSearchTextTool,
+  createGitDiffTool,
+  createRunVitestTool,
+} from "@theokit/sdk/tools";
+
+const projectRoot = process.cwd();
+const factory = createAgentFactory({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: { id: "claude-sonnet-4-6" },
+  tools: [
+    createReadFileTool({ projectRoot }),
+    createListDirTool({ projectRoot }),
+    createSearchTextTool({ projectRoot, maxMatches: 100 }),
+    createGitDiffTool({ projectRoot, timeoutMs: 30_000 }),
+    createRunVitestTool({ projectRoot, timeoutMs: 120_000 }),
+  ],
+});
+```
+
+### Tool reference
+
+| Tool | Returns on success | Error codes |
+|---|---|---|
+| `read_file` | `{ ok, content, size }` | `path_traversal`, `forbidden_path`, `binary_file`, `not_found`, `too_large` |
+| `list_dir` | `{ ok, entries: [{ name, type }], truncated, totalCount }` | `path_traversal`, `forbidden_path` |
+| `search_text` | `{ ok, matches: [{ file, line, preview }], truncated }` | `path_traversal`, `forbidden_path` |
+| `git_diff` | `{ ok, diff, truncated }` | `not_a_repo`, `timeout`, `git_failed`, `path_traversal` |
+| `run_vitest` | `{ ok, summary: { numTotalTests, numPassedTests, numFailedTests, success } }` | `no_vitest`, `timeout`, `unparseable_output`, `path_traversal` |
+
+### Safety rules (shared across all 5 tools)
+
+1. Every I/O call passes through `safePathJoin` + `assertNoSymlinkEscape`.
+2. Sensitive files refused: `.env*` (except `.env.example`), `.git/`, `node_modules/`, `.theo/`, lock files.
+3. Handlers return JSON strings; never throw on user mistakes.
+
+### Hardening
+
+- `read_file`: rejects binary files via null-byte detection in first 8 KB. Caps at 5 MB.
+- `list_dir`: caps at 500 entries by default (override via `max`).
+- `search_text`: skips binary files and files > 1 MB.
+- `git_diff` / `run_vitest`: spawn detached process groups; on timeout kill the whole group.
+
+## Tool lifecycle hooks
+
+```typescript
+const agent = await Agent.create({
+  apiKey, model,
+  onToolStart: ({ toolName, callId, args, conversationId }) => { /* ... */ },
+  onToolEnd: ({ toolName, callId, durationMs, result }) => { /* ... */ },
+  onToolError: ({ toolName, callId, error, durationMs, attempt }) => { /* ... */ },
+});
+```
+
+- `callId` correlates start/end pairs.
+- Hook errors are swallowed -- listener bugs do NOT crash the agent run.
+
+## Tool stream events
+
+Tool calls emit `SDKToolUseMessage` (type `"tool_call"`) twice: once with `status: "running"` and `args`, then with `status: "completed"` (or `"error"`) and `result`. The `args` and `result` payloads are unstable -- parse defensively.
+
+## Path safety utilities (`@theokit/sdk/path-safety`)
+
+```typescript
+import {
+  safePathJoin,
+  assertNoSymlinkEscape,
+  isForbiddenPath,
+  PathTraversalError,
+  ForbiddenPathError,
+} from "@theokit/sdk/path-safety";
+
+const safe = safePathJoin(projectRoot, userPath);
+assertNoSymlinkEscape(safe, projectRoot);
+if (isForbiddenPath(userPath)) throw new ForbiddenPathError(userPath);
+```