@theokit/sdk 4.53.1 → 4.55.0

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

@@ -1,176 +0,0 @@
----
-user-invocable: false
-description: Memory API, embedding providers, dreaming, active recall, and backends for @theokit/sdk.
-paths:
-  - "**/*memory*"
-  - "**/*Memory*"
-  - "**/*embed*"
----
-
-# TheoKit SDK -- Memory
-
-Quick reference for durable memory, embedding providers, dreaming, and backends.
-
-## Enabling memory on an agent
-
-```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() },
-  memory: {
-    enabled: true,
-    namespace: "my-app",
-    userId: "user-123",
-    scope: "user",
-  },
-});
-
-await (await agent.send("Remember: my preferred test runner is Vitest.")).wait();
-```
-
-## MemoryOptions
-
-```typescript
-interface MemoryOptions {
-  enabled: boolean;
-  namespace?: string;   // separates application domains
-  userId?: string;      // isolates user memories
-  scope?: "agent" | "user" | "team";
-  storePath?: string;   // relative to workspace; cannot escape
-}
-```
-
-## Scopes
-
-| Scope | Use for |
-|---|---|
-| `"agent"` | Durable state for one agent ID. Default scope. |
-| `"user"` | Stable user preferences across agent instances. Requires `userId`. |
-| `"team"` | Shared team facts safe for every authorized caller. |
-
-## Safety rules
-
-- Memory MUST NOT store API keys, bearer tokens, passwords, or credential material.
-- Local `storePath` is resolved relative to the workspace. Path traversal raises `ConfigurationError`.
-- Memory is durable by `{ namespace, userId, scope }`, not by JavaScript process.
-
-## SDKMemoryManager
-
-```typescript
-interface SDKMemoryManager {
-  // Reserved for explicit inspection and deletion APIs.
-}
-```
-
-The agent uses memory during runs automatically. Public management APIs are narrow until deletion and audit semantics are finalized.
-
-## Memory backends (v1.2+)
-
-```typescript
-import { Memory } from "@theokit/sdk";
-
-const memory = await Memory.create({
-  cwd: process.cwd(),
-  index: {
-    backend: "sqlite-vec",  // default
-    embedding: { provider: "openai", model: "text-embedding-3-small" },
-  },
-});
-
-// Or use LanceDB for >100k facts:
-const memory = await Memory.create({
-  cwd: process.cwd(),
-  index: {
-    backend: "lance",
-    embedding: { provider: "openai", model: "text-embedding-3-small" },
-  },
-});
-```
-
-- `@lancedb/lancedb` is an optional peer dep. If missing with `backend: "lance"`, throws `ConfigurationError(code: "lance_backend_unavailable")`.
-- Embedding dimension validated when opening existing index. Mismatch throws `ConfigurationError(code: "embedding_dimension_mismatch")`.
-
-## Embedding providers (ADR D11)
-
-Locked provider union: `openai`, `mistral`, `openrouter`, `voyage`, `deepinfra`.
-
-```typescript
-index: {
-  embedding: {
-    provider: "openai",
-    model: "text-embedding-3-small",
-  },
-}
-```
-
-Each provider adapter implements:
-
-```typescript
-interface EmbeddingAdapter {
-  id: string;
-  model: string;
-  dimension: number;
-  embed(texts: string[]): Promise<number[][]>;
-}
-```
-
-## Memory migration CLI (v1.2+)
-
-Migrate SQLite memory index to LanceDB without data loss:
-
-```bash
-# Dry-run (preview, no writes)
-pnpm exec theokit-migrate-memory --cwd . --dry-run
-
-# Real migration
-pnpm exec theokit-migrate-memory --cwd .
-```
-
-Options: `--cwd <path>`, `--dry-run`, `--keep-sqlite`, `--batch-size <n>`.
-
-Algorithm: read SQLite, write to staging `lance-new/`, validate count + sample text match, atomic rename, prompt to delete SQLite.
-
-## Dreaming (consolidation sweeps)
-
-```typescript
-await Memory.runDreamingSweep({
-  cwd: process.cwd(),
-  embedding: { provider: "openai", model: "text-embedding-3-small" },
-});
-```
-
-Dreaming consolidates redundant facts into compressed summaries. In v1.x, consolidation is deterministic only (no LLM-mediated narrative). LLM narrative mode is deferred.
-
-## Active recall
-
-Active recall queries memory during `agent.send` to inject relevant facts into the LLM context. Configured via the memory options on the agent. Query modes:
-
-- `"embedding"` -- cosine similarity search against the vector index.
-- `"keyword"` -- keyword-based search.
-- `"hybrid"` -- combines embedding and keyword results.
-
-## Semantic cache (related)
-
-`Cache.semantic` from `@theokit/sdk` reuses embedding adapters for LLM response caching with cosine-similarity matching. See the cache documentation for details.
-
-## Resume behavior
-
-Memory is durable by `{ namespace, userId, scope }`, not by process. Recreating or resuming an agent with the same memory config can recall durable facts. Inline secrets and MCP servers are NOT persisted through memory.
-
-## Conversation storage (pluggable persistence)
-
-```typescript
-import { Agent, InMemoryConversationStorage } from "@theokit/sdk";
-
-const agent = await Agent.create({
-  apiKey, model,
-  conversationStorage: new InMemoryConversationStorage(),
-});
-```
-
-Built-in adapters: `FileSystemConversationStorage`, `InMemoryConversationStorage`. Custom adapters implement `ConversationStorageAdapter`.
-
-When using custom storage, `Agent.resume` requires the adapter to be passed again -- silent FS fallback is rejected with `ConfigurationError(code: "conversation_storage_required")`.

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

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

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

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

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

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

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

@@ -1,93 +0,0 @@
----
-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);
-}
-```