@theokit/sdk 4.2.7 → 4.2.9

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/dist/a2a/index.cjs

@@ -92,12 +92,19 @@ var MessageBus = class {
     return [...this._handlers.keys()];
   }
 };
+
+// src/internal/runtime/registry/agent-factory-registry.ts
+var FACADE_KEY = /* @__PURE__ */ Symbol.for(
+  "theokit.internal.runtime.agentFacade"
+);
 function getAgentFacade() {
-  {
+  const registered = globalThis[FACADE_KEY];
+  if (registered === void 0) {
     throw new Error(
       "internal: Agent facade not registered. The `agent.ts` module must be loaded before internal subsystems (LocalAgent.runUntil/fork, eval, scorers, cron) invoke it."
     );
   }
+  return registered;
 }
 
 // src/a2a/subagent.ts