theokit 0.4.0-beta.0 → 0.5.0

package/dist/chunk-R7OC6UDK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/scan/action-scan.ts"],"sourcesContent":["/* eslint-disable security/detect-non-literal-fs-filename --\n * Build-time scanner: walks `serverDir/actions/` derived from cwd.\n * No HTTP input ever reaches these fs calls.\n */\nimport { existsSync, readFileSync, statSync } from 'node:fs'\nimport { extname, join, relative } from 'node:path'\n\nimport { walkSourceFiles } from '../_internal/scan-walker.js'\n\nexport interface ActionNode {\n  filePath: string\n  actionPath: string\n}\n\n/**\n * Enriched manifest entry per plan g3-server-actions-and-useaction v1.2\n * § Phase 1 / T1.4 + ADR D4. Consumed by virtual module `@theo/actions`\n * (T3.1) and G4 devtools \"Actions\" tab (T5.1).\n */\nexport interface ActionManifestEntry {\n  name: string\n  filePath: string\n  urlPath: string\n  accept: 'form' | 'json'\n  hasInput: boolean\n  /**\n   * P#4 plugin-forms shared-schema convention (per plan p4-plugin-forms v1.1 T1.1).\n   * When present, points to an isomorphic schema file at\n   * `<serverDir>/actions/schemas/<basename>.ts` exporting `export const schema = z.object(...)`.\n   * Virtual module emits `import {schema} from '<schemaFilePath>'` + attaches as\n   * `actions.X.__zodSchema` so client-side <TheoForm> can drive zodResolver.\n   * Undefined when convention not followed (graceful degrade — TheoForm still\n   * works via explicit `schema={...}` prop escape hatch).\n   */\n  schemaFilePath?: string\n}\n\n/**\n * EC-2: structured error for scan-time defects (name collision, reserved\n * identifier, etc.). Throw at scan time to fail loud — silent shadowing is\n * a security/correctness footgun.\n */\nexport class ActionScanError extends Error {\n  readonly code: 'NAME_COLLISION' | 'RESERVED_NAME'\n  readonly conflictingPaths: readonly string[]\n\n  constructor(\n    code: 'NAME_COLLISION' | 'RESERVED_NAME',\n    message: string,\n    conflictingPaths: readonly string[],\n  ) {\n    super(message)\n    // T4.1 fix: identify class by name so serverErrorToEnvelope boundary\n    // translator can route via class-name lookup (without this, runtime\n    // `err.name` defaults to 'Error' and the meta.name diagnostic is wrong).\n    this.name = 'ActionScanError'\n    this.code = code\n    this.conflictingPaths = conflictingPaths\n  }\n}\n\nconst ACTION_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx'])\nconst TEST_FILE_RE = /\\.(test|spec)\\.(ts|tsx|js|jsx)$/\nconst RESERVED_NAMES = new Set(['index', 'constructor', '__proto__', 'prototype', 'hasOwnProperty'])\n\n/**\n * Backward-compatible: original simple-shape scanner used by existing\n * consumers. Preserved verbatim; new consumers should call\n * `scanServerActionsEnriched`.\n */\nexport function scanServerActions(serverDir: string): ActionNode[] {\n  const actionsDir = join(serverDir, 'actions')\n  if (!existsSync(actionsDir) || !statSync(actionsDir).isDirectory()) {\n    return []\n  }\n\n  const results: ActionNode[] = []\n  walkSourceFiles(actionsDir, { extensions: ACTION_EXTENSIONS }, (absPath) => {\n    if (TEST_FILE_RE.test(absPath)) return\n    let rel = relative(actionsDir, absPath)\n    rel = rel.replace(/\\\\/g, '/')\n    rel = rel.slice(0, -extname(rel).length)\n    results.push({\n      filePath: absPath,\n      actionPath: rel,\n    })\n  })\n  return results\n}\n\n/**\n * Enriched scan: light AST detection of `accept: 'form'|'json'` + `input:`\n * presence via regex-after-comment-stripping (EC-9). Throws ActionScanError\n * on file/dir name collision (EC-2) or reserved JS identifier names.\n *\n * Output `ActionManifestEntry[]` is sorted by `name` for deterministic\n * `.theo/actions-manifest.json` emission.\n */\nexport function scanServerActionsEnriched(serverDir: string): ActionManifestEntry[] {\n  const actionsDir = join(serverDir, 'actions')\n  if (!existsSync(actionsDir) || !statSync(actionsDir).isDirectory()) {\n    return []\n  }\n\n  const seenNames = new Set<string>()\n  const entries: ActionManifestEntry[] = []\n\n  // Collect first; collision-check after the full walk.\n  walkSourceFiles(actionsDir, { extensions: ACTION_EXTENSIONS }, (absPath) => {\n    if (TEST_FILE_RE.test(absPath)) return\n    const rel = relative(actionsDir, absPath).replace(/\\\\/g, '/')\n    // P#4 plugin-forms — `schemas/` subdir holds isomorphic zod schemas\n    // for the shared-schema convention (T1.1). NOT executable actions; skip.\n    if (rel.startsWith('schemas/')) return\n    const name = rel.slice(0, -extname(rel).length)\n\n    const basename = name.includes('/') ? (name.split('/').pop() ?? name) : name\n    if (RESERVED_NAMES.has(basename)) {\n      throw new ActionScanError(\n        'RESERVED_NAME',\n        `Reserved JS identifier \"${basename}\" cannot be an action name (${absPath})`,\n        [absPath],\n      )\n    }\n    // File-level collision (one file appearing twice) is impossible via the\n    // walker; per-export collision check happens inside the export loop below.\n    const source = readFileSync(absPath, 'utf8')\n    const stripped = stripComments(source)\n    const accept = /\\baccept\\s*:\\s*['\"]form['\"]/.test(stripped) ? 'form' : 'json'\n    const hasInput = /\\binput\\s*:\\s*z\\./.test(stripped) || /\\binput\\s*:\\s*\\w+\\(/.test(stripped)\n\n    // T7.1 wire fix — extract exports so the urlPath includes the second\n    // segment required by action-middleware (`/api/__actions/<file>/<export>`).\n    // Each named action export becomes its own manifest entry.\n    // Proxy key on the EXPORT name (so consumers write `actions.saveMemory(input)`).\n    // URL keeps the runtime 2-segment shape `/api/__actions/<file>/<export>`\n    // expected by action-middleware. Cross-file export collisions become a\n    // scan error to surface the ambiguity early.\n    const exportNames = extractActionExportNames(stripped)\n    // P#4 plugin-forms shared-schema convention: check for\n    // `<actionsDir>/schemas/<basename>.ts` (or .tsx/.js/.jsx).\n    // Skip when actions live in subdirs (`schemas/` is flat by convention).\n    const schemaFilePath = name.includes('/') ? undefined : detectSchemaFile(actionsDir, basename)\n    for (const exportName of exportNames) {\n      const proxyKey = exportName === 'default' ? name : exportName\n      if (seenNames.has(proxyKey)) {\n        throw new ActionScanError(\n          'NAME_COLLISION',\n          `Duplicate action proxy key \"${proxyKey}\" (two files export the same name)`,\n          [absPath],\n        )\n      }\n      seenNames.add(proxyKey)\n      const entry: ActionManifestEntry = {\n        name: proxyKey,\n        filePath: absPath,\n        urlPath: `/api/__actions/${name}/${exportName}`,\n        accept,\n        hasInput,\n      }\n      if (schemaFilePath !== undefined) {\n        entry.schemaFilePath = schemaFilePath\n      }\n      entries.push(entry)\n    }\n  })\n\n  // EC-2: detect file vs dir collisions (e.g., foo.ts AND foo/bar.ts).\n  // After walk completes, any name that has children prefixed `name/` triggers collision.\n  for (const entry of entries) {\n    const childPrefix = `${entry.name}/`\n    const conflictingChild = entries.find((other) => other.name.startsWith(childPrefix))\n    if (conflictingChild) {\n      throw new ActionScanError(\n        'NAME_COLLISION',\n        `Action \"${entry.name}\" conflicts with directory of same name containing \"${conflictingChild.name}\"`,\n        [entry.filePath, conflictingChild.filePath],\n      )\n    }\n  }\n\n  entries.sort((a, b) => {\n    if (a.name < b.name) return -1\n    if (a.name > b.name) return 1\n    return 0\n  })\n  return entries\n}\n\n/**\n * Strip JavaScript line + block comments from source. Simple state machine\n * (does not parse strings — false positives if a comment marker appears\n * inside a string literal, but that's an acceptable trade-off for v1 vs\n * full AST parse).\n */\n/**\n * Extract action export names via regex over comment-stripped source.\n * Matches `export const <name> = defineAction(...)`, `export default\n * defineAction(...)`, and `export function <name>(...)` forms. Returns\n * `['default']` when no named action exports are found (best-effort fallback\n * for default-export shapes the regex misses).\n */\nfunction extractActionExportNames(stripped: string): string[] {\n  const names = new Set<string>()\n  const namedRe = /\\bexport\\s+(?:const|let|var|function\\*?)\\s+([a-zA-Z_$][\\w$]*)\\s*[=(]/g\n  let m: RegExpExecArray | null\n  while ((m = namedRe.exec(stripped)) !== null) {\n    const name = m[1]\n    if (typeof name === 'string' && name.length > 0) names.add(name)\n  }\n  if (/\\bexport\\s+default\\s+defineAction\\b/.test(stripped)) {\n    names.add('default')\n  }\n  if (names.size === 0) names.add('default')\n  return [...names]\n}\n\n/**\n * P#4 plugin-forms shared-schema convention helper (per plan p4-plugin-forms v1.1 T1.1).\n * Returns the resolved path to `<actionsDir>/schemas/<basename>.<ext>` if it exists.\n * Tries `.ts`, `.tsx`, `.js`, `.jsx` in that order. Returns undefined when no match.\n */\nfunction detectSchemaFile(actionsDir: string, basename: string): string | undefined {\n  const schemasDir = join(actionsDir, 'schemas')\n  if (!existsSync(schemasDir)) return undefined\n  for (const ext of ['.ts', '.tsx', '.js', '.jsx']) {\n    const candidate = join(schemasDir, `${basename}${ext}`)\n    if (existsSync(candidate)) return candidate\n  }\n  return undefined\n}\n\nfunction stripComments(source: string): string {\n  let out = ''\n  let i = 0\n  while (i < source.length) {\n    const ch = source[i]\n    const next = source[i + 1]\n    if (ch === '/' && next === '/') {\n      // Line comment: skip until newline\n      while (i < source.length && source[i] !== '\\n') i++\n      continue\n    }\n    if (ch === '/' && next === '*') {\n      // Block comment: skip until */\n      i += 2\n      while (i < source.length - 1 && !(source[i] === '*' && source[i + 1] === '/')) i++\n      i += 2\n      continue\n    }\n    out += ch\n    i++\n  }\n  return out\n}\n"],"mappings":";;;;;AAIA,SAAS,YAAY,cAAc,gBAAgB;AACnD,SAAS,SAAS,MAAM,gBAAgB;AAqCjC,IAAM,kBAAN,cAA8B,MAAM;AAAA,EAChC;AAAA,EACA;AAAA,EAET,YACE,MACA,SACA,kBACA;AACA,UAAM,OAAO;AAIb,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,mBAAmB;AAAA,EAC1B;AACF;AAEA,IAAM,oBAAoB,oBAAI,IAAI,CAAC,OAAO,QAAQ,OAAO,MAAM,CAAC;AAChE,IAAM,eAAe;AACrB,IAAM,iBAAiB,oBAAI,IAAI,CAAC,SAAS,eAAe,aAAa,aAAa,gBAAgB,CAAC;AAO5F,SAAS,kBAAkB,WAAiC;AACjE,QAAM,aAAa,KAAK,WAAW,SAAS;AAC5C,MAAI,CAAC,WAAW,UAAU,KAAK,CAAC,SAAS,UAAU,EAAE,YAAY,GAAG;AAClE,WAAO,CAAC;AAAA,EACV;AAEA,QAAM,UAAwB,CAAC;AAC/B,kBAAgB,YAAY,EAAE,YAAY,kBAAkB,GAAG,CAAC,YAAY;AAC1E,QAAI,aAAa,KAAK,OAAO,EAAG;AAChC,QAAI,MAAM,SAAS,YAAY,OAAO;AACtC,UAAM,IAAI,QAAQ,OAAO,GAAG;AAC5B,UAAM,IAAI,MAAM,GAAG,CAAC,QAAQ,GAAG,EAAE,MAAM;AACvC,YAAQ,KAAK;AAAA,MACX,UAAU;AAAA,MACV,YAAY;AAAA,IACd,CAAC;AAAA,EACH,CAAC;AACD,SAAO;AACT;AAUO,SAAS,0BAA0B,WAA0C;AAClF,QAAM,aAAa,KAAK,WAAW,SAAS;AAC5C,MAAI,CAAC,WAAW,UAAU,KAAK,CAAC,SAAS,UAAU,EAAE,YAAY,GAAG;AAClE,WAAO,CAAC;AAAA,EACV;AAEA,QAAM,YAAY,oBAAI,IAAY;AAClC,QAAM,UAAiC,CAAC;AAGxC,kBAAgB,YAAY,EAAE,YAAY,kBAAkB,GAAG,CAAC,YAAY;AAC1E,QAAI,aAAa,KAAK,OAAO,EAAG;AAChC,UAAM,MAAM,SAAS,YAAY,OAAO,EAAE,QAAQ,OAAO,GAAG;AAG5D,QAAI,IAAI,WAAW,UAAU,EAAG;AAChC,UAAM,OAAO,IAAI,MAAM,GAAG,CAAC,QAAQ,GAAG,EAAE,MAAM;AAE9C,UAAM,WAAW,KAAK,SAAS,GAAG,IAAK,KAAK,MAAM,GAAG,EAAE,IAAI,KAAK,OAAQ;AACxE,QAAI,eAAe,IAAI,QAAQ,GAAG;AAChC,YAAM,IAAI;AAAA,QACR;AAAA,QACA,2BAA2B,QAAQ,+BAA+B,OAAO;AAAA,QACzE,CAAC,OAAO;AAAA,MACV;AAAA,IACF;AAGA,UAAM,SAAS,aAAa,SAAS,MAAM;AAC3C,UAAM,WAAW,cAAc,MAAM;AACrC,UAAM,SAAS,8BAA8B,KAAK,QAAQ,IAAI,SAAS;AACvE,UAAM,WAAW,oBAAoB,KAAK,QAAQ,KAAK,sBAAsB,KAAK,QAAQ;AAS1F,UAAM,cAAc,yBAAyB,QAAQ;AAIrD,UAAM,iBAAiB,KAAK,SAAS,GAAG,IAAI,SAAY,iBAAiB,YAAY,QAAQ;AAC7F,eAAW,cAAc,aAAa;AACpC,YAAM,WAAW,eAAe,YAAY,OAAO;AACnD,UAAI,UAAU,IAAI,QAAQ,GAAG;AAC3B,cAAM,IAAI;AAAA,UACR;AAAA,UACA,+BAA+B,QAAQ;AAAA,UACvC,CAAC,OAAO;AAAA,QACV;AAAA,MACF;AACA,gBAAU,IAAI,QAAQ;AACtB,YAAM,QAA6B;AAAA,QACjC,MAAM;AAAA,QACN,UAAU;AAAA,QACV,SAAS,kBAAkB,IAAI,IAAI,UAAU;AAAA,QAC7C;AAAA,QACA;AAAA,MACF;AACA,UAAI,mBAAmB,QAAW;AAChC,cAAM,iBAAiB;AAAA,MACzB;AACA,cAAQ,KAAK,KAAK;AAAA,IACpB;AAAA,EACF,CAAC;AAID,aAAW,SAAS,SAAS;AAC3B,UAAM,cAAc,GAAG,MAAM,IAAI;AACjC,UAAM,mBAAmB,QAAQ,KAAK,CAAC,UAAU,MAAM,KAAK,WAAW,WAAW,CAAC;AACnF,QAAI,kBAAkB;AACpB,YAAM,IAAI;AAAA,QACR;AAAA,QACA,WAAW,MAAM,IAAI,uDAAuD,iBAAiB,IAAI;AAAA,QACjG,CAAC,MAAM,UAAU,iBAAiB,QAAQ;AAAA,MAC5C;AAAA,IACF;AAAA,EACF;AAEA,UAAQ,KAAK,CAAC,GAAG,MAAM;AACrB,QAAI,EAAE,OAAO,EAAE,KAAM,QAAO;AAC5B,QAAI,EAAE,OAAO,EAAE,KAAM,QAAO;AAC5B,WAAO;AAAA,EACT,CAAC;AACD,SAAO;AACT;AAeA,SAAS,yBAAyB,UAA4B;AAC5D,QAAM,QAAQ,oBAAI,IAAY;AAC9B,QAAM,UAAU;AAChB,MAAI;AACJ,UAAQ,IAAI,QAAQ,KAAK,QAAQ,OAAO,MAAM;AAC5C,UAAM,OAAO,EAAE,CAAC;AAChB,QAAI,OAAO,SAAS,YAAY,KAAK,SAAS,EAAG,OAAM,IAAI,IAAI;AAAA,EACjE;AACA,MAAI,sCAAsC,KAAK,QAAQ,GAAG;AACxD,UAAM,IAAI,SAAS;AAAA,EACrB;AACA,MAAI,MAAM,SAAS,EAAG,OAAM,IAAI,SAAS;AACzC,SAAO,CAAC,GAAG,KAAK;AAClB;AAOA,SAAS,iBAAiB,YAAoB,UAAsC;AAClF,QAAM,aAAa,KAAK,YAAY,SAAS;AAC7C,MAAI,CAAC,WAAW,UAAU,EAAG,QAAO;AACpC,aAAW,OAAO,CAAC,OAAO,QAAQ,OAAO,MAAM,GAAG;AAChD,UAAM,YAAY,KAAK,YAAY,GAAG,QAAQ,GAAG,GAAG,EAAE;AACtD,QAAI,WAAW,SAAS,EAAG,QAAO;AAAA,EACpC;AACA,SAAO;AACT;AAEA,SAAS,cAAc,QAAwB;AAC7C,MAAI,MAAM;AACV,MAAI,IAAI;AACR,SAAO,IAAI,OAAO,QAAQ;AACxB,UAAM,KAAK,OAAO,CAAC;AACnB,UAAM,OAAO,OAAO,IAAI,CAAC;AACzB,QAAI,OAAO,OAAO,SAAS,KAAK;AAE9B,aAAO,IAAI,OAAO,UAAU,OAAO,CAAC,MAAM,KAAM;AAChD;AAAA,IACF;AACA,QAAI,OAAO,OAAO,SAAS,KAAK;AAE9B,WAAK;AACL,aAAO,IAAI,OAAO,SAAS,KAAK,EAAE,OAAO,CAAC,MAAM,OAAO,OAAO,IAAI,CAAC,MAAM,KAAM;AAC/E,WAAK;AACL;AAAA,IACF;AACA,WAAO;AACP;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/dist/chunk-RESN62GB.js

@@ -0,0 +1,269 @@
+// src/server/agent/stream-agent-run.ts
+function safeJsonStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "[Unserializable]";
+  }
+}
+function safeArgs(args) {
+  if (typeof args === "object" && args !== null && !Array.isArray(args)) {
+    return args;
+  }
+  return {};
+}
+function isAssistant(msg) {
+  const m = msg;
+  return m.type === "assistant" && m.message != null && typeof m.message === "object" && Array.isArray(m.message.content);
+}
+function isToolCall(msg) {
+  const t = msg;
+  return t.type === "tool_call" && typeof t.name === "string" && typeof t.call_id === "string" && (t.status === "running" || t.status === "completed" || t.status === "error");
+}
+function isAgentRunError(err) {
+  if (!(err instanceof Error)) return false;
+  const e = err;
+  return "code" in e && typeof e.code === "string";
+}
+function errorToEvent(err, id) {
+  if (isAgentRunError(err)) {
+    const event2 = {
+      type: "error",
+      message: err.message,
+      code: err.code
+    };
+    if (err.provider !== void 0) event2.provider = err.provider;
+    if (err.retriable !== void 0) event2.retriable = err.retriable;
+    if (err.retryAfterMs !== void 0) event2.retryAfterMs = err.retryAfterMs;
+    if (id !== void 0) event2.id = id;
+    return event2;
+  }
+  let message;
+  if (err instanceof Error) {
+    message = err.message;
+  } else if (typeof err === "string") {
+    message = err;
+  } else if (err !== null && typeof err === "object" && "message" in err) {
+    const candidate = err.message;
+    message = typeof candidate === "string" ? candidate : "[object Object]";
+  } else if (err === null || err === void 0) {
+    message = String(err);
+  } else {
+    message = "[non-stringifiable error]";
+  }
+  const event = { type: "error", message };
+  if (id !== void 0) event.id = id;
+  return event;
+}
+function yieldFromToolCall(msg) {
+  if (msg.status === "running") {
+    return {
+      type: "tool_call",
+      name: msg.name,
+      args: safeArgs(msg.args),
+      id: msg.call_id
+    };
+  }
+  if (msg.status === "completed") {
+    const data = typeof msg.result === "string" ? msg.result : safeJsonStringify(msg.result);
+    return {
+      type: "tool_result",
+      name: msg.name,
+      data,
+      id: msg.call_id
+    };
+  }
+  const message = typeof msg.result === "string" ? msg.result : `Tool ${msg.name} failed`;
+  return { type: "error", message, id: msg.call_id };
+}
+async function* streamAgentRun(run) {
+  for await (const msg of run.stream()) {
+    if (isAssistant(msg)) {
+      for (const block of msg.message.content) {
+        if (block.type === "text" && typeof block.text === "string" && block.text.length > 0) {
+          yield { type: "message", content: block.text };
+        }
+      }
+    } else if (isToolCall(msg)) {
+      yield yieldFromToolCall(msg);
+    }
+  }
+  const result = await run.wait();
+  if (result.status === "error" && result.error !== void 0) {
+    yield errorToEvent(result.error);
+  }
+}
+
+// src/server/agent/provider-resolver.ts
+var DEFAULT_REGISTRY = [
+  {
+    name: "openrouter",
+    envKey: "OPENROUTER_API_KEY",
+    baseUrl: "https://openrouter.ai/api/v1",
+    priority: 1
+  },
+  {
+    name: "openai",
+    envKey: "OPENAI_API_KEY",
+    baseUrl: "https://api.openai.com/v1",
+    priority: 2
+  },
+  {
+    name: "anthropic",
+    envKey: "ANTHROPIC_API_KEY",
+    baseUrl: "https://api.anthropic.com",
+    priority: 3
+  }
+];
+var registry = [...DEFAULT_REGISTRY];
+function resolveProvider() {
+  const sorted = [...registry].sort((a, b) => a.priority - b.priority);
+  for (const desc of sorted) {
+    const apiKey = process.env[desc.envKey];
+    if (apiKey && apiKey.length > 0) {
+      return {
+        name: desc.name,
+        apiKey,
+        baseUrl: desc.baseUrl
+      };
+    }
+  }
+  const envKeys = sorted.map((p) => p.envKey).join(" OR ");
+  throw new Error(
+    `No LLM provider API key found in environment. Set one of: ${envKeys}. Get a free OpenRouter key at https://openrouter.ai/keys (recommended \u2014 one key, many models).`
+  );
+}
+function tryResolveProvider() {
+  try {
+    return resolveProvider();
+  } catch {
+    return null;
+  }
+}
+
+// src/server/agent/create-conversation-history.ts
+var sdkOverride = void 0;
+function __setSdkForTests(sdk) {
+  sdkOverride = sdk;
+}
+function __resetSdkForTests() {
+  sdkOverride = void 0;
+}
+async function loadSdk() {
+  if (sdkOverride === null) {
+    throw new Error(
+      "createConversationHistory requires @theokit/sdk. Install: pnpm add @theokit/sdk"
+    );
+  }
+  if (sdkOverride !== void 0) return sdkOverride;
+  try {
+    const { createRequire } = await import("module");
+    const requireFn = createRequire(import.meta.url);
+    const spec = "@theokit/sdk";
+    const mod = requireFn(spec);
+    return mod;
+  } catch (cause) {
+    throw new Error(
+      "createConversationHistory requires @theokit/sdk. Install: pnpm add @theokit/sdk",
+      { cause }
+    );
+  }
+}
+var DEFAULT_COOKIE_NAME = "theo_conversation";
+var DEFAULT_COOKIE_MAX_AGE = 60 * 60 * 24 * 30;
+var AGENT_ID_REGEX = /^[a-zA-Z0-9_-]{1,128}$/;
+function isValidAgentId(s) {
+  return typeof s === "string" && AGENT_ID_REGEX.test(s);
+}
+function readCookieValue(request, name) {
+  let raw;
+  const h = request.headers;
+  if (h === void 0) return void 0;
+  if (typeof h.get === "function") {
+    raw = h.get("cookie") ?? void 0;
+  } else {
+    raw = h.cookie;
+  }
+  if (raw === void 0 || raw.length === 0) return void 0;
+  const pairs = raw.split(/[;,]/);
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq < 0) continue;
+    const k = pair.slice(0, eq).trim();
+    if (k === name) return pair.slice(eq + 1).trim();
+  }
+  return void 0;
+}
+function serializeCookie(name, value, options) {
+  const parts = [`${name}=${value}`];
+  if (options.path !== void 0) parts.push(`Path=${options.path}`);
+  if (options.maxAge !== void 0) parts.push(`Max-Age=${options.maxAge}`);
+  if (options.sameSite !== void 0) {
+    const v = options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1);
+    parts.push(`SameSite=${v}`);
+  }
+  if (options.httpOnly === true) parts.push("HttpOnly");
+  return parts.join("; ");
+}
+async function createConversationHistory(args) {
+  const cookieName = args.cookieName ?? DEFAULT_COOKIE_NAME;
+  const rawMaxAge = args.cookieMaxAge;
+  const cookieMaxAge = typeof rawMaxAge === "number" && rawMaxAge > 0 ? rawMaxAge : DEFAULT_COOKIE_MAX_AGE;
+  let conversationId;
+  let isNew = false;
+  const cookieOnRequest = readCookieValue(args.request, cookieName);
+  if (isValidAgentId(args.agentId)) {
+    conversationId = args.agentId;
+  } else if (args.session !== null && args.session !== void 0) {
+    const sId = args.session.conversationId;
+    if (isValidAgentId(sId)) conversationId = sId;
+  }
+  if (conversationId === void 0 && isValidAgentId(cookieOnRequest)) {
+    conversationId = cookieOnRequest;
+  }
+  if (conversationId === void 0) {
+    conversationId = crypto.randomUUID();
+    isNew = true;
+  }
+  const shouldIssueCookie = isNew || cookieOnRequest !== conversationId;
+  if (shouldIssueCookie && args.response !== void 0) {
+    const cookie = serializeCookie(cookieName, conversationId, {
+      httpOnly: true,
+      sameSite: "lax",
+      maxAge: cookieMaxAge,
+      path: "/"
+    });
+    args.response.headers.append("set-cookie", cookie);
+  }
+  const resolvedOptions = autoResolveProviderIfNeeded(args.options);
+  const sdk = await loadSdk();
+  const agent = await sdk.Agent.getOrCreate(conversationId, resolvedOptions);
+  return { agent, conversationId, isNew };
+}
+function autoResolveProviderIfNeeded(options) {
+  if (typeof options.apiKey === "string" && options.apiKey.length > 0) {
+    return options;
+  }
+  const resolved = tryResolveProvider();
+  if (resolved === null) {
+    throw new Error(
+      "No LLM provider API key found in environment. Set OPENROUTER_API_KEY (recommended \u2014 gateway to many models) OR OPENAI_API_KEY OR ANTHROPIC_API_KEY in your .env. Get a free OpenRouter key at https://openrouter.ai/keys. (Pass `options.apiKey` explicitly to bypass auto-resolution.)"
+    );
+  }
+  return {
+    ...options,
+    apiKey: resolved.apiKey,
+    providers: {
+      routes: [{ capability: "chat", provider: resolved.name, baseUrl: resolved.baseUrl }]
+    }
+  };
+}
+
+export {
+  errorToEvent,
+  streamAgentRun,
+  __setSdkForTests,
+  __resetSdkForTests,
+  createConversationHistory
+};
+//# sourceMappingURL=chunk-RESN62GB.js.map

package/dist/chunk-RESN62GB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/agent/stream-agent-run.ts","../src/server/agent/provider-resolver.ts","../src/server/agent/create-conversation-history.ts"],"sourcesContent":["import type { AgentEvent, AgentErrorEvent } from './agent-types.js'\n\n/**\n * Item #4 — `streamAgentRun`\n *\n * Adapter that consumes the `@theokit/sdk` `Run.stream()` async generator\n * (SDKMessage variants) and yields TheoKit `AgentEvent`s suitable for SSE\n * via `defineAgentEndpoint`. One line at the consumer side:\n *\n *   ```ts\n *   const run = await agent.send(message)\n *   yield* streamAgentRun(run)\n *   ```\n *\n * Mapping table (SDK → AgentEvent):\n *\n * | SDK message                          | AgentEvent yielded                     |\n * |---|---|\n * | assistant.content[].type==='text'    | { type: 'message', content }           |\n * | assistant.content[].type==='tool_use'| (none — covered by tool_call below)    |\n * | tool_call(status='running')          | { type: 'tool_call', name, args, id }  |\n * | tool_call(status='completed')        | { type: 'tool_result', name, data, id }|\n * | tool_call(status='error')            | { type: 'error', message, id }         |\n * | run.wait() status==='error'          | { type: 'error', message }             |\n * | run.wait() status==='cancelled'      | (none — cancel ≠ error)                |\n * | system / user / thinking / status /  | (none — internal SDK telemetry)        |\n * |   task / request / object_delta      |                                        |\n *\n * Abort semantics: when the consumer calls `generator.return()` on the\n * outer `defineAgentEndpoint` generator, `streamAgentRun` exits the\n * `for await` loop and does NOT call `run.wait()`. Cleanup of in-flight\n * SDK resources is the SDK consumer's responsibility (`run.cancel()`).\n */\n\n/**\n * Local mirror of the SDK's `Run` interface — only the surfaces we consume.\n * The message contract is minimal (just `{ type: string }`) so the SDK's\n * `SDKMessage` discriminated union IS structurally assignable without any\n * cast at the consumer site (covariant — TS accepts the SDK's typed message\n * as the wider `{ type: string }`). Property access inside `streamAgentRun`\n * narrows via runtime type guards.\n *\n * `import type` from `@theokit/sdk` would couple TheoKit to the SDK at type-\n * resolution time even for consumers who never use the agent surface.\n */\nexport interface AgentRunLike {\n  stream: () => AsyncIterable<{ type: string }>\n  wait: () => Promise<AgentRunResult>\n}\n\n/**\n * Re-exported as a convenience for test fixtures. Production code typically\n * passes an SDK `Run` directly (structural match via `{ type: string }`).\n */\nexport type AgentRunStreamMessage =\n  | {\n      type: 'assistant'\n      message: { role: 'assistant'; content: { type: string; text?: string }[] }\n    }\n  | {\n      type: 'tool_call'\n      name: string\n      status: 'running' | 'completed' | 'error'\n      args?: unknown\n      result?: unknown\n      call_id: string\n    }\n  | { type: string; [k: string]: unknown }\n\n/** Subset of the SDK `RunResult` we consume. */\nexport interface AgentRunResult {\n  status: 'finished' | 'error' | 'cancelled'\n  error?: { message: string; code?: string; cause?: unknown }\n}\n\n/**\n * EC-1 (edge case review): tool result may be a Date, bigint, circular ref,\n * etc. `JSON.stringify` in `encodeSSE` would throw — uncaught inside the\n * outer generator — and `defineAgentEndpoint` would replace the legitimate\n * `tool_result` with a generic `error`. Coerce here so the wire stays honest.\n */\nfunction safeJsonStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value)\n  } catch {\n    return '[Unserializable]'\n  }\n}\n\n/**\n * EC-3 (edge case review): SDK types `args?: unknown`. A raw `as` cast hides\n * the possibility that `msg.args` is an array, primitive, or `null` (null\n * survives `??`). Type-guard BEFORE narrowing to `Record<string, unknown>`.\n */\nfunction safeArgs(args: unknown): Record<string, unknown> {\n  if (typeof args === 'object' && args !== null && !Array.isArray(args)) {\n    return args as Record<string, unknown>\n  }\n  return {}\n}\n\n/**\n * Yield AgentEvents derived from the SDK Run lifecycle.\n *\n * Consumer pattern:\n *\n *   ```ts\n *   export const POST = defineAgentEndpoint({\n *     async *handler({ body }) {\n *       const agent = await Agent.create({ apiKey, model, tools: [...] })\n *       try {\n *         const run = await agent.send(body.message)\n *         yield* streamAgentRun(run)\n *       } finally {\n *         try { await agent.dispose() } catch (e) { console.warn(e) }\n *       }\n *     },\n *   })\n *   ```\n *\n * @public\n */\ninterface AssistantLike {\n  type: 'assistant'\n  message: { role: 'assistant'; content: { type: string; text?: string }[] }\n}\ninterface ToolCallLike {\n  type: 'tool_call'\n  name: string\n  status: 'running' | 'completed' | 'error'\n  args?: unknown\n  result?: unknown\n  call_id: string\n}\n\nfunction isAssistant(msg: { type: string }): msg is AssistantLike {\n  // Wide cast to `unknown` first so runtime null guard survives ESLint\n  // narrowing complaints — the SDK contract permits `null` even when its\n  // TS type does not.\n  const m = msg as unknown as {\n    type: string\n    message?: { content?: unknown } | null\n  }\n  return (\n    m.type === 'assistant' &&\n    m.message != null &&\n    typeof m.message === 'object' &&\n    Array.isArray(m.message.content)\n  )\n}\nfunction isToolCall(msg: { type: string }): msg is ToolCallLike {\n  const t = msg as unknown as {\n    type: string\n    name?: unknown\n    status?: unknown\n    call_id?: unknown\n  }\n  return (\n    t.type === 'tool_call' &&\n    typeof t.name === 'string' &&\n    typeof t.call_id === 'string' &&\n    (t.status === 'running' || t.status === 'completed' || t.status === 'error')\n  )\n}\n\n/**\n * Phase 4 — Production-Readiness #3: structural mirror of SDK's AgentRunError.\n *\n * EC-6 (SHOULD TEST): we only require `code: string` to discriminate.\n * Provider, retriable, retryAfterMs, requestId are all optional — SDK error\n * paths may omit them (e.g., aborted before request, tool runtime error).\n */\ninterface AgentRunErrorLike {\n  message: string\n  code: string\n  provider?: string\n  retriable?: boolean\n  retryAfterMs?: number\n  requestId?: string\n  /**\n   * EC-15 (DOCUMENT) + invariant: `providerError` is QUARANTINED. We read it\n   * for type-narrowing but NEVER serialize into the AgentEvent — leaking the\n   * raw provider response could leak API keys, internal endpoints, or PII.\n   * Only sanitized fields above flow to the SSE wire. `error.message` is\n   * trusted to not contain secrets (SDK's responsibility per the v1.1.0\n   * release contract).\n   */\n  providerError?: unknown\n}\n\n/**\n * EC-6 (SHOULD TEST): minimal type guard — only requires `code: string`.\n * Does NOT require `'provider' in err` because the SDK throws AgentRunErrors\n * without `provider` in local error paths (timeout, tool runtime error,\n * aborted-before-call).\n */\nfunction isAgentRunError(err: unknown): err is AgentRunErrorLike {\n  if (!(err instanceof Error)) return false\n  const e = err as { code?: unknown }\n  return 'code' in e && typeof e.code === 'string'\n}\n\n/**\n * Map an SDK error to the AgentErrorEvent shape. Pure function — easy to test.\n *\n * Backward compat (D4): non-AgentRunError throws yield only `message` field\n * (legacy shape); discriminated fields stay `undefined`.\n *\n * Return type is the specific `AgentErrorEvent` (not the union) for ergonomic\n * call-site access — `errorToEvent(err).code` works without narrowing.\n */\nexport function errorToEvent(err: unknown, id?: string): AgentErrorEvent {\n  if (isAgentRunError(err)) {\n    const event: AgentErrorEvent = {\n      type: 'error',\n      message: err.message,\n      code: err.code,\n    }\n    if (err.provider !== undefined) event.provider = err.provider\n    if (err.retriable !== undefined) event.retriable = err.retriable\n    if (err.retryAfterMs !== undefined) event.retryAfterMs = err.retryAfterMs\n    if (id !== undefined) event.id = id\n    return event\n  }\n  // Fallback for non-AgentRunError throws (plain Error, string, plain object with message)\n  let message: string\n  if (err instanceof Error) {\n    message = err.message\n  } else if (typeof err === 'string') {\n    message = err\n  } else if (err !== null && typeof err === 'object' && 'message' in err) {\n    const candidate: unknown = (err as Record<string, unknown>).message\n    // Plain object with `message: string` — common for SDK status:error payloads\n    message = typeof candidate === 'string' ? candidate : '[object Object]'\n  } else if (err === null || err === undefined) {\n    message = String(err)\n  } else {\n    message = '[non-stringifiable error]'\n  }\n  const event: AgentErrorEvent = { type: 'error', message }\n  if (id !== undefined) event.id = id\n  return event\n}\n\nfunction yieldFromToolCall(msg: ToolCallLike): AgentEvent {\n  if (msg.status === 'running') {\n    return {\n      type: 'tool_call',\n      name: msg.name,\n      args: safeArgs(msg.args),\n      id: msg.call_id,\n    }\n  }\n  if (msg.status === 'completed') {\n    const data = typeof msg.result === 'string' ? msg.result : safeJsonStringify(msg.result)\n    return {\n      type: 'tool_result',\n      name: msg.name,\n      data,\n      id: msg.call_id,\n    }\n  }\n  // status === 'error' — exhaustive by type\n  const message = typeof msg.result === 'string' ? msg.result : `Tool ${msg.name} failed`\n  return { type: 'error', message, id: msg.call_id }\n}\n\nexport async function* streamAgentRun(\n  run: AgentRunLike,\n): AsyncGenerator<AgentEvent, void, unknown> {\n  for await (const msg of run.stream()) {\n    if (isAssistant(msg)) {\n      for (const block of msg.message.content) {\n        if (block.type === 'text' && typeof block.text === 'string' && block.text.length > 0) {\n          yield { type: 'message', content: block.text }\n        }\n      }\n    } else if (isToolCall(msg)) {\n      yield yieldFromToolCall(msg)\n    }\n    // SDK-internal variants (system, user, thinking, status, task,\n    // request, object_delta) are intentionally not yielded.\n  }\n\n  const result = await run.wait()\n  if (result.status === 'error' && result.error !== undefined) {\n    yield errorToEvent(result.error)\n  }\n}\n","/**\n * Provider Resolver — Strategy + Registry pattern (FAANG-grade).\n *\n * Inspiração: Dapr Conversation Registry (`dapr/pkg/components/conversation/registry.go`)\n * + Encore Manager provider array (`encore/runtimes/go/pubsub/manager_internal.go`).\n *\n * Princípio: provider routing é responsabilidade do FRAMEWORK, não do consumer.\n * Consumer template usa `model: { id: 'gpt-4o-mini' }` puro — sem conditionals.\n *\n * Wire protocol: OpenAI Chat Completions (universal — implementado por todos\n * os providers: OpenRouter, Groq, Mistral, Together, Anthropic via proxy, etc).\n *\n * Resolução por prioridade (FIRST match wins):\n *   1. OPENROUTER_API_KEY → baseUrl=openrouter.ai (gateway multi-modelo)\n *   2. OPENAI_API_KEY     → baseUrl=api.openai.com\n *   3. ANTHROPIC_API_KEY  → direct Anthropic (Messages API, não OpenAI-compat)\n *\n * Escape hatch: `options.apiKey` explícito SOBREPÕE auto-resolution\n * (consumer pode forçar provider específico se quiser).\n */\n\n/**\n * Provider configuration descriptor — Registry entry shape.\n *\n * @public\n */\nexport interface ProviderDescriptor {\n  /** Stable name used internally — não exposto no wire. */\n  name: string\n  /** Environment variable that holds the API key for this provider. */\n  envKey: string\n  /** Base URL for the provider's OpenAI-compatible (or native) API. */\n  baseUrl: string\n  /** Resolution priority (lower = higher priority). FIRST match wins. */\n  priority: number\n}\n\n/**\n * Resolved provider configuration — output of `resolveProvider()`.\n *\n * @public\n */\nexport interface ResolvedProvider {\n  name: string\n  apiKey: string\n  baseUrl: string\n}\n\n/**\n * Default provider registry. Order = priority (first = highest).\n *\n * Adding a new provider:\n *   1. Append entry below (or register via `registerProvider()`).\n *   2. Set `envKey` matching the user's env var convention.\n *   3. Set `baseUrl` to the OpenAI-compat endpoint (or native if not compat).\n *   4. Provider name used in telemetry/logs only — never wire-exposed.\n */\nconst DEFAULT_REGISTRY: ProviderDescriptor[] = [\n  {\n    name: 'openrouter',\n    envKey: 'OPENROUTER_API_KEY',\n    baseUrl: 'https://openrouter.ai/api/v1',\n    priority: 1,\n  },\n  {\n    name: 'openai',\n    envKey: 'OPENAI_API_KEY',\n    baseUrl: 'https://api.openai.com/v1',\n    priority: 2,\n  },\n  {\n    name: 'anthropic',\n    envKey: 'ANTHROPIC_API_KEY',\n    baseUrl: 'https://api.anthropic.com',\n    priority: 3,\n  },\n]\n\n/**\n * Runtime registry — copy of DEFAULT_REGISTRY mutable via registerProvider().\n * Sorted by priority on every resolve (stable, O(n log n) — n <= ~10 providers).\n */\nconst registry: ProviderDescriptor[] = [...DEFAULT_REGISTRY]\n\n/**\n * Register a new provider (Registry pattern — runtime extension point).\n * Useful for self-hosted endpoints or custom providers without touching theokit src.\n *\n * @example\n * registerProvider({\n *   name: 'self-hosted',\n *   envKey: 'SELF_HOSTED_API_KEY',\n *   baseUrl: 'https://llm.internal.acme.com/v1',\n *   priority: 0, // highest priority\n * })\n *\n * @public\n */\nexport function registerProvider(descriptor: ProviderDescriptor): void {\n  // Idempotent — replace existing by name.\n  const idx = registry.findIndex((p) => p.name === descriptor.name)\n  if (idx >= 0) registry[idx] = descriptor\n  else registry.push(descriptor)\n}\n\n/**\n * Reset registry to DEFAULT_REGISTRY (test-only / dev escape hatch).\n *\n * @public\n */\nexport function resetProviderRegistry(): void {\n  registry.length = 0\n  registry.push(...DEFAULT_REGISTRY)\n}\n\n/**\n * Get current registry snapshot (read-only — inspection).\n *\n * @public\n */\nexport function listProviders(): readonly ProviderDescriptor[] {\n  return [...registry].sort((a, b) => a.priority - b.priority)\n}\n\n/**\n * Resolve provider from env vars by priority. FIRST env var found wins.\n *\n * @returns ResolvedProvider with apiKey + baseUrl + name\n * @throws Error if NO provider env var is set (actionable message)\n *\n * @public\n */\nexport function resolveProvider(): ResolvedProvider {\n  const sorted = [...registry].sort((a, b) => a.priority - b.priority)\n  for (const desc of sorted) {\n    const apiKey = process.env[desc.envKey]\n    if (apiKey && apiKey.length > 0) {\n      return {\n        name: desc.name,\n        apiKey,\n        baseUrl: desc.baseUrl,\n      }\n    }\n  }\n  // No env var found — emit actionable error.\n  const envKeys = sorted.map((p) => p.envKey).join(' OR ')\n  throw new Error(\n    `No LLM provider API key found in environment. Set one of: ${envKeys}. ` +\n      `Get a free OpenRouter key at https://openrouter.ai/keys (recommended — one key, many models).`,\n  )\n}\n\n/**\n * Try to resolve — does NOT throw. Returns null if no provider available.\n * Useful for graceful degradation (e.g., mock mode).\n *\n * @public\n */\nexport function tryResolveProvider(): ResolvedProvider | null {\n  try {\n    return resolveProvider()\n  } catch {\n    return null\n  }\n}\n","/**\n * Item #5 — `createConversationHistory`\n *\n * Orchestrator that resolves a stable `agentId` from (explicit → session →\n * cookie → fresh UUID), then returns an `@theokit/sdk` `Agent` via\n * `Agent.getOrCreate(agentId, options)`. Conversation turns auto-persist in\n * `<cwd>/.theokit/agents/<agentId>/messages.jsonl` — SDK owns the storage\n * (ADR D1). `MemorySettings` (facts recall layer) is opt-in passthrough via\n * `options.memory` (ADR D2).\n *\n * Security: agentId from cookie/explicit is attacker-controlled. The SDK\n * uses it as a filesystem path component AND we serialize it into Set-Cookie.\n * EC-1 enforces a strict regex `^[a-zA-Z0-9_-]{1,128}$` at every entry point;\n * invalid values fall through (treated as \"missing\") rather than throw.\n */\n\nimport { tryResolveProvider } from './provider-resolver.js'\n\n// ──────────────────────────────────────────────────────────────────────────\n// Structural types — mirrors of SDK shapes we don't want to hard-import\n// (the SDK is an OPTIONAL peer per item #4's stance).\n// ──────────────────────────────────────────────────────────────────────────\n\n/**\n * Minimum surface of an SDK Agent that consumers care about post-creation.\n * Structural match — any object with `send` + `dispose` of compatible\n * shape works. `send` returns a `SdkRunLike` (a Run-shaped object) that\n * `streamAgentRun` can consume. Permissive `unknown` for now; consumers\n * who want stricter types can cast to the SDK's own types.\n *\n * **T5.2 (architecture-cleanup) — DP-7 decision: KEEP (Opt B).** The 5 duck-typed\n * mirrors below were flagged as \"over-engineered\" by the 2026-05-27 architecture\n * review. Decision: KEEP them because `@theokit/sdk` is `devDependency` (not\n * required at runtime for consumers that don't use agent features). Removing\n * the mirrors would force a hard runtime dep on the SDK, breaking consumers\n * who build TheoKit apps without the agent layer.\n *\n * @kept Defensive duck-type. Do NOT replace with direct SDK type imports unless\n *   `@theokit/sdk` is promoted from devDependency to dependency. If promoting,\n *   ALSO drop the mirrors (Opt A from the architecture-cleanup plan T5.2).\n */\nexport interface SdkRunLike {\n  stream: () => AsyncIterable<{ type: string }>\n  wait: () => Promise<{ status: 'finished' | 'error' | 'cancelled'; error?: { message: string } }>\n}\n\nexport interface SdkAgent {\n  send: (message: string, options?: unknown) => Promise<SdkRunLike>\n  dispose: () => Promise<void>\n}\n\n/**\n * Phase 2 — structural duck-type of `@theokit/sdk`'s `ConversationStorageAdapter`.\n *\n * D2 (decoupling): we mirror the SDK's shape locally rather than hard-import\n * the SDK type. This lets consumers pass any object matching the structural\n * contract (own implementation, SDK's `FileSystemConversationStorage`,\n * `InMemoryConversationStorage`, or a Postgres/Redis recipe).\n *\n * EC-5 (SHOULD TEST — sync drift detection): the SDK type MUST be assignable\n * to this interface AND vice-versa. A contract test asserts both directions.\n *\n * `unknown` for the message payload avoids coupling to the SDK's `SDKMessage`\n * shape. Real consumers cast at the call site if they need stricter types.\n */\nexport interface ConversationStorageLike {\n  getMessages(conversationId: string): Promise<readonly unknown[]>\n  appendMessage(conversationId: string, message: unknown): Promise<void>\n  deleteConversation(conversationId: string): Promise<void>\n  listConversationIds?(opts?: { limit?: number }): Promise<readonly string[] | undefined>\n  dispose?(): Promise<void>\n}\n\n/**\n * Minimum surface of `AgentOptions` accepted by `Agent.getOrCreate`. Forward-\n * compatible: callers pass whatever the SDK supports (memory, tools, etc.).\n *\n * Phase 2 adds typed `conversationStorage` slot. The index signature still\n * passes everything else opaquely.\n */\nexport interface SdkAgentOptions {\n  apiKey?: string\n  model?: { id: string }\n  tools?: readonly unknown[]\n  memory?: Record<string, unknown>\n  /**\n   * Phase 2 (Production-Readiness #1) — pluggable conversation persistence.\n   * Default (when omitted): SDK falls back to `FileSystemConversationStorage`.\n   * Required for serverless / multi-host deploys.\n   */\n  conversationStorage?: ConversationStorageLike\n  [key: string]: unknown\n}\n\ninterface SdkModule {\n  Agent: {\n    getOrCreate: (agentId: string, options: SdkAgentOptions) => Promise<SdkAgent>\n  }\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Public API\n// ──────────────────────────────────────────────────────────────────────────\n\nexport interface ConversationHistoryArgs {\n  /** Request — for reading the conversation cookie. */\n  request: Request | { headers?: { cookie?: string } | Headers }\n  /**\n   * Response-like surface that accepts a `Set-Cookie` header. The primitive\n   * appends a Set-Cookie line when issuing a new conversation id. If absent,\n   * the primitive still reads the existing cookie but cannot issue a new\n   * one — useful for read-only contexts.\n   */\n  response?: { headers: Headers }\n  /** Explicit override — wins over session/cookie/uuid (ADR D3 step 1). */\n  agentId?: string\n  /** Auth session containing a `conversationId` field — ADR D3 step 2. */\n  session?: { conversationId?: string } | null\n  /** SDK AgentOptions forwarded to Agent.getOrCreate. apiKey + model required. */\n  options: SdkAgentOptions\n  /** Cookie name override. Default: 'theo_conversation'. */\n  cookieName?: string\n  /** Cookie max-age in seconds. Default + min: 30 days. Non-positive coerced to default (EC-4). */\n  cookieMaxAge?: number\n}\n\nexport interface ConversationHistoryResult {\n  /** The SDK Agent, ready to receive `agent.send(message)`. */\n  agent: SdkAgent\n  /** The resolved conversation id (useful for logging / debugging). */\n  conversationId: string\n  /** True when the id was newly generated (no prior cookie / session). */\n  isNew: boolean\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Test seam — allows unit tests to swap the SDK without dynamic import flake.\n// Underscore-prefixed: NOT part of the public contract.\n// ──────────────────────────────────────────────────────────────────────────\n\nlet sdkOverride: SdkModule | null | undefined = undefined\n\n/** @internal */\nexport function __setSdkForTests(sdk: SdkModule | null): void {\n  sdkOverride = sdk\n}\n\n/** @internal */\nexport function __resetSdkForTests(): void {\n  sdkOverride = undefined\n}\n\nasync function loadSdk(): Promise<SdkModule> {\n  // EC-2 (edge case review — MUST FIX): the SDK is an optional peer; if the\n  // consumer never installed it, `import('@theokit/sdk')` throws\n  // ERR_MODULE_NOT_FOUND. Re-throw with an actionable message.\n  if (sdkOverride === null) {\n    throw new Error(\n      'createConversationHistory requires @theokit/sdk. Install: pnpm add @theokit/sdk',\n    )\n  }\n  if (sdkOverride !== undefined) return sdkOverride\n  try {\n    // Use `createRequire` — Node's CJS-style require resolves against the\n    // process's actual node_modules tree, bypassing Vite's SSR import-\n    // analysis pipeline. The dynamic ESM `import()` path got intercepted\n    // by Vite's `vite:import-analysis` plugin and failed to find the SDK\n    // even when it was installed; createRequire goes straight to Node.\n    //\n    // The SDK ships dual ESM+CJS (per its tsup build), so `require` yields\n    // the same module the ESM `import` would.\n    const { createRequire } = await import('node:module')\n    const requireFn = createRequire(import.meta.url)\n    const spec = '@theokit/sdk'\n    const mod = requireFn(spec) as unknown as SdkModule\n    return mod\n  } catch (cause) {\n    throw new Error(\n      'createConversationHistory requires @theokit/sdk. Install: pnpm add @theokit/sdk',\n      { cause },\n    )\n  }\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Implementation\n// ──────────────────────────────────────────────────────────────────────────\n\nconst DEFAULT_COOKIE_NAME = 'theo_conversation'\nconst DEFAULT_COOKIE_MAX_AGE = 60 * 60 * 24 * 30 // 30 days\n\n/**\n * EC-1 (edge case review — MUST FIX): the agentId becomes a filesystem path\n * component (`<cwd>/.theokit/agents/<agentId>/messages.jsonl`) inside the SDK\n * AND is serialized into a Set-Cookie header. The SDK does NOT validate the\n * char set. An attacker setting `Cookie: theo_conversation=../../../etc/passwd`\n * could trigger arbitrary-path writes; an `agentId` with CRLF would inject\n * HTTP headers. The same regex kills both attacks.\n */\nconst AGENT_ID_REGEX = /^[a-zA-Z0-9_-]{1,128}$/\n\nfunction isValidAgentId(s: string | undefined | null): s is string {\n  return typeof s === 'string' && AGENT_ID_REGEX.test(s)\n}\n\n/**\n * Minimal RFC 6265 cookie parser. Returns the FIRST occurrence of `name`\n * (EC-5 — pins first-wins behavior).\n */\nfunction readCookieValue(\n  request: ConversationHistoryArgs['request'],\n  name: string,\n): string | undefined {\n  let raw: string | undefined\n  const h = request.headers\n  if (h === undefined) return undefined\n  if (typeof (h as Headers).get === 'function') {\n    raw = (h as Headers).get('cookie') ?? undefined\n  } else {\n    raw = (h as { cookie?: string }).cookie\n  }\n  if (raw === undefined || raw.length === 0) return undefined\n  const pairs = raw.split(/[;,]/)\n  for (const pair of pairs) {\n    const eq = pair.indexOf('=')\n    if (eq < 0) continue\n    const k = pair.slice(0, eq).trim()\n    if (k === name) return pair.slice(eq + 1).trim()\n  }\n  return undefined\n}\n\ninterface SerializeCookieOptions {\n  httpOnly?: boolean\n  sameSite?: 'lax' | 'strict' | 'none'\n  maxAge?: number\n  path?: string\n}\n\nfunction serializeCookie(name: string, value: string, options: SerializeCookieOptions): string {\n  const parts: string[] = [`${name}=${value}`]\n  if (options.path !== undefined) parts.push(`Path=${options.path}`)\n  if (options.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`)\n  if (options.sameSite !== undefined) {\n    const v = options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1)\n    parts.push(`SameSite=${v}`)\n  }\n  if (options.httpOnly === true) parts.push('HttpOnly')\n  return parts.join('; ')\n}\n\nexport async function createConversationHistory(\n  args: ConversationHistoryArgs,\n): Promise<ConversationHistoryResult> {\n  const cookieName = args.cookieName ?? DEFAULT_COOKIE_NAME\n  // EC-4 (edge case review — SHOULD TEST): coerce non-positive to default.\n  // The `??` operator alone would let `0` through, producing `Max-Age=0`\n  // which means \"delete cookie immediately\" — almost certainly not intent.\n  const rawMaxAge = args.cookieMaxAge\n  const cookieMaxAge =\n    typeof rawMaxAge === 'number' && rawMaxAge > 0 ? rawMaxAge : DEFAULT_COOKIE_MAX_AGE\n\n  // 1. Resolve agentId per ADR D3 — sources are validated; invalid values\n  //    fall through (treated as \"missing\") rather than throw.\n  let conversationId: string | undefined\n  let isNew = false\n  const cookieOnRequest = readCookieValue(args.request, cookieName)\n\n  if (isValidAgentId(args.agentId)) {\n    conversationId = args.agentId\n  } else if (args.session !== null && args.session !== undefined) {\n    const sId = args.session.conversationId\n    if (isValidAgentId(sId)) conversationId = sId\n  }\n  if (conversationId === undefined && isValidAgentId(cookieOnRequest)) {\n    conversationId = cookieOnRequest\n  }\n\n  if (conversationId === undefined) {\n    conversationId = crypto.randomUUID()\n    isNew = true\n  }\n\n  // Issue (or refresh) the cookie when:\n  //   1. The id was newly generated (no source had it), OR\n  //   2. The request's cookie does NOT match the resolved id (explicit\n  //      `agentId` override, session-derived id, etc.). Without this,\n  //      callers that pre-probe the id (e.g. to build agentId-scoped tools)\n  //      and pass it via `agentId` would never get a Set-Cookie even on\n  //      first visit. Net effect: every response with a `response` slot\n  //      ensures the browser ends up with a cookie that matches the\n  //      resolved id.\n  const shouldIssueCookie = isNew || cookieOnRequest !== conversationId\n  if (shouldIssueCookie && args.response !== undefined) {\n    const cookie = serializeCookie(cookieName, conversationId, {\n      httpOnly: true,\n      sameSite: 'lax',\n      maxAge: cookieMaxAge,\n      path: '/',\n    })\n    args.response.headers.append('set-cookie', cookie)\n  }\n\n  // 2. Auto-resolve provider via Strategy pattern (FAANG-grade — zero\n  //    conditionals no consumer). If `options.apiKey` ausente, lê env vars\n  //    priorizadas (OPENROUTER > OPENAI > ANTHROPIC) e injeta apiKey +\n  //    providers.baseUrl. Consumer override: passar `options.apiKey` explícito\n  //    SOBREPÕE o auto-resolve (escape hatch). Ver `provider-resolver.ts` +\n  //    Dapr Conversation Registry pattern (`referencias/dapr/pkg/components/conversation/`).\n  const resolvedOptions = autoResolveProviderIfNeeded(args.options)\n\n  // 3. Resolve the agent via SDK.\n  const sdk = await loadSdk()\n  const agent = await sdk.Agent.getOrCreate(conversationId, resolvedOptions)\n\n  return { agent, conversationId, isNew }\n}\n\n/**\n * Auto-inject provider config (apiKey + baseUrl) via Strategy pattern when\n * consumer didn't pass apiKey explicit. Idempotent — se apiKey já set, noop.\n *\n * Output shape:\n *   {\n *     ...originalOptions,\n *     apiKey: env,    // resolved from process.env\n *     providers: { routes: [{ capability: 'chat', provider: name, ... }] }\n *   }\n */\nfunction autoResolveProviderIfNeeded(options: SdkAgentOptions): SdkAgentOptions {\n  // Escape hatch — consumer override wins.\n  if (typeof options.apiKey === 'string' && options.apiKey.length > 0) {\n    return options\n  }\n  // Auto-resolve via Strategy registry.\n  //\n  // Finding A workaround (sdk-residual-behavior-2026-05-28): SDK silently\n  // returns canned \"Hello! How can I assist you today?\" content when no\n  // apiKey AND no provider env vars are present. Fail-fast HERE with an\n  // actionable error — template's try/catch yields `{type:'error'}` SSE\n  // event so consumer sees what's wrong.\n  const resolved = tryResolveProvider()\n  if (resolved === null) {\n    throw new Error(\n      'No LLM provider API key found in environment. ' +\n        'Set OPENROUTER_API_KEY (recommended — gateway to many models) OR ' +\n        'OPENAI_API_KEY OR ANTHROPIC_API_KEY in your .env. ' +\n        'Get a free OpenRouter key at https://openrouter.ai/keys. ' +\n        '(Pass `options.apiKey` explicitly to bypass auto-resolution.)',\n    )\n  }\n  // Inject apiKey + provider routing. SDK ProviderRoutingSettings shape.\n  // Note: we use `chat` capability since this is the conversation primitive;\n  // SDK may extend to embeddings/etc — those routes are separate concerns.\n  return {\n    ...options,\n    apiKey: resolved.apiKey,\n    providers: {\n      routes: [{ capability: 'chat', provider: resolved.name, baseUrl: resolved.baseUrl }],\n    },\n  }\n}\n"],"mappings":"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","names":["event"]}

package/dist/{chunk-64JI5LTO.js → chunk-RMU7EBRO.js}

@@ -9,7 +9,7 @@ var __IS_DEV = (() => {
 async function trackAgentRun(input, opts) {
   if (__IS_DEV) {
     try {
-      const mod = await import("./dispatcher-AQJGI3HU.js");
+      const mod = await import("./dispatcher-63LBXYLE.js");
       mod.dispatcher.onAgentRun({
         // eslint-disable-next-line sonarjs/pseudo-random -- non-secret correlation id
         id: `run-${String(Date.now())}-${Math.random().toString(36).slice(2, 8)}`,
@@ -182,4 +182,4 @@ export {
   InMemoryUsageStorage,
   trackAgentTools
 };
-//# sourceMappingURL=chunk-64JI5LTO.js.map
+//# sourceMappingURL=chunk-RMU7EBRO.js.map

package/dist/chunk-RMU7EBRO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/cost/track-agent-run.ts","../src/server/cost/usage-storage-memory.ts","../src/server/cost/track-agent-tools.ts"],"sourcesContent":["import type { AgentRunRecord } from '../../devtools/shared.js'\n\nimport type { UsageRecord, UsageStorageAdapter } from './cost-types.js'\n\nexport interface TrackAgentRunInput {\n  userId: string\n  model: string\n  tokens: { input: number; output: number }\n  costUsd: number\n  /** Defaults to `new Date()`. */\n  timestamp?: Date\n  /** Optional execution status surfaced to devtools (default 'finished'). */\n  status?: 'finished' | 'error' | 'aborted'\n}\n\nexport interface TrackAgentRunOptions {\n  /** Adapter resolved from `theo.config.ts > cost.storage`. */\n  storage: UsageStorageAdapter | undefined\n}\n\n// v1.1 EC-4 MUST FIX — universal dev gate (Vite OR tsup-bundled).\n// Both checks are statically replaceable by bundlers in prod build,\n// so the entire dispatcher import is tree-shaken from the prod bundle.\nconst __IS_DEV = (() => {\n  try {\n    return (import.meta as { env?: { DEV?: boolean } }).env?.DEV === true\n  } catch {\n    return process.env.NODE_ENV !== 'production'\n  }\n})()\n\n/**\n * Record a single agent run's usage + cost. Companion to the client-side\n * `<CostMeter>` from `@theokit/ui`.\n *\n * EC-14: this function NEVER bubbles errors back to the caller. Adapter\n * failures (network outage, DB down, etc.) are logged via `console.warn`\n * and swallowed. The agent response MUST NOT fail because cost tracking\n * is degraded.\n *\n * No-op when `storage` is undefined (cost tracking unconfigured).\n *\n * In dev mode (Vite OR tsup-built with NODE_ENV != 'production'), fires a\n * `theokit-evolution-ci-and-dx` Phase 3 dispatcher event so the devtools\n * Agents tab can render the run. Prod tree-shakes the entire dispatcher\n * import via the `__IS_DEV` IIFE guard.\n *\n * @see docs/concepts/cost-tracking.md (when implemented in T6.3)\n */\nexport async function trackAgentRun(\n  input: TrackAgentRunInput,\n  opts: TrackAgentRunOptions,\n): Promise<void> {\n  // Dev-only: surface run to devtools Agents tab (T3.1)\n  if (__IS_DEV) {\n    try {\n      const mod = (await import('../../devtools/bridge/dispatcher.js')) as {\n        dispatcher: { onAgentRun: (r: AgentRunRecord) => void }\n      }\n      mod.dispatcher.onAgentRun({\n        // eslint-disable-next-line sonarjs/pseudo-random -- non-secret correlation id\n        id: `run-${String(Date.now())}-${Math.random().toString(36).slice(2, 8)}`,\n        timestamp: (input.timestamp ?? new Date()).getTime(),\n        userId: input.userId,\n        model: input.model,\n        tokensInput: input.tokens.input,\n        tokensOutput: input.tokens.output,\n        costUsd: input.costUsd,\n        status: input.status ?? 'finished',\n      })\n    } catch {\n      // devtools dispatcher missing in some prod-like bundle — silently skip\n    }\n  }\n\n  if (!opts.storage) return\n  const record: UsageRecord = {\n    userId: input.userId,\n    model: input.model,\n    tokens: input.tokens,\n    costUsd: input.costUsd,\n    timestamp: input.timestamp ?? new Date(),\n  }\n  try {\n    await opts.storage.record(record)\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n\n    console.warn(\n      `[theokit:cost] usage storage record failed: ${message}. ` +\n        '(Response is unaffected — cost tracking degraded.)',\n    )\n  }\n}\n","import type { StorageAdapter } from '../storage/storage-types.js'\n\nimport type {\n  ToolUsageRecord,\n  UsageQuery,\n  UsageRecord,\n  UsageResult,\n  UsageStorageAdapter,\n} from './cost-types.js'\n\n/**\n * In-memory usage storage for dev/tests. Unbounded — production\n * deployments MUST plug in a durable adapter (Postgres/Redis recipes\n * land with R0.6.7; documented in EC-114).\n *\n * Phase 5 — Production-Readiness #4: accepts both `UsageRecord` (LLM call,\n * kind='llm' or omitted) AND `ToolUsageRecord` (tool call, kind='tool').\n * `getUsage` only sums LLM records (tools have no token/cost dimension).\n *\n * EC-9 (backward compat): input without `kind` is normalized to `kind:'llm'`\n * — adapters from older versions stay working.\n *\n * Concurrency: Node's single-threaded event loop guarantees that\n * `Array.push` is atomic, so concurrent record() calls cannot lose data.\n */\nexport class InMemoryUsageStorage implements UsageStorageAdapter, StorageAdapter {\n  readonly name = 'memory'\n  readonly #records: (UsageRecord | ToolUsageRecord)[] = []\n\n  /**\n   * T2.3 — `StorageAdapter` lifecycle hook (ADR-0007 D6). In-memory storage\n   * has no real cleanup to perform — this is intentionally a noop so the\n   * adapter can be registered with `StorageManager.register()` and\n   * participate in graceful shutdown without changing behavior.\n   *\n   * Does NOT clear stored records (dispose ≠ reset). For test reset use\n   * a fresh instance.\n   */\n  dispose(): Promise<void> {\n    // Intentional noop — see jsdoc above\n    return Promise.resolve()\n  }\n\n  async record(input: UsageRecord | ToolUsageRecord): Promise<void> {\n    // EC-9: normalize legacy input (no `kind` field) to kind:'llm'.\n    const normalized: UsageRecord | ToolUsageRecord =\n      'kind' in input && input.kind === 'tool'\n        ? { ...input }\n        : ({ ...input, kind: 'llm' as const } satisfies UsageRecord)\n    this.#records.push(normalized)\n    return Promise.resolve()\n  }\n\n  async getUsage(query: UsageQuery): Promise<UsageResult> {\n    const from = query.period.from.getTime()\n    const to = query.period.to.getTime()\n    let totalTokens = 0\n    let totalCostUsd = 0\n    let runs = 0\n    for (const r of this.#records) {\n      if (r.kind === 'tool') continue\n      if (r.userId !== query.userId) continue\n      const t = r.timestamp.getTime()\n      if (t < from || t > to) continue\n      totalTokens += r.tokens.input + r.tokens.output\n      totalCostUsd += r.costUsd\n      runs += 1\n    }\n    return Promise.resolve({ totalTokens, totalCostUsd, runs })\n  }\n\n  /** @internal — test helper to inspect raw record stream */\n  __getRecords(): readonly (UsageRecord | ToolUsageRecord)[] {\n    return this.#records\n  }\n}\n","import type { ToolUsageRecord, UsageStorageAdapter } from './cost-types.js'\n\n/**\n * Phase 5 — Production-Readiness #4: tool lifecycle hooks for cost tracking.\n *\n * The SDK calls `onToolStart` → handler runs → `onToolEnd` (success) or\n * `onToolError` (throw). This factory returns the three callbacks ready to\n * attach to `Agent.create({ tools, onToolStart, onToolEnd, onToolError })`.\n *\n * Each successful tool call writes a `ToolUsageRecord{success:true}`; each\n * failure writes `ToolUsageRecord{success:false}` with `errorMessage` from\n * the thrown Error.\n *\n * Invariants:\n *   - `onToolStart` records nothing yet (no duration available). Only stashes\n *     a `startedAt` timestamp by `callId` in a per-factory Map.\n *   - `onToolEnd` reads the stashed timestamp, computes `durationMs`, writes\n *     a successful record. Removes the Map entry.\n *   - `onToolError` analog with `success:false`.\n *   - Hook throws are SWALLOWED to stderr — observation hooks must not crash\n *     the run (per the v1.1.0 release contract).\n *   - EC-8 (SHOULD TEST) — orphan starts (no matching End/Error) are pruned\n *     on every onToolStart if older than 5 minutes. Bounded memory.\n *   - EC-16 (DOCUMENT) — callId uniqueness is SDK contract; duplicate Start\n *     for the same callId uses last-write-wins.\n */\n\nconst ORPHAN_TTL_MS = 5 * 60 * 1000\n\ninterface PendingStart {\n  startedAt: number\n  userId: string\n  conversationId: string\n}\n\nexport interface TrackAgentToolsOptions {\n  storage: UsageStorageAdapter\n  /** Defaults to () => new Date() — overridable for deterministic testing. */\n  now?: () => Date\n  /** Identifier for the user — passed through to ToolUsageRecord.userId. */\n  userId?: string\n  /** Identifier for the conversation — passed through to ToolUsageRecord.conversationId. */\n  conversationId?: string\n}\n\nexport interface ToolHookEvent {\n  callId: string\n  name: string\n  // SDK shape — we only read these structurally\n  [key: string]: unknown\n}\n\nexport interface TrackAgentToolsHooks {\n  onToolStart: (event: ToolHookEvent) => void\n  onToolEnd: (event: ToolHookEvent) => void\n  onToolError: (event: ToolHookEvent) => void\n}\n\n/**\n * Create the three tool-lifecycle callbacks. Hand the returned object's\n * methods to `Agent.create({ tools, onToolStart, onToolEnd, onToolError })`.\n */\nexport function trackAgentTools(opts: TrackAgentToolsOptions): TrackAgentToolsHooks {\n  const pending = new Map<string, PendingStart>()\n  const now = opts.now ?? ((): Date => new Date())\n  const userId = opts.userId ?? 'anonymous'\n  const conversationId = opts.conversationId ?? 'unknown'\n\n  function pruneOrphans(): void {\n    const cutoff = now().getTime() - ORPHAN_TTL_MS\n    for (const [id, p] of pending) {\n      if (p.startedAt < cutoff) pending.delete(id)\n    }\n  }\n\n  function safeRecord(record: ToolUsageRecord): void {\n    Promise.resolve(opts.storage.record(record)).catch((err: unknown) => {\n      const msg = err instanceof Error ? err.message : String(err)\n      console.warn(`[theokit:trackAgentTools] storage.record failed: ${msg}`)\n    })\n  }\n\n  return {\n    onToolStart(event: ToolHookEvent): void {\n      try {\n        pruneOrphans()\n        pending.set(event.callId, {\n          startedAt: now().getTime(),\n          userId,\n          conversationId,\n        })\n      } catch (err) {\n        console.warn(\n          `[theokit:trackAgentTools] onToolStart hook crashed (swallowed): ${\n            err instanceof Error ? err.message : String(err)\n          }`,\n        )\n      }\n    },\n    onToolEnd(event: ToolHookEvent): void {\n      try {\n        const start = pending.get(event.callId)\n        const startedAt = start?.startedAt ?? now().getTime()\n        const durationMs = start ? now().getTime() - startedAt : 0\n        pending.delete(event.callId)\n        if (!start) {\n          console.warn(\n            `[theokit:trackAgentTools] orphan onToolEnd for callId=${event.callId}; durationMs:0 recorded`,\n          )\n        }\n        safeRecord({\n          kind: 'tool',\n          userId: start?.userId ?? userId,\n          conversationId: start?.conversationId ?? conversationId,\n          toolName: event.name,\n          callId: event.callId,\n          success: true,\n          durationMs,\n          timestamp: now(),\n        })\n      } catch (err) {\n        console.warn(\n          `[theokit:trackAgentTools] onToolEnd hook crashed (swallowed): ${\n            err instanceof Error ? err.message : String(err)\n          }`,\n        )\n      }\n    },\n    onToolError(event: ToolHookEvent): void {\n      try {\n        const start = pending.get(event.callId)\n        const startedAt = start?.startedAt ?? now().getTime()\n        const durationMs = start ? now().getTime() - startedAt : 0\n        pending.delete(event.callId)\n        const error = event.error\n        let errorMessage = 'unknown error'\n        if (error instanceof Error) errorMessage = error.message\n        else if (typeof error === 'string') errorMessage = error\n        safeRecord({\n          kind: 'tool',\n          userId: start?.userId ?? userId,\n          conversationId: start?.conversationId ?? conversationId,\n          toolName: event.name,\n          callId: event.callId,\n          success: false,\n          durationMs,\n          errorMessage,\n          timestamp: now(),\n        })\n      } catch (err) {\n        console.warn(\n          `[theokit:trackAgentTools] onToolError hook crashed (swallowed): ${\n            err instanceof Error ? err.message : String(err)\n          }`,\n        )\n      }\n    },\n  }\n}\n\n/**\n * @internal — testing helper. Inspects the size of the pending-starts Map of\n * a factory instance. Not in the public API.\n */\nexport const __internalsForTesting = {\n  ORPHAN_TTL_MS,\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-TQYSPYKU.js

@@ -0,0 +1,131 @@
+// src/core/contracts/theo-error.ts
+var TheoError = class extends Error {
+  name = "TheoError";
+  code;
+  meta;
+  ext;
+  constructor(opts) {
+    super(opts.message, opts.cause !== void 0 ? { cause: opts.cause } : void 0);
+    this.code = opts.code;
+    this.meta = opts.meta;
+    this.ext = opts.ext;
+  }
+  /**
+   * The canonical envelope view of this error. Use when crossing the wire
+   * boundary or feeding telemetry — exposes the shape consumers can rely on
+   * without depending on the class identity.
+   */
+  get envelope() {
+    return {
+      code: this.code,
+      message: this.message,
+      cause: this.cause,
+      meta: this.meta,
+      ext: this.ext
+    };
+  }
+  /**
+   * JSON serialization — emits envelope shape only (no name/stack class
+   * internals). Per ADR D5, `meta.stack` is auto-stripped in non-dev to
+   * prevent accidental leak; other meta keys are preserved.
+   */
+  toJSON() {
+    const meta = this.meta ? sanitizeMeta(this.meta) : void 0;
+    return {
+      code: this.code,
+      message: this.message,
+      cause: this.cause,
+      meta,
+      ext: this.ext
+    };
+  }
+};
+function sanitizeMeta(meta) {
+  if (process.env.NODE_ENV === "development") {
+    return meta;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(meta)) {
+    if (k === "stack") continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+// src/core/contracts/server-error-to-envelope.ts
+var ERROR_NAME_TO_CODE = /* @__PURE__ */ new Map([
+  ["AuthRequiredError", "UNAUTHORIZED"],
+  ["FileTooLargeError", "PAYLOAD_TOO_LARGE"],
+  ["RequestBodyTooLargeError", "PAYLOAD_TOO_LARGE"],
+  ["BodyTooLargeError", "PAYLOAD_TOO_LARGE"],
+  // 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"]
+]);
+var META_EXTRACTORS = /* @__PURE__ */ new Map([
+  [
+    "FileTooLargeError",
+    (err) => {
+      const e = err;
+      return {
+        truncatedFilenames: e.truncatedFilenames ?? [],
+        maxFileSize: e.maxFileSize
+      };
+    }
+  ],
+  [
+    "RouterConventionError",
+    (err) => {
+      const e = err;
+      return {
+        file: e.file,
+        suggestion: e.suggestion,
+        migrationUrl: e.migrationUrl
+      };
+    }
+  ]
+]);
+var EXT_BUILDERS = /* @__PURE__ */ new Map([
+  [
+    "RouterConventionError",
+    () => ({
+      hint: "Run `theokit migrate router` to convert dotted-basename routes to directory-nested form."
+    })
+  ]
+]);
+function serverErrorToEnvelope(value) {
+  if (value instanceof TheoError) {
+    return value.envelope;
+  }
+  if (!(value instanceof Error)) {
+    return {
+      code: "INTERNAL_SERVER_ERROR",
+      message: typeof value === "string" ? value : "Unknown error"
+    };
+  }
+  const name = value.name;
+  const code = ERROR_NAME_TO_CODE.get(name) ?? "INTERNAL_SERVER_ERROR";
+  const extractor = META_EXTRACTORS.get(name);
+  const extra = extractor ? extractor(value) : null;
+  const meta = { name };
+  if (extra) {
+    for (const [k, v] of Object.entries(extra)) {
+      if (v !== void 0) meta[k] = v;
+    }
+  }
+  const extBuilder = EXT_BUILDERS.get(name);
+  const ext = extBuilder ? extBuilder(value) : void 0;
+  return {
+    code,
+    message: value.message,
+    cause: value.cause,
+    meta,
+    ext
+  };
+}
+
+export {
+  serverErrorToEnvelope
+};
+//# sourceMappingURL=chunk-TQYSPYKU.js.map

package/dist/chunk-TQYSPYKU.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 (referencia:\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 */\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\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\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":[]}