theokit 0.50.2 → 0.52.0

package/dist/{chunk-FD4ZDTQ6.js.map → chunk-Z7CJHDLS.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/server/_internal/compare-by-code-unit.ts","../src/server/_internal/scan-walker.ts","../src/server/scan/errors.ts","../src/server/scan/file-stamp-cache.ts"],"sourcesContent":["/**\n * Total order over strings by UTF-16 code unit — the ordering build-time output\n * must use.\n *\n * `localeCompare` is the wrong instrument here, and reads like the right one,\n * which is why it kept being chosen. With no locale argument it uses the default\n * collator, and Node derives that from `LC_ALL`/`LANG`: under `sv-SE` an `ä`\n * sorts after `z`, under `en-US` before `a`. A scanner ordering that way emits a\n * different manifest per machine — and where the order being emitted is an\n * execution order, it decides which middleware runs first\n * (usetheokit/theokit#346, usetheokit/theokit#351).\n *\n * What build output needs from a comparator is that it be total and stable.\n * Being alphabetical for a reader of one particular language is not a property\n * it needs, and is the one that costs reproducibility.\n *\n * Presentation code is the opposite case and should keep `localeCompare`: a list\n * a human reads should collate the way that human's language collates.\n *\n * @internal\n */\nexport function compareByCodeUnit(a: string, b: string): number {\n  if (a < b) return -1\n  if (a > b) return 1\n  return 0\n}\n","/* eslint-disable security/detect-non-literal-fs-filename --\n * Build-time scanner: walks directories derived from cwd.\n * No HTTP input ever reaches these fs calls.\n */\nimport { readdirSync } from 'node:fs'\nimport type { Dirent } from 'node:fs'\nimport { extname, join, resolve } from 'node:path'\n\nimport { compareByCodeUnit } from './compare-by-code-unit.js'\n\n/**\n * Options for walkSourceFiles.\n *\n * Sequential by design — callers (route precedence) depend on insertion\n * order (EC-19 documented decision). Async-callback support is implicit\n * via JavaScript's serial await loop.\n *\n * Tested on macOS + Linux. Windows long-path support not validated (EC-20).\n */\ninterface WalkOptions {\n  /** File extensions to include (e.g., new Set(['.ts', '.tsx'])). */\n  extensions: ReadonlySet<string>\n  /** Skip directories whose name starts with any of these (default: ['_', '.']). */\n  skipPrefixes?: readonly string[]\n  /**\n   * Read one directory. Defaults to `readdirSync`.\n   *\n   * Injected for one reason: the ordering below cannot be tested against a real\n   * filesystem. `readdirSync` returns whatever the filesystem returns — creation\n   * order on tmpfs, hash order on ext4 with `dir_index` — and on the machine\n   * this was written on those four names came back already sorted, so a\n   * name-based test passed before the sort existed and proved nothing. A test\n   * that agrees with the code because both read the same accidental order is\n   * `B-022`, and writing one here would have been that item committed inside its\n   * own fix.\n   */\n  readDir?: (dir: string) => Dirent[]\n}\n\n/**\n * Recursively walk `root`, invoking `onFile(absPath)` for every file matching\n * `opts.extensions`. Directories whose name starts with any `skipPrefixes`\n * char are skipped (defaults to `_` and `.`).\n *\n * Entries are emitted in UTF-16 code-unit order, files and directories in one\n * total order. Without it the walker passed the filesystem's order through to\n * six scanners — routes, actions, websockets, cron, agents, jobs — and only one\n * re-orders afterwards, so five emitted a different manifest per machine. Where\n * that order is an execution order it decides what runs first (#346, B-004).\n *\n * Replaces 3 near-identical recursive walkers in scan.ts, action-scan.ts,\n * ws-scan.ts (PV-3 — DRY consolidation). Resolves T3.1 of\n * architecture-review-remediation-plan. Six call sites consume it today, not\n * three; the count in this paragraph was true when it was written.\n *\n * Symlink loops are NOT tracked — callers must avoid them or pre-resolve\n * via `fs.realpath`. EC-11 documented but not implemented (rare in dev).\n */\nexport function walkSourceFiles(\n  root: string,\n  opts: WalkOptions,\n  onFile: (absPath: string) => void,\n): void {\n  const skipPrefixes = opts.skipPrefixes ?? ['_', '.']\n  const readDir = opts.readDir ?? ((dir: string) => readdirSync(dir, { withFileTypes: true }))\n  const visit = (dir: string): void => {\n    let entries\n    try {\n      entries = readDir(dir)\n    } catch {\n      // Silently skip unreadable directories — caller controls discoverability\n      return\n    }\n    // One total order over files and directories together, so a name sorts the\n    // same way whichever it is. Sorting the two groups separately would emit a\n    // different interleaving than a single pass, which is an ordering decision\n    // nobody made (#346).\n    const ordered = [...entries].sort((a, b) => compareByCodeUnit(a.name, b.name))\n    for (const entry of ordered) {\n      const fullPath = join(dir, entry.name)\n      if (entry.isDirectory() && !skipPrefixes.some((p) => entry.name.startsWith(p))) {\n        visit(fullPath)\n      } else if (entry.isFile() && opts.extensions.has(extname(entry.name))) {\n        onFile(resolve(fullPath))\n      }\n    }\n  }\n  visit(root)\n}\n","import { compareByCodeUnit } from '../_internal/compare-by-code-unit.js'\n\n/**\n * Router-convention errors thrown by the server-route scanner.\n *\n *\n * theokit 0.4.0+ enforces directory-nested file-system routing\n * (`auth/[provider]/login.ts`) and REJECTS dotted-basename routes\n * (`auth.[provider].login.ts`) because the legacy regex extracted the\n * dotted basename incorrectly — `params.provider` was undefined at request\n * time. Decision recorded in the plan above (`g6-router-convention-plan.md`) and CHANGELOG 0.4.0\n * (no standalone ADR was cut for this router-convention change).\n */\n\n/**\n * Canonical migration guide URL. T4.2 establishes this as the authoritative\n * landing page. EC-3: error message uses this constant so the URL never\n * drifts from the doc location.\n */\nexport const ROUTER_MIGRATION_GUIDE_URL = 'https://theokit.dev/migration/0.3-to-0.4-router'\n\ninterface RouterConventionErrorOptions {\n  /** Absolute path of the offending route file. */\n  file: string\n  /** Suggested directory-nested replacement path (relative, e.g. `routes/auth/[provider]/login.ts`). */\n  suggestion: string\n  /** Migration guide URL (defaults to `ROUTER_MIGRATION_GUIDE_URL`). */\n  migrationUrl?: string\n}\n\n/**\n * Thrown by `scanServerRoutes` when a route file uses the legacy\n * dotted-basename convention (`auth.[provider].login.ts`).\n *\n * The error is FAIL-FAST by design — running with a route that has wrong\n * `paramNames` produces silent 404s at request time, which is strictly\n * worse than a build-time error.\n */\nexport class RouterConventionError extends Error {\n  override readonly name = 'RouterConventionError'\n  readonly file: string\n  readonly suggestion: string\n  readonly migrationUrl: string\n\n  constructor(opts: RouterConventionErrorOptions) {\n    const migrationUrl = opts.migrationUrl ?? ROUTER_MIGRATION_GUIDE_URL\n    const message = [\n      `Router convention violation: dotted route basename is not supported in theokit 0.4+.`,\n      ``,\n      `  File: ${opts.file}`,\n      `  Use directory-nested form: ${opts.suggestion}`,\n      ``,\n      `Migration guide: ${migrationUrl}`,\n      `Run \\`theokit migrate router\\` to convert all dotted basenames automatically.`,\n    ].join('\\n')\n    super(message)\n    this.file = opts.file\n    this.suggestion = opts.suggestion\n    this.migrationUrl = migrationUrl\n  }\n}\n\n/**\n * Canonical landing page for the policy-declaration migration. Held as a\n * constant for the same reason as {@link ROUTER_MIGRATION_GUIDE_URL}: the error\n * message and the doc cannot drift apart if only one of them names the URL.\n *\n * Module-local, unlike its sibling: nothing outside this file needs to name it,\n * and an export with no consumer is what `knip` exists to refuse.\n */\nconst ROUTE_POLICY_MIGRATION_GUIDE_URL = 'https://theokit.dev/migration/route-policy'\n\ninterface MissingRoutePolicyErrorOptions {\n  /** Absolute path of the route file. */\n  file: string\n  /** The URL path the file resolves to, so the message reads like the app, not like the disk. */\n  routePath: string\n  /** The exported HTTP methods that declare no policy. */\n  methods: string[]\n  /** Migration guide URL (defaults to {@link ROUTE_POLICY_MIGRATION_GUIDE_URL}). */\n  migrationUrl?: string\n}\n\n/**\n * Thrown by `scanServerRoutes` when a route file exports an HTTP method that\n * declares no access policy (ADR 0001, Decision point 5).\n *\n * Absence used to mean \"not declared\", which every reader and every transport\n * had to interpret as open. The interpretation was the bug: a route nobody\n * thought about looked exactly like a route deliberately left open. This error\n * is where the two stop looking alike.\n *\n * It fires at scan time — `theo build`, `theo start`, `theo dev`, `theo routes`\n * and every deployment adapter go through the same scanner — so the answer\n * arrives before a request does, in the same place the scanner already refuses\n * a dotted basename and a collision with the reserved batch path.\n */\nexport class MissingRoutePolicyError extends Error {\n  override readonly name = 'MissingRoutePolicyError'\n  readonly file: string\n  readonly routePath: string\n  readonly methods: string[]\n  readonly migrationUrl: string\n\n  constructor(opts: MissingRoutePolicyErrorOptions) {\n    const migrationUrl = opts.migrationUrl ?? ROUTE_POLICY_MIGRATION_GUIDE_URL\n    const methods = [...opts.methods].sort(compareByCodeUnit)\n    const message = [\n      `Route policy not declared: every route says who may call it (ADR 0001).`,\n      ``,\n      `  File:    ${opts.file}`,\n      `  Route:   ${opts.routePath}`,\n      `  Missing: ${methods.join(', ')}`,\n      ``,\n      `Add a policy to each method listed above:`,\n      ``,\n      // The import is part of the remedy, not decoration. This message shipped\n      // naming `requireOwner` while no entry point exported it, so it read as\n      // actionable and was not. `tests/unit/policy-gate-remedy-is-importable.test.ts`\n      // asserts that every symbol named here is reachable from the path named here.\n      `  import { route, requireOwner } from 'theokit/server/define'`,\n      ``,\n      `  export const ${methods[0] ?? 'GET'} = route()`,\n      `    .policy('public')                                  // anyone may call this`,\n      `    .handler(...)`,\n      `    .build()`,\n      ``,\n      `  export const ${methods[0] ?? 'GET'} = route()`,\n      `    .policy(({ subject, params }) => requireOwner(subject, ownerOf(params.id)))`,\n      `    .handler(...)`,\n      `    .build()`,\n      ``,\n      `Writing 'public' is a decision and not a default. It states that this route`,\n      `is open to anyone who can reach it, and it is greppable, so how much of the`,\n      `app is open becomes a number somebody can read.`,\n      ``,\n      `Migration guide: ${migrationUrl}`,\n    ].join('\\n')\n    super(message)\n    this.file = opts.file\n    this.routePath = opts.routePath\n    this.methods = methods\n    this.migrationUrl = migrationUrl\n  }\n}\n\n/**\n * Canonical landing page for the agent-policy migration. Module-local for the same reason as its\n * route sibling: nothing outside this file names it, and an export with no consumer is what `knip`\n * exists to refuse.\n */\nconst AGENT_POLICY_MIGRATION_GUIDE_URL = 'https://theokit.dev/migration/agent-policy'\n\ninterface MissingAgentPolicyErrorOptions {\n  /** Absolute path of the agent file. */\n  file: string\n  /** The URL the agent is served at, so the message reads like the app rather than like the disk. */\n  agentPath: string\n  /** Migration guide URL (defaults to {@link AGENT_POLICY_MIGRATION_GUIDE_URL}). */\n  migrationUrl?: string\n}\n\n/**\n * Thrown by `scanAgents` when an agent file declares no access policy\n * (ADR 0001 Decision point 5, extended to the agent surface by usetheokit/theokit#365).\n *\n * ## Why absence had to stop meaning open HERE and not at runtime\n *\n * The agent endpoints resume a conversation the CALLER names, and they are dispatched before route\n * matching, so no route, no middleware and no `server/context.ts` ever saw those URLs. A caller\n * holding a conversation id and no credential read that conversation back.\n *\n * There is no safe runtime default for that. Refusing every caller-named session id would break\n * multi-turn chat, which is the base case; admitting them is the defect. So the decision moves to\n * where a person can answer it once, in the file that owns the agent — the same place and the same\n * reasoning as the route gate, which is why this error reads like its sibling.\n *\n * ## What it costs\n *\n * Every existing application with an agent fails its next build until it adds one line. That is the\n * half of ADR 0001 the ADR itself called breaking, and the trade it names: a build error that\n * points at a file beats a silent 200 that hands over somebody else's conversation.\n */\nexport class MissingAgentPolicyError extends Error {\n  override readonly name = 'MissingAgentPolicyError'\n  readonly file: string\n  readonly agentPath: string\n  readonly migrationUrl: string\n\n  constructor(opts: MissingAgentPolicyErrorOptions) {\n    const migrationUrl = opts.migrationUrl ?? AGENT_POLICY_MIGRATION_GUIDE_URL\n    const message = [\n      `Agent policy not declared: every agent says who may run it (ADR 0001).`,\n      ``,\n      `  File:  ${opts.file}`,\n      `  Agent: ${opts.agentPath}`,\n      ``,\n      `This one declaration covers every endpoint the agent exposes - the run, the`,\n      `thread routes, the pending-approval listing, the approve route and MCP - because`,\n      `they all reach the same conversation and the same paused tools.`,\n      ``,\n      `Add ONE of these to the file above:`,\n      ``,\n      `  export const policy = 'public'   // anyone who can reach it may run it`,\n      ``,\n      `  import { requireOwner } from 'theokit/server/define'`,\n      ``,\n      `  //  subject  <- what server/context.ts put on ctx.subject`,\n      `  //  params   <- { agent, endpoint, sessionId?, approvalId? }`,\n      `  //  body     <- the parsed chat body, on the endpoints that have one`,\n      `  export const policy = ({ subject, params }) =>`,\n      `    requireOwner(subject, ownerOf(params.sessionId))`,\n      ``,\n      `Writing 'public' is a decision and not a default. The endpoint resumes whatever`,\n      `conversation the CALLER names, so 'public' means any caller holding an id may read`,\n      `and continue that conversation - a capability model, which is legitimate when it is`,\n      `the choice somebody made and greppable once it is written down.`,\n      ``,\n      `Migration guide: ${migrationUrl}`,\n    ].join('\\n')\n    super(message)\n    this.file = opts.file\n    this.agentPath = opts.agentPath\n    this.migrationUrl = migrationUrl\n  }\n}\n","/**\n * Memoise per source file, invalidated by the file's own stamp.\n *\n * ## Why this exists\n *\n * `theokit dev` re-scans the routes and agents directories on EVERY request, so any work that\n * parses a file with the TypeScript AST turns a build-time check into per-request latency.\n * `agent-scan.ts` recognised this and carried its own `Map` keyed on `path:mtimeMs:size`;\n * `scan.ts` — with far more files — carried neither the cache nor the reasoning, and the\n * route-policy gate then added a SECOND full parse of every route file on top of the one\n * `detectExportedHttpMethods` had been paying since before it (usetheokit/theokit#417).\n *\n * Lifting the mechanism here rather than copying it is the point: two hand-rolled caches keyed\n * \"the same way\" are two chances for the keys to stop being the same.\n *\n * ## Why the stamp and not a watcher\n *\n * `mtimeMs` and `size` together come from the `statSync` the scanner is doing anyway, so an edit\n * invalidates the entry without anyone remembering to, and a `theokit build` — one process, one\n * scan — never notices the cache exists.\n *\n * The known limit, stated rather than discovered: a rewrite that preserves BOTH mtime and size is\n * invisible. That is a deliberate trade every mtime cache makes, and the alternative (hashing the\n * contents) reads the file to avoid reading the file.\n */\nimport { statSync } from 'node:fs'\n\nexport interface FileStampCache<T> {\n  /** The memoised value for `filePath`, computing it when the file's stamp has changed. */\n  get: (filePath: string, compute: () => T) => T\n  /** Test seam — a module-level cache would otherwise outlive a fixture directory. */\n  clear: () => void\n}\n\nexport function createFileStampCache<T>(): FileStampCache<T> {\n  const entries = new Map<string, T>()\n\n  return {\n    get(filePath, compute) {\n      // A path the scanner itself discovered by globbing the project, never caller input at runtime.\n      // eslint-disable-next-line security/detect-non-literal-fs-filename -- see above\n      const stat = statSync(filePath)\n      const key = `${filePath}:${String(stat.mtimeMs)}:${String(stat.size)}`\n\n      const hit = entries.get(key)\n      // `has` rather than a truthiness check on the value: `false`, `0` and `''` are all legitimate\n      // results to cache, and a truthiness test would recompute them on every call — which is the\n      // defect this file exists to remove, wearing a subtler hat.\n      if (hit !== undefined || entries.has(key)) return hit as T\n\n      const value = compute()\n      entries.set(key, value)\n      return value\n    },\n    clear() {\n      entries.clear()\n    },\n  }\n}\n"],"mappings":";;;;AAqBO,SAAS,kBAAkB,GAAW,GAAmB;AAC9D,MAAI,IAAI,EAAG,QAAO;AAClB,MAAI,IAAI,EAAG,QAAO;AAClB,SAAO;AACT;;;ACrBA,SAAS,mBAAmB;AAE5B,SAAS,SAAS,MAAM,eAAe;AAoDhC,SAAS,gBACd,MACA,MACA,QACM;AACN,QAAM,eAAe,KAAK,gBAAgB,CAAC,KAAK,GAAG;AACnD,QAAM,UAAU,KAAK,YAAY,CAAC,QAAgB,YAAY,KAAK,EAAE,eAAe,KAAK,CAAC;AAC1F,QAAM,QAAQ,CAAC,QAAsB;AACnC,QAAI;AACJ,QAAI;AACF,gBAAU,QAAQ,GAAG;AAAA,IACvB,QAAQ;AAEN;AAAA,IACF;AAKA,UAAM,UAAU,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC,GAAG,MAAM,kBAAkB,EAAE,MAAM,EAAE,IAAI,CAAC;AAC7E,eAAW,SAAS,SAAS;AAC3B,YAAM,WAAW,KAAK,KAAK,MAAM,IAAI;AACrC,UAAI,MAAM,YAAY,KAAK,CAAC,aAAa,KAAK,CAAC,MAAM,MAAM,KAAK,WAAW,CAAC,CAAC,GAAG;AAC9E,cAAM,QAAQ;AAAA,MAChB,WAAW,MAAM,OAAO,KAAK,KAAK,WAAW,IAAI,QAAQ,MAAM,IAAI,CAAC,GAAG;AACrE,eAAO,QAAQ,QAAQ,CAAC;AAAA,MAC1B;AAAA,IACF;AAAA,EACF;AACA,QAAM,IAAI;AACZ;;;ACrEO,IAAM,6BAA6B;AAmBnC,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAC7B,OAAO;AAAA,EAChB;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,MAAoC;AAC9C,UAAM,eAAe,KAAK,gBAAgB;AAC1C,UAAM,UAAU;AAAA,MACd;AAAA,MACA;AAAA,MACA,WAAW,KAAK,IAAI;AAAA,MACpB,gCAAgC,KAAK,UAAU;AAAA,MAC/C;AAAA,MACA,oBAAoB,YAAY;AAAA,MAChC;AAAA,IACF,EAAE,KAAK,IAAI;AACX,UAAM,OAAO;AACb,SAAK,OAAO,KAAK;AACjB,SAAK,aAAa,KAAK;AACvB,SAAK,eAAe;AAAA,EACtB;AACF;AAUA,IAAM,mCAAmC;AA2BlC,IAAM,0BAAN,cAAsC,MAAM;AAAA,EAC/B,OAAO;AAAA,EAChB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,MAAsC;AAChD,UAAM,eAAe,KAAK,gBAAgB;AAC1C,UAAM,UAAU,CAAC,GAAG,KAAK,OAAO,EAAE,KAAK,iBAAiB;AACxD,UAAM,UAAU;AAAA,MACd;AAAA,MACA;AAAA,MACA,cAAc,KAAK,IAAI;AAAA,MACvB,cAAc,KAAK,SAAS;AAAA,MAC5B,cAAc,QAAQ,KAAK,IAAI,CAAC;AAAA,MAChC;AAAA,MACA;AAAA,MACA;AAAA;AAAA;AAAA;AAAA;AAAA,MAKA;AAAA,MACA;AAAA,MACA,kBAAkB,QAAQ,CAAC,KAAK,KAAK;AAAA,MACrC;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,kBAAkB,QAAQ,CAAC,KAAK,KAAK;AAAA,MACrC;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,oBAAoB,YAAY;AAAA,IAClC,EAAE,KAAK,IAAI;AACX,UAAM,OAAO;AACb,SAAK,OAAO,KAAK;AACjB,SAAK,YAAY,KAAK;AACtB,SAAK,UAAU;AACf,SAAK,eAAe;AAAA,EACtB;AACF;AAOA,IAAM,mCAAmC;AAgClC,IAAM,0BAAN,cAAsC,MAAM;AAAA,EAC/B,OAAO;AAAA,EAChB;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,MAAsC;AAChD,UAAM,eAAe,KAAK,gBAAgB;AAC1C,UAAM,UAAU;AAAA,MACd;AAAA,MACA;AAAA,MACA,YAAY,KAAK,IAAI;AAAA,MACrB,YAAY,KAAK,SAAS;AAAA,MAC1B;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,oBAAoB,YAAY;AAAA,IAClC,EAAE,KAAK,IAAI;AACX,UAAM,OAAO;AACb,SAAK,OAAO,KAAK;AACjB,SAAK,YAAY,KAAK;AACtB,SAAK,eAAe;AAAA,EACtB;AACF;;;ACxMA,SAAS,gBAAgB;AASlB,SAAS,uBAA6C;AAC3D,QAAM,UAAU,oBAAI,IAAe;AAEnC,SAAO;AAAA,IACL,IAAI,UAAU,SAAS;AAGrB,YAAM,OAAO,SAAS,QAAQ;AAC9B,YAAM,MAAM,GAAG,QAAQ,IAAI,OAAO,KAAK,OAAO,CAAC,IAAI,OAAO,KAAK,IAAI,CAAC;AAEpE,YAAM,MAAM,QAAQ,IAAI,GAAG;AAI3B,UAAI,QAAQ,UAAa,QAAQ,IAAI,GAAG,EAAG,QAAO;AAElD,YAAM,QAAQ,QAAQ;AACtB,cAAQ,IAAI,KAAK,KAAK;AACtB,aAAO;AAAA,IACT;AAAA,IACA,QAAQ;AACN,cAAQ,MAAM;AAAA,IAChB;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/server/_internal/compare-by-code-unit.ts","../src/server/_internal/scan-walker.ts","../src/server/scan/errors.ts","../src/server/scan/file-stamp-cache.ts"],"sourcesContent":["/**\n * Total order over strings by UTF-16 code unit — the ordering build-time output\n * must use.\n *\n * `localeCompare` is the wrong instrument here, and reads like the right one,\n * which is why it kept being chosen. With no locale argument it uses the default\n * collator, and Node derives that from `LC_ALL`/`LANG`: under `sv-SE` an `ä`\n * sorts after `z`, under `en-US` before `a`. A scanner ordering that way emits a\n * different manifest per machine — and where the order being emitted is an\n * execution order, it decides which middleware runs first\n * (usetheokit/theokit#346, usetheokit/theokit#351).\n *\n * What build output needs from a comparator is that it be total and stable.\n * Being alphabetical for a reader of one particular language is not a property\n * it needs, and is the one that costs reproducibility.\n *\n * Presentation code is the opposite case and should keep `localeCompare`: a list\n * a human reads should collate the way that human's language collates.\n *\n * @internal\n */\nexport function compareByCodeUnit(a: string, b: string): number {\n  if (a < b) return -1\n  if (a > b) return 1\n  return 0\n}\n","/* eslint-disable security/detect-non-literal-fs-filename --\n * Build-time scanner: walks directories derived from cwd.\n * No HTTP input ever reaches these fs calls.\n */\nimport { readdirSync } from 'node:fs'\nimport type { Dirent } from 'node:fs'\nimport { extname, join, resolve } from 'node:path'\n\nimport { compareByCodeUnit } from './compare-by-code-unit.js'\n\n/**\n * Options for walkSourceFiles.\n *\n * Sequential by design — callers (route precedence) depend on insertion\n * order (EC-19 documented decision). Async-callback support is implicit\n * via JavaScript's serial await loop.\n *\n * Tested on macOS + Linux. Windows long-path support not validated (EC-20).\n */\ninterface WalkOptions {\n  /** File extensions to include (e.g., new Set(['.ts', '.tsx'])). */\n  extensions: ReadonlySet<string>\n  /** Skip directories whose name starts with any of these (default: ['_', '.']). */\n  skipPrefixes?: readonly string[]\n  /**\n   * Read one directory. Defaults to `readdirSync`.\n   *\n   * Injected for one reason: the ordering below cannot be tested against a real\n   * filesystem. `readdirSync` returns whatever the filesystem returns — creation\n   * order on tmpfs, hash order on ext4 with `dir_index` — and on the machine\n   * this was written on those four names came back already sorted, so a\n   * name-based test passed before the sort existed and proved nothing. A test\n   * that agrees with the code because both read the same accidental order is\n   * `B-022`, and writing one here would have been that item committed inside its\n   * own fix.\n   */\n  readDir?: (dir: string) => Dirent[]\n}\n\n/**\n * Recursively walk `root`, invoking `onFile(absPath)` for every file matching\n * `opts.extensions`. Directories whose name starts with any `skipPrefixes`\n * char are skipped (defaults to `_` and `.`).\n *\n * Entries are emitted in UTF-16 code-unit order, files and directories in one\n * total order. Without it the walker passed the filesystem's order through to\n * six scanners — routes, actions, websockets, cron, agents, jobs — and only one\n * re-orders afterwards, so five emitted a different manifest per machine. Where\n * that order is an execution order it decides what runs first (#346, B-004).\n *\n * Replaces 3 near-identical recursive walkers in scan.ts, action-scan.ts,\n * ws-scan.ts (PV-3 — DRY consolidation). Resolves T3.1 of\n * architecture-review-remediation-plan. Six call sites consume it today, not\n * three; the count in this paragraph was true when it was written.\n *\n * Symlink loops are NOT tracked — callers must avoid them or pre-resolve\n * via `fs.realpath`. EC-11 documented but not implemented (rare in dev).\n */\nexport function walkSourceFiles(\n  root: string,\n  opts: WalkOptions,\n  onFile: (absPath: string) => void,\n): void {\n  const skipPrefixes = opts.skipPrefixes ?? ['_', '.']\n  const readDir = opts.readDir ?? ((dir: string) => readdirSync(dir, { withFileTypes: true }))\n  const visit = (dir: string): void => {\n    let entries\n    try {\n      entries = readDir(dir)\n    } catch {\n      // Silently skip unreadable directories — caller controls discoverability\n      return\n    }\n    // One total order over files and directories together, so a name sorts the\n    // same way whichever it is. Sorting the two groups separately would emit a\n    // different interleaving than a single pass, which is an ordering decision\n    // nobody made (#346).\n    const ordered = [...entries].sort((a, b) => compareByCodeUnit(a.name, b.name))\n    for (const entry of ordered) {\n      const fullPath = join(dir, entry.name)\n      if (entry.isDirectory() && !skipPrefixes.some((p) => entry.name.startsWith(p))) {\n        visit(fullPath)\n      } else if (entry.isFile() && opts.extensions.has(extname(entry.name))) {\n        onFile(resolve(fullPath))\n      }\n    }\n  }\n  visit(root)\n}\n","import { compareByCodeUnit } from '../_internal/compare-by-code-unit.js'\n\n/**\n * Router-convention errors thrown by the server-route scanner.\n *\n *\n * theokit 0.4.0+ enforces directory-nested file-system routing\n * (`auth/[provider]/login.ts`) and REJECTS dotted-basename routes\n * (`auth.[provider].login.ts`) because the legacy regex extracted the\n * dotted basename incorrectly — `params.provider` was undefined at request\n * time. Decision recorded in the plan above (`g6-router-convention-plan.md`) and CHANGELOG 0.4.0\n * (no standalone ADR was cut for this router-convention change).\n */\n\n/**\n * Canonical migration guide URL. T4.2 establishes this as the authoritative\n * landing page. EC-3: error message uses this constant so the URL never\n * drifts from the doc location.\n */\nexport const ROUTER_MIGRATION_GUIDE_URL = 'https://theokit.dev/migration/0.3-to-0.4-router'\n\ninterface RouterConventionErrorOptions {\n  /** Absolute path of the offending route file. */\n  file: string\n  /** Suggested directory-nested replacement path (relative, e.g. `routes/auth/[provider]/login.ts`). */\n  suggestion: string\n  /** Migration guide URL (defaults to `ROUTER_MIGRATION_GUIDE_URL`). */\n  migrationUrl?: string\n}\n\n/**\n * Thrown by `scanServerRoutes` when a route file uses the legacy\n * dotted-basename convention (`auth.[provider].login.ts`).\n *\n * The error is FAIL-FAST by design — running with a route that has wrong\n * `paramNames` produces silent 404s at request time, which is strictly\n * worse than a build-time error.\n */\nexport class RouterConventionError extends Error {\n  override readonly name = 'RouterConventionError'\n  readonly file: string\n  readonly suggestion: string\n  readonly migrationUrl: string\n\n  constructor(opts: RouterConventionErrorOptions) {\n    const migrationUrl = opts.migrationUrl ?? ROUTER_MIGRATION_GUIDE_URL\n    const message = [\n      `Router convention violation: dotted route basename is not supported in theokit 0.4+.`,\n      ``,\n      `  File: ${opts.file}`,\n      `  Use directory-nested form: ${opts.suggestion}`,\n      ``,\n      `Migration guide: ${migrationUrl}`,\n      `Run \\`theokit migrate router\\` to convert all dotted basenames automatically.`,\n    ].join('\\n')\n    super(message)\n    this.file = opts.file\n    this.suggestion = opts.suggestion\n    this.migrationUrl = migrationUrl\n  }\n}\n\n/**\n * Canonical landing page for the policy-declaration migration. Held as a\n * constant for the same reason as {@link ROUTER_MIGRATION_GUIDE_URL}: the error\n * message and the doc cannot drift apart if only one of them names the URL.\n *\n * Module-local, unlike its sibling: nothing outside this file needs to name it,\n * and an export with no consumer is what `knip` exists to refuse.\n */\nconst ROUTE_POLICY_MIGRATION_GUIDE_URL = 'https://theokit.dev/migration/route-policy'\n\ninterface MissingRoutePolicyErrorOptions {\n  /** Absolute path of the route file. */\n  file: string\n  /** The URL path the file resolves to, so the message reads like the app, not like the disk. */\n  routePath: string\n  /** The exported HTTP methods that declare no policy. */\n  methods: string[]\n  /** Migration guide URL (defaults to {@link ROUTE_POLICY_MIGRATION_GUIDE_URL}). */\n  migrationUrl?: string\n}\n\n/**\n * Thrown by `scanServerRoutes` when a route file exports an HTTP method that\n * declares no access policy (ADR 0001, Decision point 5).\n *\n * Absence used to mean \"not declared\", which every reader and every transport\n * had to interpret as open. The interpretation was the bug: a route nobody\n * thought about looked exactly like a route deliberately left open. This error\n * is where the two stop looking alike.\n *\n * It fires at scan time — `theo build`, `theo start`, `theo dev`, `theo routes`\n * and every deployment adapter go through the same scanner — so the answer\n * arrives before a request does, in the same place the scanner already refuses\n * a dotted basename and a collision with the reserved batch path.\n */\nexport class MissingRoutePolicyError extends Error {\n  override readonly name = 'MissingRoutePolicyError'\n  readonly file: string\n  readonly routePath: string\n  readonly methods: string[]\n  readonly migrationUrl: string\n\n  constructor(opts: MissingRoutePolicyErrorOptions) {\n    const migrationUrl = opts.migrationUrl ?? ROUTE_POLICY_MIGRATION_GUIDE_URL\n    const methods = [...opts.methods].sort(compareByCodeUnit)\n    const message = [\n      `Route policy not declared: every route says who may call it (ADR 0001).`,\n      ``,\n      `  File:    ${opts.file}`,\n      `  Route:   ${opts.routePath}`,\n      `  Missing: ${methods.join(', ')}`,\n      ``,\n      `Add a policy to each method listed above:`,\n      ``,\n      // The import is part of the remedy, not decoration. This message shipped\n      // naming `requireOwner` while no entry point exported it, so it read as\n      // actionable and was not. `tests/unit/policy-gate-remedy-is-importable.test.ts`\n      // asserts that every symbol named here is reachable from the path named here.\n      `  import { route, requireOwner } from 'theokit/server/define'`,\n      ``,\n      `  export const ${methods[0] ?? 'GET'} = route()`,\n      `    .policy('public')                                  // anyone may call this`,\n      `    .handler(...)`,\n      `    .build()`,\n      ``,\n      `  export const ${methods[0] ?? 'GET'} = route()`,\n      `    .policy(({ subject, params }) => requireOwner(subject, ownerOf(params.id)))`,\n      `    .handler(...)`,\n      `    .build()`,\n      ``,\n      `Writing 'public' is a decision and not a default. It states that this route`,\n      `is open to anyone who can reach it, and it is greppable, so how much of the`,\n      `app is open becomes a number somebody can read.`,\n      ``,\n      `Migration guide: ${migrationUrl}`,\n    ].join('\\n')\n    super(message)\n    this.file = opts.file\n    this.routePath = opts.routePath\n    this.methods = methods\n    this.migrationUrl = migrationUrl\n  }\n}\n\n/**\n * Canonical landing page for the agent-policy migration. Module-local for the same reason as its\n * route sibling: nothing outside this file names it, and an export with no consumer is what `knip`\n * exists to refuse.\n */\nconst AGENT_POLICY_MIGRATION_GUIDE_URL = 'https://theokit.dev/migration/agent-policy'\n\ninterface MissingAgentPolicyErrorOptions {\n  /** Absolute path of the agent file. */\n  file: string\n  /** The URL the agent is served at, so the message reads like the app rather than like the disk. */\n  agentPath: string\n  /** Migration guide URL (defaults to {@link AGENT_POLICY_MIGRATION_GUIDE_URL}). */\n  migrationUrl?: string\n}\n\n/**\n * Thrown by `scanAgents` when an agent file declares no access policy\n * (ADR 0001 Decision point 5, extended to the agent surface by usetheokit/theokit#365).\n *\n * ## Why absence had to stop meaning open HERE and not at runtime\n *\n * The agent endpoints resume a conversation the CALLER names, and they are dispatched before route\n * matching, so no route, no middleware and no `server/context.ts` ever saw those URLs. A caller\n * holding a conversation id and no credential read that conversation back.\n *\n * There is no safe runtime default for that. Refusing every caller-named session id would break\n * multi-turn chat, which is the base case; admitting them is the defect. So the decision moves to\n * where a person can answer it once, in the file that owns the agent — the same place and the same\n * reasoning as the route gate, which is why this error reads like its sibling.\n *\n * ## What it costs\n *\n * Every existing application with an agent fails its next build until it adds one line. That is the\n * half of ADR 0001 the ADR itself called breaking, and the trade it names: a build error that\n * points at a file beats a silent 200 that hands over somebody else's conversation.\n */\nexport class MissingAgentPolicyError extends Error {\n  override readonly name = 'MissingAgentPolicyError'\n  readonly file: string\n  readonly agentPath: string\n  readonly migrationUrl: string\n\n  constructor(opts: MissingAgentPolicyErrorOptions) {\n    const migrationUrl = opts.migrationUrl ?? AGENT_POLICY_MIGRATION_GUIDE_URL\n    const message = [\n      `Agent policy not declared: every agent says who may run it (ADR 0001).`,\n      ``,\n      `  File:  ${opts.file}`,\n      `  Agent: ${opts.agentPath}`,\n      ``,\n      `This one declaration covers every endpoint the agent exposes - the run, the`,\n      `thread routes, the pending-approval listing, the approve route and MCP - because`,\n      `they all reach the same conversation and the same paused tools.`,\n      ``,\n      `Add ONE of these to the file above:`,\n      ``,\n      `  export const policy = 'public'   // anyone who can reach it may run it`,\n      ``,\n      `  import { requireOwner } from 'theokit/server/define'`,\n      ``,\n      `  //  subject  <- what server/context.ts put on ctx.subject`,\n      `  //  params   <- { agent, endpoint, sessionId?, approvalId? }`,\n      `  //  body     <- the parsed chat body, on the endpoints that have one`,\n      `  export const policy = ({ subject, params }) =>`,\n      `    requireOwner(subject, ownerOf(params.sessionId))`,\n      ``,\n      `Writing 'public' is a decision and not a default. The endpoint resumes whatever`,\n      `conversation the CALLER names, so 'public' means any caller holding an id may read`,\n      `and continue that conversation - a capability model, which is legitimate when it is`,\n      `the choice somebody made and greppable once it is written down.`,\n      ``,\n      `Migration guide: ${migrationUrl}`,\n    ].join('\\n')\n    super(message)\n    this.file = opts.file\n    this.agentPath = opts.agentPath\n    this.migrationUrl = migrationUrl\n  }\n}\n\ninterface RedundantApiSegmentErrorOptions {\n  /** Absolute path of the offending route file. */\n  file: string\n  /** The path it resolves to today, with the doubled prefix. */\n  doubledRoutePath: string\n  /** Where the file belongs, relative and ready to copy. */\n  suggestion: string\n  /** The typed-client chain it produces today, with the redundant segment. */\n  doubledClientChain: string\n}\n\n/**\n * Thrown by `scanServerRoutes` when a route file sits under `routes/api/`.\n *\n * `routes/` is already served under `/api`, so the directory doubles the prefix — and it does so\n * in two places at once, which is why this is an error rather than a lint.\n *\n * The URL is the visible half: `routes/api/auth/callback.ts` answers at `/api/api/auth/callback`,\n * which is not the redirect URI anybody registered with an identity provider. The second half\n * survives a reader's attention: `.theokit/client.d.ts` mirrors the file tree into the typed\n * client, so the same file produces `client.api.auth.callback.get()` — an `api` segment that reads\n * as a typo and is not one.\n *\n * Refusing rather than silently stripping the segment is deliberate. Collapsing would swap one\n * silent behaviour for another, and would let `routes/api/foo.ts` and `routes/foo.ts` resolve to\n * one URL — a collision needing its own error anyway.\n *\n * The `/api` prefix itself is not the defect. It is the boundary between what the server answers\n * and what the SPA answers, and three framework namespaces live under it (`/api/__actions/`,\n * `/api/agents/`, `/api/__theo_batch__`).\n */\nexport class RedundantApiSegmentError extends Error {\n  override readonly name = 'RedundantApiSegmentError'\n  readonly file: string\n  readonly doubledRoutePath: string\n  readonly suggestion: string\n\n  constructor(opts: RedundantApiSegmentErrorOptions) {\n    const message = [\n      `Redundant 'api' directory: routes/ is already served under /api.`,\n      ``,\n      `  File:    ${opts.file}`,\n      `  Answers: ${opts.doubledRoutePath}`,\n      `  Client:  ${opts.doubledClientChain}`,\n      ``,\n      `Move it up one level:`,\n      ``,\n      `  ${opts.suggestion}`,\n      ``,\n      `Both halves are wrong from one cause. The URL is not the one you would register with an`,\n      `identity provider or call from anywhere, and the generated typed client in`,\n      `.theokit/client.d.ts carries the same redundant segment.`,\n    ].join('\\n')\n    super(message)\n    this.file = opts.file\n    this.doubledRoutePath = opts.doubledRoutePath\n    this.suggestion = opts.suggestion\n  }\n}\n","/**\n * Memoise per source file, invalidated by the file's own stamp.\n *\n * ## Why this exists\n *\n * `theokit dev` re-scans the routes and agents directories on EVERY request, so any work that\n * parses a file with the TypeScript AST turns a build-time check into per-request latency.\n * `agent-scan.ts` recognised this and carried its own `Map` keyed on `path:mtimeMs:size`;\n * `scan.ts` — with far more files — carried neither the cache nor the reasoning, and the\n * route-policy gate then added a SECOND full parse of every route file on top of the one\n * `detectExportedHttpMethods` had been paying since before it (usetheokit/theokit#417).\n *\n * Lifting the mechanism here rather than copying it is the point: two hand-rolled caches keyed\n * \"the same way\" are two chances for the keys to stop being the same.\n *\n * ## Why the stamp and not a watcher\n *\n * `mtimeMs` and `size` together come from the `statSync` the scanner is doing anyway, so an edit\n * invalidates the entry without anyone remembering to, and a `theokit build` — one process, one\n * scan — never notices the cache exists.\n *\n * The known limit, stated rather than discovered: a rewrite that preserves BOTH mtime and size is\n * invisible. That is a deliberate trade every mtime cache makes, and the alternative (hashing the\n * contents) reads the file to avoid reading the file.\n */\nimport { statSync } from 'node:fs'\n\nexport interface FileStampCache<T> {\n  /** The memoised value for `filePath`, computing it when the file's stamp has changed. */\n  get: (filePath: string, compute: () => T) => T\n  /** Test seam — a module-level cache would otherwise outlive a fixture directory. */\n  clear: () => void\n}\n\nexport function createFileStampCache<T>(): FileStampCache<T> {\n  const entries = new Map<string, T>()\n\n  return {\n    get(filePath, compute) {\n      // A path the scanner itself discovered by globbing the project, never caller input at runtime.\n      // eslint-disable-next-line security/detect-non-literal-fs-filename -- see above\n      const stat = statSync(filePath)\n      const key = `${filePath}:${String(stat.mtimeMs)}:${String(stat.size)}`\n\n      const hit = entries.get(key)\n      // `has` rather than a truthiness check on the value: `false`, `0` and `''` are all legitimate\n      // results to cache, and a truthiness test would recompute them on every call — which is the\n      // defect this file exists to remove, wearing a subtler hat.\n      if (hit !== undefined || entries.has(key)) return hit as T\n\n      const value = compute()\n      entries.set(key, value)\n      return value\n    },\n    clear() {\n      entries.clear()\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-ZDUO4IYN.js

@@ -0,0 +1,174 @@
+// src/core/contracts/action-protocol.ts
+var CODE_TO_STATUS = {
+  VALIDATION_ERROR: 422,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  CONFLICT: 409,
+  CONTENT_TOO_LARGE: 413,
+  PAYLOAD_TOO_LARGE: 413,
+  UNSUPPORTED_MEDIA_TYPE: 415,
+  TOO_MANY_REQUESTS: 429,
+  INTERNAL_SERVER_ERROR: 500
+};
+var STATUS_TO_CODE = {
+  400: "BAD_REQUEST",
+  401: "UNAUTHORIZED",
+  403: "FORBIDDEN",
+  404: "NOT_FOUND",
+  405: "METHOD_NOT_ALLOWED",
+  409: "CONFLICT",
+  413: "PAYLOAD_TOO_LARGE",
+  415: "UNSUPPORTED_MEDIA_TYPE",
+  422: "VALIDATION_ERROR",
+  429: "TOO_MANY_REQUESTS",
+  500: "INTERNAL_SERVER_ERROR"
+};
+var ActionError = class _ActionError extends Error {
+  // Discriminator widened to the full union so subclasses can narrow to their
+  // specific literal (TypeScript would otherwise reject the override). Concrete
+  // values are still always exact literals at runtime.
+  type = "TheoActionError";
+  code;
+  status;
+  constructor(params) {
+    super(params.message ?? params.code);
+    this.code = params.code;
+    this.status = _ActionError.codeToStatus(params.code);
+    if (params.stack) {
+      this.stack = params.stack;
+    }
+  }
+  /**
+   * G5 T2.4 — canonical envelope view of the action error. Maps the G3
+   * ActionErrorCode to a canonical TheoErrorCode (VALIDATION_ERROR ↔
+   * UNPROCESSABLE_ENTITY, CONTENT_TOO_LARGE ↔ PAYLOAD_TOO_LARGE) so consumer
+   * UI / SDK code can switch on the unified envelope.
+   *
+   * Subclasses override to populate `ext` (see `ActionInputError.envelope`).
+   */
+  get envelope() {
+    return {
+      code: _ActionError.toTheoErrorCode(this.code),
+      message: this.message
+    };
+  }
+  /**
+   * Translate G3 ActionErrorCode → canonical TheoErrorCode (blueprint
+   * Recommendations § "G3 ActionError becomes inaugural envelope user").
+   */
+  static toTheoErrorCode(code) {
+    if (code === "VALIDATION_ERROR") return "UNPROCESSABLE_ENTITY";
+    if (code === "CONTENT_TOO_LARGE") return "PAYLOAD_TOO_LARGE";
+    return code;
+  }
+  static codeToStatus(code) {
+    return CODE_TO_STATUS[code];
+  }
+  static statusToCode(status) {
+    return STATUS_TO_CODE[status] ?? "INTERNAL_SERVER_ERROR";
+  }
+  /**
+   * Parse a serialized error JSON back into the typed class hierarchy.
+   * Distinguishes `TheoActionInputError` (with `issues` array) from
+   * `TheoActionError` via the `type` discriminator. Falls back to
+   * `INTERNAL_SERVER_ERROR` for malformed bodies (non-object, missing
+   * `type`, unknown `code`).
+   */
+  static fromJson(body) {
+    if (typeof body !== "object" || body === null) {
+      return new _ActionError({ code: "INTERNAL_SERVER_ERROR" });
+    }
+    const obj = body;
+    if (obj.type === "TheoActionInputError" && Array.isArray(obj.issues)) {
+      return new ActionInputError(obj.issues);
+    }
+    if (obj.type === "TheoActionError" && typeof obj.code === "string" && obj.code in CODE_TO_STATUS) {
+      return new _ActionError({
+        code: obj.code,
+        message: typeof obj.message === "string" ? obj.message : void 0
+      });
+    }
+    return new _ActionError({ code: "INTERNAL_SERVER_ERROR" });
+  }
+};
+var ActionInputError = class extends ActionError {
+  type = "TheoActionInputError";
+  issues;
+  fields;
+  constructor(rawIssues) {
+    super({ code: "VALIDATION_ERROR", message: "Validation failed" });
+    this.issues = extractUniversalIssues(rawIssues);
+    this.fields = buildFieldsMap(this.issues);
+  }
+  /**
+   * G5 T2.4 — envelope view with ValidationFieldsExt populated from .fields.
+   * UI consumers can `switch (env.code)` on `UNPROCESSABLE_ENTITY` and read
+   * `(env.ext as ValidationFieldsExt).fields` for field-level rendering.
+   */
+  get envelope() {
+    return {
+      code: "UNPROCESSABLE_ENTITY",
+      message: this.message,
+      ext: { fields: this.fields }
+    };
+  }
+};
+function buildFieldsMap(issues) {
+  const fields = {};
+  const seen = /* @__PURE__ */ new Set();
+  for (const issue of issues) {
+    const key = issue.path.length === 0 ? "" : issue.path.join(".");
+    const dedupeKey = `${key}\0${issue.message}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    const bucket = fields[key] ?? [];
+    bucket.push(issue.message);
+    fields[key] = bucket;
+  }
+  return fields;
+}
+function extractUniversalIssues(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const entry of raw) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const obj = entry;
+    if (!Array.isArray(obj.path)) continue;
+    if (typeof obj.message !== "string") continue;
+    const path = [];
+    let pathValid = true;
+    for (const seg of obj.path) {
+      if (typeof seg === "string" || typeof seg === "number") {
+        path.push(seg);
+      } else {
+        pathValid = false;
+        break;
+      }
+    }
+    if (!pathValid) continue;
+    out.push({
+      path,
+      message: obj.message,
+      code: typeof obj.code === "string" ? obj.code : void 0
+    });
+  }
+  return out;
+}
+function isActionError(value) {
+  return value instanceof ActionError;
+}
+function isInputError(value) {
+  return value instanceof ActionInputError;
+}
+
+export {
+  ActionError,
+  ActionInputError,
+  extractUniversalIssues,
+  isActionError,
+  isInputError
+};
+//# sourceMappingURL=chunk-ZDUO4IYN.js.map

package/dist/chunk-ZDUO4IYN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/contracts/action-protocol.ts"],"mappings":"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","names":[]}

package/dist/cli/index.js

@@ -15,12 +15,12 @@ function cliVersion() {
 // src/cli/index.ts
 var cli = cac("theokit");
 cli.command("dev", "Start development server").option("--port <port>", "Port number").action(async (options) => {
-  const { devCommand } = await import("../dev-Z4YLROZD.js");
+  const { devCommand } = await import("../dev-W7OXHMSP.js");
   await devCommand({ port: options.port ? Number(options.port) : void 0 });
 });
 cli.command("build", "Build for production").option("--target <target>", "Deploy target (node, vercel, cloudflare)").action(async (options) => {
   try {
-    const { buildCommand } = await import("../build-4LPUE2H3.js");
+    const { buildCommand } = await import("../build-3AYYQZGQ.js");
     await buildCommand({ target: options.target });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -32,7 +32,7 @@ cli.command("build", "Build for production").option("--target <target>", "Deploy
 });
 cli.command("start", "Start production server").option("--port <port>", "Port number").action(async (options) => {
   try {
-    const { startCommand } = await import("../start-G2JS6422.js");
+    const { startCommand } = await import("../start-WILEDDW2.js");
     await startCommand({ port: options.port ? Number(options.port) : void 0 });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -44,7 +44,7 @@ cli.command("start", "Start production server").option("--port <port>", "Port nu
 });
 cli.command("preview", "Build for production, then serve it \u2014 one step (B-030)").option("--port <port>", "Port number").option("--target <target>", "Deploy target (node, vercel, cloudflare)").action(async (options) => {
   try {
-    const { previewCommand } = await import("../preview-LB3YL6U5.js");
+    const { previewCommand } = await import("../preview-4ZTFJG2D.js");
     await previewCommand({
       port: options.port ? Number(options.port) : void 0,
       target: options.target
@@ -77,7 +77,7 @@ cli.command(
   "Run an agent in the terminal (stream + tool calls + approval)"
 ).action(async (name, message) => {
   try {
-    const { agentCommand } = await import("../agent-7RP3VTSI.js");
+    const { agentCommand } = await import("../agent-AHGYRVQX.js");
     const { sawError } = await agentCommand(name, message);
     if (sawError) process.exit(1);
   } catch (err) {
@@ -108,7 +108,7 @@ cli.command("agent sessions gc", "Collect old transcripts for this project (dry
 });
 cli.command("mcp <agent>", "Serve an agent as an MCP server over stdio (for desktop MCP clients)").action(async (agent) => {
   try {
-    const { mcpCommand } = await import("../mcp-RKD4QQFS.js");
+    const { mcpCommand } = await import("../mcp-7BXBN7PD.js");
     await mcpCommand(agent);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -120,7 +120,7 @@ cli.command("mcp <agent>", "Serve an agent as an MCP server over stdio (for desk
 });
 cli.command("routes", "List all routes, actions, and WebSocket endpoints").action(async () => {
   try {
-    const { routesCommand } = await import("../routes-BPLU3ISV.js");
+    const { routesCommand } = await import("../routes-PP5PHHLR.js");
     await routesCommand();
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -173,7 +173,7 @@ cli.command(
   "Generate <distDir>/openapi.json from route schemas (opt-in via config.openapi)"
 ).option("--dry-run", "Print the document to stdout without writing to disk (EC-3)").action(async (options) => {
   try {
-    const { openapiCommand } = await import("../openapi-VFPEZSRI.js");
+    const { openapiCommand } = await import("../openapi-2IBBOS3Q.js");
     await openapiCommand({ dryRun: Boolean(options.dryRun) });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);

package/dist/client/index.d.ts

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import { T as TheoErrorEnvelope } from '../error-envelope-DG47lt8E.js';
 export { FetchOptionsLike, Fetcher, QueryKey, UseTheoQueryConfig, buildUseTheoQueryConfig, stableQueryKey } from '../react-query/index.js';
 export { AgentClient, AgentClientState, AgentHandle, AgentStreamInterruptedError, AgentTransport, ApprovalDecision, ChannelPushSource, ChannelTransport, ChannelTransportOptions, ChannelTurnHandlers, HttpTransport, HttpTransportOptions, InProcessApprovalRequestLike, InProcessAwaitApproval, InProcessRunInput, InProcessRunner, InProcessTransport, InProcessTransportOptions, RequestContext, agentHandle, consumeChunkStream, consumeUIMessageStream, isAgentHandle, responseToChunkStream } from '@theokit/agents/client';
+import { A as ActionError } from '../action-protocol-tGm3NKRg.js';
+export { a as ActionErrorCode, b as ActionInputError, c as ActionResult, i as isActionError, d as isInputError } from '../action-protocol-tGm3NKRg.js';
 export { PendingApproval, UseAgentOptions, UseAgentReturn, UseAgentStatus, useAgent } from '@theokit/agents/client/react';
 export { AgentClientHandle, CreateAgentClientOptions, createAgentClient } from './core.js';
 import * as react from 'react';
@@ -118,6 +120,120 @@ interface Batcher {
 }
 declare function createBatcher(options: BatcherOptions): Batcher;
 
+/**
+ * usetheokit/theokit#453 — the framework-agnostic store behind {@link useAction}.
+ *
+ * `core/contracts/action-protocol.ts` opens by describing itself as the "cross-boundary contract
+ * for `defineAction` + `useAction`" and points the client half at `@theokit/react/useAction` — a
+ * package outside this repository, with one version, no `repository` field, and a
+ * `@theokit/sdk ^1.1.0` peer against a published 4.x. The server half of that contract has always
+ * lived here; this is the client half arriving.
+ *
+ * The state machine lives in a store rather than in the hook, following `useAgent`: it is testable
+ * with no DOM, and a non-React surface can subscribe to it directly. The hook in `use-action.ts` is
+ * a `useSyncExternalStore` binding over it.
+ */
+/**
+ * What a generated callable resolves.
+ *
+ * Deliberately NOT `ActionResult`, whose `error` is an `ActionError` instance: the envelope crosses
+ * the wire as JSON, so what arrives is a plain object, and a callable typed against the class would
+ * be one no honest implementation can satisfy. `error` is `unknown` here and normalized on the way
+ * into the state.
+ *
+ * Both keys are present — the generated facade always emits both — which is also what tells an
+ * envelope apart from a payload that merely has a field named `data` or `error`.
+ */
+interface ActionEnvelope<TData = unknown> {
+    readonly data: TData | undefined;
+    readonly error: unknown;
+}
+/**
+ * A callable shaped like the ones `@theo/actions` generates. They resolve an
+ * {@link ActionEnvelope} rather than throwing — including for network failure — but a hand-written
+ * callable that resolves a bare value or throws is handled too, since consumers pass both.
+ */
+type ActionCallable<TInput = unknown, TData = unknown> = (input: TInput) => Promise<ActionEnvelope<TData> | TData>;
+type ActionStatus = 'idle' | 'pending' | 'error' | 'success';
+/** The observable state, one frozen object per transition (`useSyncExternalStore` contract). */
+interface ActionState<TInput = unknown, TData = unknown> {
+    readonly status: ActionStatus;
+    readonly data: TData | undefined;
+    readonly error: ActionError | undefined;
+    /** The input of the most recent call — what a retry button replays. */
+    readonly variables: TInput | undefined;
+}
+/**
+ * Holds `{status, data, error, variables}` for one action callable and notifies subscribers on each
+ * transition.
+ */
+declare class ActionClient<TInput = unknown, TData = unknown> {
+    #private;
+    constructor(action: ActionCallable<TInput, TData>);
+    /** Subscribe to state changes; returns an unsubscribe fn. */
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * The current snapshot, stable by reference until the next transition. Allocating here instead
+     * would re-render a React consumer forever.
+     */
+    getSnapshot: () => ActionState<TInput, TData>;
+    /** Invoke the action, resolving its data or rejecting with a typed {@link ActionError}. */
+    mutateAsync: (input: TInput) => Promise<TData>;
+    /**
+     * Fire-and-forget: the outcome lands in the state, and the returned promise is consumed here so a
+     * failure does not surface as an unhandled rejection in a component that only reads `isError`.
+     */
+    mutate: (input: TInput) => void;
+    /** Back to idle, discarding whatever is in flight. */
+    reset: () => void;
+}
+
+/**
+ * usetheokit/theokit#453 — call a server action from a component and track its state.
+ *
+ * The framework already generates the typed callable (`@theo/actions`), serves it at
+ * `/api/__actions/`, and defines the error hierarchy it answers with. This is the last piece:
+ *
+ * ```tsx
+ * import { actions } from '@theo/actions'
+ * import { useAction } from 'theokit/client'
+ *
+ * function SaveButton() {
+ *   const save = useAction(actions.saveMemory)
+ *   return (
+ *     <button disabled={save.isPending} onClick={() => save.mutate({ content: 'hi' })}>
+ *       {save.isPending ? 'Saving…' : 'Save'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * A failure lands in `error` as the protocol's own {@link ActionError} — so a validation failure is
+ * an `ActionInputError` with its `fields` map intact, which is what a form library binds to.
+ *
+ * The state machine lives in {@link ActionClient}; this is a `useSyncExternalStore` binding over it,
+ * the same shape as `useAgent`.
+ */
+interface UseActionResult<TInput = unknown, TData = unknown> {
+    /** The data of the most recent successful call. */
+    data: TData | undefined;
+    /** The typed error of the most recent failed call. */
+    error: ActionError | undefined;
+    isIdle: boolean;
+    isPending: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+    /** The input of the most recent call — what a retry button replays. */
+    variables: TInput | undefined;
+    /** Fire and forget; read the outcome off `isPending` / `error`. */
+    mutate: (input: TInput) => void;
+    /** Await the data, or catch the typed {@link ActionError}. */
+    mutateAsync: (input: TInput) => Promise<TData>;
+    /** Back to idle, discarding whatever is in flight. */
+    reset: () => void;
+}
+declare function useAction<TInput = unknown, TData = unknown>(action: ActionCallable<TInput, TData>): UseActionResult<TInput, TData>;
+
 type PrefetchBehavior = 'none' | 'intent' | 'viewport';
 interface LinkProps extends LinkProps$1 {
     /** Prefetch strategy. Default: 'intent' (on hover + focus). */
@@ -299,4 +415,4 @@ declare function mountMcpApp(container: HTMLElement, resource: {
     html: string;
 }, opts: McpAppHostOptions): McpAppHandle;
 
-export { type BatchRequest, type BatchResponse, type BatchTransport, type Batcher, type BatcherOptions, type CreateAppClientOptions, type GuestMessage, Image, type ImageProps, type InferBody, type InferQuery, type InferResponse, Link, type LinkProps, MCP_APP_SANDBOX, type McpAppHandle, type McpAppHostOptions, Metadata, type MetadataProps, type PrefetchBehavior, TheoFetchError, type TheoFetchOptions, createAppClient, createBatcher, createGuestMessageHandler, mountMcpApp, theoFetch };
+export { type ActionCallable, ActionClient, type ActionEnvelope, ActionError, type ActionState, type ActionStatus, type BatchRequest, type BatchResponse, type BatchTransport, type Batcher, type BatcherOptions, type CreateAppClientOptions, type GuestMessage, Image, type ImageProps, type InferBody, type InferQuery, type InferResponse, Link, type LinkProps, MCP_APP_SANDBOX, type McpAppHandle, type McpAppHostOptions, Metadata, type MetadataProps, type PrefetchBehavior, TheoFetchError, type TheoFetchOptions, type UseActionResult, createAppClient, createBatcher, createGuestMessageHandler, mountMcpApp, theoFetch, useAction };