@theokit/sdk 4.2.7 → 4.2.8

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 4.2.8
+
+### Patch Changes
+
+- feat(init-claude): the scaffolded `.claude/` template now covers **every public `@theokit/sdk` subpath**. Added 16 per-module skills — models, subagents (`/a2a` + tool-scope), retry, task-store, sandbox, compaction, messages, auth (`/server/auth` + errors-envelope), sanitize, skills, path-safety, concurrency, persistence, client, filesystem, project — each authored against the shipped type declarations (verified signatures: `Retry.create` executor, `Semaphore.create`, `SubAgent.create`, `Auth.create`, `sanitizeToolInput`, …). The `claude-template-no-drift` gate covers the expanded set.
+
 ## 4.2.7
 
 ### Patch Changes

package/claude-template/CLAUDE.md

@@ -24,6 +24,22 @@ These skills inject TheoKit knowledge automatically when you edit files matching
 | `theokit-config` | `.theokit/**`, `config.*`, `theo.config.*` |
 | `theokit-streaming` | `*stream*`, `*Stream*`, `*SDKMessage*` |
 | `theokit-budget` | `*budget*`, `*Budget*`, `*cost*`, `*token*` |
+| `theokit-models` | `*model*`, `*Model*` |
+| `theokit-subagents` | `*subagent*`, `*a2a*`, `*delegat*` |
+| `theokit-retry` | `*retry*`, `*Retry*` |
+| `theokit-task-store` | `*task-store*`, `*taskstore*`, `*TaskStore*` |
+| `theokit-sandbox` | `*sandbox*`, `*Sandbox*` |
+| `theokit-compaction` | `*compact*`, `*Compact*` |
+| `theokit-messages` | `*message*`, `*Message*` |
+| `theokit-auth` | `*auth*`, `*Auth*`, `*envelope*` |
+| `theokit-sanitize` | `*sanitize*`, `*Sanitize*` |
+| `theokit-skills` | `*skill*`, `*Skill*` |
+| `theokit-path-safety` | `*path-safety*`, `*pathsafety*` |
+| `theokit-concurrency` | `*concurren*`, `*semaphore*`, `*Semaphore*` |
+| `theokit-persistence` | `*persist*`, `*Persist*` |
+| `theokit-client` | `*client*`, `*Client*` |
+| `theokit-filesystem` | `*filesystem*`, `*Filesystem*` |
+| `theokit-project` | `*project*`, `*Project*` |
 
 ### Settings
 

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

@@ -0,0 +1,102 @@
+---
+user-invocable: false
+paths:
+  - "**/*auth*"
+  - "**/*Auth*"
+  - "**/*envelope*"
+description: TheoKit SDK server auth — Auth.create orchestrator, validateReturnTo, and the cross-layer error envelope
+---
+
+# TheoKit Server Auth
+
+Server-side auth orchestrator and the cross-layer error envelope. These live
+under the `@theokit/sdk/server/*` sub-paths (not the main barrel). Concrete
+OAuth/email providers ship in opt-in `@theokit/auth-*` packages — the SDK only
+defines the orchestrator contract.
+
+## `Auth.create` — session + provider orchestrator
+
+```typescript
+import {
+  Auth,
+  validateReturnTo,
+  AuthConfigError,
+  AuthProviderNotFoundError,
+  AuthCallbackError,
+  AuthCancelledError,
+  AuthSecretTooShortError,
+} from "@theokit/sdk/server/auth";
+import type {
+  AuthProvider,
+  SessionManager,
+  AuthOrchestrator,
+} from "@theokit/sdk/server/auth";
+```
+
+`Auth.create(opts)` returns an `AuthOrchestrator<TSession>` with 5 methods.
+`providers` is optional — an empty list is the manual-`signIn`-only escape hatch.
+
+```typescript
+const auth: AuthOrchestrator<Session> = Auth.create<Session>({
+  session,                 // your SessionManager<Session> implementation
+  providers: [githubProvider], // AuthProvider<Profile>[] from a @theokit/auth-* package
+  onSignIn: async ({ profile, provider }) => {
+    return toSession(profile, provider); // returns the TSession to persist
+  },
+  onSignOut: async (session) => {
+    /* revoke, audit, etc. */
+  },
+});
+
+// OAuth flow (node:http req/res):
+const redirect = await auth.startSignIn("github", req, { returnTo: "/dashboard" });
+const { session, returnTo } = await auth.finishSignIn("github", req, res); // rotates session id (OWASP A07)
+const current = await auth.getSession(req);
+await auth.signOut(res);
+
+// Escape hatch — persist a session directly, skipping the OAuth flow:
+const s = await auth.signIn(externalProfile, "github", req, res);
+```
+
+## `validateReturnTo` — open-redirect guard (OWASP A01)
+
+Returns a safe same-origin path. Cross-origin, protocol-relative (`//evil.com`),
+empty, and defensive cases all collapse to `"/"`.
+
+```typescript
+const safe = validateReturnTo(returnTo, new URL("https://app.example.com"));
+// "/dashboard" -> kept; "https://evil.com" -> "/"; undefined -> "/"
+```
+
+Typed errors: `AuthConfigError`, `AuthProviderNotFoundError`, `AuthCallbackError`,
+`AuthCancelledError`, `AuthSecretTooShortError`.
+
+## Error envelope — cross-layer boundary translation
+
+```typescript
+import {
+  toEnvelope,
+  fromEnvelope,
+  MemoryAdapterError,
+} from "@theokit/sdk/server/errors-envelope";
+import type {
+  TheokitErrorEnvelope,
+  TheokitErrorCode,
+} from "@theokit/sdk/server/errors-envelope";
+```
+
+`toEnvelope` translates any SDK error (or arbitrary thrown value) into the wire
+envelope at egress; `fromEnvelope` reconstructs SDK class identity at ingress so
+`instanceof` checks keep working across an IPC/serialization boundary.
+
+```typescript
+try {
+  await agent.send(prompt);
+} catch (err) {
+  const envelope: TheokitErrorEnvelope = toEnvelope(err); // { code, message, meta?, ext? }
+  send(envelope); // code is a TheokitErrorCode, e.g. "RATE_LIMITED"
+}
+
+// Inbound edge (e.g. worker receiving the envelope):
+const restored = fromEnvelope(envelope); // a TheokitAgentError subclass
+```

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

@@ -0,0 +1,58 @@
+---
+user-invocable: false
+paths:
+  - "**/*client*"
+  - "**/*Client*"
+description: TheoKit SDK low-level HTTP client — TheoKitClient (DEPRECATED; prefer the Agent façade)
+---
+
+# TheoKit Client
+
+`TheoKitClient` is a browser-safe, zero-Node-dependency HTTP client (native
+`fetch` + manual SSE parsing) for a legacy server-adapter contract.
+
+> DEPRECATED since 2.x — the `@theokit/sdk/client` sub-path consumes a legacy
+> server-adapter HTTP contract (`POST /agent/send`, `GET /agent/stream`) that the
+> ecosystem no longer produces, and will be removed in the next major. For
+> in-process runs use the `Agent` façade (`@theokit/sdk`); for HTTP, use the
+> framework's typed `POST /api/agents/<name>` client. Reach for this only when
+> maintaining an existing integration against the old contract.
+
+```ts
+import { TheoKitClient } from "@theokit/sdk/client";
+import type { ClientOptions, SendResponse, StreamEvent } from "@theokit/sdk/client";
+```
+
+## Construct
+
+The constructor takes `ClientOptions` — `baseUrl` (required), optional `basePath`
+and `headers`.
+
+```ts
+const client = new TheoKitClient({
+  baseUrl: "https://adapter.example.com",
+  basePath: "/agent",                      // optional
+  headers: { authorization: "Bearer …" },  // optional
+});
+```
+
+## Send (one-shot)
+
+`send(input)` POSTs and resolves a `SendResponse` (`{ status, output?, error? }`).
+
+```ts
+const res: SendResponse = await client.send("summarize the repo");
+if (res.error) throw new Error(res.error);
+console.log(res.status, res.output);
+```
+
+## Stream (SSE)
+
+`stream(input)` returns an `AsyncGenerator<StreamEvent>`; each `StreamEvent` has a
+`type` and an optional `text` (plus arbitrary extra fields).
+
+```ts
+for await (const event of client.stream("build the changelog")) {
+  if (event.type === "text" && event.text) process.stdout.write(event.text);
+}
+```

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

@@ -0,0 +1,102 @@
+---
+user-invocable: false
+paths:
+  - "**/*compact*"
+  - "**/*Compact*"
+description: TheoKit SDK compaction reference — compactTranscript, shouldCompact, checkpoints, context-overflow
+---
+
+# TheoKit Compaction
+
+Public context-management helpers. Every function is pure and never mutates its
+input. A `CompressibleMessage` is `{ role: "user" | "assistant" | "system"; content: string }`.
+
+```typescript
+import {
+  compactTranscript,
+  shouldCompact,
+  estimateTokens,
+  buildCheckpoint,
+  filterFromLatestCheckpoint,
+  isContextOverflowError,
+  CHECKPOINT_MARKER,
+  SUMMARY_TEMPLATE,
+  type CompactTranscriptOptions,
+  type ShouldCompactInput,
+  type CompressibleMessage,
+} from "@theokit/sdk/compaction";
+```
+
+## Pre-call gate — `estimateTokens` + `shouldCompact`
+
+`estimateTokens` is a tokenizer-free `ceil(text.length / 4)` heuristic — a cheap
+gate, NOT exact tokenization. `shouldCompact` is pure: the caller supplies the
+model's window.
+
+```typescript
+const estimated = estimateTokens(transcript.map((m) => m.content).join("\n"));
+
+const input: ShouldCompactInput = {
+  estimated,
+  contextWindow: 200_000,
+  buffer: 8_000,     // headroom to reserve (output + safety margin)
+  maxOutput: 4_000,  // optional; separate response reservation (default 0)
+};
+
+if (shouldCompact(input)) {
+  // compact before sending — see below
+}
+```
+
+## `compactTranscript` — summarize the older window
+
+Default `keepRecent` mode keeps the last N turns verbatim (default 6) and
+preserves leading system prompts. The older window is summarized via the
+caller-supplied `summarize` callback (or dropped if omitted). With `failSafe`, a
+thrown summarizer returns the ORIGINAL transcript instead of propagating.
+
+```typescript
+const opts: CompactTranscriptOptions = {
+  keepRecent: 6,        // OR keepTokens: 40_000 (token-budget mode, takes precedence)
+  failSafe: true,
+  summarize: async (older: CompressibleMessage[], template: string) => {
+    // template is SUMMARY_TEMPLATE unless overridden via summaryTemplate
+    const summary = await callYourModel(template, older);
+    return { role: "system", content: summary };
+  },
+};
+
+const compacted = await compactTranscript(transcript, opts);
+```
+
+## Checkpoints — mark and filter
+
+`buildCheckpoint` produces a `system` turn whose content starts with
+`CHECKPOINT_MARKER`. `filterFromLatestCheckpoint` returns turns relative to the
+most recent marker (`include: "after"` excludes it — the default; `"from"`
+includes it).
+
+```typescript
+const marked = [...transcript, buildCheckpoint("milestone: tests green")];
+
+const recent = filterFromLatestCheckpoint(marked);              // after (exclusive)
+const withHead = filterFromLatestCheckpoint(marked, { include: "from" });
+```
+
+## Context-overflow detection
+
+`isContextOverflowError` is `true` only for a `TheokitAgentError` reporting the
+typed `context_too_long` code — never a brittle message regex.
+
+```typescript
+try {
+  await agent.send(prompt);
+} catch (err) {
+  if (isContextOverflowError(err)) {
+    const compacted = await compactTranscript(transcript, { keepRecent: 4 });
+    // retry with the compacted transcript
+  } else {
+    throw err;
+  }
+}
+```

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

@@ -0,0 +1,68 @@
+---
+user-invocable: false
+description: Bound in-process parallelism with Semaphore.create and mapWithConcurrency from @theokit/sdk/concurrency.
+paths:
+  - "**/*concurren*"
+  - "**/*semaphore*"
+  - "**/*Semaphore*"
+---
+
+# TheoKit SDK -- Concurrency
+
+In-house concurrency helpers (no `p-limit`/`p-map` dependency). `Semaphore.create(permits)` builds an N-permit async counting gate; `mapWithConcurrency` runs an async mapper over items with bounded parallelism while preserving input order.
+
+## Import
+
+```typescript
+import { Semaphore, mapWithConcurrency } from "@theokit/sdk/concurrency";
+import type { AsyncSemaphore } from "@theokit/sdk/concurrency";
+```
+
+## Signatures
+
+```typescript
+class Semaphore {
+  static create(permits: number): AsyncSemaphore; // canonical factory (ADR 0015)
+}
+
+interface AsyncSemaphore {
+  acquire(): Promise<() => void>; // returns a release fn; call it exactly once
+  inFlight(): number;             // permits currently held
+  pending(): number;              // in-flight + queued waiters
+}
+
+function mapWithConcurrency<T, R>(
+  items: ReadonlyArray<T>,
+  concurrency: number,                                     // positive integer; validated
+  fn: (item: T, index: number, signal: AbortSignal) => Promise<R>,
+  options?: { signal?: AbortSignal },
+): Promise<R[]>; // ordered; fail-fast; throws ConfigurationError on bad concurrency
+```
+
+## Semaphore -- release in a finally
+
+```typescript
+const sem = Semaphore.create(4); // at most 4 in flight
+
+async function guarded<T>(task: () => Promise<T>): Promise<T> {
+  const release = await sem.acquire();
+  try {
+    return await task();
+  } finally {
+    release(); // release exactly once (idempotent, but leaking it consumes a permit)
+  }
+}
+```
+
+## mapWithConcurrency -- ordered bounded map
+
+```typescript
+const controller = new AbortController();
+const results = await mapWithConcurrency(
+  ["a", "b", "c"],
+  2, // max 2 concurrent fetches
+  async (url, _index, signal) => (await fetch(url, { signal })).json(),
+  { signal: controller.signal },
+);
+// results align with input order; rejects on the first task error
+```

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

@@ -0,0 +1,74 @@
+---
+user-invocable: false
+paths:
+  - "**/*filesystem*"
+  - "**/*Filesystem*"
+description: TheoKit SDK filesystem seam — FilesystemBackend, LocalFilesystem, boundary-enforced storage with read-before-write safety
+---
+
+# TheoKit Filesystem
+
+A pluggable, boundary-enforced file *storage* provider for agent file tools —
+the storage-side twin of the sandbox seam. Ship a `FilesystemBackend` (default
+`LocalFilesystem`) with an optional `readOnly` flag and a per-request resolver.
+
+```ts
+import {
+  LocalFilesystem, FilesystemBackend, resolveFilesystem,
+} from "@theokit/sdk/filesystem";
+import type {
+  FilesystemProvider, FilesystemConfig, FileStat, WriteFileOptions,
+} from "@theokit/sdk/filesystem";
+import {
+  FileNotFoundError, FilesystemError,
+  FilesystemReadOnlyError, FilesystemSecurityError, StaleFileError,
+} from "@theokit/sdk/filesystem";
+```
+
+## LocalFilesystem
+
+Boundary-enforced over `node:fs/promises`. Every path resolves within `basePath`;
+traversal / symlink escapes are rejected with `FilesystemSecurityError`. NOT an
+isolation boundary — run untrusted code inside a container/VM.
+
+```ts
+const fs = new LocalFilesystem({ basePath: "/workspace", readOnly: false });
+
+const stat: FileStat = await fs.writeFile("notes.md", "# hello"); // returns FileStat
+const text = await fs.readFile("notes.md");
+const names = await fs.list(".");            // entry names, not recursive
+if (await fs.exists("notes.md")) { /* … */ }
+```
+
+## Read-before-write safety (SE32)
+
+`stat().mtimeMs` is the oracle. Pass `expectedMtime` so a concurrent change makes
+the write fail with `StaleFileError` instead of silently clobbering.
+
+```ts
+const before = await fs.stat("notes.md");
+try {
+  await fs.writeFile("notes.md", updated, { expectedMtime: before.mtimeMs });
+} catch (err) {
+  if (err instanceof StaleFileError) { /* someone changed it — re-read + merge */ }
+}
+```
+
+## Per-request provider (multi-tenant)
+
+A `FilesystemProvider` is a backend OR a resolver `(ctx) => backend` run at
+tool-execution time, giving each request its own root. `resolveFilesystem`
+collapses either form to a concrete backend.
+
+```ts
+const provider: FilesystemProvider<{ tenant: string }> = (ctx) =>
+  new LocalFilesystem({ basePath: `/data/${ctx.tenant}` });
+
+const backend = await resolveFilesystem(provider, { tenant: "acme" });
+```
+
+## Custom backend
+
+Extend `FilesystemBackend` and implement `readFile` / `writeFile` / `stat` /
+`list`; `exists()`, `readOnly`, and `basePath` derive on the base class. Map raw
+Node errors to the typed errors above (`FileNotFoundError`, `FilesystemError`).

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

@@ -0,0 +1,58 @@
+---
+user-invocable: false
+paths:
+  - "**/*message*"
+  - "**/*Message*"
+description: TheoKit SDK message readers — assistantText, extractToolUses, costAmountUsd over the SDKMessage stream
+---
+
+# TheoKit Messages
+
+Pure readers over the `SDKMessage` stream — no I/O, no mutation, deterministic.
+Use these instead of re-implementing a wire-event mapper.
+
+```typescript
+import { assistantText, extractToolUses, costAmountUsd } from "@theokit/sdk/messages";
+import type { SDKMessage, ToolUseBlock } from "@theokit/sdk";
+import type { CostBreakdown } from "@theokit/sdk";
+```
+
+## `assistantText(msg)` — concatenate assistant text blocks
+
+Returns `""` for any non-assistant message (or an assistant with no text
+blocks). `tool_use` blocks are ignored — only `text` blocks contribute.
+
+```typescript
+for await (const event of run.stream()) {
+  // event is an SDKMessage; assistantText is safe on any variant
+  const text = assistantText(event);
+  if (text) process.stdout.write(text);
+}
+```
+
+## `extractToolUses(msg)` — read assistant `ToolUseBlock`s
+
+Returns `[]` for any non-assistant message. This reads the assistant message's
+content blocks — NOT the separate `tool_call` lifecycle event (a different
+stream). Tool `input` is `unknown`; parse it defensively.
+
+```typescript
+const uses: ToolUseBlock[] = extractToolUses(event);
+for (const use of uses) {
+  console.log(use.name, use.id); // use.input is `unknown` — validate before use
+}
+```
+
+## `costAmountUsd(cost)` — honesty-preserving cost read
+
+Returns `number | undefined`. `undefined` means "cost unknown" — distinct from a
+real `$0` (e.g. a subscription-included route). NEVER coerced to 0.
+
+```typescript
+const amount = costAmountUsd(cost); // cost: CostBreakdown | undefined
+if (amount === undefined) {
+  console.log("cost unknown");
+} else {
+  console.log(`$${amount.toFixed(4)}`);
+}
+```

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

@@ -0,0 +1,79 @@
+---
+user-invocable: false
+paths:
+  - "**/*model*"
+  - "**/*Model*"
+description: TheoKit SDK model helpers — @theokit/sdk/models (parseModelId, resolveModelCapabilities, toModelOption, humanizeModelName); API catalog via Theokit.models.list()
+---
+
+# TheoKit Models
+
+Pure, sync, offline helpers for model ids. No network — these read a static catalog
+and parse strings. For the live API-backed catalog, use `Theokit.models.list()` from
+the main `@theokit/sdk` barrel.
+
+```typescript
+import {
+  parseModelId,
+  resolveModelCapabilities,
+  toModelOption,
+  humanizeModelName,
+  type ModelCapabilities,
+  type ModelOption,
+  type ParsedModelId,
+} from "@theokit/sdk/models";
+```
+
+## Parse a model id
+
+`parseModelId` splits on the first `/` into `{ provider, name }`. No `/` means
+`provider` is `undefined` (so callers can fall back to env-var detection). Tag
+suffixes like `:3b` / `:latest` stay part of `name`.
+
+```typescript
+const a: ParsedModelId = parseModelId("anthropic/claude-3-5-sonnet");
+// { provider: "anthropic", name: "claude-3-5-sonnet" }
+
+const b = parseModelId("openrouter/meta-llama/llama-3");
+// { provider: "openrouter", name: "meta-llama/llama-3" }  (embedded slash kept)
+
+const c = parseModelId("claude-sonnet-4-6");
+// { provider: undefined, name: "claude-sonnet-4-6" }
+```
+
+## Gate features by capability
+
+`resolveModelCapabilities` returns typed flags + token limits from an OFFLINE
+catalog. It strips routing prefixes (`openrouter/`/`vertex/`/`bedrock/`) and the
+OpenRouter `:variant` suffix before lookup; unknown models get conservative defaults.
+
+```typescript
+const caps: ModelCapabilities = resolveModelCapabilities("anthropic/claude-3-5-sonnet");
+// { supportsVision, supportsStructuredOutput, supportsToolUse,
+//   supportsCacheControl, maxContextTokens, maxOutputTokens }
+
+if (!caps.supportsVision) {
+  throw new Error("This model cannot accept images");
+}
+```
+
+## Build dropdown options
+
+`humanizeModelName` produces a best-effort label; `toModelOption` composes it with
+`parseModelId` into `{ value, label, provider }`.
+
+```typescript
+humanizeModelName("anthropic/claude-3-5-sonnet"); // "Claude 3 5 Sonnet"
+
+const opt: ModelOption = toModelOption("openrouter/meta-llama/llama-3");
+// { value: "openrouter/meta-llama/llama-3", label: "...", provider: "openrouter" }
+```
+
+## Live catalog (API-backed)
+
+```typescript
+import { Theokit } from "@theokit/sdk";
+
+const models = await Theokit.models.list({ apiKey: process.env.THEOKIT_API_KEY });
+const options: ModelOption[] = models.map((m) => toModelOption(m.id));
+```

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

@@ -0,0 +1,60 @@
+---
+user-invocable: false
+description: Path-traversal, symlink-escape, and forbidden-path guards from @theokit/sdk/path-safety for agent file I/O.
+paths:
+  - "**/*path-safety*"
+  - "**/*pathsafety*"
+---
+
+# TheoKit SDK -- Path Safety
+
+TOCTOU-safe path primitives to wire wherever user input becomes a filesystem path in a custom tool. `safePathJoin` resolves then prefix-checks; `assertNoSymlinkEscape` resolves the whole symlink chain via `realpathSync`; `isForbiddenPath` blocks sensitive files even when they are lexically inside the project.
+
+## Import
+
+```typescript
+import {
+  safePathJoin,
+  assertNoSymlinkEscape,
+  isForbiddenPath,
+  safeFilenameForId,
+  sanitizeIdentifier,
+  PathTraversalError,
+  ForbiddenPathError,
+} from "@theokit/sdk/path-safety";
+```
+
+## Signatures
+
+```typescript
+function safePathJoin(base: string, ...parts: string[]): string;   // throws PathTraversalError on escape
+function assertNoSymlinkEscape(path: string, base: string): void;  // throws PathTraversalError on symlink escape
+function isForbiddenPath(input: string): boolean;                  // true for .env*, .git/, node_modules/, .theo/, lock files
+function safeFilenameForId(id: string, options?: { maxLen?: number }): string; // total: passthrough or h-<16hex>
+function sanitizeIdentifier(input: string, options?: { maxLen?: number }): string; // grammar ^[a-z0-9][a-z0-9-_]*$
+
+class PathTraversalError extends ConfigurationError { constructor(input: string, resolvedPath: string); } // code "path_traversal"
+class ForbiddenPathError extends ConfigurationError { constructor(path: string); }                         // code "forbidden_path"
+```
+
+## Guard a tool's file read
+
+```typescript
+const projectRoot = process.cwd();
+
+function resolveUserPath(userPath: string): string {
+  if (isForbiddenPath(userPath)) throw new ForbiddenPathError(userPath);
+  const safe = safePathJoin(projectRoot, userPath); // throws PathTraversalError on "../" escape
+  assertNoSymlinkEscape(safe, projectRoot);          // throws PathTraversalError on symlink escape
+  return safe;
+}
+```
+
+## Derive a safe filename from an opaque id
+
+`safeFilenameForId` never throws on a non-empty string: it returns the id verbatim when it already matches the safe grammar, otherwise a deterministic `h-<16 hex>` sha256 token.
+
+```typescript
+safeFilenameForId("550e8400-e29b-41d4-a716-446655440000"); // passthrough
+safeFilenameForId("user@example.com");                       // "h-<16hex>"
+```

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

@@ -0,0 +1,85 @@
+---
+user-invocable: false
+paths:
+  - "**/*persist*"
+  - "**/*Persist*"
+  - "**/*.jsonl"
+  - "**/*sqlite*"
+description: TheoKit SDK persistence primitives — atomic writes, JSONL persist/resume, resilient SQLite, cross-process locks
+---
+
+# TheoKit Persistence
+
+Durable, crash-safe persistence helpers on the STABLE `@theokit/sdk/persistence`
+sub-path. Do NOT import them from `@theokit/sdk/internal/persistence` (semver-exempt).
+
+```ts
+import {
+  // atomic writes
+  replaceFileAtomic, atomicWriteText, atomicWriteJson,
+  // jsonl persist/resume
+  appendJsonl, loadJsonl, readJsonlIds, JsonlParseError,
+  // resilient sqlite
+  openSqliteResilient, applyWalWithFallback, isCorruptionError, sanitizeFts5Query,
+  // locks
+  withFileLock, withCwdMutex,
+  // misc
+  PersistenceSchema, transcriptPath, encodeProjectDir,
+} from "@theokit/sdk/persistence";
+```
+
+## Atomic writes
+
+Crash mid-write leaves either the old file intact or the new file complete —
+never a half-written file (temp + fsync + rename). `atomicWriteJson` /
+`atomicWriteText` auto-`mkdir` the parent dir; `replaceFileAtomic` does not.
+
+```ts
+await replaceFileAtomic("/data/config.md", markdown);         // (filePath, content)
+await atomicWriteText("/data/notes.txt", text);               // + auto-mkdir
+await atomicWriteJson("/data/state.json", { runs: 3 });        // default indent 2, trailing \n
+await atomicWriteJson("/data/state.json", data, { indent: 0, trailingNewline: false });
+```
+
+## JSONL persist / resume
+
+`appendJsonl` writes one `\n`-terminated line per record (synchronous, interleave-safe
+within a process). Resume a crashed batch by reading already-persisted keys.
+
+```ts
+appendJsonl("/data/results.jsonl", { id: "task-1", status: "passed" });
+
+// Skip rows already done (partial trailing line tolerated; missing file -> empty set)
+const done = readJsonlIds("/data/results.jsonl", (row) =>
+  row.status === "passed" ? String(row.id) : undefined,
+);
+
+// loadJsonl throws JsonlParseError (with 1-based .line) on a malformed line
+const rows = loadJsonl<{ id: string }>("/data/results.jsonl");
+```
+
+## Resilient SQLite
+
+`openSqliteResilient` loads the driver, applies WAL (with DELETE fallback), and
+recovers from corruption by renaming the file aside. Apply schema in `onOpen`.
+
+```ts
+const db = await openSqliteResilient({
+  filePath: "/data/index.db",
+  label: "memory-index",
+  onOpen: (db) => db.exec("CREATE TABLE IF NOT EXISTS docs (id TEXT PRIMARY KEY)"),
+});
+applyWalWithFallback(db, "memory-index");        // { mode: "wal"|"delete", fellBack }
+const q = sanitizeFts5Query("error-code");        // "" means caller must short-circuit
+```
+
+## Locks
+
+`withFileLock` takes a cross-process lock (needs the `proper-lockfile` peer dep;
+falls back to in-process `withCwdMutex` with a warning). `withCwdMutex` serializes
+by key within one process.
+
+```ts
+await withFileLock("/data/state.json", async () => { /* exclusive section */ });
+await withCwdMutex("migrate-config", async () => { /* in-process critical section */ });
+```

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

@@ -0,0 +1,55 @@
+---
+user-invocable: false
+paths:
+  - "**/*project*"
+  - "**/*Project*"
+  - "**/THEO.md"
+description: TheoKit SDK project-instruction reader/writer — hierarchical walk-up discovery + atomic write of THEO.md
+---
+
+# TheoKit Project Instructions
+
+Hierarchical project-instruction reader/writer on `@theokit/sdk/project`. The
+reader walks up from `cwd` collecting an instruction file (default `THEO.md`) and
+NEVER throws; the writer writes it atomically and FAILS LOUD on error.
+
+```ts
+import {
+  readProjectInstructions, writeProjectInstructions,
+} from "@theokit/sdk/project";
+import type {
+  ProjectInstructions, ProjectInstructionFile, ProjectInstructionScope,
+  ReadProjectInstructionsOptions, WriteProjectInstructionsOptions,
+} from "@theokit/sdk/project";
+```
+
+## Read (walk-up, never throws)
+
+Discovers every `<dir>/<filename>` from `cwd` up to the filesystem root (or
+`stopDir`). Returns `files` nearest-first plus a `content` reduction chosen by
+`scope` (`"nearest"` → innermost file; `"merged"` → all joined root-first).
+No file found → `{ files: [], content: undefined }`.
+
+```ts
+const result: ProjectInstructions = await readProjectInstructions(process.cwd(), {
+  filename: "THEO.md",   // default "THEO.md"
+  scope: "merged",       // default "nearest"
+  stopDir: "/home/me/repo",
+});
+
+if (result.content) applySystemPrompt(result.content);
+for (const f of result.files) console.log(f.path, f.content.length);
+```
+
+## Write (atomic, fails loud)
+
+Writes `<cwd>/<filename>` via temp + fsync + rename. An unsafe `filename`
+(traversal, separators, absolute) is rejected with `ConfigurationError`
+(`code: "unsafe_filename"`); a real write error (e.g. missing parent dir)
+propagates — never silently swallowed.
+
+```ts
+await writeProjectInstructions(process.cwd(), "# Project rules\n…", {
+  filename: "THEO.md",   // default "THEO.md"
+});
+```

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

@@ -0,0 +1,50 @@
+---
+user-invocable: false
+paths:
+  - "**/*retry*"
+  - "**/*Retry*"
+description: TheoKit SDK retry primitive — @theokit/sdk/retry (Retry.create executor with exponential backoff + full jitter, RetryOptions)
+---
+
+# TheoKit Retry
+
+`@theokit/sdk/retry` exposes one primitive: `Retry`. NOTE — `Retry.create` is an
+EXECUTOR, not a constructor. `Retry.create(fn, opts)` RUNS `fn` with retry/backoff and
+resolves to its result (`Promise<T>`) — it does not return a `Retry` instance.
+
+```typescript
+import { Retry, type RetryOptions } from "@theokit/sdk/retry";
+```
+
+## Run a fn with retry
+
+Exponential backoff with full jitter. The default `isRetryable` predicate is the SDK's
+own `isTransientError`, so retries follow the SDK's error classification (rate-limit /
+network retry; business-rule violations do not).
+
+```typescript
+const data = await Retry.create(() => fetchJson(url));
+// retries transient failures up to 3 times (4 attempts total), then throws the last error
+```
+
+## Tuning with `RetryOptions`
+
+All fields are optional; defaults shown in comments.
+
+```typescript
+const result = await Retry.create(
+  () => callFlakyApi(),
+  {
+    retries: 5,               // retries AFTER the first attempt (default 3)
+    initialDelayMs: 200,      // base backoff for the first retry (default 100)
+    maxDelayMs: 10_000,       // cap per single sleep (default 30_000)
+    backoffMultiplier: 2,     // exponential multiplier per retry (default 2)
+    isRetryable: (err) => err instanceof NetworkGlitch, // default: isTransientError
+    signal: controller.signal, // aborts the backoff loop when triggered
+  } satisfies RetryOptions,
+);
+```
+
+`rng` and `sleep` are also injectable — override them for deterministic tests (no real
+timers). When retries are exhausted or the error is not retryable, `Retry.create`
+re-throws the last error.

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

@@ -0,0 +1,93 @@
+---
+user-invocable: false
+paths:
+  - "**/*sandbox*"
+  - "**/*Sandbox*"
+description: TheoKit SDK sandbox reference — SandboxBackend / LocalSandbox execution + provisionRepo
+---
+
+# TheoKit Sandbox
+
+```typescript
+import {
+  LocalSandbox,
+  provisionRepo,
+  SandboxBackend,
+  SandboxNotAvailableError,
+  SandboxSecurityError,
+  RepoProvisionError,
+  type ExecuteResult,
+  type SandboxConfig,
+  type ProvisionRepoOptions,
+} from "@theokit/sdk/sandbox";
+```
+
+## `LocalSandbox` — subprocess execution
+
+`LocalSandbox` runs commands via `/bin/sh -c` in the SAME OS as the host. It is
+**NOT an isolation boundary** — no process, filesystem, or network isolation.
+Its only safety affordances are a wall-clock timeout, an output-size cap, and
+env scrubbing. For real isolation of untrusted code, use a container/VM backend.
+
+```typescript
+const sandbox = new LocalSandbox({
+  workDir: "/tmp/work",
+  timeoutMs: 5_000,
+  maxOutputBytes: 1024,
+  // env defaults to "inherit-scrubbed": drops *KEY* / *SECRET* / *TOKEN* /
+  // *PASSWORD* / *_AUTH* from the child. Pass "all" or "core" to change.
+});
+
+const result: ExecuteResult = await sandbox.execute("echo hi", { timeoutMs: 2_000 });
+console.log(result.stdout, result.exitCode, result.timedOut);
+
+// Derived helpers on the base class (no need to reimplement):
+await sandbox.writeFile("a.txt", "content");
+const text = await sandbox.readFile("a.txt");
+const files = await sandbox.glob("**/*.ts");
+const hits = await sandbox.grep("TODO", "src");
+```
+
+## Custom backend — implement only 2 abstract methods
+
+New backends (Docker, Firecracker, E2B) extend `SandboxBackend` and implement
+only `execute` + `uploadFile`; `readFile` / `writeFile` / `glob` / `grep` /
+`listDir` are derived on the base class.
+
+```typescript
+class MyBackend extends SandboxBackend {
+  async execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult> {
+    // run command remotely; return { stdout, stderr, exitCode, timedOut }
+    throw new SandboxNotAvailableError("backend offline");
+  }
+  async uploadFile(path: string, content: string | Buffer): Promise<void> {
+    /* ... */
+  }
+}
+```
+
+`SandboxSecurityError` (`code: "sandbox_security"`) and
+`SandboxNotAvailableError` (`code: "sandbox_not_available"`) both extend `Error`.
+
+## `provisionRepo` — clone + checkout into the sandbox
+
+Clones `repoUrl` into `<workDir>/<instanceId>` and checks out `ref`, running
+every git command through the sandbox. The `sandbox` argument is optional — when
+omitted a default `LocalSandbox` (process cwd) is used.
+
+```typescript
+const opts: ProvisionRepoOptions = {
+  repoUrl: "https://github.com/acme/repo.git",
+  ref: "main",           // branch, tag, or SHA (rejected if it begins with "-")
+  instanceId: "task-001", // validated to [A-Za-z0-9._-] — becomes a dir name
+};
+
+const { repoDir } = await provisionRepo(new LocalSandbox({ workDir: "/tmp/work" }), opts);
+// or, with the default LocalSandbox: await provisionRepo(opts);
+
+try {
+  await provisionRepo({ repoUrl: "bad", ref: "main", instanceId: "x" });
+} catch (err) {
+  if (err instanceof RepoProvisionError) console.error(err.instanceId, err.message);
+}
+```

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

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

@@ -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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.2.7",
+  "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",