@theokit/sdk 1.5.0

package/dist/path-safety.cjs

@@ -0,0 +1,126 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+// src/internal/security/path-guard.ts
+
+// src/errors.ts
+var TheokitAgentError = class extends Error {
+  name = "TheokitAgentError";
+  isRetryable;
+  code;
+  protoErrorCode;
+  metadata;
+  constructor(message, options = {}) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.isRetryable = options.isRetryable ?? false;
+    if (options.code !== void 0) this.code = options.code;
+    if (options.protoErrorCode !== void 0) this.protoErrorCode = options.protoErrorCode;
+    if (options.metadata !== void 0) this.metadata = options.metadata;
+  }
+};
+var ConfigurationError = class extends TheokitAgentError {
+  name = "ConfigurationError";
+  constructor(message, options = {}) {
+    super(message, { ...options, isRetryable: false });
+  }
+};
+
+// src/internal/security/path-guard.ts
+var PathTraversalError = class extends ConfigurationError {
+  name = "PathTraversalError";
+  constructor(input, resolvedPath) {
+    super(`Path traversal attempt: ${input} \u2192 ${resolvedPath}`, {
+      code: "path_traversal"
+    });
+  }
+};
+var ForbiddenPathError = class extends ConfigurationError {
+  name = "ForbiddenPathError";
+  constructor(path) {
+    super(
+      `Path '${path}' is in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files)`,
+      {
+        code: "forbidden_path"
+      }
+    );
+  }
+};
+function safePathJoin(base, ...parts) {
+  if (base === "") {
+    throw new Error("safePathJoin: base must be non-empty");
+  }
+  const baseResolved = path.resolve(base);
+  const target = path.resolve(base, ...parts);
+  if (target !== baseResolved && !target.startsWith(baseResolved + path.sep)) {
+    throw new PathTraversalError(parts.join("/"), target);
+  }
+  return target;
+}
+function assertNoSymlinkEscape(path$1, base) {
+  let baseResolved;
+  try {
+    baseResolved = fs.realpathSync(base);
+  } catch {
+    baseResolved = path.resolve(base);
+  }
+  const resolved = realpathOfDeepestExisting(path$1);
+  if (resolved === void 0) return;
+  if (resolved !== baseResolved && !resolved.startsWith(baseResolved + path.sep)) {
+    throw new PathTraversalError(`symlink ${path$1}`, resolved);
+  }
+}
+function realpathOfDeepestExisting(path$1) {
+  try {
+    return fs.realpathSync(path$1);
+  } catch {
+  }
+  try {
+    const stat = fs.lstatSync(path$1);
+    if (stat.isSymbolicLink()) {
+      const target = fs.readlinkSync(path$1);
+      const parentReal = realpathOfDeepestExisting(path.dirname(path$1));
+      const parentBase = parentReal ?? path.dirname(path$1);
+      return path.resolve(parentBase, target);
+    }
+  } catch {
+  }
+  let cursor = path.dirname(path$1);
+  let suffix = path$1.slice(cursor.length);
+  while (cursor !== path.dirname(cursor)) {
+    try {
+      const real = fs.realpathSync(cursor);
+      return path.resolve(real, `.${suffix}`);
+    } catch {
+      suffix = path$1.slice(path.dirname(cursor).length);
+      cursor = path.dirname(cursor);
+    }
+  }
+  return void 0;
+}
+var LOCK_FILES = /* @__PURE__ */ new Set(["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"]);
+function isForbiddenPath(input) {
+  const normalized = input.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (normalized.length === 0) return false;
+  const segments = normalized.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) return false;
+  const first = segments[0];
+  if (first === ".env.example") return false;
+  if (first === ".env") return true;
+  if (/^\.env\./.test(first)) return true;
+  if (first === ".git") return true;
+  if (first === "node_modules") return true;
+  if (first === ".theo") return true;
+  const basename = segments[segments.length - 1];
+  if (LOCK_FILES.has(basename)) return true;
+  return false;
+}
+
+exports.ForbiddenPathError = ForbiddenPathError;
+exports.PathTraversalError = PathTraversalError;
+exports.assertNoSymlinkEscape = assertNoSymlinkEscape;
+exports.isForbiddenPath = isForbiddenPath;
+exports.safePathJoin = safePathJoin;
+//# sourceMappingURL=path-safety.cjs.map
+//# sourceMappingURL=path-safety.cjs.map

package/dist/path-safety.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/internal/security/path-guard.ts"],"names":["resolve","sep","path","realpathSync","lstatSync","readlinkSync","dirname"],"mappings":"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","file":"path-safety.cjs","sourcesContent":["import type { RunOperation } from \"./types/run.js\";\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  | \"unknown\";\n\n/**\n * Codes used by {@link AgentRunError} (Production-Readiness #3, ADR D311).\n *\n * Superset of {@link ErrorCode} extended with codes that do NOT originate\n * from a provider HTTP response:\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 * The `& {}` tail keeps the literal-union ergonomics (autocomplete) while\n * accepting any string for forward compatibility with constructor calls\n * that pass arbitrary code values (legacy callers).\n *\n * @public\n */\nexport type AgentRunErrorCode =\n  | ErrorCode\n  | \"quota_exceeded\"\n  | \"tool_runtime_error\"\n  | \"aborted\"\n  | \"invalid_model\"\n  | \"safety_blocked\"\n  | \"provider_unreachable\"\n  | (string & {});\n\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/**\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/**\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: alias for `metadata.raw`. Provider response body for debugging.\n   * Available but NEVER serialized into `.message` (anti-leak invariant).\n   */\n  get providerError(): unknown {\n    return this.metadata?.raw;\n  }\n}\n\n/**\n * D311 helper: choose a sensible default `isRetryable` value when the\n * caller did not supply `retriable` explicitly. Conservative defaults —\n * provider mappers override per-status when they know better.\n *\n * @internal\n */\nfunction defaultRetriableForCode(code: AgentRunErrorCode): 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/**\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 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/**\n * Thrown by `Budget` enforcement (ADR D386) when a `mode: \"block\"`\n * budget would be exceeded by the upcoming LLM call. Caller pega\n * tipado para retry-after-window-reset or surface 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 * Thrown when `CloudAgent.send({ budget })` is invoked (D388). Cloud\n * budget surface waits for Theo PaaS GA.\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 * Canonical path-guard module (ADRs D79-D81).\n *\n * Three primitives + one typed error:\n *   - `safePathJoin(base, ...parts)` — resolve THEN prefix-check (ADR D80).\n *   - `assertNoSymlinkEscape(path, base)` — `realpathSync` resolves entire\n *     symlink chain (EC-1 fix; Hermes v0.2 #386, #61).\n *   - `sanitizeIdentifier(input, { maxLen })` — strict grammar\n *     `^[a-z0-9][a-z0-9-_]*$` (ADR D81; case-insensitive on input,\n *     lowercase on output).\n *   - `PathTraversalError` — extends ConfigurationError with code\n *     `path_traversal` (ADR D65: no new hierarchy).\n *\n * Wire at all sites where user input becomes a path. CI lint gate\n * `tests/lint/no-unguarded-path-input.test.ts` prevents regression\n * (ADR D85).\n *\n * @internal\n */\n\nimport { lstatSync, readlinkSync, realpathSync, type Stats } from \"node:fs\";\nimport { dirname, resolve, sep } from \"node:path\";\n\nimport { ConfigurationError } from \"../../errors.js\";\n\n/**\n * Thrown when a path operation would escape its allowed base directory.\n * Extends `ConfigurationError` (no new error hierarchy per ADR D65).\n *\n * @internal\n */\nexport class PathTraversalError extends ConfigurationError {\n  override readonly name: string = \"PathTraversalError\";\n\n  constructor(input: string, resolvedPath: string) {\n    super(`Path traversal attempt: ${input} → ${resolvedPath}`, {\n      code: \"path_traversal\",\n    });\n  }\n}\n\n/**\n * Thrown when an agent tool is asked to read or write a sensitive path\n * that the blocklist forbids (`.env`, `.git/`, `node_modules/`, `.theo/`,\n * lock files). Distinct from `PathTraversalError` because the path is\n * lexically inside the project — it is just sensitive.\n *\n * Extends `ConfigurationError` (no new error hierarchy per ADR D65).\n *\n * @public\n */\nexport class ForbiddenPathError extends ConfigurationError {\n  override readonly name: string = \"ForbiddenPathError\";\n\n  constructor(path: string) {\n    super(\n      `Path '${path}' is in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files)`,\n      {\n        code: \"forbidden_path\",\n      },\n    );\n  }\n}\n\n/**\n * Join `base` with `...parts` and ensure the resolved absolute path stays\n * under `base`. Resolves FIRST, then prefix-checks (ADR D80) — prevents\n * normalized-escape bypasses like `subdir/.\\\\./bar`.\n *\n * Returns the safe absolute path. Throws `PathTraversalError` if escape.\n *\n * @internal\n */\nexport function safePathJoin(base: string, ...parts: string[]): string {\n  if (base === \"\") {\n    throw new Error(\"safePathJoin: base must be non-empty\");\n  }\n  const baseResolved = resolve(base);\n  const target = resolve(base, ...parts);\n  if (target !== baseResolved && !target.startsWith(baseResolved + sep)) {\n    throw new PathTraversalError(parts.join(\"/\"), target);\n  }\n  return target;\n}\n\n/**\n * Assert that `path` — including every directory component in the chain —\n * stays under `base` after symlink resolution. No-op when nothing on the\n * path exists yet.\n *\n * Two-bug history:\n *   1. **EC-1** (original fix, kept): a multi-level symlink chain A → B → C\n *      must be resolved end-to-end. `realpathSync` does this in 1 syscall.\n *   2. **Defence-in-depth** (added v1.x): the previous implementation only\n *      called `lstatSync(path)` on the terminal component. If an INTERMEDIATE\n *      directory was a symlink (`base/inner-symlink → /outside`), `lstat` on\n *      `base/inner-symlink/file.txt` followed the symlink and reported the\n *      regular file — escape went undetected. Fix: walk up to the nearest\n *      existing ancestor and `realpath` THAT, then re-attach the suffix and\n *      check the result against the canonical base.\n *\n * @internal\n */\nexport function assertNoSymlinkEscape(path: string, base: string): void {\n  // Canonical base — symlinks in the base path itself are absorbed once here.\n  let baseResolved: string;\n  try {\n    baseResolved = realpathSync(base);\n  } catch {\n    // base doesn't exist as a real directory yet — fall back to lexical resolve.\n    baseResolved = resolve(base);\n  }\n\n  // Find the deepest ancestor of `path` that exists, then realpath it.\n  // Anything from there onward is \"not yet on disk\" and contributes only\n  // its lexical suffix. This covers three cases:\n  //   - path exists (regular file or symlink at any depth) → realpath the full path\n  //   - path doesn't exist but intermediate dir is a symlink → realpath the ancestor\n  //   - nothing on the path exists → no escape risk (return)\n  const resolved = realpathOfDeepestExisting(path);\n  if (resolved === undefined) return; // path has no existing prefix — nothing to attack\n\n  if (resolved !== baseResolved && !resolved.startsWith(baseResolved + sep)) {\n    throw new PathTraversalError(`symlink ${path}`, resolved);\n  }\n}\n\n/**\n * Find the deepest ancestor of `path` that exists on disk, resolve all\n * symlinks in that ancestor via `realpathSync`, and re-attach the\n * lexical suffix. Returns `undefined` when no ancestor exists.\n *\n * Handles dangling symlinks: if the terminal IS a symlink but its target\n * is missing, we still detect escape via `readlinkSync` + parent resolve.\n */\nfunction realpathOfDeepestExisting(path: string): string | undefined {\n  // First try the full path — the common case.\n  try {\n    return realpathSync(path);\n  } catch {\n    // Not resolvable. Two sub-cases.\n  }\n\n  // Sub-case A: terminal is a dangling symlink.\n  try {\n    const stat: Stats = lstatSync(path);\n    if (stat.isSymbolicLink()) {\n      const target = readlinkSync(path);\n      // Resolve target relative to the REAL parent dir, so intermediate\n      // symlinks in the parent chain are absorbed.\n      const parentReal = realpathOfDeepestExisting(dirname(path));\n      const parentBase = parentReal ?? dirname(path);\n      return resolve(parentBase, target);\n    }\n  } catch {\n    // lstat failed too — terminal doesn't exist at all.\n  }\n\n  // Sub-case B: walk up to the nearest existing ancestor, then re-attach\n  // the suffix lexically.\n  let cursor = dirname(path);\n  let suffix = path.slice(cursor.length);\n  while (cursor !== dirname(cursor)) {\n    try {\n      const real = realpathSync(cursor);\n      // Reconstruct: ancestor's realpath + remaining (still-lexical) suffix\n      return resolve(real, `.${suffix}`);\n    } catch {\n      suffix = path.slice(dirname(cursor).length);\n      cursor = dirname(cursor);\n    }\n  }\n  // Reached filesystem root without finding any existing ancestor.\n  return undefined;\n}\n\nconst LOCK_FILES = new Set([\"pnpm-lock.yaml\", \"package-lock.json\", \"yarn.lock\", \"bun.lockb\"]);\n\n/**\n * Decide whether a project-relative path points to a known-sensitive file\n * that a coding agent must not read or write.\n *\n * Universal blocklist (works for any agent operating on a project tree):\n *\n *   - `.env`, `.env.<anything>` — except `.env.example` (template safe to read)\n *   - `.git/` — version control internals\n *   - `node_modules/` — dependency cache (changes don't belong to the user)\n *   - `.theo/` — TheoKit build artefacts / state\n *   - Lock files at any depth: `pnpm-lock.yaml`, `package-lock.json`,\n *     `yarn.lock`, `bun.lockb`\n *\n * Operates on path segments (forward-slash normalized). Cross-platform safe.\n *\n * Use together with `safePathJoin` + `assertNoSymlinkEscape`: the former two\n * defeat traversal, this one defeats reading a file that is lexically inside\n * the project but should not be agent-visible.\n *\n * @public\n */\nexport function isForbiddenPath(input: string): boolean {\n  // Normalize: forward slashes only, strip leading \"./\"\n  const normalized = input.replace(/\\\\/g, \"/\").replace(/^\\.\\//, \"\");\n  if (normalized.length === 0) return false;\n\n  const segments = normalized.split(\"/\").filter((s) => s.length > 0);\n  if (segments.length === 0) return false;\n\n  const first = segments[0]!;\n  // .env.example is explicitly allowlisted (template safe to read)\n  if (first === \".env.example\") return false;\n  if (first === \".env\") return true;\n  if (/^\\.env\\./.test(first)) return true;\n\n  if (first === \".git\") return true;\n  if (first === \"node_modules\") return true;\n  if (first === \".theo\") return true;\n\n  const basename = segments[segments.length - 1]!;\n  if (LOCK_FILES.has(basename)) return true;\n\n  return false;\n}\n\nconst IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9\\-_]*$/i;\n\n/**\n * Validate that `input` is a safe path component (skill name, agent ID,\n * namespace, etc.) and return its lowercase form. Strict grammar\n * `^[a-z0-9][a-z0-9-_]*$` rejects path separators, dots, null bytes,\n * whitespace, unicode invisible chars, and any leading `-`/`_`.\n *\n * @param input - User-supplied identifier candidate.\n * @param options.maxLen - Maximum allowed length (default 64).\n * @returns Lowercase form of `input`.\n * @throws `ConfigurationError` with code `invalid_identifier` on rejection.\n *\n * @internal\n */\nexport function sanitizeIdentifier(input: string, options?: { maxLen?: number }): string {\n  const maxLen = options?.maxLen ?? 64;\n  if (input.length === 0 || input.length > maxLen) {\n    throw new ConfigurationError(`Identifier length out of range (1-${maxLen}): \"${input}\"`, {\n      code: \"invalid_identifier\",\n    });\n  }\n  if (!IDENTIFIER_PATTERN.test(input)) {\n    throw new ConfigurationError(`Identifier contains invalid characters: \"${input}\"`, {\n      code: \"invalid_identifier\",\n    });\n  }\n  return input.toLowerCase();\n}\n"]}

package/dist/path-safety.d.cts

@@ -0,0 +1,15 @@
+/**
+ * Public path-safety primitives.
+ *
+ * Thin re-export of the canonical implementation in
+ * `internal/security/path-guard.ts`. Splitting this into its own
+ * top-level module gives `rollup-plugin-dts` a clean boundary when
+ * bundling declarations — without it, including the path-guard module
+ * via the main barrel propagates a cascade of transitive imports that
+ * surface a known-spurious "ForkOptions not exported" error from
+ * `types/agent.ts` (dynamic-import-type quirk in rollup-plugin-dts).
+ *
+ * See `docs.md → Security — path traversal + TOCTOU` for the full
+ * primitive reference. Public from v1.x.
+ */
+export { assertNoSymlinkEscape, ForbiddenPathError, isForbiddenPath, PathTraversalError, safePathJoin, } from "./internal/security/path-guard.js";

package/dist/path-safety.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public path-safety primitives.
+ *
+ * Thin re-export of the canonical implementation in
+ * `internal/security/path-guard.ts`. Splitting this into its own
+ * top-level module gives `rollup-plugin-dts` a clean boundary when
+ * bundling declarations — without it, including the path-guard module
+ * via the main barrel propagates a cascade of transitive imports that
+ * surface a known-spurious "ForkOptions not exported" error from
+ * `types/agent.ts` (dynamic-import-type quirk in rollup-plugin-dts).
+ *
+ * See `docs.md → Security — path traversal + TOCTOU` for the full
+ * primitive reference. Public from v1.x.
+ */
+export { assertNoSymlinkEscape, ForbiddenPathError, isForbiddenPath, PathTraversalError, safePathJoin, } from "./internal/security/path-guard.js";

package/dist/path-safety.js

@@ -0,0 +1,120 @@
+import { realpathSync, lstatSync, readlinkSync } from 'fs';
+import { resolve, sep, dirname } from 'path';
+
+// src/internal/security/path-guard.ts
+
+// src/errors.ts
+var TheokitAgentError = class extends Error {
+  name = "TheokitAgentError";
+  isRetryable;
+  code;
+  protoErrorCode;
+  metadata;
+  constructor(message, options = {}) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.isRetryable = options.isRetryable ?? false;
+    if (options.code !== void 0) this.code = options.code;
+    if (options.protoErrorCode !== void 0) this.protoErrorCode = options.protoErrorCode;
+    if (options.metadata !== void 0) this.metadata = options.metadata;
+  }
+};
+var ConfigurationError = class extends TheokitAgentError {
+  name = "ConfigurationError";
+  constructor(message, options = {}) {
+    super(message, { ...options, isRetryable: false });
+  }
+};
+
+// src/internal/security/path-guard.ts
+var PathTraversalError = class extends ConfigurationError {
+  name = "PathTraversalError";
+  constructor(input, resolvedPath) {
+    super(`Path traversal attempt: ${input} \u2192 ${resolvedPath}`, {
+      code: "path_traversal"
+    });
+  }
+};
+var ForbiddenPathError = class extends ConfigurationError {
+  name = "ForbiddenPathError";
+  constructor(path) {
+    super(
+      `Path '${path}' is in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files)`,
+      {
+        code: "forbidden_path"
+      }
+    );
+  }
+};
+function safePathJoin(base, ...parts) {
+  if (base === "") {
+    throw new Error("safePathJoin: base must be non-empty");
+  }
+  const baseResolved = resolve(base);
+  const target = resolve(base, ...parts);
+  if (target !== baseResolved && !target.startsWith(baseResolved + sep)) {
+    throw new PathTraversalError(parts.join("/"), target);
+  }
+  return target;
+}
+function assertNoSymlinkEscape(path, base) {
+  let baseResolved;
+  try {
+    baseResolved = realpathSync(base);
+  } catch {
+    baseResolved = resolve(base);
+  }
+  const resolved = realpathOfDeepestExisting(path);
+  if (resolved === void 0) return;
+  if (resolved !== baseResolved && !resolved.startsWith(baseResolved + sep)) {
+    throw new PathTraversalError(`symlink ${path}`, resolved);
+  }
+}
+function realpathOfDeepestExisting(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+  }
+  try {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) {
+      const target = readlinkSync(path);
+      const parentReal = realpathOfDeepestExisting(dirname(path));
+      const parentBase = parentReal ?? dirname(path);
+      return resolve(parentBase, target);
+    }
+  } catch {
+  }
+  let cursor = dirname(path);
+  let suffix = path.slice(cursor.length);
+  while (cursor !== dirname(cursor)) {
+    try {
+      const real = realpathSync(cursor);
+      return resolve(real, `.${suffix}`);
+    } catch {
+      suffix = path.slice(dirname(cursor).length);
+      cursor = dirname(cursor);
+    }
+  }
+  return void 0;
+}
+var LOCK_FILES = /* @__PURE__ */ new Set(["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"]);
+function isForbiddenPath(input) {
+  const normalized = input.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (normalized.length === 0) return false;
+  const segments = normalized.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) return false;
+  const first = segments[0];
+  if (first === ".env.example") return false;
+  if (first === ".env") return true;
+  if (/^\.env\./.test(first)) return true;
+  if (first === ".git") return true;
+  if (first === "node_modules") return true;
+  if (first === ".theo") return true;
+  const basename = segments[segments.length - 1];
+  if (LOCK_FILES.has(basename)) return true;
+  return false;
+}
+
+export { ForbiddenPathError, PathTraversalError, assertNoSymlinkEscape, isForbiddenPath, safePathJoin };
+//# sourceMappingURL=path-safety.js.map
+//# sourceMappingURL=path-safety.js.map

package/dist/path-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/internal/security/path-guard.ts"],"names":[],"mappings":"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","file":"path-safety.js","sourcesContent":["import type { RunOperation } from \"./types/run.js\";\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  | \"unknown\";\n\n/**\n * Codes used by {@link AgentRunError} (Production-Readiness #3, ADR D311).\n *\n * Superset of {@link ErrorCode} extended with codes that do NOT originate\n * from a provider HTTP response:\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 * The `& {}` tail keeps the literal-union ergonomics (autocomplete) while\n * accepting any string for forward compatibility with constructor calls\n * that pass arbitrary code values (legacy callers).\n *\n * @public\n */\nexport type AgentRunErrorCode =\n  | ErrorCode\n  | \"quota_exceeded\"\n  | \"tool_runtime_error\"\n  | \"aborted\"\n  | \"invalid_model\"\n  | \"safety_blocked\"\n  | \"provider_unreachable\"\n  | (string & {});\n\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/**\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/**\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: alias for `metadata.raw`. Provider response body for debugging.\n   * Available but NEVER serialized into `.message` (anti-leak invariant).\n   */\n  get providerError(): unknown {\n    return this.metadata?.raw;\n  }\n}\n\n/**\n * D311 helper: choose a sensible default `isRetryable` value when the\n * caller did not supply `retriable` explicitly. Conservative defaults —\n * provider mappers override per-status when they know better.\n *\n * @internal\n */\nfunction defaultRetriableForCode(code: AgentRunErrorCode): 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/**\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 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/**\n * Thrown by `Budget` enforcement (ADR D386) when a `mode: \"block\"`\n * budget would be exceeded by the upcoming LLM call. Caller pega\n * tipado para retry-after-window-reset or surface 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 * Thrown when `CloudAgent.send({ budget })` is invoked (D388). Cloud\n * budget surface waits for Theo PaaS GA.\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 * Canonical path-guard module (ADRs D79-D81).\n *\n * Three primitives + one typed error:\n *   - `safePathJoin(base, ...parts)` — resolve THEN prefix-check (ADR D80).\n *   - `assertNoSymlinkEscape(path, base)` — `realpathSync` resolves entire\n *     symlink chain (EC-1 fix; Hermes v0.2 #386, #61).\n *   - `sanitizeIdentifier(input, { maxLen })` — strict grammar\n *     `^[a-z0-9][a-z0-9-_]*$` (ADR D81; case-insensitive on input,\n *     lowercase on output).\n *   - `PathTraversalError` — extends ConfigurationError with code\n *     `path_traversal` (ADR D65: no new hierarchy).\n *\n * Wire at all sites where user input becomes a path. CI lint gate\n * `tests/lint/no-unguarded-path-input.test.ts` prevents regression\n * (ADR D85).\n *\n * @internal\n */\n\nimport { lstatSync, readlinkSync, realpathSync, type Stats } from \"node:fs\";\nimport { dirname, resolve, sep } from \"node:path\";\n\nimport { ConfigurationError } from \"../../errors.js\";\n\n/**\n * Thrown when a path operation would escape its allowed base directory.\n * Extends `ConfigurationError` (no new error hierarchy per ADR D65).\n *\n * @internal\n */\nexport class PathTraversalError extends ConfigurationError {\n  override readonly name: string = \"PathTraversalError\";\n\n  constructor(input: string, resolvedPath: string) {\n    super(`Path traversal attempt: ${input} → ${resolvedPath}`, {\n      code: \"path_traversal\",\n    });\n  }\n}\n\n/**\n * Thrown when an agent tool is asked to read or write a sensitive path\n * that the blocklist forbids (`.env`, `.git/`, `node_modules/`, `.theo/`,\n * lock files). Distinct from `PathTraversalError` because the path is\n * lexically inside the project — it is just sensitive.\n *\n * Extends `ConfigurationError` (no new error hierarchy per ADR D65).\n *\n * @public\n */\nexport class ForbiddenPathError extends ConfigurationError {\n  override readonly name: string = \"ForbiddenPathError\";\n\n  constructor(path: string) {\n    super(\n      `Path '${path}' is in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files)`,\n      {\n        code: \"forbidden_path\",\n      },\n    );\n  }\n}\n\n/**\n * Join `base` with `...parts` and ensure the resolved absolute path stays\n * under `base`. Resolves FIRST, then prefix-checks (ADR D80) — prevents\n * normalized-escape bypasses like `subdir/.\\\\./bar`.\n *\n * Returns the safe absolute path. Throws `PathTraversalError` if escape.\n *\n * @internal\n */\nexport function safePathJoin(base: string, ...parts: string[]): string {\n  if (base === \"\") {\n    throw new Error(\"safePathJoin: base must be non-empty\");\n  }\n  const baseResolved = resolve(base);\n  const target = resolve(base, ...parts);\n  if (target !== baseResolved && !target.startsWith(baseResolved + sep)) {\n    throw new PathTraversalError(parts.join(\"/\"), target);\n  }\n  return target;\n}\n\n/**\n * Assert that `path` — including every directory component in the chain —\n * stays under `base` after symlink resolution. No-op when nothing on the\n * path exists yet.\n *\n * Two-bug history:\n *   1. **EC-1** (original fix, kept): a multi-level symlink chain A → B → C\n *      must be resolved end-to-end. `realpathSync` does this in 1 syscall.\n *   2. **Defence-in-depth** (added v1.x): the previous implementation only\n *      called `lstatSync(path)` on the terminal component. If an INTERMEDIATE\n *      directory was a symlink (`base/inner-symlink → /outside`), `lstat` on\n *      `base/inner-symlink/file.txt` followed the symlink and reported the\n *      regular file — escape went undetected. Fix: walk up to the nearest\n *      existing ancestor and `realpath` THAT, then re-attach the suffix and\n *      check the result against the canonical base.\n *\n * @internal\n */\nexport function assertNoSymlinkEscape(path: string, base: string): void {\n  // Canonical base — symlinks in the base path itself are absorbed once here.\n  let baseResolved: string;\n  try {\n    baseResolved = realpathSync(base);\n  } catch {\n    // base doesn't exist as a real directory yet — fall back to lexical resolve.\n    baseResolved = resolve(base);\n  }\n\n  // Find the deepest ancestor of `path` that exists, then realpath it.\n  // Anything from there onward is \"not yet on disk\" and contributes only\n  // its lexical suffix. This covers three cases:\n  //   - path exists (regular file or symlink at any depth) → realpath the full path\n  //   - path doesn't exist but intermediate dir is a symlink → realpath the ancestor\n  //   - nothing on the path exists → no escape risk (return)\n  const resolved = realpathOfDeepestExisting(path);\n  if (resolved === undefined) return; // path has no existing prefix — nothing to attack\n\n  if (resolved !== baseResolved && !resolved.startsWith(baseResolved + sep)) {\n    throw new PathTraversalError(`symlink ${path}`, resolved);\n  }\n}\n\n/**\n * Find the deepest ancestor of `path` that exists on disk, resolve all\n * symlinks in that ancestor via `realpathSync`, and re-attach the\n * lexical suffix. Returns `undefined` when no ancestor exists.\n *\n * Handles dangling symlinks: if the terminal IS a symlink but its target\n * is missing, we still detect escape via `readlinkSync` + parent resolve.\n */\nfunction realpathOfDeepestExisting(path: string): string | undefined {\n  // First try the full path — the common case.\n  try {\n    return realpathSync(path);\n  } catch {\n    // Not resolvable. Two sub-cases.\n  }\n\n  // Sub-case A: terminal is a dangling symlink.\n  try {\n    const stat: Stats = lstatSync(path);\n    if (stat.isSymbolicLink()) {\n      const target = readlinkSync(path);\n      // Resolve target relative to the REAL parent dir, so intermediate\n      // symlinks in the parent chain are absorbed.\n      const parentReal = realpathOfDeepestExisting(dirname(path));\n      const parentBase = parentReal ?? dirname(path);\n      return resolve(parentBase, target);\n    }\n  } catch {\n    // lstat failed too — terminal doesn't exist at all.\n  }\n\n  // Sub-case B: walk up to the nearest existing ancestor, then re-attach\n  // the suffix lexically.\n  let cursor = dirname(path);\n  let suffix = path.slice(cursor.length);\n  while (cursor !== dirname(cursor)) {\n    try {\n      const real = realpathSync(cursor);\n      // Reconstruct: ancestor's realpath + remaining (still-lexical) suffix\n      return resolve(real, `.${suffix}`);\n    } catch {\n      suffix = path.slice(dirname(cursor).length);\n      cursor = dirname(cursor);\n    }\n  }\n  // Reached filesystem root without finding any existing ancestor.\n  return undefined;\n}\n\nconst LOCK_FILES = new Set([\"pnpm-lock.yaml\", \"package-lock.json\", \"yarn.lock\", \"bun.lockb\"]);\n\n/**\n * Decide whether a project-relative path points to a known-sensitive file\n * that a coding agent must not read or write.\n *\n * Universal blocklist (works for any agent operating on a project tree):\n *\n *   - `.env`, `.env.<anything>` — except `.env.example` (template safe to read)\n *   - `.git/` — version control internals\n *   - `node_modules/` — dependency cache (changes don't belong to the user)\n *   - `.theo/` — TheoKit build artefacts / state\n *   - Lock files at any depth: `pnpm-lock.yaml`, `package-lock.json`,\n *     `yarn.lock`, `bun.lockb`\n *\n * Operates on path segments (forward-slash normalized). Cross-platform safe.\n *\n * Use together with `safePathJoin` + `assertNoSymlinkEscape`: the former two\n * defeat traversal, this one defeats reading a file that is lexically inside\n * the project but should not be agent-visible.\n *\n * @public\n */\nexport function isForbiddenPath(input: string): boolean {\n  // Normalize: forward slashes only, strip leading \"./\"\n  const normalized = input.replace(/\\\\/g, \"/\").replace(/^\\.\\//, \"\");\n  if (normalized.length === 0) return false;\n\n  const segments = normalized.split(\"/\").filter((s) => s.length > 0);\n  if (segments.length === 0) return false;\n\n  const first = segments[0]!;\n  // .env.example is explicitly allowlisted (template safe to read)\n  if (first === \".env.example\") return false;\n  if (first === \".env\") return true;\n  if (/^\\.env\\./.test(first)) return true;\n\n  if (first === \".git\") return true;\n  if (first === \"node_modules\") return true;\n  if (first === \".theo\") return true;\n\n  const basename = segments[segments.length - 1]!;\n  if (LOCK_FILES.has(basename)) return true;\n\n  return false;\n}\n\nconst IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9\\-_]*$/i;\n\n/**\n * Validate that `input` is a safe path component (skill name, agent ID,\n * namespace, etc.) and return its lowercase form. Strict grammar\n * `^[a-z0-9][a-z0-9-_]*$` rejects path separators, dots, null bytes,\n * whitespace, unicode invisible chars, and any leading `-`/`_`.\n *\n * @param input - User-supplied identifier candidate.\n * @param options.maxLen - Maximum allowed length (default 64).\n * @returns Lowercase form of `input`.\n * @throws `ConfigurationError` with code `invalid_identifier` on rejection.\n *\n * @internal\n */\nexport function sanitizeIdentifier(input: string, options?: { maxLen?: number }): string {\n  const maxLen = options?.maxLen ?? 64;\n  if (input.length === 0 || input.length > maxLen) {\n    throw new ConfigurationError(`Identifier length out of range (1-${maxLen}): \"${input}\"`, {\n      code: \"invalid_identifier\",\n    });\n  }\n  if (!IDENTIFIER_PATTERN.test(input)) {\n    throw new ConfigurationError(`Identifier contains invalid characters: \"${input}\"`, {\n      code: \"invalid_identifier\",\n    });\n  }\n  return input.toLowerCase();\n}\n"]}