@theokit/sdk 4.2.6 → 4.2.8

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);
+```