@theokit/sdk 4.2.6 → 4.2.8

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

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

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

@@ -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-task-store/SKILL.md

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

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.8",
   "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.