theokit 0.21.0 → 0.22.1

package/dist/{dev-NHHTXOA4.js → dev-SHAN56K5.js}

@@ -8,9 +8,9 @@ import {
 } from "./chunk-HNBWZKIQ.js";
 import {
   theoPluginAsync
-} from "./chunk-3WOODHXK.js";
-import "./chunk-DXF64KS5.js";
-import "./chunk-DMC6HYUR.js";
+} from "./chunk-AYZCGJXA.js";
+import "./chunk-LGVVX3BV.js";
+import "./chunk-2CVV6CNN.js";
 import "./chunk-M6NMS5LR.js";
 import "./chunk-IEES3CHD.js";
 import {
@@ -111,4 +111,4 @@ export {
   devCommand,
   startDevServer
 };
-//# sourceMappingURL=dev-NHHTXOA4.js.map
+//# sourceMappingURL=dev-SHAN56K5.js.map

package/dist/index.js

@@ -8,11 +8,11 @@ import {
   scanRoutes,
   theoConfigSchema,
   theoPlugin
-} from "./chunk-7PFHQ56Q.js";
+} from "./chunk-BLL5LY7R.js";
 import "./chunk-D7ZH7DTG.js";
 import "./chunk-RSVN727G.js";
 import "./chunk-7BIM27LV.js";
-import "./chunk-W4YO6S4I.js";
+import "./chunk-W4XWVTN4.js";
 import "./chunk-5QW7IQQU.js";
 import "./chunk-IAJ2JVEH.js";
 import "./chunk-VMEWD57H.js";

package/dist/{mcp-HP5RVOOZ.js → mcp-P4MHP3VA.js}

@@ -2,11 +2,11 @@
 import "tsx/esm";
 import {
   createAgentSsrLoader
-} from "./chunk-23T4CO4M.js";
+} from "./chunk-JITNAZXE.js";
 import {
   extractAppResources,
   handleMcpJsonRpc
-} from "./chunk-DMC6HYUR.js";
+} from "./chunk-2CVV6CNN.js";
 import "./chunk-M6NMS5LR.js";
 import "./chunk-GDN3PXFH.js";
 import {
@@ -31,7 +31,7 @@ async function handleMcpStdioLine(line, mod, name, appResources = []) {
       error: { code: -32700, message: "Parse error" }
     });
   }
-  const response = handleMcpJsonRpc(mod, name, body, appResources);
+  const response = await handleMcpJsonRpc(mod, name, body, appResources);
   const payload = await response.json();
   return JSON.stringify(payload);
 }
@@ -75,4 +75,4 @@ async function mcpCommand(name, deps = {}) {
 export {
   mcpCommand
 };
-//# sourceMappingURL=mcp-HP5RVOOZ.js.map
+//# sourceMappingURL=mcp-P4MHP3VA.js.map

package/dist/{mcp-HP5RVOOZ.js.map → mcp-P4MHP3VA.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/cli/commands/mcp.ts","../src/server/agent/mcp-stdio.ts"],"sourcesContent":["/**\n * `theokit mcp <agent>` — expose a scanned agent as an MCP server over stdio.\n *\n * The stdio sibling of the M16 HTTP route (`POST /api/agents/<name>/mcp`): a desktop MCP client\n * (e.g. Claude Desktop) spawns this command and speaks newline-delimited JSON-RPC over the pipe.\n * It reuses the framework's OWN `serveMcpStdio` / `handleMcpJsonRpc` (no LLM call, no runtime — a\n * TRANSPORT, like the HTTP route). `deps` is injectable so the routing is tested without Vite/stdin.\n */\nimport { createInterface } from 'node:readline'\n\nimport { extractAppResources } from '../../server/agent/mcp-app-resources.js'\nimport { type StdioStreams, serveMcpStdio } from '../../server/agent/mcp-stdio.js'\nimport { scanAgents } from '../../server/scan/agent-scan.js'\n\nimport { createAgentSsrLoader } from './agent.js'\n\nexport interface McpCommandDeps {\n  projectRoot?: string\n  /** Load a TS agent module; defaults to the framework's Vite SSR loader (same transpile as dev). */\n  loadModule?: (filePath: string) => Promise<Record<string, unknown>>\n  /** stdio streams; defaults to `readline(process.stdin)` + `process.stdout`. Injected in tests. */\n  streams?: StdioStreams\n  /** Agents dir name (config `agentsDir`); defaults to the loaded config's value (\"agents\"). Tests inject it. */\n  agentsDir?: string\n}\n\nexport async function mcpCommand(name: string, deps: McpCommandDeps = {}): Promise<void> {\n  const projectRoot = deps.projectRoot ?? process.cwd()\n  // #95 follow-up — resolve agents dir from config (default \"agents\") so `agentsDir` is honored here too.\n  const agentsDir =\n    deps.agentsDir ??\n    (await (await import('../../config/load-config.js')).loadConfig(projectRoot)).agentsDir\n  const agent = scanAgents(projectRoot, agentsDir).find((a) => a.name === name)\n  if (!agent) {\n    const names = scanAgents(projectRoot, agentsDir)\n      .map((a) => a.name)\n      .join(', ')\n    throw new Error(\n      `theokit mcp: agent '${name}' not found. Available: ${names || '(none in agents/)'}`,\n    )\n  }\n\n  let loadModule = deps.loadModule\n  let dispose: (() => Promise<void>) | undefined\n  if (!loadModule) {\n    const loader = await createAgentSsrLoader(projectRoot)\n    loadModule = loader.load\n    dispose = loader.dispose\n  }\n\n  const streams =\n    deps.streams ??\n    ({\n      lines: createInterface({ input: process.stdin }),\n      write: (line: string) => process.stdout.write(line),\n    } satisfies StdioStreams)\n\n  try {\n    const mod = await loadModule(agent.filePath)\n    await serveMcpStdio(mod, agent.name, extractAppResources(mod), streams)\n  } finally {\n    if (dispose) await dispose()\n  }\n}\n","/**\n * MCP stdio transport (M16 follow-up) — expose a TheoKit agent as an MCP server over stdin/stdout,\n * the sibling of the M16 HTTP route (`POST /api/agents/<name>/mcp`). A desktop MCP client (e.g.\n * Claude Desktop) spawns `theokit mcp <agent>` and speaks newline-delimited JSON-RPC over the pipe.\n *\n * This is a TRANSPORT over the framework's OWN {@link handleMcpJsonRpc} — it reuses the exact handler\n * the HTTP route uses; it calls no LLM, spawns no MCP client, and reimplements no runtime (G2 /\n * sdk-runtime.md). Distinct from the SDK's MCP CLIENT stdio (which spawns external MCP servers via\n * `mcpServers` command/args) — that stays SDK-side. Here TheoKit is the SERVER. The framework-side\n * placement of this server-exposure transport is recorded in ADR-0042 (refining ADR-0040's M16 note).\n */\nimport type { AppResource } from './mcp-app-resources.js'\nimport { handleMcpJsonRpc } from './mcp-handler.js'\n\n/**\n * Handle one newline-delimited JSON-RPC line. Returns the response line to write to stdout, or\n * `null` for a blank line (nothing to emit). A malformed JSON line yields a `-32700` (Parse error)\n * envelope — never throws, so the stdio loop never dies on bad input.\n */\nexport async function handleMcpStdioLine(\n  line: string,\n  mod: unknown,\n  name: string,\n  appResources: readonly AppResource[] = [],\n): Promise<string | null> {\n  const trimmed = line.trim()\n  if (trimmed.length === 0) return null\n  let body: unknown\n  try {\n    body = JSON.parse(trimmed)\n  } catch {\n    return JSON.stringify({\n      jsonrpc: '2.0',\n      id: null,\n      error: { code: -32700, message: 'Parse error' },\n    })\n  }\n  const response = handleMcpJsonRpc(mod, name, body, appResources)\n  const payload: unknown = await response.json()\n  return JSON.stringify(payload)\n}\n\n/** A minimal readable line source (an async iterable of lines) + a writable sink. */\nexport interface StdioStreams {\n  /** Async iterable of newline-delimited input lines (e.g. `readline.createInterface({ input })`). */\n  lines: AsyncIterable<string>\n  /** Write a response line (the caller appends no newline). */\n  write: (line: string) => void\n}\n\n/**\n * Drive the MCP stdio server loop: for each input line, dispatch via {@link handleMcpStdioLine} and\n * write the response line (with a trailing `\\n`). Returns when the input stream ends (EOF).\n */\nexport async function serveMcpStdio(\n  mod: unknown,\n  name: string,\n  appResources: readonly AppResource[],\n  streams: StdioStreams,\n): Promise<void> {\n  for await (const line of streams.lines) {\n    const out = await handleMcpStdioLine(line, mod, name, appResources)\n    if (out !== null) streams.write(`${out}\\n`)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAQA,SAAS,uBAAuB;;;ACWhC,eAAsB,mBACpB,MACA,KACA,MACA,eAAuC,CAAC,GAChB;AACxB,QAAM,UAAU,KAAK,KAAK;AAC1B,MAAI,QAAQ,WAAW,EAAG,QAAO;AACjC,MAAI;AACJ,MAAI;AACF,WAAO,KAAK,MAAM,OAAO;AAAA,EAC3B,QAAQ;AACN,WAAO,KAAK,UAAU;AAAA,MACpB,SAAS;AAAA,MACT,IAAI;AAAA,MACJ,OAAO,EAAE,MAAM,QAAQ,SAAS,cAAc;AAAA,IAChD,CAAC;AAAA,EACH;AACA,QAAM,WAAW,iBAAiB,KAAK,MAAM,MAAM,YAAY;AAC/D,QAAM,UAAmB,MAAM,SAAS,KAAK;AAC7C,SAAO,KAAK,UAAU,OAAO;AAC/B;AAcA,eAAsB,cACpB,KACA,MACA,cACA,SACe;AACf,mBAAiB,QAAQ,QAAQ,OAAO;AACtC,UAAM,MAAM,MAAM,mBAAmB,MAAM,KAAK,MAAM,YAAY;AAClE,QAAI,QAAQ,KAAM,SAAQ,MAAM,GAAG,GAAG;AAAA,CAAI;AAAA,EAC5C;AACF;;;ADtCA,eAAsB,WAAW,MAAc,OAAuB,CAAC,GAAkB;AACvF,QAAM,cAAc,KAAK,eAAe,QAAQ,IAAI;AAEpD,QAAM,YACJ,KAAK,cACJ,OAAO,MAAM,OAAO,2BAA6B,GAAG,WAAW,WAAW,GAAG;AAChF,QAAM,QAAQ,WAAW,aAAa,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,SAAS,IAAI;AAC5E,MAAI,CAAC,OAAO;AACV,UAAM,QAAQ,WAAW,aAAa,SAAS,EAC5C,IAAI,CAAC,MAAM,EAAE,IAAI,EACjB,KAAK,IAAI;AACZ,UAAM,IAAI;AAAA,MACR,uBAAuB,IAAI,2BAA2B,SAAS,mBAAmB;AAAA,IACpF;AAAA,EACF;AAEA,MAAI,aAAa,KAAK;AACtB,MAAI;AACJ,MAAI,CAAC,YAAY;AACf,UAAM,SAAS,MAAM,qBAAqB,WAAW;AACrD,iBAAa,OAAO;AACpB,cAAU,OAAO;AAAA,EACnB;AAEA,QAAM,UACJ,KAAK,WACJ;AAAA,IACC,OAAO,gBAAgB,EAAE,OAAO,QAAQ,MAAM,CAAC;AAAA,IAC/C,OAAO,CAAC,SAAiB,QAAQ,OAAO,MAAM,IAAI;AAAA,EACpD;AAEF,MAAI;AACF,UAAM,MAAM,MAAM,WAAW,MAAM,QAAQ;AAC3C,UAAM,cAAc,KAAK,MAAM,MAAM,oBAAoB,GAAG,GAAG,OAAO;AAAA,EACxE,UAAE;AACA,QAAI,QAAS,OAAM,QAAQ;AAAA,EAC7B;AACF;","names":[]}
+{"version":3,"sources":["../src/cli/commands/mcp.ts","../src/server/agent/mcp-stdio.ts"],"sourcesContent":["/**\n * `theokit mcp <agent>` — expose a scanned agent as an MCP server over stdio.\n *\n * The stdio sibling of the M16 HTTP route (`POST /api/agents/<name>/mcp`): a desktop MCP client\n * (e.g. Claude Desktop) spawns this command and speaks newline-delimited JSON-RPC over the pipe.\n * It reuses the framework's OWN `serveMcpStdio` / `handleMcpJsonRpc` (no LLM call, no runtime — a\n * TRANSPORT, like the HTTP route). `deps` is injectable so the routing is tested without Vite/stdin.\n */\nimport { createInterface } from 'node:readline'\n\nimport { extractAppResources } from '../../server/agent/mcp-app-resources.js'\nimport { type StdioStreams, serveMcpStdio } from '../../server/agent/mcp-stdio.js'\nimport { scanAgents } from '../../server/scan/agent-scan.js'\n\nimport { createAgentSsrLoader } from './agent.js'\n\nexport interface McpCommandDeps {\n  projectRoot?: string\n  /** Load a TS agent module; defaults to the framework's Vite SSR loader (same transpile as dev). */\n  loadModule?: (filePath: string) => Promise<Record<string, unknown>>\n  /** stdio streams; defaults to `readline(process.stdin)` + `process.stdout`. Injected in tests. */\n  streams?: StdioStreams\n  /** Agents dir name (config `agentsDir`); defaults to the loaded config's value (\"agents\"). Tests inject it. */\n  agentsDir?: string\n}\n\nexport async function mcpCommand(name: string, deps: McpCommandDeps = {}): Promise<void> {\n  const projectRoot = deps.projectRoot ?? process.cwd()\n  // #95 follow-up — resolve agents dir from config (default \"agents\") so `agentsDir` is honored here too.\n  const agentsDir =\n    deps.agentsDir ??\n    (await (await import('../../config/load-config.js')).loadConfig(projectRoot)).agentsDir\n  const agent = scanAgents(projectRoot, agentsDir).find((a) => a.name === name)\n  if (!agent) {\n    const names = scanAgents(projectRoot, agentsDir)\n      .map((a) => a.name)\n      .join(', ')\n    throw new Error(\n      `theokit mcp: agent '${name}' not found. Available: ${names || '(none in agents/)'}`,\n    )\n  }\n\n  let loadModule = deps.loadModule\n  let dispose: (() => Promise<void>) | undefined\n  if (!loadModule) {\n    const loader = await createAgentSsrLoader(projectRoot)\n    loadModule = loader.load\n    dispose = loader.dispose\n  }\n\n  const streams =\n    deps.streams ??\n    ({\n      lines: createInterface({ input: process.stdin }),\n      write: (line: string) => process.stdout.write(line),\n    } satisfies StdioStreams)\n\n  try {\n    const mod = await loadModule(agent.filePath)\n    await serveMcpStdio(mod, agent.name, extractAppResources(mod), streams)\n  } finally {\n    if (dispose) await dispose()\n  }\n}\n","/**\n * MCP stdio transport (M16 follow-up) — expose a TheoKit agent as an MCP server over stdin/stdout,\n * the sibling of the M16 HTTP route (`POST /api/agents/<name>/mcp`). A desktop MCP client (e.g.\n * Claude Desktop) spawns `theokit mcp <agent>` and speaks newline-delimited JSON-RPC over the pipe.\n *\n * This is a TRANSPORT over the framework's OWN {@link handleMcpJsonRpc} — it reuses the exact handler\n * the HTTP route uses; it calls no LLM, spawns no MCP client, and reimplements no runtime (G2 /\n * sdk-runtime.md). Distinct from the SDK's MCP CLIENT stdio (which spawns external MCP servers via\n * `mcpServers` command/args) — that stays SDK-side. Here TheoKit is the SERVER. The framework-side\n * placement of this server-exposure transport is recorded in ADR-0042 (refining ADR-0040's M16 note).\n */\nimport type { AppResource } from './mcp-app-resources.js'\nimport { handleMcpJsonRpc } from './mcp-handler.js'\n\n/**\n * Handle one newline-delimited JSON-RPC line. Returns the response line to write to stdout, or\n * `null` for a blank line (nothing to emit). A malformed JSON line yields a `-32700` (Parse error)\n * envelope — never throws, so the stdio loop never dies on bad input.\n */\nexport async function handleMcpStdioLine(\n  line: string,\n  mod: unknown,\n  name: string,\n  appResources: readonly AppResource[] = [],\n): Promise<string | null> {\n  const trimmed = line.trim()\n  if (trimmed.length === 0) return null\n  let body: unknown\n  try {\n    body = JSON.parse(trimmed)\n  } catch {\n    return JSON.stringify({\n      jsonrpc: '2.0',\n      id: null,\n      error: { code: -32700, message: 'Parse error' },\n    })\n  }\n  const response = await handleMcpJsonRpc(mod, name, body, appResources)\n  const payload: unknown = await response.json()\n  return JSON.stringify(payload)\n}\n\n/** A minimal readable line source (an async iterable of lines) + a writable sink. */\nexport interface StdioStreams {\n  /** Async iterable of newline-delimited input lines (e.g. `readline.createInterface({ input })`). */\n  lines: AsyncIterable<string>\n  /** Write a response line (the caller appends no newline). */\n  write: (line: string) => void\n}\n\n/**\n * Drive the MCP stdio server loop: for each input line, dispatch via {@link handleMcpStdioLine} and\n * write the response line (with a trailing `\\n`). Returns when the input stream ends (EOF).\n */\nexport async function serveMcpStdio(\n  mod: unknown,\n  name: string,\n  appResources: readonly AppResource[],\n  streams: StdioStreams,\n): Promise<void> {\n  for await (const line of streams.lines) {\n    const out = await handleMcpStdioLine(line, mod, name, appResources)\n    if (out !== null) streams.write(`${out}\\n`)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAQA,SAAS,uBAAuB;;;ACWhC,eAAsB,mBACpB,MACA,KACA,MACA,eAAuC,CAAC,GAChB;AACxB,QAAM,UAAU,KAAK,KAAK;AAC1B,MAAI,QAAQ,WAAW,EAAG,QAAO;AACjC,MAAI;AACJ,MAAI;AACF,WAAO,KAAK,MAAM,OAAO;AAAA,EAC3B,QAAQ;AACN,WAAO,KAAK,UAAU;AAAA,MACpB,SAAS;AAAA,MACT,IAAI;AAAA,MACJ,OAAO,EAAE,MAAM,QAAQ,SAAS,cAAc;AAAA,IAChD,CAAC;AAAA,EACH;AACA,QAAM,WAAW,MAAM,iBAAiB,KAAK,MAAM,MAAM,YAAY;AACrE,QAAM,UAAmB,MAAM,SAAS,KAAK;AAC7C,SAAO,KAAK,UAAU,OAAO;AAC/B;AAcA,eAAsB,cACpB,KACA,MACA,cACA,SACe;AACf,mBAAiB,QAAQ,QAAQ,OAAO;AACtC,UAAM,MAAM,MAAM,mBAAmB,MAAM,KAAK,MAAM,YAAY;AAClE,QAAI,QAAQ,KAAM,SAAQ,MAAM,GAAG,GAAG;AAAA,CAAI;AAAA,EAC5C;AACF;;;ADtCA,eAAsB,WAAW,MAAc,OAAuB,CAAC,GAAkB;AACvF,QAAM,cAAc,KAAK,eAAe,QAAQ,IAAI;AAEpD,QAAM,YACJ,KAAK,cACJ,OAAO,MAAM,OAAO,2BAA6B,GAAG,WAAW,WAAW,GAAG;AAChF,QAAM,QAAQ,WAAW,aAAa,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,SAAS,IAAI;AAC5E,MAAI,CAAC,OAAO;AACV,UAAM,QAAQ,WAAW,aAAa,SAAS,EAC5C,IAAI,CAAC,MAAM,EAAE,IAAI,EACjB,KAAK,IAAI;AACZ,UAAM,IAAI;AAAA,MACR,uBAAuB,IAAI,2BAA2B,SAAS,mBAAmB;AAAA,IACpF;AAAA,EACF;AAEA,MAAI,aAAa,KAAK;AACtB,MAAI;AACJ,MAAI,CAAC,YAAY;AACf,UAAM,SAAS,MAAM,qBAAqB,WAAW;AACrD,iBAAa,OAAO;AACpB,cAAU,OAAO;AAAA,EACnB;AAEA,QAAM,UACJ,KAAK,WACJ;AAAA,IACC,OAAO,gBAAgB,EAAE,OAAO,QAAQ,MAAM,CAAC;AAAA,IAC/C,OAAO,CAAC,SAAiB,QAAQ,OAAO,MAAM,IAAI;AAAA,EACpD;AAEF,MAAI;AACF,UAAM,MAAM,MAAM,WAAW,MAAM,QAAQ;AAC3C,UAAM,cAAc,KAAK,MAAM,MAAM,oBAAoB,GAAG,GAAG,OAAO;AAAA,EACxE,UAAE;AACA,QAAI,QAAS,OAAM,QAAQ;AAAA,EAC7B;AACF;","names":[]}

package/dist/server/index.d.ts

@@ -1115,6 +1115,167 @@ interface ExecuteWebRequestOptions {
 }
 declare function executeWebRequest(request: Request, routeModule: WebRouteModule, opts?: ExecuteWebRequestOptions): Promise<Response>;
 
+/**
+ * M33 — the SINGLE route-input validation pipeline, shared by the HTTP path (`web-handler.ts`
+ * `runHandler`) and the in-process caller (`in-process-caller.ts` `callProcedure`).
+ *
+ * Both surfaces validate the same three channels (`query`/`body`/`params`) against the same
+ * `RouteConfig` Zod schemas. Extracting the logic here means there is ONE validation pipeline
+ * (no duplication, no drift) — each caller only differs in how it MAPS a failure: the HTTP path
+ * emits a 400 Response, the in-process path throws a typed error.
+ */
+
+/** The three request-input channels a route may declare a Zod schema for. */
+type RouteInputChannel = 'query' | 'body' | 'params';
+/**
+ * The minimal structural shape the validator needs: the three optional channel schemas. Both
+ * `RouteConfig` (the 5-arity generic contract) and `WebRouteHandlerConfig` (the Web runtime shape)
+ * satisfy this — the validator depends only on the schemas, not the full route generic.
+ */
+interface RouteInputSchemas {
+    query?: z.ZodType;
+    body?: z.ZodType;
+    params?: z.ZodType;
+}
+/** Raw (pre-validation) channel values. A channel absent from the config passes through unchanged. */
+interface RawRouteInput {
+    query?: unknown;
+    body?: unknown;
+    params?: unknown;
+}
+/** Discriminated result — each caller maps `ok:false` to its own surface (Response vs throw). */
+type RouteInputValidation = {
+    ok: true;
+    query: unknown;
+    body: unknown;
+    params: unknown;
+} | {
+    ok: false;
+    channel: RouteInputChannel;
+    error: z.ZodError;
+};
+/**
+ * Validate the three input channels against the route's declared Zod schemas. A channel with no
+ * declared schema passes its raw value through. First failing channel short-circuits (query → body
+ * → params order, matching `runHandler`).
+ */
+declare function validateRouteInput(config: RouteInputSchemas, raw: RawRouteInput): RouteInputValidation;
+
+/**
+ * M33 Phase 1 — `callProcedure`, the in-process typed caller.
+ *
+ * The load-bearing seam for non-HTTP surfaces (TUI / Tauri / MCP-tools): invoke a route's shared
+ * logic with STRUCTURED input, WITHOUT going through the HTTP transport (no URL/body parsing, no
+ * middleware chain, no Response). It reuses the SAME Zod validation pipeline as the HTTP path
+ * (`validateRouteInput`) so there is no drift, and reuses the SAME `config.response` server-fault
+ * check. Failures throw typed errors (there is no HTTP status off-web).
+ *
+ * Prior art: tRPC `callProcedure` / `createCallerFactory`
+ * (`.claude/knowledge-base/references/trpc/packages/server/src/unstable-core-do-not-import/router.ts:401,441`).
+ *
+ * Design (ADR-0044 / blueprint §5.4): the AUTHOR passes structured input `{query?, body?, params?}`
+ * — never synthesizes a Request. A minimal in-process `Request` is provided to the handler ONLY so
+ * handlers that read `request.headers`/`request.url` still work (opencode's proven pattern); the
+ * input itself is NOT parsed from it.
+ */
+
+/** Structured input for an in-process procedure call — one object per declared channel. */
+type ProcedureInput = RawRouteInput;
+/**
+ * Thrown when structured input fails the route's Zod validation. The in-process analog of the HTTP
+ * 400 — carries the failing channel + the Zod issues (typed error, not a magic value; Rule 8).
+ */
+declare class ProcedureInputError extends Error {
+    readonly channel: RouteInputChannel;
+    readonly issues: z.core.$ZodIssue[];
+    constructor(channel: RouteInputChannel, error: z.ZodError);
+}
+/**
+ * Thrown when the handler's plain-object return drifts from `config.response` — a SERVER fault
+ * (the handler violated its own declared contract), mirroring the HTTP path's 500 as a throw.
+ */
+declare class ProcedureOutputError extends Error {
+    readonly issues: z.core.$ZodIssue[];
+    constructor(error: z.ZodError);
+}
+/**
+ * Invoke a route/procedure's handler in-process with structured, Zod-validated input.
+ *
+ * @param config  the `RouteConfig` (what `route().build()` produces).
+ * @param input   structured `{query?, body?, params?}` — validated by the route's schemas.
+ * @param ctx     the typed run-context the handler receives (built by the CALLER — a TUI/Tauri/MCP
+ *                surface supplies its own ctx factory; there is no HTTP middleware chain here).
+ * @returns       the handler's result (validated against `config.response` when declared).
+ * @throws ProcedureInputError  on invalid structured input (the off-web analog of a 400).
+ * @throws ProcedureOutputError on a handler output that drifts from `config.response` (server fault).
+ */
+declare function callProcedure(config: RouteConfig<z.ZodType, z.ZodType, z.ZodType>, input?: ProcedureInput, ctx?: unknown): Promise<unknown>;
+
+/**
+ * M33 Phase 1 — the ctx reconciliation contract (ADR-0044 D4 / blueprint §5.2, §8.5).
+ *
+ * ## The problem the deep research verified against our own code
+ *
+ * At runtime (`execute.ts:122-165`) the handler's `ctx` is written by THREE sources, not one:
+ *
+ *   1. **the user `context.ts` factory** — via `runMiddlewareAndContext` (`execute.ts:131`). This is
+ *      the ONLY writer the author controls + declares a shape for. **This is the typed surface.**
+ *   2. **plugin decorations** — `pluginRunner.applyDecorations(ctx)` (`execute.ts:124,136`). Plugins
+ *      add arbitrary keys (`decorateRequest`) whose types the route author does not see.
+ *   3. **the jobs backend** — `ctx.queue` injected when `jobs.backend` is configured (`execute.ts:141-150`).
+ *
+ * A naive "infer `TCtx` from everything on `ctx`" would LIE — it cannot see writers (2) and (3), so
+ * `ctx.queue` / plugin keys would be typed as present when they are not (or vice-versa). That is the
+ * exact Hono/global-augmentation failure the blueprint refuted (§8.5). oRPC/tRPC avoid it only
+ * because middleware is their SOLE ctx writer; TheoKit is multi-writer.
+ *
+ * ## The reconciliation (what this contract locks)
+ *
+ * The typed `TCtx` a route handler sees reflects **only writer (1)** — the user `context.ts` factory
+ * (`ContextValue` below). Writers (2) and (3) are **explicitly untyped** on the route surface:
+ *
+ *   - `ctx.queue` (jobs) is reached through the dedicated {@link JobsAugmentedCtx} helper, NOT the
+ *     inferred `TCtx` — a handler that needs the queue opts into the augmented type explicitly.
+ *   - plugin-decorated keys are `unknown` by design (a plugin is a cross-cutting, per-app concern;
+ *     typing them into every route's `TCtx` would couple routes to plugin internals — G5).
+ *
+ * This keeps the LOCKED 5-arity `RouteConfig` generic (`route-config-generic-arity.test.ts`, GAP-4)
+ * intact — `TCtx` stays the single typed ctx slot; we only define WHICH writer it corresponds to,
+ * so `runtime ⊇ type` holds honestly (the type is a sound subset of the runtime ctx, never a lie).
+ *
+ * Type-tests proving this live in `tests/ctx-reconciliation.test-d.ts`.
+ */
+/**
+ * The typed run-context a route handler sees = the return of the user `context.ts` factory.
+ * `TValue` is inferred from that factory at the web adapter seam; it EXCLUDES plugin decorations and
+ * `ctx.queue` (those are not part of the author-declared shape).
+ */
+type ContextValue<TValue extends Record<string, unknown> = Record<string, unknown>> = TValue;
+/** The `ctx.queue` client shape injected by the jobs backend (writer 3). Reached explicitly. */
+interface QueueClientLike {
+    enqueue(name: string, input: unknown): void | Promise<void>;
+}
+/**
+ * Opt-in augmentation for handlers that read `ctx.queue`. A route that uses the jobs queue annotates
+ * its ctx as `JobsAugmentedCtx<MyCtx>` — making the jobs dependency explicit in the type, instead of
+ * silently assuming `ctx.queue` exists on every route (which would lie when `jobs.backend` is unset).
+ */
+type JobsAugmentedCtx<TValue extends Record<string, unknown> = Record<string, unknown>> = TValue & {
+    queue: QueueClientLike;
+};
+/**
+ * The three runtime ctx writers, named for documentation + the type-test. This is the reconciliation
+ * artifact the plan requires as a deliverable (not a footnote).
+ */
+declare const CTX_WRITERS: {
+    /** Writer 1 — user `context.ts` factory. THE typed surface (`TCtx`). execute.ts:131 */
+    readonly contextFactory: "context.ts";
+    /** Writer 2 — plugin `decorateRequest`. Untyped on the route surface. execute.ts:124,136 */
+    readonly pluginDecorations: "pluginRunner.applyDecorations";
+    /** Writer 3 — jobs backend `ctx.queue`. Reached via JobsAugmentedCtx, not TCtx. execute.ts:141-150 */
+    readonly jobsQueue: "jobBackend";
+};
+
 /**
  * Types for `loadEnv()` — env auto-load utility (Phase 1 of
  * docs/plans/framework-zero-config-polish-plan.md).
@@ -1156,4 +1317,4 @@ interface LoadEnvResult {
 declare function _resetEnvCache(): void;
 declare function loadEnv(options?: LoadEnvOptions): LoadEnvResult;
 
-export { type AcpToolConfig, ActionError, type ActionErrorCode, ActionInputError, type ActionManifestEntry, type ActionResult, type AppResource, type AppResourceInput, type BodyParserOptions, DEFAULT_MAX_AGE as CACHE_DEFAULT_MAX_AGE, DEFAULT_MAX_ENTRY_SIZE as CACHE_DEFAULT_MAX_ENTRY_SIZE, DEFAULT_SWR_MULTIPLIER as CACHE_DEFAULT_SWR_MULTIPLIER, CACHE_TAG_MAX_ITEMS, CACHE_TAG_MAX_LENGTH, type CacheControlInput, type CacheEngine, type CacheEngineOptions, type CacheEntry, type CacheStatus, type CacheStorageAdapter, type CacheStore, type CacheStoreAdmin, type ValidationResult as CacheValidationResult, type CachedFunction, type CachedRouteConfig, type ChannelMessage, type ChannelWebhookConfig, type CodeModeApi, type CodeModeConfig, type CodeModePermission, CodeModePermissionDeniedError, type CompiledRouteRule, CustomTool, DEFAULT_EXCLUDED_QUERY_PARAMS, type DefineCachedFunctionOptions, FileTooLargeError, type GetOrComputeOptions, InMemoryCacheAdapter, type InMemoryCacheAdapterOptions, type KeyDerivationOptions, type LoadEnvOptions, type LoadEnvResult, type McpResourceContents, type McpResourceDescriptor, NodeAcpTransport, type NormalizedCacheConfig, type OpenApiDocsOptions, type ParsedBody, type RevalidateResult, type RouteCacheOptions, RouteConfig, type RouteRule, type RouteRules, type Sandbox, type SerializedActionResult, type SerializedResponse, type StdioStreams, THEO_T_PREFIX, type UniversalZodIssue, type UploadedFile, type VendorAgentClient, type VendorAgentToolConfig, VerifyFn, type WorkflowLike, type WorkflowToolConfig, _resetCacheEngine, _resetEnvCache, buildResourceDescriptors, compileRouteRules, createACPTool, createCacheEngine, createCodeMode, createOpenApiHandler, createVendorAgentTool, createWorkflowTool, defineAppResource, defineCachedFunction, defineCachedRoute, deriveKey as deriveCacheKey, deserializeResponse, executeWebRequest, extractAppResources, extractUniversalIssues, getCacheControlHeader, getCacheEngine, handleChannelWebhook, handleMcpStdioLine, initCacheEngine, isActionError, isChannelPath, isInputError, loadEnv, parseChannelPath, parseRequestBody, readAppResource, resolveRouteRule, revalidatePath, revalidateTag, serializeResponse, serveMcpStdio, updateTag, validateExpire as validateCacheExpire, validateMaxAge as validateCacheMaxAge, validateTags as validateCacheTags };
+export { type AcpToolConfig, ActionError, type ActionErrorCode, ActionInputError, type ActionManifestEntry, type ActionResult, type AppResource, type AppResourceInput, type BodyParserOptions, DEFAULT_MAX_AGE as CACHE_DEFAULT_MAX_AGE, DEFAULT_MAX_ENTRY_SIZE as CACHE_DEFAULT_MAX_ENTRY_SIZE, DEFAULT_SWR_MULTIPLIER as CACHE_DEFAULT_SWR_MULTIPLIER, CACHE_TAG_MAX_ITEMS, CACHE_TAG_MAX_LENGTH, CTX_WRITERS, type CacheControlInput, type CacheEngine, type CacheEngineOptions, type CacheEntry, type CacheStatus, type CacheStorageAdapter, type CacheStore, type CacheStoreAdmin, type ValidationResult as CacheValidationResult, type CachedFunction, type CachedRouteConfig, type ChannelMessage, type ChannelWebhookConfig, type CodeModeApi, type CodeModeConfig, type CodeModePermission, CodeModePermissionDeniedError, type CompiledRouteRule, type ContextValue, CustomTool, DEFAULT_EXCLUDED_QUERY_PARAMS, type DefineCachedFunctionOptions, FileTooLargeError, type GetOrComputeOptions, InMemoryCacheAdapter, type InMemoryCacheAdapterOptions, type JobsAugmentedCtx, type KeyDerivationOptions, type LoadEnvOptions, type LoadEnvResult, type McpResourceContents, type McpResourceDescriptor, NodeAcpTransport, type NormalizedCacheConfig, type OpenApiDocsOptions, type ParsedBody, type ProcedureInput, ProcedureInputError, ProcedureOutputError, type QueueClientLike, type RawRouteInput, type RevalidateResult, type RouteCacheOptions, RouteConfig, type RouteInputChannel, type RouteInputSchemas, type RouteInputValidation, type RouteRule, type RouteRules, type Sandbox, type SerializedActionResult, type SerializedResponse, type StdioStreams, THEO_T_PREFIX, type UniversalZodIssue, type UploadedFile, type VendorAgentClient, type VendorAgentToolConfig, VerifyFn, type WorkflowLike, type WorkflowToolConfig, _resetCacheEngine, _resetEnvCache, buildResourceDescriptors, callProcedure, compileRouteRules, createACPTool, createCacheEngine, createCodeMode, createOpenApiHandler, createVendorAgentTool, createWorkflowTool, defineAppResource, defineCachedFunction, defineCachedRoute, deriveKey as deriveCacheKey, deserializeResponse, executeWebRequest, extractAppResources, extractUniversalIssues, getCacheControlHeader, getCacheEngine, handleChannelWebhook, handleMcpStdioLine, initCacheEngine, isActionError, isChannelPath, isInputError, loadEnv, parseChannelPath, parseRequestBody, readAppResource, resolveRouteRule, revalidatePath, revalidateTag, serializeResponse, serveMcpStdio, updateTag, validateExpire as validateCacheExpire, validateMaxAge as validateCacheMaxAge, validateTags as validateCacheTags, validateRouteInput };

package/dist/server/index.js

@@ -59,8 +59,9 @@ import {
   loadEnv,
   readAppResource,
   resolveTransformer,
-  superjsonTransformer
-} from "../chunk-W4YO6S4I.js";
+  superjsonTransformer,
+  validateRouteInput
+} from "../chunk-W4XWVTN4.js";
 import {
   findSuggestion,
   levenshtein
@@ -1328,7 +1329,7 @@ async function handleMcpStdioLine(line, mod, name, appResources = []) {
       error: { code: -32700, message: "Parse error" }
     });
   }
-  const response = handleMcpJsonRpc(mod, name, body, appResources);
+  const response = await handleMcpJsonRpc(mod, name, body, appResources);
   const payload = await response.json();
   return JSON.stringify(payload);
 }
@@ -1349,6 +1350,57 @@ function deserializeResponse(serialized) {
   return superjson.deserialize(serialized);
 }
 
+// src/server/http/in-process-caller.ts
+var ProcedureInputError = class extends Error {
+  channel;
+  issues;
+  constructor(channel, error) {
+    super(`Invalid ${channel} for in-process procedure call: ${error.message}`);
+    this.name = "ProcedureInputError";
+    this.channel = channel;
+    this.issues = error.issues;
+  }
+};
+var ProcedureOutputError = class extends Error {
+  issues;
+  constructor(error) {
+    super(`In-process procedure output failed its response schema: ${error.message}`);
+    this.name = "ProcedureOutputError";
+    this.issues = error.issues;
+  }
+};
+function inProcessRequest() {
+  return new Request("theo://in-process/procedure", { method: "POST" });
+}
+async function callProcedure(config, input = {}, ctx) {
+  const validated = validateRouteInput(config, input);
+  if (!validated.ok) throw new ProcedureInputError(validated.channel, validated.error);
+  const result = await config.handler({
+    query: validated.query,
+    body: validated.body,
+    params: validated.params,
+    request: inProcessRequest(),
+    ctx
+  });
+  const responseSchema = config.response;
+  if (responseSchema !== void 0 && !(result instanceof Response)) {
+    const parsed = responseSchema.safeParse(result);
+    if (!parsed.success) throw new ProcedureOutputError(parsed.error);
+    return parsed.data;
+  }
+  return result;
+}
+
+// src/server/http/ctx-reconciliation.ts
+var CTX_WRITERS = {
+  /** Writer 1 — user `context.ts` factory. THE typed surface (`TCtx`). execute.ts:131 */
+  contextFactory: "context.ts",
+  /** Writer 2 — plugin `decorateRequest`. Untyped on the route surface. execute.ts:124,136 */
+  pluginDecorations: "pluginRunner.applyDecorations",
+  /** Writer 3 — jobs backend `ctx.queue`. Reached via JobsAugmentedCtx, not TCtx. execute.ts:141-150 */
+  jobsQueue: "jobBackend"
+};
+
 // src/server/index.ts
 if (typeof globalThis !== "undefined") {
   const WARN_KEY = "__theokit_server_umbrella_warn_emitted__";
@@ -1379,6 +1431,7 @@ export {
   CSRF_READINESS_RESET_PATH,
   CSRF_WARN_CODE,
   CSRF_WARN_DOCS_URL,
+  CTX_WRITERS,
   ChannelManager,
   CodeModePermissionDeniedError,
   ConsoleObservabilityAdapter,
@@ -1410,6 +1463,8 @@ export {
   NotFoundError,
   PluginRunner,
   PostgresJobBackend,
+  ProcedureInputError,
+  ProcedureOutputError,
   READY_PATH,
   STRIPPED_HEADERS,
   SpanImpl,
@@ -1434,6 +1489,7 @@ export {
   buildJobManifest,
   buildResourceDescriptors,
   buildSecurityHeaders,
+  callProcedure,
   checkThrottle,
   clearOidcCache,
   compilePattern,
@@ -1590,6 +1646,7 @@ export {
   validateCronSchedule,
   validateCsrf,
   validateCsrfRequest,
+  validateRouteInput,
   verifyBackupCode,
   verifyOAuthState,
   verifyTotp,