@theokit/sdk 1.6.2 → 1.8.0

package/dist/server/auth/types.d.cts

@@ -0,0 +1,91 @@
+/**
+ * @theokit/sdk/server/auth — orchestrator types (Caminho C Hybrid per G11)
+ *
+ * Plan: g11-auth-architecture-implementation v1.4 (sha256 4d381020...)
+ * Blueprint: g11-auth-architecture-decision v1.1 (SHIPPABLE 97.9)
+ * AUTH-DELEGATION lock (theokit/CLAUDE.md:217-225) — these types are the
+ * orchestrator contract; concrete OAuth/email providers ship in opt-in
+ * @theokit/auth-* packages (adapters layer per ADR D11).
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * SessionManager contract (matches theokit/packages/theo/src/server/auth/session.ts:49).
+ * Imported as type-only — runtime depends via peerDep `theokit@>=0.2.4`.
+ */
+export interface SessionManager<TSession> {
+    getSession(req: IncomingMessage): Promise<TSession | null>;
+    createSession(res: ServerResponse, data: TSession): Promise<void>;
+    destroySession(res: ServerResponse): void;
+    rotateSession(req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
+}
+/**
+ * Per ADR D5 — OAuth transaction state stored in encrypted HttpOnly cookie
+ * (cookie-state pattern). Expires within 10 minutes per invariant.
+ */
+export interface OAuthTransaction {
+    state: string;
+    pkceVerifier?: string;
+    returnTo?: string;
+    createdAt: number;
+    expiresAt: number;
+}
+/**
+ * Per ADR D9 — provider profile types are provider-specific (not unified).
+ * Each @theokit/auth-* package exports its own profile shape.
+ * Generic param TProfile lets consumers narrow via discriminated unions on providerName.
+ */
+export interface AuthResult<TProfile, TName extends string = string> {
+    profile: TProfile;
+    providerName: TName;
+    rawTokens?: {
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        expiresAt?: number;
+    };
+}
+/**
+ * Provider contract — each @theokit/auth-* package implements this.
+ * Per blueprint Q5 + ADR D11 (adapters layer).
+ */
+export interface AuthProvider<TProfile, TName extends string = string> {
+    name: TName;
+    createAuthorizationURL(tx: OAuthTransaction): URL | Promise<URL>;
+    handleCallback(req: IncomingMessage, tx: OAuthTransaction): Promise<AuthResult<TProfile, TName>>;
+}
+/**
+ * `defineAuth(opts)` configuration shape — Caminho C (Hybrid).
+ * `providers` optional: empty = Caminho A escape hatch (manual signIn only).
+ * `onSignIn` invoked after provider callback success; returns TSession to persist.
+ */
+export interface DefineAuthOptions<TSession> {
+    session: SessionManager<TSession>;
+    providers?: AuthProvider<unknown, string>[];
+    onSignIn?: <TProfile>(args: {
+        profile: TProfile;
+        provider: string;
+    }) => Promise<TSession>;
+    onSignOut?: (session: TSession | null) => Promise<void> | void;
+}
+/**
+ * Returned by `defineAuth<TSession>(opts)` — 5-method orchestrator surface.
+ *
+ * - startSignIn: returns Response.redirect to provider authorization URL with state cookie
+ * - finishSignIn: handles provider callback; verifies state; calls onSignIn; rotates session ID
+ *   (OWASP A07:2021 per EC-10); creates session cookie; clears transaction cookie
+ * - signIn: Caminho A escape hatch — skip OAuth flow; directly persist session from external profile
+ * - signOut: destroys session cookie + invokes onSignOut callback
+ * - getSession: read-only passthrough to session.getSession
+ */
+export interface AuthOrchestrator<TSession> {
+    startSignIn(providerName: string, req: IncomingMessage, opts?: {
+        returnTo?: string;
+    }): Promise<Response>;
+    finishSignIn(providerName: string, req: IncomingMessage, res: ServerResponse): Promise<{
+        session: TSession;
+        returnTo?: string;
+    }>;
+    signIn<TProfile>(profile: TProfile, providerName: string, req: IncomingMessage, res: ServerResponse): Promise<TSession>;
+    signOut(res: ServerResponse): void | Promise<void>;
+    getSession(req: IncomingMessage): Promise<TSession | null>;
+}

package/dist/server/auth/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @theokit/sdk/server/auth — orchestrator types (Caminho C Hybrid per G11)
+ *
+ * Plan: g11-auth-architecture-implementation v1.4 (sha256 4d381020...)
+ * Blueprint: g11-auth-architecture-decision v1.1 (SHIPPABLE 97.9)
+ * AUTH-DELEGATION lock (theokit/CLAUDE.md:217-225) — these types are the
+ * orchestrator contract; concrete OAuth/email providers ship in opt-in
+ * @theokit/auth-* packages (adapters layer per ADR D11).
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * SessionManager contract (matches theokit/packages/theo/src/server/auth/session.ts:49).
+ * Imported as type-only — runtime depends via peerDep `theokit@>=0.2.4`.
+ */
+export interface SessionManager<TSession> {
+    getSession(req: IncomingMessage): Promise<TSession | null>;
+    createSession(res: ServerResponse, data: TSession): Promise<void>;
+    destroySession(res: ServerResponse): void;
+    rotateSession(req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
+}
+/**
+ * Per ADR D5 — OAuth transaction state stored in encrypted HttpOnly cookie
+ * (cookie-state pattern). Expires within 10 minutes per invariant.
+ */
+export interface OAuthTransaction {
+    state: string;
+    pkceVerifier?: string;
+    returnTo?: string;
+    createdAt: number;
+    expiresAt: number;
+}
+/**
+ * Per ADR D9 — provider profile types are provider-specific (not unified).
+ * Each @theokit/auth-* package exports its own profile shape.
+ * Generic param TProfile lets consumers narrow via discriminated unions on providerName.
+ */
+export interface AuthResult<TProfile, TName extends string = string> {
+    profile: TProfile;
+    providerName: TName;
+    rawTokens?: {
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        expiresAt?: number;
+    };
+}
+/**
+ * Provider contract — each @theokit/auth-* package implements this.
+ * Per blueprint Q5 + ADR D11 (adapters layer).
+ */
+export interface AuthProvider<TProfile, TName extends string = string> {
+    name: TName;
+    createAuthorizationURL(tx: OAuthTransaction): URL | Promise<URL>;
+    handleCallback(req: IncomingMessage, tx: OAuthTransaction): Promise<AuthResult<TProfile, TName>>;
+}
+/**
+ * `defineAuth(opts)` configuration shape — Caminho C (Hybrid).
+ * `providers` optional: empty = Caminho A escape hatch (manual signIn only).
+ * `onSignIn` invoked after provider callback success; returns TSession to persist.
+ */
+export interface DefineAuthOptions<TSession> {
+    session: SessionManager<TSession>;
+    providers?: AuthProvider<unknown, string>[];
+    onSignIn?: <TProfile>(args: {
+        profile: TProfile;
+        provider: string;
+    }) => Promise<TSession>;
+    onSignOut?: (session: TSession | null) => Promise<void> | void;
+}
+/**
+ * Returned by `defineAuth<TSession>(opts)` — 5-method orchestrator surface.
+ *
+ * - startSignIn: returns Response.redirect to provider authorization URL with state cookie
+ * - finishSignIn: handles provider callback; verifies state; calls onSignIn; rotates session ID
+ *   (OWASP A07:2021 per EC-10); creates session cookie; clears transaction cookie
+ * - signIn: Caminho A escape hatch — skip OAuth flow; directly persist session from external profile
+ * - signOut: destroys session cookie + invokes onSignOut callback
+ * - getSession: read-only passthrough to session.getSession
+ */
+export interface AuthOrchestrator<TSession> {
+    startSignIn(providerName: string, req: IncomingMessage, opts?: {
+        returnTo?: string;
+    }): Promise<Response>;
+    finishSignIn(providerName: string, req: IncomingMessage, res: ServerResponse): Promise<{
+        session: TSession;
+        returnTo?: string;
+    }>;
+    signIn<TProfile>(profile: TProfile, providerName: string, req: IncomingMessage, res: ServerResponse): Promise<TSession>;
+    signOut(res: ServerResponse): void | Promise<void>;
+    getSession(req: IncomingMessage): Promise<TSession | null>;
+}

package/dist/server/auth/validate-return-to.d.cts

@@ -0,0 +1,17 @@
+/**
+ * @theokit/sdk/server/auth — same-origin returnTo validator
+ *
+ * Per v1.1 EC-2 MUST FIX — OWASP A01:2021 open-redirect mitigation.
+ *
+ * Without this check, attacker craft `/login?returnTo=https://evil.com` would
+ * cause post-login redirect to attacker domain with authenticated session cookie.
+ *
+ * Rules:
+ *   - undefined/empty returnTo → default '/'
+ *   - protocol-relative `//evil.com` → default '/' (URL parser would resolve to baseUrl protocol)
+ *   - absolute URL with origin ≠ baseUrl.origin → default '/' (cross-origin redirect)
+ *   - absolute URL with origin === baseUrl.origin → keep (same-origin allowed)
+ *   - relative path starting with '/' → keep (same-app navigation)
+ *   - relative path not starting with '/' → default '/' (defensive)
+ */
+export declare function validateReturnTo(returnTo: string | undefined, baseUrl: URL): string;

package/dist/server/auth/validate-return-to.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @theokit/sdk/server/auth — same-origin returnTo validator
+ *
+ * Per v1.1 EC-2 MUST FIX — OWASP A01:2021 open-redirect mitigation.
+ *
+ * Without this check, attacker craft `/login?returnTo=https://evil.com` would
+ * cause post-login redirect to attacker domain with authenticated session cookie.
+ *
+ * Rules:
+ *   - undefined/empty returnTo → default '/'
+ *   - protocol-relative `//evil.com` → default '/' (URL parser would resolve to baseUrl protocol)
+ *   - absolute URL with origin ≠ baseUrl.origin → default '/' (cross-origin redirect)
+ *   - absolute URL with origin === baseUrl.origin → keep (same-origin allowed)
+ *   - relative path starting with '/' → keep (same-app navigation)
+ *   - relative path not starting with '/' → default '/' (defensive)
+ */
+export declare function validateReturnTo(returnTo: string | undefined, baseUrl: URL): string;

package/dist/server/errors-envelope.cjs

@@ -0,0 +1,409 @@
+'use strict';
+
+// src/internal/security/redact.ts
+var REDACT_ENABLED = readEnvOnce();
+function readEnvOnce() {
+  const raw = process.env.THEOKIT_REDACT_SECRETS;
+  if (raw === void 0) return true;
+  return ["1", "true", "yes", "on"].includes(raw.toLowerCase());
+}
+var warnedOptOut = false;
+if (!REDACT_ENABLED && !warnedOptOut) {
+  process.stderr.write(
+    "[theokit-sdk] Secret redaction is DISABLED via THEOKIT_REDACT_SECRETS. Credentials may leak into errors, telemetry, logs, transcripts.\n"
+  );
+  warnedOptOut = true;
+}
+var BUILTIN_PATTERNS = [
+  // T5.4: 30+ vendor prefixes (was 12 pre-T5.4). Order matters — more
+  // specific prefixes precede generic ones (e.g., sk-ant-admin01 before
+  // sk-ant-, sk-proj- before sk-). PEM block deliberately first so its
+  // multi-line span runs before any per-line patterns can fire.
+  /-----BEGIN[ ]+(?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----[\s\S]+?-----END[ ]+(?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----/g,
+  // JWT — exact 3-segment base64url. Dotted; the body floor of 4 chars per
+  // segment matches the minimum legal payload while skipping `a.b.c` noise.
+  /eyJ[A-Za-z0-9_-]{4,}\.eyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}/g,
+  // Azure Storage SAS — match the sig= component (URL-encoded base64).
+  /(?<=[?&]sig=)[A-Za-z0-9%+/]{20,}/g,
+  // Anthropic
+  /sk-ant-admin01-[A-Za-z0-9_-]{10,}/g,
+  //   Anthropic admin keys (must precede sk-ant-)
+  /sk-ant-[A-Za-z0-9_-]{10,}/g,
+  //           Anthropic regular
+  // OpenAI family + clones (sk- generic must come AFTER all sk-foo- variants)
+  /sk-proj-[A-Za-z0-9_-]{10,}/g,
+  //  OpenAI project key (must precede sk- generic)
+  /sk-[A-Za-z0-9_-]{10,}/g,
+  //       OpenAI / OpenRouter / DeepInfra / Together / DeepSeek
+  // Provider prefixes (alphabetized for maintainability)
+  /AIza[A-Za-z0-9_-]{35}/g,
+  //       Google API key
+  /AKIA[A-Z0-9]{16}/g,
+  //            AWS access key
+  /fw_[A-Za-z0-9]{20,}/g,
+  //         Fireworks
+  /glpat-[A-Za-z0-9_-]{20}/g,
+  //     GitLab PAT
+  /ghp_[A-Za-z0-9]{36}/g,
+  //         GitHub PAT classic
+  /github_pat_[A-Za-z0-9_]{82}/g,
+  // GitHub PAT fine-grained
+  /gsk_[A-Za-z0-9]{20,}/g,
+  //        Groq
+  /hf_[A-Za-z0-9]{20,}/g,
+  //         HuggingFace
+  /\bpa-[A-Za-z0-9_-]{20,}/g,
+  //     Voyage AI (word-boundary to skip CSS / kebab IDs)
+  /pcsk_[A-Za-z0-9_-]{20,}/g,
+  //     Pinecone
+  /pplx-[A-Za-z0-9_-]{20,}/g,
+  //     Perplexity
+  /r8_[A-Za-z0-9_-]{20,}/g,
+  //       Replicate
+  /rk_live_[A-Za-z0-9]{20,}/g,
+  //    Stripe restricted
+  /sk_live_[A-Za-z0-9]{20,}/g,
+  //    Stripe secret
+  /sntrys_[A-Za-z0-9]{40,}/g,
+  //     Sentry user auth
+  /xai-[A-Za-z0-9_-]{20,}/g,
+  //      xAI (Grok)
+  /xox[bpasr]-[A-Za-z0-9-]{10,}/g,
+  //Slack tokens
+  // Additional unique-prefix tokens with low false-positive risk
+  /npm_[A-Za-z0-9]{36}/g,
+  //         npm access token
+  /SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}/g,
+  // SendGrid
+  /\bSK[A-Za-z0-9]{32}\b/g,
+  //       Twilio API SID (word-boundary to skip CSS class noise)
+  /\bkey-[a-f0-9]{32}\b/g,
+  //        Mailgun (hex-only narrows false positives)
+  /MT[A-Za-z0-9_-]{23}\.[A-Za-z0-9_-]{6}\.[A-Za-z0-9_-]{27}/g,
+  // Discord bot
+  /\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
+];
+var BEARER_PATTERN = /\b(Bearer\s+)([A-Za-z0-9_\-.+/=]{8,})/g;
+var PARAM_PATTERN = /(\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;
+var _extraPatterns = [];
+function maskToken(token) {
+  if (token.length < 18) return "***";
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+function coerceToString(value) {
+  if (typeof value === "string") return value;
+  if (value === null || value === void 0) return null;
+  if (typeof value === "object") {
+    try {
+      const s = JSON.stringify(value);
+      return s === void 0 ? null : s;
+    } catch {
+      return "[unredactable: circular]";
+    }
+  }
+  return String(value);
+}
+function redactSecrets(text, opts) {
+  const coerced = coerceToString(text);
+  if (coerced === null) return "";
+  if (!REDACT_ENABLED) return coerced;
+  let s = coerced;
+  for (const re of BUILTIN_PATTERNS) {
+    s = s.replace(re, (m) => maskToken(m));
+  }
+  for (const re of _extraPatterns) {
+    s = s.replace(re, (m) => maskToken(m));
+  }
+  {
+    s = s.replace(BEARER_PATTERN, (_, prefix) => `${prefix}***`);
+    s = s.replace(PARAM_PATTERN, (whole, prefix, value) => {
+      if (value.includes("...")) return whole;
+      return `${prefix}***`;
+    });
+  }
+  return s;
+}
+
+// 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 AuthenticationError = class extends TheokitAgentError {
+  name = "AuthenticationError";
+  constructor(message, options = {}) {
+    super(message, { ...options, isRetryable: false });
+  }
+};
+var RateLimitError = class extends TheokitAgentError {
+  name = "RateLimitError";
+  constructor(message, options = {}) {
+    super(message, { ...options, isRetryable: true });
+  }
+};
+var ConfigurationError = class extends TheokitAgentError {
+  name = "ConfigurationError";
+  constructor(message, options = {}) {
+    super(message, { ...options, isRetryable: false });
+  }
+};
+var NetworkError = class extends TheokitAgentError {
+  name = "NetworkError";
+  constructor(message, options = {}) {
+    super(message, { ...options, isRetryable: true });
+  }
+};
+var UnknownAgentError = class extends TheokitAgentError {
+  name = "UnknownAgentError";
+  constructor(message, options = {}) {
+    super(message, { ...options, isRetryable: false });
+  }
+};
+var AgentRunError = class extends TheokitAgentError {
+  name = "AgentRunError";
+  provider;
+  raw;
+  /** Provider's request id (`x-request-id` / `request-id` header). Useful for support tickets. */
+  requestId;
+  /** SDK conversation id this error was raised inside. */
+  conversationId;
+  constructor(message, options) {
+    super(message, {
+      code: options.code,
+      cause: options.cause,
+      metadata: options.metadata,
+      // D311: most AgentRunErrors are not retriable (auth, validation, abort).
+      // Provider mappers (D314) override per-status — explicit `retriable` wins
+      // over the implicit default when supplied.
+      isRetryable: options.retriable ?? defaultRetriableForCode(options.code)
+    });
+    if (options.provider !== void 0) this.provider = options.provider;
+    if (options.raw !== void 0) this.raw = options.raw;
+    if (options.requestId !== void 0) this.requestId = options.requestId;
+    if (options.conversationId !== void 0) this.conversationId = options.conversationId;
+  }
+  /**
+   * Production-Readiness #3 (ADR D311): alias for `isRetryable` exposed as
+   * `retriable` to match the handoff contract. Future v2 will deprecate
+   * `isRetryable` in favor of this.
+   */
+  get retriable() {
+    return this.isRetryable;
+  }
+  /**
+   * D312: provider's `Retry-After` header in **milliseconds**. Mappers store
+   * the header value (seconds) in `metadata.retryAfter`; this getter
+   * multiplies by 1000 so the result composes with `Date.now()`/`setTimeout`.
+   *
+   * Returns `undefined` when no hint was provided. `0` is a legitimate value
+   * — use `=== undefined` check rather than truthy check.
+   */
+  get retryAfterMs() {
+    if (this.metadata?.retryAfter === void 0) return void 0;
+    return this.metadata.retryAfter * 1e3;
+  }
+  /**
+   * D313 + T1.5: alias for `metadata.raw`. Provider response body for
+   * debugging. T1.5 wraps the value in `redactSecrets` at the getter
+   * boundary so secret-shaped substrings (`sk-...`, Bearer JWTs, etc.) are
+   * stripped before reaching the caller. Available but NEVER serialized
+   * into `.message` (anti-leak invariant).
+   */
+  get providerError() {
+    const raw = this.metadata?.raw;
+    if (raw === void 0) return void 0;
+    if (typeof raw === "string") return redactSecrets(raw);
+    try {
+      return redactSecrets(JSON.stringify(raw));
+    } catch {
+      return redactSecrets(String(raw));
+    }
+  }
+  /**
+   * T1.5 — sanitized JSON form. `metadata.raw` is OMITTED by default; opt
+   * in via `THEOKIT_DEBUG_RAW_ERRORS=1` to surface the (redacted) raw
+   * payload for diagnostics. Every other field stays accessible.
+   *
+   * The single env-var gate is read each call so operators can toggle at
+   * runtime without restarting the process.
+   */
+  toJSON() {
+    const json = {
+      name: this.name,
+      message: this.message,
+      isRetryable: this.isRetryable
+    };
+    addOptionalFields(json, this);
+    const safeMeta = sanitizeMetadata(this.metadata);
+    if (safeMeta !== void 0) json.metadata = safeMeta;
+    return json;
+  }
+};
+function addOptionalFields(json, err) {
+  if (err.code !== void 0) json.code = err.code;
+  if (err.provider !== void 0) json.provider = err.provider;
+  if (err.requestId !== void 0) json.requestId = err.requestId;
+  if (err.conversationId !== void 0) json.conversationId = err.conversationId;
+  if (err.raw !== void 0) json.raw = redactSecrets(err.raw);
+}
+function sanitizeMetadata(meta) {
+  if (meta === void 0) return void 0;
+  const { raw, ...rest } = meta;
+  const debugRaw = process.env.THEOKIT_DEBUG_RAW_ERRORS === "1";
+  if (debugRaw && raw !== void 0) {
+    const redactedRaw = typeof raw === "string" ? redactSecrets(raw) : redactSecrets(safeStringify(raw));
+    return { ...rest, raw: redactedRaw };
+  }
+  return rest;
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function defaultRetriableForCode(code) {
+  switch (code) {
+    case "rate_limit":
+    case "timeout":
+    case "server_error":
+    case "network":
+    case "provider_unreachable":
+      return true;
+    default:
+      return false;
+  }
+}
+var CredentialPoolExhaustedError = class extends TheokitAgentError {
+  name = "CredentialPoolExhaustedError";
+  provider;
+  nextRetryAt;
+  constructor(message, options) {
+    super(message, {
+      ...options,
+      isRetryable: true,
+      code: options.code ?? "credential_pool_exhausted"
+    });
+    this.provider = options.provider;
+    this.nextRetryAt = options.nextRetryAt;
+  }
+};
+var MemoryAdapterError = class extends TheokitAgentError {
+  name = "MemoryAdapterError";
+  adapterId;
+  constructor(message, options) {
+    super(message, {
+      isRetryable: options.code === "rate_limited" || options.code === "network",
+      code: options.code,
+      ...options.cause !== void 0 ? { cause: options.cause } : {},
+      ...options.metadata !== void 0 ? { metadata: options.metadata } : {}
+    });
+    this.adapterId = options.adapterId;
+  }
+};
+
+// src/server/errors-envelope.ts
+var NAME_TO_CODE = /* @__PURE__ */ new Map([
+  ["AuthenticationError", "UNAUTHORIZED"],
+  ["RateLimitError", "RATE_LIMITED"],
+  ["ConfigurationError", "PROVIDER_KEY_MISSING"],
+  ["IntegrationNotConnectedError", "PROVIDER_KEY_MISSING"],
+  ["NetworkError", "SERVICE_UNAVAILABLE"],
+  ["AgentRunError", "AGENT_RUN_ERROR"],
+  ["BudgetExceededError", "BUDGET_EXCEEDED"],
+  ["CredentialPoolExhaustedError", "CREDENTIAL_POOL_EXHAUSTED"],
+  ["UnknownAgentError", "INTERNAL_SERVER_ERROR"],
+  ["MemoryAdapterError", "INTERNAL_SERVER_ERROR"]
+]);
+function toEnvelope(value) {
+  if (!(value instanceof Error)) {
+    return {
+      code: "INTERNAL_SERVER_ERROR",
+      message: typeof value === "string" ? value : "Unknown error"
+    };
+  }
+  const name = value.name;
+  const code = NAME_TO_CODE.get(name) ?? "INTERNAL_SERVER_ERROR";
+  const meta = buildMeta(name, value);
+  const ext = buildExt(value);
+  return {
+    code,
+    message: value.message,
+    cause: value.cause,
+    meta,
+    ext
+  };
+}
+function buildMeta(name, err) {
+  const meta = { sdkErrorName: name };
+  if (err instanceof TheokitAgentError && err.metadata !== void 0) {
+    meta.provider = err.metadata.provider;
+    meta.endpoint = err.metadata.endpoint;
+    if (err.metadata.statusCode !== void 0) {
+      meta.statusCode = err.metadata.statusCode;
+    }
+  }
+  return meta;
+}
+function buildExt(err) {
+  if (err instanceof RateLimitError && err.metadata?.retryAfter !== void 0) {
+    return {
+      retryable: true,
+      retryAfterMs: err.metadata.retryAfter * 1e3
+    };
+  }
+  if (err instanceof CredentialPoolExhaustedError && err.nextRetryAt !== void 0) {
+    const delayMs = Math.max(0, err.nextRetryAt - Date.now());
+    return {
+      retryable: true,
+      retryAfterMs: delayMs
+    };
+  }
+  return void 0;
+}
+var CODE_TO_RECONSTRUCTOR = /* @__PURE__ */ new Map([
+  ["UNAUTHORIZED", (env) => new AuthenticationError(env.message)],
+  [
+    "RATE_LIMITED",
+    (env) => new RateLimitError(env.message, env.cause !== void 0 ? { cause: env.cause } : {})
+  ],
+  ["PROVIDER_KEY_MISSING", (env) => new ConfigurationError(env.message)],
+  ["SERVICE_UNAVAILABLE", (env) => new NetworkError(env.message)],
+  ["GATEWAY_TIMEOUT", (env) => new NetworkError(env.message)],
+  [
+    "AGENT_RUN_ERROR",
+    (env) => new AgentRunError(env.message, {
+      code: "unknown",
+      ...env.cause !== void 0 ? { cause: env.cause } : {}
+    })
+  ],
+  ["INTERNAL_SERVER_ERROR", (env) => new UnknownAgentError(env.message)]
+  // BUDGET_EXCEEDED + CREDENTIAL_POOL_EXHAUSTED reconstructors require
+  // domain-specific args (budgetName, provider) that the envelope doesn't
+  // always carry. Fall back to UnknownAgentError when those fields are
+  // missing; consumer code that needs the typed class should call the
+  // constructor directly.
+]);
+function fromEnvelope(env) {
+  const reconstructor = CODE_TO_RECONSTRUCTOR.get(env.code);
+  if (reconstructor) return reconstructor(env);
+  return new UnknownAgentError(env.message);
+}
+
+exports.MemoryAdapterError = MemoryAdapterError;
+exports.fromEnvelope = fromEnvelope;
+exports.toEnvelope = toEnvelope;
+//# sourceMappingURL=errors-envelope.cjs.map
+//# sourceMappingURL=errors-envelope.cjs.map