@theokit/sdk 4.53.1 → 4.55.0

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

@@ -1,66 +0,0 @@
----
-user-invocable: false
-description: Clean model-emitted tool arguments with sanitizeToolInput from @theokit/sdk/sanitize (total, never throws).
-paths:
-  - "**/*sanitize*"
-  - "**/*Sanitize*"
----
-
-# TheoKit SDK -- Sanitize
-
-`sanitizeToolInput` cleans the raw arguments a model emitted for a tool call: trim (default on), optionally coerce string values toward their expected type, optionally repair malformed JSON. It is pure, synchronous, and TOTAL -- it NEVER throws (non-object input is returned unchanged) and never changes a value's meaning, only its hygiene/representation.
-
-## Import
-
-```typescript
-import { sanitizeToolInput } from "@theokit/sdk/sanitize";
-import type { SanitizeOptions, SanitizeResult } from "@theokit/sdk/sanitize";
-```
-
-## Signature
-
-```typescript
-function sanitizeToolInput(
-  input: Record<string, unknown>,
-  options?: SanitizeOptions,
-): SanitizeResult;
-
-interface SanitizeOptions {
-  trim?: boolean;        // trim whitespace on string values. Default true
-  coerce?: boolean;      // "5"->5, "true"->true, "null"->null, JSON. Default false
-  repairJson?: boolean;  // repair-then-parse malformed JSON strings (jsonrepair). Default false
-  schema?: ZodType;      // when a z.object(...), coercion is schema-aware per top-level field
-  deep?: boolean;        // recurse into nested objects/arrays. Default false (shallow)
-  maxDepth?: number;     // max recursion depth when deep. Default 8
-}
-
-interface SanitizeResult<T = Record<string, unknown>> {
-  value: T;          // the sanitized copy
-  changed: boolean;  // true when any value was altered
-  notes: string[];   // one human-readable line per change (for logging)
-}
-```
-
-## Trim only (default)
-
-```typescript
-const { value, changed, notes } = sanitizeToolInput({ query: "  hello  " });
-// value -> { query: "hello" }, changed -> true, notes -> ["query: trimmed whitespace"]
-```
-
-## Schema-aware coercion inside a tool handler
-
-Pass the tool's Zod object schema so a `z.string()` field keeps `"5"` as a string while a `z.number()` field coerces it. Never throws, so it is safe to run before `schema.parse`.
-
-```typescript
-import { z } from "zod";
-
-const inputSchema = z.object({ count: z.number(), label: z.string() });
-
-const { value } = sanitizeToolInput(
-  { count: "5", label: "42" },
-  { coerce: true, schema: inputSchema },
-);
-// value -> { count: 5, label: "42" }  (label stays a string; count coerced)
-const parsed = inputSchema.parse(value);
-```

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

@@ -1,68 +0,0 @@
----
-user-invocable: false
-description: Discover SKILL.md packs and render the <skills> block with @theokit/sdk/skills, plus enabling skills on an agent.
-paths:
-  - "**/*skill*"
-  - "**/*Skill*"
----
-
-# TheoKit SDK -- Skills
-
-`discoverSkills` walks a directory for `<dir>/<name>/SKILL.md` packs, parses strict YAML frontmatter (`name`/`description` required; `category`/`dependencies` optional), skips malformed skills and symlink escapes, and NEVER throws (a missing/unreadable/non-directory path yields `[]`). `buildSkillsBlock` renders the prompt-injection-safe `<skills>` system-prompt block from the discovered list. These are the same primitives the SDK runtime uses internally for `.theokit/skills` discovery.
-
-## Import
-
-```typescript
-import { discoverSkills, buildSkillsBlock } from "@theokit/sdk/skills";
-import type { Skill, DiscoverSkillsOptions, InvalidSkillInfo } from "@theokit/sdk/skills";
-```
-
-## Signatures
-
-```typescript
-function discoverSkills(dir: string, options?: DiscoverSkillsOptions): Promise<Skill[]>;
-function buildSkillsBlock(
-  skills: ReadonlyArray<{ name: string; description: string }>,
-): string | undefined; // undefined for an empty list
-
-interface Skill {
-  name: string;
-  description: string;
-  source: string;         // absolute path to the discovered SKILL.md
-  category?: string;
-  dependencies?: string[];
-}
-
-interface DiscoverSkillsOptions {
-  onInvalidSkill?: (info: InvalidSkillInfo) => void; // called per malformed SKILL.md
-}
-```
-
-## Discover and render
-
-```typescript
-const skills = await discoverSkills(".theokit/skills", {
-  onInvalidSkill: (info: InvalidSkillInfo) =>
-    console.warn(`skipped ${info.name}: ${info.code} — ${info.message}`),
-});
-
-// readdir order is OS-dependent; sort for a stable block
-skills.sort((a, b) => a.name.localeCompare(b.name));
-
-const block = buildSkillsBlock(skills); // string | undefined
-```
-
-## Skill packs live at `.theokit/skills/<name>/SKILL.md`
-
-Each pack is a directory with a `SKILL.md` whose frontmatter has `name` + `description`. Enable specific packs on an agent by name:
-
-```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() },
-  skills: { enabled: ["research", "code-review"] },
-});
-```

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

@@ -1,156 +0,0 @@
----
-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-subagents/SKILL.md

@@ -1,109 +0,0 @@
----
-user-invocable: false
-paths:
-  - "**/*subagent*"
-  - "**/*a2a*"
-  - "**/*delegat*"
-description: TheoKit SDK subagents — @theokit/sdk/a2a (SubAgent.create, AgentMailbox, MessageBus, delegation hooks) and @theokit/sdk/subagents (subagentToolWhitelist, withSubagentToolScope)
----
-
-# TheoKit SubAgents
-
-Two subpaths cover delegation. `@theokit/sdk/a2a` builds a child agent invocable as
-a tool plus the in-process message bus; `@theokit/sdk/subagents` scopes which tools a
-subagent may call.
-
-```typescript
-import {
-  SubAgent,
-  AgentMailbox,
-  MessageBus,
-  MaxDelegationDepthError,
-  type SubAgentSpec,
-} from "@theokit/sdk/a2a";
-import { subagentToolWhitelist, withSubagentToolScope } from "@theokit/sdk/subagents";
-```
-
-## `SubAgent.create` — delegation as a tool
-
-`SubAgent.create(spec, parentDepth?)` returns a `CustomTool`. When the LLM invokes it,
-a child agent runs the input as a message. Depth is tracked — exceeding
-`maxDelegationDepth` throws `MaxDelegationDepthError`.
-
-```typescript
-const researcher = SubAgent.create({
-  name: "researcher",
-  description: "Delegate research questions to a focused child agent",
-  instructions: "You research topics and return a concise summary.",
-  model: "google/gemini-2.0-flash-001",
-  tools: [],                 // CustomTool[] the child may use
-  maxDelegationDepth: 3,
-  onDelegationStart: (ctx) => {
-    if (ctx.iteration > 5) return { proceed: false, rejectionReason: "too many calls" };
-    return { proceed: true };
-  },
-  onDelegationComplete: (ctx) => {
-    if (ctx.result) return { feedback: "(reviewed)" };
-  },
-});
-
-const agent = await Agent.create({
-  apiKey: process.env.THEOKIT_API_KEY!,
-  model: { id: "google/gemini-2.0-flash-001" },
-  local: { cwd: process.cwd() },
-  tools: [researcher],
-});
-```
-
-`SubAgentSpec` also supports `messageFilter` (opt-in parent-context forwarding, off by
-default so memory isolation stays the default) and `includeToolResults` (append the
-child's tool results, otherwise text-only).
-
-## Inline subagents on `Agent.create`
-
-Simple cases need no `SubAgent.create` — declare them inline:
-
-```typescript
-const agent = await Agent.create({
-  apiKey: process.env.THEOKIT_API_KEY!,
-  model: { id: "google/gemini-2.0-flash-001" },
-  local: { cwd: process.cwd() },
-  agents: {
-    reviewer: {
-      description: "Reviews code for bugs",
-      prompt: "You are a strict code reviewer.",
-      model: "google/gemini-2.0-flash-001",
-    },
-  },
-});
-```
-
-## Tool scoping — `withSubagentToolScope`
-
-`subagentToolWhitelist(definition)` derives the allowed tool-name `Set` (or `undefined`
-when unscoped) from `definition.tools`. `withSubagentToolScope` runs a fn under that
-whitelist so a `tools: ["read_file"]` subagent provably cannot call `write_file`.
-
-```typescript
-const whitelist = subagentToolWhitelist({ tools: ["read_file"] }); // Set(["read_file"])
-
-await withSubagentToolScope({ tools: ["read_file"] }, async () => {
-  // dispatch veto enforces the whitelist here
-});
-```
-
-## Agent-to-agent messaging
-
-```typescript
-const bus = new MessageBus();
-const alice = new AgentMailbox("alice", bus);
-const bob = new AgentMailbox("bob", bus);
-
-bob.onMessage(async (msg) => ({ type: "ack", payload: { ok: true } }));
-
-await alice.send("bob", { type: "greet", payload: { text: "hi" } });
-const reply = await alice.request("bob", { type: "ping", payload: null }, { timeoutMs: 1000 });
-
-alice.dispose();
-bob.dispose();
-```

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

@@ -1,148 +0,0 @@
----
-user-invocable: false
-paths:
-  - "**/*subscri*"
-  - "**/*sse*"
-  - "**/*websocket*"
-  - "**/*ws.*"
-description: TheoKit SDK Subscriptions API — Subscription.create, 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 — `Subscription.create`
-
-```typescript
-import { Subscription } from "@theokit/sdk/subscription";
-import { z } from "zod";
-
-export default Subscription.create({
-  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 `Subscription.create` are independent surfaces. Call
-`Agent.streamObject` inside a subscription handler:
-
-```typescript
-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) {
-    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-task-store/SKILL.md

@@ -1,75 +0,0 @@
----
-user-invocable: false
-paths:
-  - "**/*task-store*"
-  - "**/*taskstore*"
-  - "**/*TaskStore*"
-description: TheoKit SDK task persistence — @theokit/sdk/task-store (TaskStore interface, InMemoryTaskStore, JsonFileTaskStore, getTaskStoreFor factory)
----
-
-# TheoKit Task Store
-
-`@theokit/sdk/task-store` is the storage layer behind the task registry. Pick
-`InMemoryTaskStore` (transient, single-process default) or `JsonFileTaskStore` (one JSON
-file per task under a dir; single-process invariant — v0.2 SQLite covers cross-process).
-
-```typescript
-import {
-  getTaskStoreFor,
-  InMemoryTaskStore,
-  JsonFileTaskStore,
-  type TaskStore,
-} from "@theokit/sdk/task-store";
-```
-
-## The `TaskStore` interface
-
-All methods are async. `TaskHandle` / `TaskFilter` come from the main `@theokit/sdk`
-barrel.
-
-```typescript
-interface TaskStore {
-  insert(handle: TaskHandle): Promise<void>;
-  update(id: string, mutate: (h: TaskHandle) => TaskHandle): Promise<TaskHandle | undefined>;
-  get(id: string): Promise<TaskHandle | undefined>;
-  list(filter: TaskFilter): Promise<TaskHandle[]>;
-  delete(id: string): Promise<boolean>;
-  evictTerminalOlderThan(epochMs: number): Promise<number>;
-}
-```
-
-## Factory — `getTaskStoreFor`
-
-Discriminated on `backend`; the `json` backend auto-creates its dir (mkdir recursive).
-
-```typescript
-const memory: TaskStore = getTaskStoreFor({ backend: "memory" });
-const onDisk: TaskStore = getTaskStoreFor({ backend: "json", dir: ".theokit/tasks" });
-```
-
-Or construct directly:
-
-```typescript
-const store = new JsonFileTaskStore(".theokit/tasks"); // constructor(dir: string)
-```
-
-## Reading tasks
-
-`list` returns at most `filter.limit ?? 100` handles; `JsonFileTaskStore` hard-caps
-loaded entries at 256 — page larger timelines via `submittedBefore`.
-
-```typescript
-import type { TaskFilter } from "@theokit/sdk";
-
-const filter: TaskFilter = { state: ["running", "queued"], kind: "run", limit: 50 };
-const running = await store.list(filter);
-
-for (const h of running) {
-  console.log(h.id, h.state, h.submittedAt);
-  if (h.cancelRequested) console.log("  (cross-process cancel requested)");
-}
-```
-
-`cancelRequested` is set by the CLI's cross-process best-effort cancel (EC-7); the owning
-process polls it at checkpoints. `evictTerminalOlderThan(epochMs)` removes terminal
-handles older than a cutoff and returns the count removed.