@theokit/sdk 5.11.1 → 5.12.1

package/dist/chunk-6LHQPOMI.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/internal/env.ts","../src/internal/diagnostics.ts","../src/internal/security/redact.ts"],"names":[],"mappings":"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","file":"chunk-6LHQPOMI.cjs","sourcesContent":["/**\n * Environment variable used to provide the default API key.\n *\n * @internal\n */\nexport const API_KEY_ENV_VAR = \"THEOKIT_API_KEY\";\n\n/**\n * Read an environment variable without assuming `process` exists.\n *\n * Parts of this package legitimately reach a browser: `errors.ts` is imported by the client\n * bindings that framework consumers ship to the front end, and it in turn pulls in the redaction\n * and retry modules. `process` is a Node global — a bare `process.env` in any of them throws\n * `ReferenceError: process is not defined` while the module graph is still evaluating, before a\n * single component renders. The page goes blank with one console error that names no cause.\n *\n * `globalThis.process?.env?.[name]` degrades instead: on the server it reads the variable, and in\n * a browser it yields `undefined`, which every caller here already treats as \"not set\". Bundlers\n * that inline `process.env.X` at build time keep working, because they replace the expression\n * before it ever runs.\n *\n * This is the same pattern the sibling design system uses for `NODE_ENV`, for the same reason.\n *\n * @internal\n */\nexport function readEnv(name: string): string | undefined {\n  return globalThis.process?.env?.[name];\n}\n\n/**\n * Resolve the API key with the documented precedence:\n *\n *   1. Explicit `apiKey` argument.\n *   2. The `THEOKIT_API_KEY` environment variable.\n *\n * Returns `undefined` when neither is set.\n *\n * @internal\n */\nexport function resolveApiKey(explicit?: string): string | undefined {\n  if (explicit !== undefined && explicit.length > 0) {\n    return explicit;\n  }\n  const fromEnv = readEnv(API_KEY_ENV_VAR);\n  if (fromEnv !== undefined && fromEnv.length > 0) {\n    return fromEnv;\n  }\n  return undefined;\n}\n","/**\n * The library's single diagnostics channel — silent by default (#147).\n *\n * ## The problem\n *\n * The SDK wrote diagnostics straight to `process.stderr` from hot paths — 92 sites across 51\n * files under `internal/`. In a TUI host (Ink, alternate screen), those writes interleave with the\n * render and **corrupt the frame**. And the host had no way to intercept them: there was no\n * injectable logger. One consumer went as far as installing `proper-lockfile` just to silence ONE\n * of them.\n *\n * A library cannot assume `stdout`/`stderr` are free sinks. The application owns the terminal, not\n * the dependency.\n *\n * ## The contract\n *\n * - **`setDiagnosticsSink(fn)`** hands the messages to the application, which decides where to put\n *   them (a status line, a file, a panel). It is what was missing for a TUI to coexist with the SDK.\n * - **With no sink, nothing is emitted.** A library does not own the host's terminal.\n *\n * ## Silent by default, and how 36 suites survived the flip\n *\n * The default WAS `stderr`, and 36 test files spy on `process.stderr.write` to assert a given\n * warning is emitted. That contract is real and had to survive; migrating all 36 by hand, across\n * four different spy styles, is how you weaken 36 suites in one commit.\n *\n * So the flip happened at the default, and `vitest.setup.ts` installs a sink that FORWARDS to\n * `stderr` for the duration of every test. Those assertions still test what they always tested —\n * \"this condition emits a diagnostic\" — through the channel a host would use, while production\n * emits nothing unless asked.\n *\n * The cost is stated rather than hidden: no test observes the production default by accident, so\n * `tests/diagnostics-public-entry.test.ts` pins it explicitly by clearing the sink first.\n *\n * ## Coverage is the whole guarantee\n *\n * The first sweep migrated the 92 sites under `internal/` and left `src/`'s own modules —\n * `event-bus.ts`, `batch.ts`, `compaction.ts`, `internal/workflow/step-branch.ts`. A host could\n * therefore install a sink and still have its frame corrupted by a batch run, which is the reported\n * defect with a smaller blast radius. Those are routed here too, and\n * `tests/lint/no-direct-terminal-write.test.ts` is what keeps the next hot path from\n * reintroducing one. \"Mostly interceptable\" is not interceptable.\n *\n * The remaining direct writers are allowlisted there with a reason, and every one of them is a seam\n * whose destination the CALLER already chooses (`opts.warn`, `opts.logger`, the Workflow logger).\n *\n * ## What this is NOT\n *\n * It is not a logger with levels, formatting or multiple destinations. It is the minimum that\n * resolves the reported blocker; a full logger here would be inventing a requirement nobody asked\n * for.\n */\n\n/** Receives each diagnostic message already formatted, with the trailing `\\n`. */\nexport type DiagnosticsSink = (message: string) => void;\n\n/**\n * The registry lives on `globalThis`, not in a module-level `let` (theokit#173).\n *\n * A module-level binding is a per-INSTANCE singleton, and a package manager will install two\n * physical copies of the same version whenever two dependents resolve different peer sets. Measured:\n * `@theokit/sdk@4.39.1` existed under two pnpm store hashes in the theokit workspace, so a sink\n * installed through `@theokit/agents` landed in a different registry than the emitter writes to.\n *\n * The failure mode is the quiet one — the re-export resolves, the function is callable, nothing\n * throws, and no diagnostic ever arrives. `Symbol.for` gives every copy in the process the same\n * slot; the `v1` suffix leaves room to change the shape without colliding with an older copy.\n */\nconst SINK_SLOT = Symbol.for(\"theokit.sdk.diagnostics.sink.v1\");\n\ntype SinkHolder = Record<symbol, DiagnosticsSink | undefined>;\n\nfunction currentSink(): DiagnosticsSink | undefined {\n  return (globalThis as unknown as SinkHolder)[SINK_SLOT];\n}\n\n/**\n * Installs (or removes, by passing `undefined`) the diagnostics destination.\n *\n * When a sink is present it is the ONLY destination — `stderr` gets no copy. Duplicating\n * destinations would hand the problem back to the TUI that installed the sink precisely to get the\n * messages out of the terminal.\n */\nexport function setDiagnosticsSink(next: DiagnosticsSink | undefined): void {\n  (globalThis as unknown as SinkHolder)[SINK_SLOT] = next;\n}\n\n/**\n * Emits a library diagnostic message.\n *\n * Replaces `process.stderr.write` on internal paths. Never throws: a faulty sink must not\n * must not take down the run it merely observes.\n */\nexport function diag(message: string): void {\n  // Silent by default (#147): with no sink installed the message is dropped. A library must not\n  // assume the host's stdout/stderr are free-form log sinks — in a TUI they are the render surface.\n  const sink = currentSink();\n  if (sink === undefined) return;\n  try {\n    sink(message);\n  } catch {\n    // Observability never breaks the run — same principle as `emitRunEvent`.\n  }\n}\n\n/**\n * Emits a diagnostic that reports a USER-VISIBLE FAILURE, and is never silently dropped.\n *\n * `diag` is silent with no sink installed, and that is right for chatter: a library must not assume\n * the host's stderr is a free-form log, because in a TUI it is the render surface. A failure is a\n * different message. `theokit-sdk#189` is the record of the difference — an MCP server failed to\n * start, the only report went to `diag()`, the embedding UI never read it, and the user saw an\n * agent with missing tools and no reason given.\n *\n * The two failure modes are not symmetric, which is the whole decision: a corrupted frame is\n * visible and recoverable, while a silently dropped failure is neither. So this falls back to\n * stderr rather than to silence.\n *\n * A sink still takes precedence — the host installed it precisely to keep these off the terminal —\n * EXCEPT when the sink throws. A broken sink swallowing the one report of a failure is the same\n * defect one layer further in.\n *\n * @internal\n */\nexport function diagFailure(message: string): void {\n  const sink = currentSink();\n  if (sink !== undefined) {\n    try {\n      sink(message);\n      return;\n    } catch {\n      // Fall through: the sink is broken, and this message is too important to drop with it.\n    }\n  }\n  try {\n    // `globalThis.process?.stderr` rather than a bare `process`: in a browser the bare form is a\n    // ReferenceError that the catch below would swallow — working by accident, on an exception used\n    // as ordinary control flow. Optional chaining states the intent: write to stderr where one\n    // exists, stay silent where none does.\n    globalThis.process?.stderr?.write(`${message}\\n`);\n  } catch {\n    // Nothing left to try. Observability never breaks the run.\n  }\n}\n","import { diag } from \"../diagnostics.js\";\nimport { readEnv } from \"../env.js\";\n\n/**\n * Canonical secret redaction module (ADRs D68-D73).\n *\n * Single source of truth for credential pattern masking across the SDK.\n * Wired at output boundaries: `ErrorMetadata.raw` (mappers/shared.ts),\n * telemetry span attributes (telemetry/tracer.ts), transcript JSONL\n * appends (agent-session-store.ts), migration logger output\n * (memory/migrate-sqlite-to-lance.ts).\n *\n * - D68: central module, single source of truth (replaces 2 duplicates)\n * - D69: env snapshot at module init (prompt-injection defense)\n * - D70: ON by default, warn on opt-out\n * - D71: two-bucket masking — short fully masked, long preserves prefix+suffix\n * - D72: `codeFile` opt-out for legitimate prefix-shaped content\n * - D73: redact at OUTPUT boundaries, not at storage\n *\n * @internal\n */\n\n// D69: env snapshot captured at module load. Subsequent mutations of\n// process.env.THEOKIT_REDACT_SECRETS are ignored — defends against\n// prompt injection that tries to disable redaction mid-run.\nlet REDACT_ENABLED: boolean = readEnvOnce();\n\nfunction readEnvOnce(): boolean {\n  // `readEnv` rather than `process.env`: this module reaches the browser through `errors.ts`, and\n  // a bare `process` there is a ReferenceError at module scope — a blank page, not a warning.\n  const raw = readEnv(\"THEOKIT_REDACT_SECRETS\");\n  if (raw === undefined) return true; // D70: default ON\n  return [\"1\", \"true\", \"yes\", \"on\"].includes(raw.toLowerCase());\n}\n\n// D70: warn once on opt-out so the user knows they're vulnerable.\nlet warnedOptOut = false;\nif (!REDACT_ENABLED && !warnedOptOut) {\n  diag(\n    \"[theokit-sdk] Secret redaction is DISABLED via THEOKIT_REDACT_SECRETS. \" +\n      \"Credentials may leak into errors, telemetry, logs, transcripts.\\n\",\n  );\n  warnedOptOut = true;\n}\n\n/**\n * Built-in credential patterns. Order matters — more specific prefixes\n * must come before generic ones (e.g., `sk-ant-` before `sk-`). Quantifiers\n * are all bounded `{n,m}` or applied to char classes — linear time, no ReDoS.\n *\n * @internal\n */\nconst BUILTIN_PATTERNS: readonly RegExp[] = [\n  // T5.4: 30+ vendor prefixes (was 12 pre-T5.4). Order matters — more\n  // specific prefixes precede generic ones (e.g., sk-ant-admin01 before\n  // sk-ant-, sk-proj- before sk-). PEM block deliberately first so its\n  // multi-line span runs before any per-line patterns can fire.\n  /-----BEGIN[ ]+(?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----[\\s\\S]+?-----END[ ]+(?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----/g,\n  // JWT — exact 3-segment base64url. Dotted; the body floor of 4 chars per\n  // segment matches the minimum legal payload while skipping `a.b.c` noise.\n  /eyJ[A-Za-z0-9_-]{4,}\\.eyJ[A-Za-z0-9_-]{4,}\\.[A-Za-z0-9_-]{4,}/g,\n  // Azure Storage SAS — match the sig= component (URL-encoded base64).\n  /(?<=[?&]sig=)[A-Za-z0-9%+/]{20,}/g,\n  // Anthropic\n  /sk-ant-admin01-[A-Za-z0-9_-]{10,}/g, //   Anthropic admin keys (must precede sk-ant-)\n  /sk-ant-[A-Za-z0-9_-]{10,}/g, //           Anthropic regular\n  // OpenAI family + clones (sk- generic must come AFTER all sk-foo- variants)\n  /sk-proj-[A-Za-z0-9_-]{10,}/g, //  OpenAI project key (must precede sk- generic)\n  /sk-[A-Za-z0-9_-]{10,}/g, //       OpenAI / OpenRouter / DeepInfra / Together / DeepSeek\n  // Provider prefixes (alphabetized for maintainability)\n  /AIza[A-Za-z0-9_-]{35}/g, //       Google API key\n  /AKIA[A-Z0-9]{16}/g, //            AWS access key\n  /fw_[A-Za-z0-9]{20,}/g, //         Fireworks\n  /glpat-[A-Za-z0-9_-]{20}/g, //     GitLab PAT\n  /ghp_[A-Za-z0-9]{36}/g, //         GitHub PAT classic\n  /github_pat_[A-Za-z0-9_]{82}/g, // GitHub PAT fine-grained\n  /gsk_[A-Za-z0-9]{20,}/g, //        Groq\n  /hf_[A-Za-z0-9]{20,}/g, //         HuggingFace\n  /\\bpa-[A-Za-z0-9_-]{20,}/g, //     Voyage AI (word-boundary to skip CSS / kebab IDs)\n  /pcsk_[A-Za-z0-9_-]{20,}/g, //     Pinecone\n  /pplx-[A-Za-z0-9_-]{20,}/g, //     Perplexity\n  /r8_[A-Za-z0-9_-]{20,}/g, //       Replicate\n  /rk_live_[A-Za-z0-9]{20,}/g, //    Stripe restricted\n  /sk_live_[A-Za-z0-9]{20,}/g, //    Stripe secret\n  /sntrys_[A-Za-z0-9]{40,}/g, //     Sentry user auth\n  /xai-[A-Za-z0-9_-]{20,}/g, //      xAI (Grok)\n  /xox[bpasr]-[A-Za-z0-9-]{10,}/g, //Slack tokens\n  // Additional unique-prefix tokens with low false-positive risk\n  /npm_[A-Za-z0-9]{36}/g, //         npm access token\n  /SG\\.[A-Za-z0-9_-]{22}\\.[A-Za-z0-9_-]{43}/g, // SendGrid\n  /\\bSK[A-Za-z0-9]{32}\\b/g, //       Twilio API SID (word-boundary to skip CSS class noise)\n  /\\bkey-[a-f0-9]{32}\\b/g, //        Mailgun (hex-only narrows false positives)\n  /MT[A-Za-z0-9_-]{23}\\.[A-Za-z0-9_-]{6}\\.[A-Za-z0-9_-]{27}/g, // Discord bot\n  /\\b(?:sdk|mob)-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\\b/g, // LaunchDarkly\n];\n\n// `Bearer <token>` matched as its own first-class pattern so PARAM_PATTERN\n// doesn't have to handle the unusual `Authorization: Bearer xxx` shape\n// (no `:` or `=` between \"Bearer\" and the value — bare whitespace).\nconst BEARER_PATTERN = /\\b(Bearer\\s+)([A-Za-z0-9_\\-.+/=]{8,})/g;\n\n// Parametric: matches `key=value` and `key: value` (with optional quote\n// between the key and the separator, to handle JSON: `\"api_key\": \"...\"`)\n// in URLs, query strings, JSON-like bodies, HTTP headers. Captures the\n// prefix so we keep it visible while masking the value.\n//\n// `authorization` deliberately excluded — BEARER_PATTERN handles the\n// common `Authorization: Bearer xxx` shape. Including it here causes\n// double-masking (\"Authorization: *** ***\") after Bearer fires.\n// T5.4: keyword set expanded from 6 → 16 to cover the OAuth / JWT / generic\n// credential vocabulary surfaced by DR6 finding #4. `authorization`,\n// `auth`, `bearer` stay excluded — BEARER_PATTERN handles the\n// `Authorization: Bearer xxx` shape and including these here would\n// re-catch the post-BUILTIN-masked form (D71 prefix-preservation\n// contract) and double-mask to `***`.\n//\n// Value class includes `.` so JWT / `.env` / dotted base64url values\n// match; the callback skips already-masked values (containing the\n// `...` D71 separator) to preserve the BUILTIN prefix-mask result.\nconst PARAM_PATTERN =\n  /(\\b(?:access_token|api_key|api-key|client_secret|credential|credentials|id_token|jwt|password|private_key|refresh_token|secret|service_account|session_token|token|x-api-key)\\b[\"']?\\s*[:=]\\s*[\"']?)([A-Za-z0-9_\\-.+/]+)/gi;\n\nconst _extraPatterns: RegExp[] = [];\n\n/**\n * Register an extra pattern for `redactSecrets` to mask, on top of the built-in vendor set.\n *\n * Additive and irreversible for the life of the process: patterns accumulate in module scope,\n * builtins are never replaced or reordered, and there is no way to remove one. Registering the\n * same regex twice registers it twice.\n *\n * Throws immediately when the regex has no `/g` flag. That is not pedantry — `String.replace`\n * with a non-global regex substitutes only the FIRST match, so a pattern registered without it\n * would mask the first credential in a payload and let every later one through, which reads as\n * working.\n *\n * Extras run after the builtins and before the parametric `key=value` sweep, and each whole match\n * is replaced by `maskToken` of that match. Anchor and bound the pattern with care: a regex that\n * matches more than the secret masks more than the secret, and one that backtracks badly runs on\n * every string crossing an output boundary.\n *\n * Registering a pattern does not enable redaction. When `THEOKIT_REDACT_SECRETS` was off at\n * module load, `redactSecrets` returns its input untouched and extras never run.\n *\n * Also exposed publicly, and under semver, as `Security.addPattern` in `src/security.ts`; the\n * direct export here additionally reaches the semver-exempt `@theokit/sdk/internal/security`\n * sub-path.\n */\nexport function addPattern(re: RegExp): void {\n  if (!re.global) {\n    // A BARE Error here, deliberately, and this is the one place in the package where that is the\n    // right answer. `errors.ts` imports `redactSecrets` from this module for the anti-leak invariant\n    // on `providerError`, so this module must stay below it — importing ConfigurationError closes a\n    // cycle (measured: `madge --circular` reports `errors.ts > internal/security/redact.ts`).\n    //\n    // The typed error lives at the surface a consumer touches: `Security.addPattern` in\n    // `src/security.ts` validates first and throws ConfigurationError with a code. This throw is the\n    // backstop for the semver-exempt `@theokit/sdk/internal/security` sub-path.\n    throw new Error(\"addPattern: regex must have /g flag for replace-all semantics\");\n  }\n  _extraPatterns.push(re);\n}\n\n/**\n * Mask one string, keeping enough of it to be recognizable in a log.\n *\n * Under 18 characters the whole string becomes the literal `***`; the length is not preserved and\n * nothing of the input survives. From 18 characters up, the result is the first 6 characters, the\n * literal `...`, and the last 4 — so exactly 10 characters of the input are RETAINED IN CLEAR and\n * the middle is dropped. That is the trade the threshold encodes: short strings could be brute\n * forced from a partial, long ones cannot, and the surviving prefix is usually the vendor tag\n * (`sk-ant`, `ghp_de`) that tells an operator which credential misbehaved.\n *\n * Be clear about what this is and is not. It is a readability aid for logs, not an anonymizer and\n * not a security boundary. The retained prefix and suffix identify the credential's issuer and\n * often the credential itself to anyone who has seen it before, so a masked value still belongs in\n * a trusted log and not in a bug report or a support ticket.\n *\n * It masks whatever it is handed. There is no check that the argument is a secret, so calling it\n * on ordinary text mangles the text, and calling it on something the caller merely hopes is a\n * secret proves nothing about what leaked.\n *\n * `redactSecrets` applies it to the ENTIRE match of a pattern, not to a captured group. For a\n * match like `Bearer sk-ant-...` the first 6 characters retained are `Bearer`, not the key's\n * prefix.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/security` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function maskToken(token: string): string {\n  if (token.length < 18) return \"***\";\n  return `${token.slice(0, 6)}...${token.slice(-4)}`;\n}\n\n// issue #117 — the EXACT shape of a `maskToken` output (`slice(0,6)+\"...\"+slice(-4)`\n// = 6 chars, literal `...`, 4 chars). Used to detect a value PARAM_PATTERN would\n// otherwise re-mask, WITHOUT skipping a raw secret that merely contains `...`.\nconst MASK_SHAPE = /^.{6}\\.\\.\\..{4}$/s;\n\n// Coerce arbitrary input to a string for redaction. Returns `null`\n// sentinel when the value is null/undefined/non-stringifiable, so the\n// caller can short-circuit with `\"\"`. EC-7 fix: circular refs go through\n// the try/catch and produce the sentinel marker, never throwing.\nfunction coerceToString(value: unknown): string | null {\n  if (typeof value === \"string\") return value;\n  if (value === null || value === undefined) return null;\n  if (typeof value === \"object\") {\n    try {\n      const s = JSON.stringify(value);\n      return s === undefined ? null : s;\n    } catch {\n      return \"[unredactable: circular]\";\n    }\n  }\n  return String(value);\n}\n\n/**\n * Redact known credential patterns from `text`. Default behavior masks\n * builtins + extras + parametric `key=value` sinks.\n *\n * With `{ codeFile: true }` (D72), skips PARAM_PATTERN to avoid mangling\n * `.env.example`, schema JSON, or test fixtures that legitimately contain\n * prefix-like strings.\n *\n * Returns the redacted string. Coerces non-strings via JSON.stringify;\n * EC-7 fix (edge-case review): wraps in try/catch so circular references\n * never propagate — returns sentinel `\"[unredactable: circular]\"`.\n *\n * `null` and `undefined` return `\"\"`. When redaction was switched off at module load via\n * `THEOKIT_REDACT_SECRETS`, the coerced input is returned with no masking at all — the value is\n * still stringified, but nothing is removed from it.\n *\n * Masking is best-effort against a list of known shapes. A credential in a format no pattern\n * covers passes through unchanged, so a redacted string is not a string proven free of secrets.\n */\nexport function redactSecrets(text: unknown, opts?: { codeFile?: boolean }): string {\n  const coerced = coerceToString(text);\n  if (coerced === null) return \"\";\n  if (!REDACT_ENABLED) return coerced;\n\n  let s = coerced;\n  for (const re of BUILTIN_PATTERNS) {\n    s = s.replace(re, (m) => maskToken(m));\n  }\n  for (const re of _extraPatterns) {\n    s = s.replace(re, (m) => maskToken(m));\n  }\n  if (!opts?.codeFile) {\n    // Bearer first (preserves \"Bearer \" prefix, masks the token after).\n    // Must run before PARAM_PATTERN so the bare-whitespace shape doesn't\n    // get mis-handled as a value.\n    s = s.replace(BEARER_PATTERN, (_, prefix: string) => `${prefix}***`);\n    // T5.4: skip if value already contains the D71 bucket-mask separator\n    // (`...`) — BUILTIN ran first and produced a prefix-preserved mask;\n    // re-masking would lose the prefix and degrade debuggability.\n    s = s.replace(PARAM_PATTERN, (whole, prefix: string, value: string) => {\n      // issue #117 — skip ONLY when the value is already a mask that a BUILTIN\n      // pattern produced (maskToken's exact `6chars...4chars` shape), so we don't\n      // re-mask and lose the prefix. The old `value.includes(\"...\")` was too broad:\n      // a REAL secret that happens to contain `...` (e.g. `L_-cxw-.2UI_..._`) was\n      // skipped and LEAKED. The mask shape is exact (maskToken: slice(0,6)+\"...\"+\n      // slice(-4)), so a raw secret with `...` elsewhere is now masked.\n      if (MASK_SHAPE.test(value)) return whole;\n      return `${prefix}***`;\n    });\n  }\n  return s;\n}\n\n/**\n * Test-only helper exported for `_test-reset.ts`. NOT included in the\n * `index.ts` barrel — vitest setup imports the dedicated module via\n * explicit path to discourage production callers.\n *\n * @internal\n */\nexport function _resetForTests(opts: { enabled?: boolean; clearExtras?: boolean }): void {\n  if (opts.enabled !== undefined) REDACT_ENABLED = opts.enabled;\n  if (opts.clearExtras === true) _extraPatterns.length = 0;\n}\n\n/**\n * T5.4 — Test-only count of BUILTIN_PATTERNS. Exposed so the count-floor\n * assertion can run without re-deriving the array shape in test land.\n * NOT included in the public barrel.\n *\n * @internal\n */\nexport function __TESTING__BUILTIN_PATTERN_COUNT(): number {\n  return BUILTIN_PATTERNS.length;\n}\n"]}

package/dist/chunk-7NQ7HJ3E.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/sandbox/shell-escape.ts","../src/sandbox/types.ts","../src/sandbox/local-sandbox.ts"],"names":["TheokitAgentError","ConfigurationError","execFile","resolveChildEnv","path","mkdir","dirname","fsWriteFile"],"mappings":"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","file":"chunk-7NQ7HJ3E.cjs","sourcesContent":["/**\n * POSIX shell escaping for values interpolated into a `SandboxBackend.execute`\n * command string. `execute` runs via `/bin/sh -c`, so any untrusted value\n * (repo URL, ref, path) MUST be quoted to prevent command injection.\n *\n * @internal\n */\n\n/** Wrap `arg` in single quotes, escaping embedded single quotes (`'\\''`). */\nexport function shellEscapePosix(arg: string): string {\n  return `'${arg.replace(/'/g, \"'\\\\''\")}'`;\n}\n","/**\n * Sandbox backend protocol — pluggable execution environment for agent tools.\n *\n * Per ADR D1: only 2 abstract methods (`execute` + `uploadFile`). All\n * higher-level operations are derived on the base class. New backends\n * (Docker, Firecracker, E2B) only implement those 2 methods.\n *\n * @public\n */\n\nimport { ConfigurationError, TheokitAgentError } from \"../errors.js\";\nimport type { EnvPolicy } from \"../types/env-policy.js\";\nimport { shellEscapePosix } from \"./shell-escape.js\";\n\n/**\n * What a {@link SandboxBackend} returns for one command.\n *\n * `exitCode` is a coarse signal rather than the child's real exit status: the backends in this\n * package report `0` on success, `124` on timeout, and `1` for everything else — including a command\n * that exited with its own non-zero code. Read `timedOut` to tell a killed command from a failed one,\n * and `stderr` for the reason; branching on a specific exit code will not work here.\n *\n * `stdout` and `stderr` are truncated independently at `SandboxConfig.maxOutputBytes`, with a\n * trailing `...(truncated)` marker. Neither is safe to parse as a complete document without checking\n * for it.\n */\nexport interface ExecuteResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n  timedOut: boolean;\n}\n\n/**\n * Construction-time settings shared by every {@link SandboxBackend}. All fields are optional and the\n * base constructor fills them in, so `{}` is a valid config: `workDir` `/tmp`, `timeoutMs` 30000,\n * `maxOutputBytes` 5 MiB, `env` `\"inherit-scrubbed\"`.\n *\n * `workDir` is the child process's cwd and the base a relative `uploadFile` path resolves against. It\n * is not a boundary — under `LocalSandbox` nothing stops a command, or an absolute path, from leaving\n * it. Only `LinuxSandbox` makes it enforceable.\n *\n * `timeoutMs` is the default for every call; `execute(command, { timeoutMs })` overrides it per\n * command. On expiry the child is killed and the result carries `timedOut: true` with `exitCode`\n * 124 — the partial output collected so far is still returned.\n */\nexport interface SandboxConfig {\n  workDir?: string;\n  timeoutMs?: number;\n  maxOutputBytes?: number;\n  /**\n   * #54 — env inherit/scrub policy for the executed command's child process.\n   * Defaults to `\"inherit-scrubbed\"` (drop secret-like vars: `*KEY*`, `*SECRET*`,\n   * `*TOKEN*`, `*PASSWORD*`, `*_AUTH*`). Pass `\"all\"` to restore full inheritance\n   * or `\"core\"` for a minimal safe allowlist.\n   */\n  env?: EnvPolicy;\n}\n\n/**\n * A backend refused a command on policy grounds — the environment works, and it said no. Carries a\n * stable `code: \"sandbox_security\"` for callers that prefer not to match on the class.\n *\n * Nothing in this package throws it, which is worth knowing before you write a `catch` for it:\n * `LocalSandbox` and `LinuxSandbox` report a refusal through {@link ExecuteResult} (non-zero\n * `exitCode`, reason on `stderr`), and a write blocked under confinement surfaces as a plain `Error`\n * from `uploadFile`. This type exists so a custom backend that must reject a command BEFORE spawning\n * anything — a container or VM runner enforcing its own policy — can do so in the protocol's\n * vocabulary instead of inventing an error of its own.\n */\nexport class SandboxSecurityError extends TheokitAgentError {\n  override readonly name = \"SandboxSecurityError\";\n  override readonly code = \"sandbox_security\" as const;\n  constructor(message: string) {\n    // not retryable: a refused command is refused every time; retrying re-asks the same question\n    super(message, { code: \"sandbox_security\", isRetryable: false });\n  }\n}\n\n/**\n * A backend cannot be used at all: its runtime is missing or unusable. The distinction from\n * {@link SandboxSecurityError} is which side failed — there the sandbox worked and denied the\n * command, here there is no sandbox. Carries `code: \"sandbox_not_available\"`.\n *\n * Nothing in this package throws it either, and that is a position rather than an oversight:\n * `createSandboxBackend` treats a missing bubblewrap as a degradation, warns once, and hands back an\n * unconfined `LocalSandbox`. Throw this instead from a backend that must never silently run outside\n * its isolation.\n */\nexport class SandboxNotAvailableError extends TheokitAgentError {\n  override readonly name = \"SandboxNotAvailableError\";\n  override readonly code = \"sandbox_not_available\" as const;\n  constructor(message: string) {\n    // not retryable: a missing runtime does not appear on a second attempt\n    super(message, { code: \"sandbox_not_available\", isRetryable: false });\n  }\n}\n\n/**\n * The execution capability handed to an agent tool, and the extension point for new environments.\n *\n * A backend implements exactly two methods, `execute` and `uploadFile`. Everything else here —\n * `readFile`, `glob`, `grep`, `listDir` — is derived from `execute` by shelling out `cat`, `find`,\n * `grep` and `ls`, so a subclass that overrides `execute` alone inherits confined reads, searches and\n * listings for free. It does not inherit confined writes: `writeFile` delegates to `uploadFile`, and\n * that is the second override `LinuxSandbox` needs.\n *\n * Choosing one: `LocalSandbox` runs the command on the host with no isolation and suits code you\n * already trust; `LinuxSandbox` adds kernel confinement where bubblewrap is available;\n * `createSandboxBackend` probes and picks between them, and is the right entry point unless you have\n * a reason to pin one. For genuinely untrusted code you want a container or VM backend, which this\n * package does not ship — write it against these two methods.\n *\n * Because the derived helpers assemble shell command lines (arguments escaped for POSIX `sh`), a\n * backend whose `execute` is not a POSIX shell must override them as well.\n */\nexport abstract class SandboxBackend {\n  protected config: SandboxConfig;\n\n  constructor(config: SandboxConfig = {}) {\n    this.config = {\n      workDir: config.workDir ?? \"/tmp\",\n      timeoutMs: config.timeoutMs ?? 30_000,\n      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024,\n      // #54 — preserve the env policy so backends can scrub secrets.\n      env: config.env ?? \"inherit-scrubbed\",\n    };\n  }\n\n  abstract execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult>;\n\n  abstract uploadFile(path: string, content: string | Buffer): Promise<void>;\n\n  async readFile(path: string): Promise<string> {\n    const result = await this.execute(`cat ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) {\n      throw new Error(`readFile failed: ${result.stderr}`);\n    }\n    return result.stdout;\n  }\n\n  async writeFile(path: string, content: string): Promise<void> {\n    await this.uploadFile(path, content);\n  }\n\n  async glob(pattern: string, cwd?: string): Promise<string[]> {\n    const dir = cwd ?? this.config.workDir ?? \".\";\n    const result = await this.execute(\n      `find ${this.shellEscape(dir)} -name ${this.shellEscape(pattern)} -type f 2>/dev/null`,\n    );\n    this.assertCommandRan(\"glob\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async grep(pattern: string, path?: string): Promise<string[]> {\n    const target = path ?? \".\";\n    const result = await this.execute(\n      `grep -rn ${this.shellEscape(pattern)} ${this.shellEscape(target)} 2>/dev/null`,\n    );\n    // `grep` exits 1 for NO MATCH and >= 2 for an error, so a 1 is an answer and is not asserted on.\n    if (result.exitCode !== 1) this.assertCommandRan(\"grep\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async listDir(path: string): Promise<string[]> {\n    const result = await this.execute(`ls -1 ${this.shellEscape(path)}`);\n    this.assertCommandRan(\"listDir\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  /**\n   * Turns \"the command did not run\" into an error instead of an empty array.\n   *\n   * `glob`, `grep` and `listDir` used to `return []` on any non-zero exit, so a search that could not\n   * run reported the same thing as a search that found nothing — opposite facts, one normal and one\n   * meaning the agent is looking at a filesystem it cannot read. That is the failure mode a backend\n   * whose `execute` is not a POSIX shell hits, which this class's own docblock warns about in prose\n   * and could not enforce.\n   *\n   * A genuine no-match is still `[]`: `find` exits 0 with empty output, and `grep`'s exit 1 is\n   * checked by its caller before this is reached.\n   */\n  private assertCommandRan(operation: string, result: ExecuteResult): void {\n    if (result.exitCode === 0) return;\n    throw new ConfigurationError(\n      `${operation} failed (exit ${String(result.exitCode)}): ${result.stderr.trim() || \"no stderr\"}. ` +\n        `The derived helpers shell out to POSIX \\`cat\\`/\\`find\\`/\\`grep\\`/\\`ls\\` — a backend whose ` +\n        `execute() is not a POSIX shell must override them.`,\n      { code: \"sandbox_derived_helper_failed\" },\n    );\n  }\n\n  protected truncateOutput(output: string): string {\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    if (Buffer.byteLength(output) > max) {\n      return `${output.slice(0, max)}\\n...(truncated)`;\n    }\n    return output;\n  }\n\n  private shellEscape(arg: string): string {\n    return shellEscapePosix(arg);\n  }\n}\n\n/**\n * A backend OR a per-request resolver of one — mirrors `FilesystemProvider` / `InteractiveProvider`.\n * A resolver runs at tool-execution time (request scope), so a multi-tenant / multi-role agent gets a\n * distinct sandbox per request without a shared mutable one. This is how a tool takes execution as an\n * INJECTED capability: the same tool runs on a local sandbox, a container/E2B backend (cluster/web), or\n * any future backend, with no direct `child_process` import.\n *\n * @public\n */\nexport type SandboxProvider<Ctx = unknown> =\n  | SandboxBackend\n  | ((ctx: Ctx) => SandboxBackend | Promise<SandboxBackend>);\n\n/** Resolve a {@link SandboxProvider} to a concrete backend for `ctx`. */\nexport async function resolveSandbox<Ctx>(\n  provider: SandboxProvider<Ctx>,\n  ctx: Ctx,\n): Promise<SandboxBackend> {\n  return provider instanceof SandboxBackend ? provider : provider(ctx);\n}\n","/**\n * LocalSandbox — subprocess-based execution. **This is NOT an isolation\n * boundary.** It runs the command via `/bin/sh -c` in the SAME OS as the host\n * with the host's filesystem and network fully reachable — it provides NO\n * process, filesystem, or network isolation. Its only safety affordances are:\n *   - a wall-clock timeout (kills a runaway command),\n *   - an output-size cap (bounds memory), and\n *   - env scrubbing (#54): secret-like parent env vars (`*KEY*`/`*SECRET*`/\n *     `*TOKEN*`/`*PASSWORD*`/`*_AUTH*`) are dropped from the child by default\n *     (`SandboxConfig.env`), so a shell tool cannot exfiltrate host secrets via\n *     the environment.\n *\n * For real isolation (untrusted code), use a container/VM backend — NOT this.\n *\n * @public\n */\n\nimport { execFile } from \"node:child_process\";\nimport { writeFile as fsWriteFile, mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport { resolveChildEnv } from \"../internal/runtime/lifecycle/env-policy.js\";\nimport { type ExecuteResult, SandboxBackend, type SandboxConfig } from \"./types.js\";\n\n/**\n * Runs a command with `/bin/sh -c` on the host. NOT an isolation boundary — the\n * module note above states exactly what it does and does not protect.\n *\n *   const sandbox = new LocalSandbox({ workDir: \"/srv/repo\", timeoutMs: 10_000 });\n *   const { stdout, exitCode, timedOut } = await sandbox.execute(\"ls -1\");\n *\n * Needs a POSIX host with `/bin/sh`. Every helper inherited from\n * {@link SandboxBackend} — `readFile`, `glob`, `grep`, `listDir` — is built on\n * this `execute`, so they inherit that requirement too.\n *\n * How it fails: `execute` NEVER rejects. Every outcome, including a failure to\n * spawn, comes back as an {@link ExecuteResult}; read `timedOut` first\n * (`true` implies `exitCode` 124) and `stderr` for the reason. `uploadFile` DOES\n * reject, with the raw `node:fs` error, on a bad path or missing permission.\n *\n * Traps:\n *  - `exitCode` is not the child's exit code. It is 0, 124 (timed out) or 1 — a\n *    command that exits 3 is reported as 1, so branching on a specific code does\n *    not work here.\n *  - Output beyond `maxOutputBytes` (default 5 MiB) makes Node kill the child.\n *    The result is `exitCode: 1` and `timedOut: false`, with the cut stream\n *    carrying the `...(truncated)` marker described on `ExecuteResult` (#363).\n *    Since `exitCode` is 1 either way, that marker is what tells a lost-output\n *    result from a command that genuinely failed.\n *  - `uploadFile` resolves a relative path against `workDir` but does not contain\n *    it: an absolute path, or one containing `..`, writes wherever the process\n *    can. `workDir` is a starting directory, not a jail.\n *  - Secret-like parent env vars are dropped by default. Passing\n *    `env: \"all\"` in {@link SandboxConfig} puts the host's API keys back within\n *    reach of any command the agent runs.\n */\nexport class LocalSandbox extends SandboxBackend {\n  constructor(config: SandboxConfig = {}) {\n    super(config);\n  }\n\n  async execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult> {\n    const timeout = opts?.timeoutMs ?? this.config.timeoutMs ?? 30_000;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n\n    return new Promise<ExecuteResult>((resolve) => {\n      const child = execFile(\n        \"/bin/sh\",\n        [\"-c\", command],\n        {\n          cwd: this.config.workDir,\n          timeout,\n          maxBuffer: max,\n          encoding: \"utf-8\",\n          // #54 — scrub secret-like host env vars from the child by default.\n          env: resolveChildEnv({ policy: this.config.env }),\n        },\n        (error, stdout, stderr) => {\n          resolve(this.buildResult(error, stdout ?? \"\", stderr ?? \"\"));\n        },\n      );\n\n      // Safety: if child somehow doesn't callback\n      child.on(\"error\", () => {\n        resolve({ stdout: \"\", stderr: \"spawn error\", exitCode: 1, timedOut: false });\n      });\n    });\n  }\n\n  private buildResult(error: Error | null, stdout: string, stderr: string): ExecuteResult {\n    const timedOut = error !== null && \"killed\" in error && (error as { killed: boolean }).killed;\n    // #363 — the ONLY reliable signal that output was lost. Node caps the buffer AT `maxBuffer`, so\n    // for ASCII output the string comes back exactly at the cap and `truncateOutput`'s `> max` test\n    // never fires; a length comparison cannot tell a cut document from a complete one that happens\n    // to be that long. The child being killed for overflow can.\n    const overflowed =\n      error !== null && (error as { code?: unknown }).code === \"ERR_CHILD_PROCESS_STDIO_MAXBUFFER\";\n    return {\n      stdout: this.markIfCut(this.truncateOutput(stdout), overflowed),\n      stderr: this.markIfCut(this.truncateOutput(stderr), overflowed),\n      exitCode: timedOut ? 124 : error ? 1 : 0,\n      timedOut,\n    };\n  }\n\n  /**\n   * Append the `...(truncated)` marker `ExecuteResult` tells callers to branch on, when the child\n   * was killed for exceeding `maxOutputBytes` and this stream is the one sitting at the cap.\n   *\n   * `truncateOutput` has already run, so an output it marked is left alone rather than marked\n   * twice. Node does not say WHICH stream overflowed, so the stream at the cap is the one that\n   * lost data — the other, being shorter, is complete.\n   */\n  private markIfCut(output: string, overflowed: boolean): string {\n    if (!overflowed) return output;\n    if (output.endsWith(\"...(truncated)\")) return output;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    return Buffer.byteLength(output) >= max ? `${output}\\n...(truncated)` : output;\n  }\n\n  async uploadFile(path: string, content: string | Buffer): Promise<void> {\n    const fullPath = path.startsWith(\"/\") ? path : `${this.config.workDir}/${path}`;\n    await mkdir(dirname(fullPath), { recursive: true });\n    await fsWriteFile(fullPath, content, \"utf-8\");\n  }\n}\n"]}

package/dist/chunk-B5MHRQJZ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/errors-base.ts","../src/internal/error-mappers/default-retriable.ts","../src/task-errors.ts","../src/errors.ts"],"names":[],"mappings":"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","file":"chunk-B5MHRQJZ.js","sourcesContent":["/**\n * The root of the SDK error hierarchy, and the two types it is built from.\n *\n * A LEAF module on purpose: every other error in this package extends `TheokitAgentError`, and\n * `errors.ts` re-exports the ones that live in their own files. If the root lived in that catalogue,\n * each sibling would import it from a file that imports the sibling — a cycle madge reports and\n * `tests/architecture/no-cycles-at-all.test.ts` fails on. `types/messages-base.ts` exists for the\n * same reason, one layer over.\n *\n * Re-exported from `errors.ts`, so `@theokit/sdk/errors` is unchanged and consumers keep catching\n * `TheokitAgentError` from where the README tells them to.\n *\n * NOTE ON THE MODULE TAG: this header deliberately carries no internal-visibility tag, and does not\n * even name one — TypeScript attaches a file-leading docblock to the FIRST declaration below it, and\n * `stripInternal: true` (tsconfig.base) then deletes that declaration from the emitted `.d.ts`.\n * `tsc --noEmit` stays clean and the declaration rollup fails with `\"X\" is not exported by \"...\"`.\n * Measured twice on this file on 2026-09-01: once with the tag, and again when the comment\n * EXPLAINING the trap quoted the tag verbatim and re-armed it.\n */\n\n/**\n * Finite, machine-readable error codes for provider-originated errors\n * (ADR D66). Consumers can `switch (err.metadata?.code)` exhaustively\n * — adding a new variant is an explicit decision + test coverage.\n *\n * @public\n */\nexport type ErrorCode =\n  | \"rate_limit\"\n  | \"auth_failed\"\n  | \"invalid_request\"\n  | \"timeout\"\n  | \"server_error\"\n  | \"context_too_long\"\n  | \"content_filtered\"\n  | \"model_unavailable\"\n  | \"network\"\n  | \"quota_exceeded\"\n  | \"unknown\";\n/**\n * Structured context for errors that originated from a provider HTTP\n * call (ADR D65). Lets callers retry with the right backoff (`retryAfter`),\n * surface actionable diagnostics (`provider`, `endpoint`), and inspect the\n * raw response body when needed (`raw`, capped at ~2KB by the mapper).\n *\n * @public\n */\nexport interface ErrorMetadata {\n  /** Provider canonical name (e.g., `\"anthropic\"`, `\"openai\"`, `\"openrouter\"`, `\"gemini\"`). */\n  provider: string;\n  /** HTTP endpoint that failed (e.g., `\"/v1/messages\"`, `\"/v1/chat/completions\"`). */\n  endpoint: string;\n  /** Machine-readable error code (finite enum). */\n  code: ErrorCode;\n  /** HTTP status code if applicable. */\n  statusCode?: number;\n  /** Seconds to wait before retry, per provider's `retry-after` header (numeric form only). */\n  retryAfter?: number;\n  /** Raw response body for debugging (truncated to ~2KB by the mapper). */\n  raw?: unknown;\n}\n/**\n * Base class for all errors thrown by `@theokit/sdk`.\n *\n * Use `isRetryable` to drive retry/backoff logic. `code` and `protoErrorCode`\n * are populated for server-originated errors when available. `metadata`\n * (ADR D65) carries structured `{ provider, endpoint, code, ... }` when\n * the error originated from a provider HTTP call.\n *\n * @public\n */\nexport class TheokitAgentError extends Error {\n  override readonly name: string = \"TheokitAgentError\";\n  readonly isRetryable: boolean;\n  readonly code?: string;\n  readonly protoErrorCode?: string;\n  readonly metadata?: ErrorMetadata;\n\n  constructor(\n    message: string,\n    options: {\n      isRetryable?: boolean;\n      code?: string;\n      protoErrorCode?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    } = {},\n  ) {\n    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);\n    this.isRetryable = options.isRetryable ?? false;\n    if (options.code !== undefined) this.code = options.code;\n    if (options.protoErrorCode !== undefined) this.protoErrorCode = options.protoErrorCode;\n    if (options.metadata !== undefined) this.metadata = options.metadata;\n  }\n}\n","/**\n * Default retryability verdict for an `AgentRunError` code.\n *\n * Extracted from `errors.ts` (G8 LoC budget — SRP). The parameter is typed\n * `string` (not the `AgentRunErrorCode` union) deliberately: this is a leaf\n * with NO import back into `errors.ts`, so it cannot form an import cycle. The\n * `default` branch makes the behavior identical to the typed switch.\n *\n * @internal\n */\nexport function defaultRetriableForCode(code: string): boolean {\n  switch (code) {\n    case \"rate_limit\":\n    case \"timeout\":\n    case \"server_error\":\n    case \"network\":\n    case \"provider_unreachable\":\n      return true;\n    default:\n      return false;\n  }\n}\n","/**\n * Errors raised by the Task API (`src/task.ts`).\n *\n * One actor, one module: these three are about task identity and task lifecycle, and they change\n * when the Task surface changes rather than when the agent-run surface does. They extend\n * `TheokitAgentError` like every other error in this package — the hierarchy is the contract, and\n * `tests/lint/every-error-is-in-the-hierarchy.test.ts` enforces it wherever the class lives.\n *\n * Re-exported from `errors.ts`, so `@theokit/sdk/errors` still names every error in one place.\n *\n * NOTE ON THE MODULE TAG: this header deliberately carries no internal-visibility tag, and does not\n * even name one — TypeScript attaches a file-leading docblock to the FIRST declaration below it, and\n * `stripInternal: true` (tsconfig.base) then deletes that declaration from the emitted `.d.ts`.\n * `tsc --noEmit` stays clean and the declaration rollup fails with `\"X\" is not exported by \"...\"`.\n * Measured twice on this file on 2026-09-01: once with the tag, and again when the comment\n * EXPLAINING the trap quoted the tag verbatim and re-armed it.\n */\n\nimport { TheokitAgentError } from \"./errors-base.js\";\n\n/**\n * Thrown when a user-supplied task ID violates the grammar\n * `^[a-z0-9][a-z0-9_-]*$` (D368) OR starts with a reserved adapter\n * prefix (`wf-` / `b-` / `cron-`, EC-5).\n *\n * @public\n */\nexport class InvalidTaskIdError extends TheokitAgentError {\n  override readonly name: string = \"InvalidTaskIdError\";\n  readonly taskId: string;\n\n  constructor(message: string, taskId: string, options: { cause?: unknown } = {}) {\n    super(message, {\n      ...options,\n      isRetryable: false,\n      code: \"invalid_task_id\",\n    });\n    this.taskId = taskId;\n  }\n}\n\n/**\n * Thrown when `Task.subscribe(id)` is called for a task that has been\n * evicted, never submitted, or evicted after retention (D373).\n *\n * @public\n */\nexport class TaskNotFoundError extends TheokitAgentError {\n  override readonly name: string = \"TaskNotFoundError\";\n  readonly taskId: string;\n\n  constructor(taskId: string, options: { cause?: unknown } = {}) {\n    super(`Task not found: ${taskId}`, {\n      ...options,\n      isRetryable: false,\n      code: \"task_not_found\",\n    });\n    this.taskId = taskId;\n  }\n}\n\n/**\n * Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud\n * task observability is deferred until Theo PaaS GA.\n *\n * @public\n */\nexport class UnsupportedTaskOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedTaskOperationError\";\n  readonly operation: string;\n\n  constructor(operation: string, options: { cause?: unknown } = {}) {\n    super(\n      `Task operation \"${operation}\" is not supported on CloudAgent (pre-release; see ADR D370)`,\n      {\n        ...options,\n        isRetryable: false,\n        code: \"task_op_unsupported\",\n      },\n    );\n    this.operation = operation;\n  }\n}\n","/**\n * Published as `@theokit/sdk/errors`.\n */\n// The hierarchy ROOT lives in a leaf module so a sibling error module can extend it without\n// importing this catalogue — which is a cycle, since this file re-exports those siblings. Same\n// remedy as `types/messages-base.ts` for the same shape. Re-exported below, so\n// `@theokit/sdk/errors` is unchanged.\n\nimport { type ErrorCode, type ErrorMetadata, TheokitAgentError } from \"./errors-base.js\";\n\nexport type { ErrorCode, ErrorMetadata };\n// Re-exported by NAME rather than with `export ... from`, and the difference is not cosmetic:\n// rollup-plugin-dts refused the combined form with `\"ErrorCode\" is not exported by\n// \"src/errors-base.ts\"` while `tsc --noEmit` was clean — the same class of failure\n// `StructuredOutputError` below records, and the reason the declaration rollup has to be run\n// before believing a split is done.\nexport { TheokitAgentError };\n\nimport { readEnv } from \"./internal/env.js\";\nimport { defaultRetriableForCode } from \"./internal/error-mappers/default-retriable.js\";\nimport { redactSecrets } from \"./internal/security/redact.js\";\nimport type { RunOperation } from \"./types/run.js\";\n\n/**\n * T1.1 — closed literal union for `AgentRunError.code`. The previous\n * `(string & {})` escape hatch let arbitrary strings slip into the type\n * surface and defeated exhaustive `switch (code)` discrimination. This is\n * the canonical closed form. `AgentRunErrorCode` is re-aliased below for\n * source-level back-compat.\n *\n * Superset of {@link ErrorCode}, extended with codes that do NOT originate from a\n * provider HTTP response (Production-Readiness #3, ADR D311):\n *\n * - `quota_exceeded` — billing limit hit (provider 402 or signalled error)\n * - `tool_runtime_error` — custom tool handler threw inside dispatch\n * - `aborted` — caller's `AbortSignal` fired (Phase 4)\n * - `invalid_model` — model id rejected by provider (400 \"model not found\")\n * - `safety_blocked` — provider safety filter blocked req or resp\n * - `provider_unreachable` — DNS/TCP/timeout/5xx at transport boundary\n *\n * Adding a new code: append the literal here AND audit every `switch (err.code)`\n * in callers. Type-checker enforces the audit via the `default: assertNever(code)`\n * convention.\n *\n * @public\n */\nexport type KnownAgentRunErrorCode =\n  | ErrorCode\n  | \"quota_exceeded\"\n  | \"tool_runtime_error\"\n  | \"aborted\"\n  | \"invalid_model\"\n  | \"safety_blocked\"\n  | \"provider_unreachable\";\n\n/**\n * Back-compat alias of {@link KnownAgentRunErrorCode}. Pre-T1.1 callers that\n * imported `AgentRunErrorCode` keep working; new code SHOULD prefer\n * `KnownAgentRunErrorCode` to make the closed-union intent explicit.\n *\n * @public\n */\nexport type AgentRunErrorCode = KnownAgentRunErrorCode;\n\n/** Snapshot of every known code at runtime — used by the boundary coercer. */\nconst KNOWN_AGENT_RUN_ERROR_CODES = new Set<string>([\n  \"rate_limit\",\n  \"auth_failed\",\n  \"invalid_request\",\n  \"timeout\",\n  \"server_error\",\n  \"context_too_long\",\n  \"content_filtered\",\n  \"model_unavailable\",\n  \"network\",\n  \"unknown\",\n  \"quota_exceeded\",\n  \"tool_runtime_error\",\n  \"aborted\",\n  \"invalid_model\",\n  \"safety_blocked\",\n  \"provider_unreachable\",\n]);\n\n/**\n * T1.1 boundary helper — coerce an arbitrary string (typically arriving from\n * a downstream `RunErrorDetail.code` or a deserialized cloud response) into a\n * `KnownAgentRunErrorCode`.\n *\n * A string that is not one of the known codes collapses to `\"unknown\"`, and so\n * does `undefined` — the parameter is optional precisely so a caller can forward\n * an absent `code` without a guard. The closed type contract therefore holds at\n * the boundary without forcing every caller to switch.\n *\n * This is the migration path the 4.x release notes point at for code that used\n * to rely on `AgentRunErrorCode` being an open string union.\n *\n * @public\n */\nexport function coerceToKnownAgentRunErrorCode(code: string | undefined): KnownAgentRunErrorCode {\n  if (code !== undefined && KNOWN_AGENT_RUN_ERROR_CODES.has(code)) {\n    return code as KnownAgentRunErrorCode;\n  }\n  return \"unknown\";\n}\n\n/**\n * Invalid API key, not logged in, insufficient permissions.\n *\n * @public\n */\nexport class AuthenticationError extends TheokitAgentError {\n  override readonly name: string = \"AuthenticationError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Too many requests or usage limits exceeded.\n *\n * @public\n */\nexport class RateLimitError extends TheokitAgentError {\n  override readonly name: string = \"RateLimitError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: true });\n  }\n}\n\n/**\n * Invalid model, bad request parameters, malformed options.\n *\n * @public\n */\nexport class ConfigurationError extends TheokitAgentError {\n  override readonly name: string = \"ConfigurationError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Thrown when creating a cloud agent for a repo whose SCM provider is not\n * connected. Use `helpUrl` to point the user at the right reconnect flow.\n *\n * @public\n */\nexport class IntegrationNotConnectedError extends ConfigurationError {\n  override readonly name: string = \"IntegrationNotConnectedError\";\n  readonly provider: string;\n  readonly helpUrl: string;\n\n  constructor(\n    message: string,\n    options: {\n      provider: string;\n      helpUrl: string;\n      code?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, options);\n    this.provider = options.provider;\n    this.helpUrl = options.helpUrl;\n  }\n}\n\n/**\n * Service unavailable, timeout, transport-level failure.\n *\n * @public\n */\nexport class NetworkError extends TheokitAgentError {\n  override readonly name: string = \"NetworkError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: true });\n  }\n}\n\n/**\n * Catch-all for unclassified server or runtime errors.\n *\n * @public\n */\nexport class UnknownAgentError extends TheokitAgentError {\n  override readonly name: string = \"UnknownAgentError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Thrown by `Agent.prompt` (and helpers that go through `run.wait()`) when\n * the option `{ throwOnError: true }` is set and the run terminates with\n * `status: 'error'`. Carries the structured `RunResult.error` fields so\n * callers can `catch` once and branch on `code` / `provider` instead of\n * unwrapping the run.\n *\n * Extends {@link TheokitAgentError} per ADR D65 — no new hierarchy.\n *\n * @example\n *   try {\n *     await Agent.prompt(msg, { apiKey, model, throwOnError: true });\n *   } catch (err) {\n *     if (err instanceof AgentRunError && err.code === 'auth_failed') {\n *       // bad key\n *     }\n *   }\n *\n * @public\n */\nexport class AgentRunError extends TheokitAgentError {\n  override readonly name: string = \"AgentRunError\";\n  readonly provider?: string;\n  readonly raw?: string;\n  /** Provider's request id (`x-request-id` / `request-id` header). Useful for support tickets. */\n  readonly requestId?: string;\n  /** SDK conversation id this error was raised inside. */\n  readonly conversationId?: string;\n\n  constructor(\n    message: string,\n    options: {\n      code: AgentRunErrorCode;\n      provider?: string;\n      raw?: string;\n      requestId?: string;\n      conversationId?: string;\n      retriable?: boolean;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      code: options.code,\n      cause: options.cause,\n      metadata: options.metadata,\n      // D311: most AgentRunErrors are not retriable (auth, validation, abort).\n      // Provider mappers (D314) override per-status — explicit `retriable` wins\n      // over the implicit default when supplied.\n      isRetryable: options.retriable ?? defaultRetriableForCode(options.code),\n    });\n    if (options.provider !== undefined) this.provider = options.provider;\n    if (options.raw !== undefined) this.raw = options.raw;\n    if (options.requestId !== undefined) this.requestId = options.requestId;\n    if (options.conversationId !== undefined) this.conversationId = options.conversationId;\n  }\n\n  /**\n   * Production-Readiness #3 (ADR D311): alias for `isRetryable` exposed as\n   * `retriable` to match the handoff contract. Future v2 will deprecate\n   * `isRetryable` in favor of this.\n   */\n  get retriable(): boolean {\n    return this.isRetryable;\n  }\n\n  /**\n   * D312: provider's `Retry-After` header in **milliseconds**. Mappers store\n   * the header value (seconds) in `metadata.retryAfter`; this getter\n   * multiplies by 1000 so the result composes with `Date.now()`/`setTimeout`.\n   *\n   * Returns `undefined` when no hint was provided. `0` is a legitimate value\n   * — use `=== undefined` check rather than truthy check.\n   */\n  get retryAfterMs(): number | undefined {\n    if (this.metadata?.retryAfter === undefined) return undefined;\n    return this.metadata.retryAfter * 1000;\n  }\n\n  /**\n   * D313 + T1.5: alias for `metadata.raw`. Provider response body for\n   * debugging. T1.5 wraps the value in `redactSecrets` at the getter\n   * boundary so secret-shaped substrings (`sk-...`, Bearer JWTs, etc.) are\n   * stripped before reaching the caller. Available but NEVER serialized\n   * into `.message` (anti-leak invariant).\n   */\n  get providerError(): unknown {\n    const raw = this.metadata?.raw;\n    if (raw === undefined) return undefined;\n    if (typeof raw === \"string\") return redactSecrets(raw);\n    // Non-string raw (object/buffer) — stringify then redact.\n    try {\n      return redactSecrets(JSON.stringify(raw));\n    } catch {\n      return redactSecrets(String(raw));\n    }\n  }\n\n  /**\n   * T1.5 — sanitized JSON form. `metadata.raw` is OMITTED by default; opt\n   * in via `THEOKIT_DEBUG_RAW_ERRORS=1` to surface the (redacted) raw\n   * payload for diagnostics. Every other field stays accessible.\n   *\n   * The single env-var gate is read each call so operators can toggle at\n   * runtime without restarting the process.\n   */\n  toJSON(): Record<string, unknown> {\n    const json: Record<string, unknown> = {\n      name: this.name,\n      message: this.message,\n      isRetryable: this.isRetryable,\n    };\n    addOptionalFields(json, this);\n    const safeMeta = sanitizeMetadata(this.metadata);\n    if (safeMeta !== undefined) json.metadata = safeMeta;\n    return json;\n  }\n}\n\nfunction addOptionalFields(json: Record<string, unknown>, err: AgentRunError): void {\n  if (err.code !== undefined) json.code = err.code;\n  if (err.provider !== undefined) json.provider = err.provider;\n  if (err.requestId !== undefined) json.requestId = err.requestId;\n  if (err.conversationId !== undefined) json.conversationId = err.conversationId;\n  if (err.raw !== undefined) json.raw = redactSecrets(err.raw);\n}\n\nfunction sanitizeMetadata(meta: ErrorMetadata | undefined): ErrorMetadata | undefined {\n  if (meta === undefined) return undefined;\n  const { raw, ...rest } = meta;\n  const debugRaw = readEnv(\"THEOKIT_DEBUG_RAW_ERRORS\") === \"1\";\n  if (debugRaw && raw !== undefined) {\n    const redactedRaw =\n      typeof raw === \"string\" ? redactSecrets(raw) : redactSecrets(safeStringify(raw));\n    return { ...rest, raw: redactedRaw } as ErrorMetadata;\n  }\n  return rest as ErrorMetadata;\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n\n/**\n * Is this error transient (worth retrying)?\n *\n * Returns the SDK's own retryability verdict: every {@link TheokitAgentError}\n * subclass computes `isRetryable` at construction (rate-limit / network /\n * credential-pool-exhausted are retryable; auth / configuration / unsupported\n * are not), so this predicate is a single source of truth rather than a\n * re-derivation. Non-SDK errors return `false` conservatively — wrap a foreign\n * error in the appropriate SDK error first if you want it considered transient.\n * It never inspects `err.message`.\n *\n * @example\n *   try {\n *     await agent.send(message, { throwOnError: true });\n *   } catch (err) {\n *     if (isTransientError(err)) return retryWithBackoff();\n *     throw err;\n *   }\n *\n * @public\n */\nexport function isTransientError(err: unknown): boolean {\n  return err instanceof TheokitAgentError && err.isRetryable === true;\n}\n\n/**\n * Thrown when a {@link Run} or agent operation is not available on the current\n * runtime. Check first with `run.supports(operation)`.\n *\n * Extends {@link TheokitAgentError} (so error-catching code that branches on\n * `instanceof TheokitAgentError` continues to work) but is never retryable —\n * an unsupported operation will not become supported on retry.\n *\n * @public\n */\nexport class UnsupportedRunOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedRunOperationError\";\n  readonly operation: RunOperation;\n\n  constructor(\n    message: string,\n    operation: RunOperation,\n    options: { code?: string; cause?: unknown } = {},\n  ) {\n    super(message, {\n      ...options,\n      isRetryable: false,\n      code: options.code ?? \"unsupported_run_operation\",\n    });\n    this.operation = operation;\n  }\n}\n\n/**\n * Thrown when every credential in a per-provider pool is in cooldown\n * and no healthy key is available (ADR D133). The caller's\n * {@link import(\"./internal/llm/fallback-client.js\").FallbackLlmClient}\n * catches this and tries the next provider in the fallback chain.\n *\n * `metadata.nextRetryAt` (epoch ms) tells callers when the soonest\n * pool entry resumes — useful for manual retry scheduling.\n *\n * @public\n */\nexport class CredentialPoolExhaustedError extends TheokitAgentError {\n  override readonly name: string = \"CredentialPoolExhaustedError\";\n  readonly provider: string;\n  readonly nextRetryAt: number | undefined;\n\n  constructor(\n    message: string,\n    options: {\n      provider: string;\n      nextRetryAt?: number;\n      code?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      ...options,\n      isRetryable: true,\n      code: options.code ?? \"credential_pool_exhausted\",\n    });\n    this.provider = options.provider;\n    this.nextRetryAt = options.nextRetryAt;\n  }\n}\n\n/**\n * Finite error codes specific to memory adapter operations (ADR D141).\n *\n * @public\n */\nexport type MemoryAdapterErrorCode =\n  | \"auth_failed\"\n  | \"rate_limited\"\n  | \"not_found\"\n  | \"network\"\n  | \"invalid_input\"\n  | \"unknown\";\n\n/**\n * Error raised by `@theokit-memory-*` adapters. Carries `adapterId`\n * so callers can branch on which provider failed (ADR D141).\n *\n * @public\n */\nexport class MemoryAdapterError extends TheokitAgentError {\n  override readonly name: string = \"MemoryAdapterError\";\n  readonly adapterId: string;\n\n  constructor(\n    message: string,\n    options: {\n      adapterId: string;\n      code: MemoryAdapterErrorCode;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      isRetryable: options.code === \"rate_limited\" || options.code === \"network\",\n      code: options.code,\n      ...(options.cause !== undefined ? { cause: options.cause } : {}),\n      ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),\n    });\n    this.adapterId = options.adapterId;\n  }\n}\n\n/**\n * Thrown by `Budget` enforcement (ADR D386) when a `mode: \"block\"`\n * budget would be exceeded by the upcoming LLM call. The caller catches a\n * typed error to retry after the window resets, or surfaces it to the user.\n *\n * @public\n */\nexport class BudgetExceededError extends TheokitAgentError {\n  override readonly name: string = \"BudgetExceededError\";\n  readonly budgetName: string;\n  readonly window: import(\"./types/budget.js\").BudgetWindow;\n  readonly spentUsd: number;\n  readonly limitUsd: number;\n  readonly mode: import(\"./types/budget.js\").BudgetMode;\n\n  constructor(args: {\n    budgetName: string;\n    window: import(\"./types/budget.js\").BudgetWindow;\n    spentUsd: number;\n    limitUsd: number;\n    mode: import(\"./types/budget.js\").BudgetMode;\n    cause?: unknown;\n  }) {\n    super(\n      `Budget \"${args.budgetName}\" exceeded for window ${args.window}: spent $${args.spentUsd.toFixed(4)} > limit $${args.limitUsd.toFixed(4)}`,\n      {\n        ...(args.cause !== undefined ? { cause: args.cause } : {}),\n        isRetryable: false,\n        code: \"budget_exceeded\",\n      },\n    );\n    this.budgetName = args.budgetName;\n    this.window = args.window;\n    this.spentUsd = args.spentUsd;\n    this.limitUsd = args.limitUsd;\n    this.mode = args.mode;\n  }\n}\n\n/**\n * T1.6 — Thrown when a consumer calls `agent.send()` or any method\n * on an agent that has already been `dispose()`d. Pre-T1.6 this was\n * a generic `new Error(\"Agent has been disposed\")` — consumers\n * couldn't catch it without string-matching the message.\n *\n * @public\n */\nexport class AgentDisposedError extends TheokitAgentError {\n  override readonly name: string = \"AgentDisposedError\";\n  readonly agentId: string;\n\n  constructor(agentId: string) {\n    super(`Agent \"${agentId}\" has been disposed. Create a new agent or use Agent.resume().`, {\n      isRetryable: false,\n      code: \"agent_disposed\",\n    });\n    this.agentId = agentId;\n  }\n}\n\n/**\n * Thrown when a budget operation is requested on a `CloudAgent` (D388). The cloud budget surface\n * waits for Theo PaaS GA, so the operation is not merely failing — it does not exist yet.\n *\n * Not retryable: `isRetryable` is `false`, and retrying cannot change the outcome until the\n * feature ships. Catch it by `instanceof`, or by `code === \"budget_op_unsupported\"` when the\n * error has crossed a serialization boundary that dropped the prototype. `operation` carries the\n * name that was refused and is interpolated into the message.\n *\n * The local agent does not raise this — the same call against a local agent runs the budget path\n * normally.\n *\n * @public\n */\nexport class UnsupportedBudgetOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedBudgetOperationError\";\n  readonly operation: string;\n\n  constructor(operation: string, options: { cause?: unknown } = {}) {\n    super(\n      `Budget operation \"${operation}\" is not supported on CloudAgent (pre-release; see ADR D388)`,\n      {\n        ...options,\n        isRetryable: false,\n        code: \"budget_op_unsupported\",\n      },\n    );\n    this.operation = operation;\n  }\n}\n\n/**\n * Why a structured-output call failed.\n *\n * A named union rather than a repeated inline one: the narrow form was written out at the class AND\n * in `agent-generate.ts`'s local type, so widening it meant finding both. One name, one edit.\n *\n * @public\n */\nexport type StructuredOutputErrorCode =\n  /** The model did not call the forced output tool. The original meaning, unchanged. */\n  | \"no_tool_call\"\n  /** The tool was called and its arguments did not parse against the schema. */\n  | \"parse_failed\"\n  /** The agent run errored before there was an answer to structure. */\n  | \"upstream_run_failed\"\n  /** The agent run was cancelled before there was an answer to structure. */\n  | \"run_cancelled\"\n  /** The loop finished with tools only and produced no text to structure. */\n  | \"no_text_answer\";\n\n/**\n * The failure contract shared by `generateObject` and `streamObject`.\n *\n * Both entry points run the same rule — up to `maxRetries` attempts; if the model never called the\n * output tool, fail as `no_tool_call`, naming the underlying run error when there was one; if the\n * schema never parsed, fail as `parse_failed` — and both declared their own error class for it, with\n * byte-identical user-facing strings. A change to the taxonomy or the wording had to be made twice,\n * or the two APIs would start describing the same failure differently.\n *\n * It extends `TheokitAgentError` because every typed error the SDK publishes does, and these two did\n * not: a consumer catching `TheokitAgentError` — the documented way to catch anything this SDK throws\n * — silently missed both, and neither carried `isRetryable`.\n *\n * It lives HERE rather than beside the two entry points because it is an error class and this is the\n * error module. The first home was `internal/structured-output-helpers.ts`, and rollup-plugin-dts\n * could not resolve it from there when bundling the root declaration — a failure `tsc --noEmit`\n * does not see, because it never runs the declaration rollup.\n *\n * `isRetryable` is false. Both codes mean the model did not produce the requested shape; the caller's\n * own `maxRetries` has already been spent by the time either is thrown, so an outer retry loop would\n * re-run a sequence that already gave up.\n *\n * The two public names stay DISTINCT subclasses rather than aliases of this one. Collapsing them\n * would make `streamObjectError instanceof GenerateObjectError` true, which is a semantic widening\n * nobody asked for; the duplication being removed is the contract, not the identity.\n *\n * @public\n */\n\nexport class StructuredOutputError extends TheokitAgentError {\n  override readonly name: string = \"StructuredOutputError\";\n  /**\n   * Why the structuring failed.\n   *\n   * Three of these are new, and they name causes the SDK ALREADY distinguished in prose while\n   * reporting all three as `no_tool_call`: an upstream run that errored, a run that was cancelled,\n   * and a tool-only completion with no text to structure. Three tests asserted the byte-identical\n   * oracle for three genuinely different setups — swap any two and all three still passed — because\n   * the only thing that differed was the free-text message.\n   *\n   * `no_tool_call` keeps its original meaning: the model did not call the forced output tool.\n   */\n  override readonly code:\n    | \"no_tool_call\"\n    | \"parse_failed\"\n    | \"upstream_run_failed\"\n    | \"run_cancelled\"\n    | \"no_text_answer\";\n\n  constructor(\n    code:\n      | \"no_tool_call\"\n      | \"parse_failed\"\n      | \"upstream_run_failed\"\n      | \"run_cancelled\"\n      | \"no_text_answer\",\n    message: string,\n    cause?: unknown,\n  ) {\n    super(message, { code, isRetryable: false, ...(cause === undefined ? {} : { cause }) });\n    this.code = code;\n  }\n}\n\n// The three Task-API errors live beside the API they belong to (`task-errors.ts`), and are\n// re-exported here so `@theokit/sdk/errors` keeps naming every error in one place. They are one\n// ACTOR — the Task surface — not a slice cut to fit a line budget; the budget is what made the\n// grouping visible, and `StructuredOutputError` above shows the opposite case, a class that must\n// stay in this file because rollup-plugin-dts could not resolve it elsewhere.\nexport {\n  InvalidTaskIdError,\n  TaskNotFoundError,\n  UnsupportedTaskOperationError,\n} from \"./task-errors.js\";\n\n/**\n * Compression of a conversation failed. Declared HERE rather than re-exported from the module\n * that throws it: this file is imported by 45 modules, and a re-export from `internal/` was the\n * only one in the file — it closed `errors -> summarizer -> compaction -> errors`, which madge\n * rejects. Every other domain error is declared in this file for the same reason.\n *\n * Thrown when the compression LLM call fails or returns an empty / ineffective summary. The\n * caller catches it and handles the ADR D440 failure mode: WARN, keep the original\n * conversation, bump the counter.\n *\n * A typed error nobody can import is a message string with extra ceremony:\n * `catch (e) { if (e instanceof CompressionFailedError) }` is the entire reason it exists rather\n * than a string comparison, and that line did not compile for any consumer before this export.\n *\n * @public\n */\nexport class CompressionFailedError extends TheokitAgentError {\n  override readonly name = \"CompressionFailedError\";\n\n  constructor(message: string, options: { cause?: unknown } = {}) {\n    // Retryable: both throw sites are about ONE LLM call that failed or came back empty, which is\n    // the transient shape the SDK's retry layer exists for.\n    super(message, { ...options, code: \"compression_failed\", isRetryable: true });\n  }\n}\n"]}