theokit 0.46.1 → 0.48.0

package/dist/{chunk-HGZL5EOI.js → chunk-VQIUTCK2.js}

@@ -64,7 +64,19 @@ var ERROR_NAME_TO_CODE = /* @__PURE__ */ new Map([
   // RouterConventionError reaches the wire only during dev-error overlay;
   // INTERNAL_SERVER_ERROR is appropriate, but we add a HintExt-shaped ext
   // with the migration guidance for the devtools display.
-  ["RouterConventionError", "INTERNAL_SERVER_ERROR"]
+  ["RouterConventionError", "INTERNAL_SERVER_ERROR"],
+  // M80 — the agent errors, which this table contained NONE of.
+  //
+  // The consequence was concrete: a `GuardrailViolationError` — thrown when a prompt-injection or
+  // PII guard BLOCKS — crossed as HTTP 500, indistinguishable from a real server failure. Retry
+  // middleware then re-submitted the very input the guard had just rejected.
+  //
+  // The status codes say what actually happened: the request was refused (400), the caller has
+  // spent its budget (429), or a human must approve before this proceeds (403). None of the three
+  // is "the server broke", and none should be retried by a generic 5xx policy.
+  ["GuardrailViolationError", "BAD_REQUEST"],
+  ["CostBudgetExceededError", "TOO_MANY_REQUESTS"],
+  ["InProcessApprovalRequiredError", "FORBIDDEN"]
 ]);
 var META_EXTRACTORS = /* @__PURE__ */ new Map([
   [
@@ -87,6 +99,20 @@ var META_EXTRACTORS = /* @__PURE__ */ new Map([
         migrationUrl: e.migrationUrl
       };
     }
+  ],
+  [
+    // M80 — so telemetry can count blocks PER GUARD without parsing the message. A count derived
+    // from message text breaks the first time somebody improves the wording, and the improvement
+    // looks harmless right up until the dashboard goes flat.
+    //
+    // Read from the class's own public fields rather than the SDK's `metadata`: that type is
+    // provider-transport shaped (`provider`, `endpoint`, `statusCode`, `retryAfter`), and an
+    // agent-domain fact does not belong in it.
+    "GuardrailViolationError",
+    (err) => {
+      const e = err;
+      return { guardName: e.guardName, phase: e.phase };
+    }
   ]
 ]);
 var EXT_BUILDERS = /* @__PURE__ */ new Map([
@@ -132,4 +158,4 @@ export {
   TheoError,
   serverErrorToEnvelope
 };
-//# sourceMappingURL=chunk-HGZL5EOI.js.map
+//# sourceMappingURL=chunk-VQIUTCK2.js.map

package/dist/chunk-VQIUTCK2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/contracts/theo-error.ts","../src/core/contracts/server-error-to-envelope.ts"],"sourcesContent":["/**\n * `TheoError` — envelope-emitting `Error` subclass per plan\n * g5-error-envelope-cross-layer v1.0 § Phase 1 / T1.2.\n *\n * Mirrors trpc's TRPCError ergonomic pattern (reference:\n * trpc/packages/server/src/unstable-core-do-not-import/error/TRPCError.ts:65-87)\n * adapted for theokit's hybrid envelope model (blueprint Form 4).\n *\n * Per ADR D5: `meta.stack` is auto-stripped in non-dev builds when serialized\n * via `toJSON()` — defense against accidental stack leak to clients (encore\n * `json:\"-\"` analog).\n *\n * Lives in `core/contracts/` per architecture.md v3 invariant #3.\n */\n\nimport type { TheoErrorCode, TheoErrorEnvelope } from './error-envelope.js'\n\n/**\n * Constructor options. `code` and `message` are required; `cause` follows TC39\n * proposal-error-cause; `meta` and `ext` are opt-in per blueprint ADR D2.\n */\nexport interface TheoErrorOptions<TExt = unknown> {\n  readonly code: TheoErrorCode\n  readonly message: string\n  readonly cause?: unknown\n  readonly meta?: Record<string, unknown>\n  readonly ext?: TExt\n}\n\n/**\n * `TheoError` — envelope-emitting Error subclass. Use this anywhere in\n * `theokit/server`, route handlers, or middleware to emit a typed,\n * cross-layer-compatible error.\n *\n * Mirrors TRPCError pattern: `code` is required, `message` defaults to\n * code if omitted, `cause` chain is preserved via TC39 proposal-error-cause.\n */\nexport class TheoError<TExt = unknown> extends Error {\n  override readonly name = 'TheoError'\n  readonly code: TheoErrorCode\n  readonly meta?: Record<string, unknown>\n  readonly ext?: TExt\n\n  constructor(opts: TheoErrorOptions<TExt>) {\n    super(opts.message, opts.cause !== undefined ? { cause: opts.cause } : undefined)\n    this.code = opts.code\n    this.meta = opts.meta\n    this.ext = opts.ext\n  }\n\n  /**\n   * The canonical envelope view of this error. Use when crossing the wire\n   * boundary or feeding telemetry — exposes the shape consumers can rely on\n   * without depending on the class identity.\n   */\n  get envelope(): TheoErrorEnvelope<TExt> {\n    return {\n      code: this.code,\n      message: this.message,\n      cause: (this as Error & { cause?: unknown }).cause,\n      meta: this.meta,\n      ext: this.ext,\n    }\n  }\n\n  /**\n   * JSON serialization — emits envelope shape only (no name/stack class\n   * internals). Per ADR D5, `meta.stack` is auto-stripped in non-dev to\n   * prevent accidental leak; other meta keys are preserved.\n   */\n  toJSON(): TheoErrorEnvelope<TExt> {\n    const meta = this.meta ? sanitizeMeta(this.meta) : undefined\n    return {\n      code: this.code,\n      message: this.message,\n      cause: (this as Error & { cause?: unknown }).cause,\n      meta,\n      ext: this.ext,\n    }\n  }\n}\n\n/**\n * Strip server-only sensitive meta keys in non-dev builds. Per ADR D5,\n * `stack` is the canonical leak vector (trpc accidentally exposes it via\n * `config.isDev` even today — references/trpc getErrorShape.ts:29-31).\n * Default to safe-by-default; preserve in dev only.\n */\nfunction sanitizeMeta(meta: Record<string, unknown>): Record<string, unknown> | undefined {\n  // Treat anything other than NODE_ENV === 'development' as production-safe\n  // (CI, staging, production all strip). Matches the security posture in\n  // blueprint EC-5 (default STRICT).\n  if (process.env.NODE_ENV === 'development') {\n    return meta\n  }\n  const out: Record<string, unknown> = {}\n  for (const [k, v] of Object.entries(meta)) {\n    if (k === 'stack') continue\n    out[k] = v\n  }\n  return out\n}\n\n/**\n * Coerce any unknown value into a TheoError envelope.\n *\n * - If value is already a TheoError, returns it unchanged (no double-wrap).\n * - If value is a plain Error, wraps it as `INTERNAL_SERVER_ERROR` with\n *   `cause` chain preserving the original.\n * - Other values (string, undefined, object) are coerced safely with a\n *   meaningful message.\n *\n * Use at framework boundaries (route handler catch-all, middleware catch,\n * SDK egress) to ensure every error crossing the wire carries an envelope.\n */\n/**\n * `NotFoundError` — typed 404. A `TheoError` with code `NOT_FOUND`, so it\n * carries a stable `code` (not a bare status literal) and maps to HTTP 404 via\n * `envelopeCodeToStatus`. Throw it from a `defineRoute` handler for ergonomic\n * 404s (M7-1).\n */\nexport class NotFoundError extends TheoError {\n  constructor(message = 'Not Found', meta?: Record<string, unknown>) {\n    super({ code: 'NOT_FOUND', message, ...(meta !== undefined ? { meta } : {}) })\n  }\n}\n\nexport function fromUnknown(value: unknown): TheoError {\n  if (value instanceof TheoError) return value\n  if (value instanceof Error) {\n    return new TheoError({\n      code: 'INTERNAL_SERVER_ERROR',\n      message: value.message,\n      cause: value,\n    })\n  }\n  if (typeof value === 'string') {\n    return new TheoError({ code: 'INTERNAL_SERVER_ERROR', message: value })\n  }\n  if (value === undefined || value === null) {\n    return new TheoError({ code: 'INTERNAL_SERVER_ERROR', message: 'Unknown error' })\n  }\n  // Object / number / boolean / etc. — best-effort stringify\n  return new TheoError({\n    code: 'INTERNAL_SERVER_ERROR',\n    message: `Non-Error value thrown: ${safeStringify(value)}`,\n    cause: value,\n  })\n}\n\n/**\n * Best-effort stringify of an unknown value for error message context.\n * JSON.stringify first (preserves shape for diagnostics); on cycle/BigInt/symbol\n * failure, signal explicitly instead of falling back to `[object Object]`.\n */\nfunction safeStringify(value: unknown): string {\n  if (typeof value === 'string') return value\n  if (typeof value === 'number' || typeof value === 'boolean') return String(value)\n  if (typeof value === 'bigint') return `${value.toString()}n`\n  if (typeof value === 'symbol') return value.toString()\n  try {\n    return JSON.stringify(value)\n  } catch {\n    return '[unstringifiable value]'\n  }\n}\n","/**\n * G5 T2.5 — server-side boundary translation per blueprint ADR D3.\n *\n * Translates ad-hoc Error class instances (FileTooLargeError,\n * AuthRequiredError, RouterConventionError, etc.) into the canonical\n * `TheoErrorEnvelope` shape at the wire boundary. This is the SINGLE\n * boundary translation point — class identities stay in place inside the\n * codebase (no invasive call-site rewrites), but the envelope is what\n * crosses to clients.\n *\n * Pure; no I/O. Lives in `core/contracts/` per architecture.md v3\n * invariant #3 (canonical home for shared client↔server types). This file\n * is the EXCEPTION-of-an-exception: it intentionally inspects Error names\n * by string instead of `instanceof` to avoid `core/contracts/` taking a\n * dependency on `server/`. The mapping table is small and grep-discoverable.\n */\n\nimport type { TheoErrorCode, TheoErrorEnvelope } from './error-envelope.js'\nimport { TheoError } from './theo-error.js'\n\n/**\n * Mapping from ad-hoc Error class name to envelope code. Add entries here\n * when a new ad-hoc Error is introduced anywhere in `theokit/server/`.\n * Build-time errors (Duplicate*, ActionScanError, InvalidPluginShapeError)\n * are NOT in this table by design — they never cross the wire boundary,\n * so their canonical shape is `INTERNAL_SERVER_ERROR` via the default branch.\n */\nconst ERROR_NAME_TO_CODE: ReadonlyMap<string, TheoErrorCode> = new Map<string, TheoErrorCode>([\n  ['AuthRequiredError', 'UNAUTHORIZED'],\n  ['FileTooLargeError', 'PAYLOAD_TOO_LARGE'],\n  ['RequestBodyTooLargeError', 'PAYLOAD_TOO_LARGE'],\n  ['BodyTooLargeError', 'PAYLOAD_TOO_LARGE'],\n  // RouterConventionError reaches the wire only during dev-error overlay;\n  // INTERNAL_SERVER_ERROR is appropriate, but we add a HintExt-shaped ext\n  // with the migration guidance for the devtools display.\n  ['RouterConventionError', 'INTERNAL_SERVER_ERROR'],\n\n  // M80 — the agent errors, which this table contained NONE of.\n  //\n  // The consequence was concrete: a `GuardrailViolationError` — thrown when a prompt-injection or\n  // PII guard BLOCKS — crossed as HTTP 500, indistinguishable from a real server failure. Retry\n  // middleware then re-submitted the very input the guard had just rejected.\n  //\n  // The status codes say what actually happened: the request was refused (400), the caller has\n  // spent its budget (429), or a human must approve before this proceeds (403). None of the three\n  // is \"the server broke\", and none should be retried by a generic 5xx policy.\n  ['GuardrailViolationError', 'BAD_REQUEST'],\n  ['CostBudgetExceededError', 'TOO_MANY_REQUESTS'],\n  ['InProcessApprovalRequiredError', 'FORBIDDEN'],\n])\n\ntype MetaExtractor = (err: Error) => Record<string, unknown> | null\n\n/**\n * Class-specific metadata extractors. Each function receives the raw Error\n * and returns an object merged into envelope.meta (excluding name/message\n * which are reserved).\n */\nconst META_EXTRACTORS: ReadonlyMap<string, MetaExtractor> = new Map<string, MetaExtractor>([\n  [\n    'FileTooLargeError',\n    (err) => {\n      const e = err as Error & { truncatedFilenames?: string[]; maxFileSize?: number }\n      return {\n        truncatedFilenames: e.truncatedFilenames ?? [],\n        maxFileSize: e.maxFileSize,\n      }\n    },\n  ],\n  [\n    'RouterConventionError',\n    (err) => {\n      const e = err as Error & { file?: string; suggestion?: string; migrationUrl?: string }\n      return {\n        file: e.file,\n        suggestion: e.suggestion,\n        migrationUrl: e.migrationUrl,\n      }\n    },\n  ],\n  [\n    // M80 — so telemetry can count blocks PER GUARD without parsing the message. A count derived\n    // from message text breaks the first time somebody improves the wording, and the improvement\n    // looks harmless right up until the dashboard goes flat.\n    //\n    // Read from the class's own public fields rather than the SDK's `metadata`: that type is\n    // provider-transport shaped (`provider`, `endpoint`, `statusCode`, `retryAfter`), and an\n    // agent-domain fact does not belong in it.\n    'GuardrailViolationError',\n    (err) => {\n      const e = err as Error & { guardName?: string; phase?: string }\n      return { guardName: e.guardName, phase: e.phase }\n    },\n  ],\n])\n\ntype ExtBuilder = (err: Error) => unknown\n\n/**\n * Class-specific ext (extension slot) builders. RouterConventionError ships a\n * HintExt-shaped `{ hint }` so devtools / dev overlay can render the actionable\n * migration tip directly.\n */\nconst EXT_BUILDERS: ReadonlyMap<string, ExtBuilder> = new Map<string, ExtBuilder>([\n  [\n    'RouterConventionError',\n    () => ({\n      hint: 'Run `theokit migrate router` to convert dotted-basename routes to directory-nested form.',\n    }),\n  ],\n])\n\n/**\n * Translate any server-side Error instance into a canonical envelope.\n *\n * Pass-through behavior:\n * - `TheoError` instances return their `.envelope` unchanged.\n * - Plain `Error` with unknown name → `INTERNAL_SERVER_ERROR`.\n * - Non-Error values → wrapped via `TheoError.fromUnknown` semantics.\n *\n * Meta carries the source class `name` plus class-specific fields when an\n * extractor is registered. This keeps wire-side telemetry useful without\n * leaking implementation details.\n */\nexport function serverErrorToEnvelope(value: unknown): TheoErrorEnvelope {\n  if (value instanceof TheoError) {\n    return value.envelope\n  }\n  if (!(value instanceof Error)) {\n    return {\n      code: 'INTERNAL_SERVER_ERROR',\n      message: typeof value === 'string' ? value : 'Unknown error',\n    }\n  }\n  const name = value.name\n  const code = ERROR_NAME_TO_CODE.get(name) ?? 'INTERNAL_SERVER_ERROR'\n  const extractor = META_EXTRACTORS.get(name)\n  const extra = extractor ? extractor(value) : null\n  const meta: Record<string, unknown> = { name }\n  if (extra) {\n    for (const [k, v] of Object.entries(extra)) {\n      if (v !== undefined) meta[k] = v\n    }\n  }\n  const extBuilder = EXT_BUILDERS.get(name)\n  const ext = extBuilder ? extBuilder(value) : undefined\n  return {\n    code,\n    message: value.message,\n    cause: (value as Error & { cause?: unknown }).cause,\n    meta,\n    ext,\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-6VDYQ4I6.js → chunk-VTJMND23.js}

@@ -2,7 +2,7 @@
 import "tsx/esm";
 import {
   getApprovalRegistry
-} from "./chunk-TDNNBLGW.js";
+} from "./chunk-6GGWS7J3.js";
 import {
   dispatchCsrfWarn,
   enforceCsrf,
@@ -16,7 +16,7 @@ import {
 import {
   TheoError,
   serverErrorToEnvelope
-} from "./chunk-HGZL5EOI.js";
+} from "./chunk-VQIUTCK2.js";
 
 // src/core/contracts/auth-error-guard.ts
 function isAuthRequiredError(err) {
@@ -1546,7 +1546,7 @@ function createRateLimiter(config, opts = {}) {
       return resultFromState(state, config);
     }
     throw new Error(
-      "createRateLimiter: async RateLimitStore implementations are not supported by this sync fa\xE7ade. Use the InMemoryStore default or build a custom middleware around the async store directly."
+      "createRateLimiter: async RateLimitStore implementations are not supported by this sync facade. Use the InMemoryStore default or build a custom middleware around the async store directly."
     );
   };
 }
@@ -1922,4 +1922,4 @@ export {
   applySecurityHeaders,
   generateNonce
 };
-//# sourceMappingURL=chunk-6VDYQ4I6.js.map
+//# sourceMappingURL=chunk-VTJMND23.js.map