@theokit/sdk 1.7.0 → 1.8.0

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);
+```

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

@@ -0,0 +1,218 @@
+---
+user-invocable: false
+description: Workflow orchestration -- Workflow.create, steps, branching, retry, suspend/resume.
+paths:
+  - "**/*workflow*"
+  - "**/*Workflow*"
+  - "**/*step*"
+---
+
+# TheoKit SDK -- Workflows
+
+Quick reference for declarative multi-step orchestration (v1.17+).
+
+## Workflow.create / .run
+
+```typescript
+import { Agent, Workflow, fn, agentStep } from "@theokit/sdk";
+
+const classifier = await Agent.create({ /* ... */ });
+const billingExpert = await Agent.create({ /* ... */ });
+
+const wf = Workflow.create<{ claim: string }, string>({ name: "refund-pipeline" })
+  .then(fn("validate", (input) => {
+    if (!input.claim) throw new Error("missing claim");
+    return input;
+  }))
+  .then(agentStep("classify", classifier, (i) => `Classify: ${JSON.stringify(i)}`))
+  .branch([
+    [(out) => String(out).includes("BILLING"), [agentStep("resolve", billingExpert, "Handle it")]],
+  ], { fallback: [fn("escalate", () => "escalated")] })
+  .commit();
+
+const run = await wf.run({ claim: "I was charged twice" });
+console.log(run.status, run.output);
+```
+
+## Step types
+
+### fn step (pure function)
+
+```typescript
+import { fn } from "@theokit/sdk";
+
+fn("validate", (input, ctx) => {
+  // input: previous step's output
+  // ctx: { signal, suspend(), stepId }
+  return transformedInput;
+}, {
+  inputSchema: z.object({ /* ... */ }),   // optional Zod validation
+  outputSchema: z.object({ /* ... */ }),  // optional Zod validation
+  retry: {
+    maxAttempts: 3,
+    initialBackoffMs: 1000,
+    backoffCoefficient: 2.0,
+    maximumBackoffMs: 30_000,
+    nonRetryableErrors: ["ConfigurationError"],
+  },
+});
+```
+
+### agentStep (agent.send wrapper)
+
+```typescript
+import { agentStep } from "@theokit/sdk";
+
+agentStep("classify", agent, (input) => `Classify this: ${JSON.stringify(input)}`, {
+  retry: { maxAttempts: 2, initialBackoffMs: 2000 },
+});
+// Third arg is a prompt renderer: (stepInput) => string
+```
+
+## Control-flow primitives
+
+### .then (sequential)
+
+```typescript
+wf.then(fn("a", ...)).then(fn("b", ...))
+```
+
+### .parallel (fan-out)
+
+```typescript
+wf.parallel([
+  [fn("branch-a", ...)],
+  [fn("branch-b", ...)],
+], {
+  concurrency: 4,
+  errorPolicy: "fail-fast",  // or "collect"
+})
+```
+
+### .branch (first-match routing)
+
+```typescript
+wf.branch([
+  [(output) => output.category === "billing", [agentStep("billing", billingAgent, "Handle")]],
+  [(output) => output.category === "support", [agentStep("support", supportAgent, "Handle")]],
+], {
+  fallback: [fn("unknown", () => "escalated")],
+})
+```
+
+### .foreach (map over array)
+
+```typescript
+wf.foreach("source-step-id", fn("process", (item) => transform(item)), {
+  concurrency: 4,
+})
+```
+
+### .dowhile (loop)
+
+```typescript
+wf.dowhile(
+  fn("iterate", (input) => { /* ... */ return { done: false, data: input }; }),
+  (output) => !output.done,
+  { maxIterations: 100 },
+)
+```
+
+### .sleep
+
+```typescript
+wf.sleep(5000, "wait-for-api")  // abortable via signal
+```
+
+### .suspend (human-in-the-loop)
+
+```typescript
+wf.then(fn("wait_approval", async (input, ctx) => {
+  await ctx.suspend({ awaiting: "human-approval", draft: input });
+  return "sentinel";  // never reached
+}))
+```
+
+## Suspend / resume
+
+```typescript
+const first = await wf.run(undefined);
+// first.status === "suspended"
+
+// Later, after human approves:
+const resumed = await Workflow.resume({
+  runId: first.id,
+  workflow: wf,
+  payload: { approved: true, by: "manager" },
+});
+// resumed.status === "completed"
+```
+
+## Persistence
+
+| Backend | When | How |
+|---|---|---|
+| `memory` (default) | Same-process suspend/resume | `Workflow.create({ name })` |
+| `json` | Survive process restart | `Workflow.create({ name, persistence: { backend: "json", dir: ".theokit/workflows" } })` |
+
+## Retry policy
+
+```typescript
+retry: {
+  maxAttempts: 3,              // 1..20, required
+  initialBackoffMs: 1000,      // default 1000
+  backoffCoefficient: 2.0,     // default 2.0
+  maximumBackoffMs: 30_000,    // default 30s
+  nonRetryableErrors: ["ConfigurationError", "AbortError"],
+}
+```
+
+Retry sleeps are abortable via `AbortSignal`. Non-retryable errors skip the retry loop.
+
+## Cancellation
+
+```typescript
+const ctrl = new AbortController();
+const promise = wf.run(input, { signal: ctrl.signal });
+
+ctrl.abort("user cancelled");
+const run = await promise;
+// run.status === "cancelled"
+```
+
+`AbortSignal` is checked at step boundaries AND mid-backoff sleep. `ctx.signal` is passed to step functions so `fetch` / `agent.send` can be cancelled too.
+
+## WorkflowRun result
+
+```typescript
+interface WorkflowRun<O> {
+  id: string;
+  status: "completed" | "suspended" | "cancelled" | "failed";
+  output?: O;
+  error?: Error;
+  steps: WorkflowStepResult[];
+}
+```
+
+## Telemetry
+
+When OTel is installed, each `wf.run` emits a `workflow.run` root span and per-step `workflow.step.<id>` child spans with attributes: `workflow.name`, `workflow.run_id`, `step.kind`, `step.attempts`, `step.status`.
+
+## Errors
+
+| Error | Cause |
+|---|---|
+| `WorkflowDuplicateStepIdError` | Two steps with same id at `.commit()` |
+| `WorkflowAlreadyRunningError` | Concurrent `.run()` with same `(workflowId, runId)` |
+| `WorkflowSnapshotNotFoundError` | `Workflow.resume(runId)` with unknown runId |
+| `WorkflowMaxIterationsExceededError` | `.dowhile` over `maxIterations` |
+| `WorkflowNotSerializableError` | `ctx.suspend(payload)` with non-JSON value |
+| `WorkflowResumeStepNotFoundError` | Resume against a diverged workflow definition |
+| `WorkflowParallelError` | Aggregate of branch failures in fail-fast mode |
+| `WorkflowCompensateNotImplementedError` | `compensate` field set (saga deferred to v1.2) |
+
+## Limitations (v1)
+
+- **LocalAgent only** -- cloud agent steps throw `UnsupportedRunOperationError`.
+- **Saga compensation deferred** -- `compensate?` field reserved but throws if set.
+- **No cron-trigger integration** -- wire via `Cron.create` calling `wf.run` directly.