theokit 0.21.0 → 0.22.0

package/dist/{chunk-DMC6HYUR.js → chunk-VS6LJM2V.js}

@@ -27,12 +27,18 @@ function extractAppResources(mod) {
 }
 
 // src/server/agent/mcp-handler.ts
-import {
-  buildMcpToolDescriptors,
-  compileAgentModule,
-  mcpServerInfo
-} from "@theokit/agents";
+import { compileAgentModule } from "@theokit/agents";
 var MCP_PATH = /^\/api\/agents\/([^/]+)\/mcp$/;
+var MCP_PROTOCOL_VERSION = "2025-06-18";
+function toolDescriptors(tools) {
+  return tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    // The compiled tool already carries a JSON Schema (via `z.toJSONSchema()` in defineAgentTool).
+    // Fall back to a permissive object only when a tool genuinely declared no schema.
+    inputSchema: t.inputSchema && typeof t.inputSchema === "object" ? t.inputSchema : { type: "object", properties: {} }
+  }));
+}
 function isMcpPath(urlPath) {
   const match = MCP_PATH.exec(urlPath);
   return match ? decodeURIComponent(match[1]) : null;
@@ -46,26 +52,50 @@ function jsonResponse(payload) {
     headers: { "content-type": "application/json; charset=utf-8" }
   });
 }
-function toEntry(name, mod) {
-  const compiled = compileAgentModule(mod, `mcp server for "${name}"`);
-  return {
-    name,
-    route: `/api/agents/${name}`,
-    stream: compiled.stream,
-    mainLoop: { method: "", strategy: "" },
-    guards: [],
-    interceptors: [],
-    tools: compiled.tools.map((t) => ({
-      name: t.name,
-      description: t.description,
-      approval: false,
-      trace: false,
-      audit: false
-    })),
-    subAgents: []
-  };
+async function callTool(tools, toolName, args) {
+  if (typeof toolName !== "string") {
+    return {
+      content: [{ type: "text", text: "tools/call requires a string `name`." }],
+      isError: true
+    };
+  }
+  const tool = tools.find((t) => t.name === toolName);
+  if (!tool) {
+    return { content: [{ type: "text", text: `Unknown tool: ${toolName}` }], isError: true };
+  }
+  try {
+    const result = await tool.handler(args);
+    const text = typeof result === "string" ? result : JSON.stringify(result);
+    return { content: [{ type: "text", text }] };
+  } catch (err) {
+    return {
+      content: [
+        { type: "text", text: err instanceof Error ? err.message : "Tool execution failed" }
+      ],
+      isError: true
+    };
+  }
 }
-function handleMcpJsonRpc(mod, name, body, appResources = []) {
+function handleResourcesRead(id, params, appResources) {
+  const uri = params?.uri;
+  if (typeof uri !== "string") {
+    return jsonResponse({
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32602, message: "resources/read requires a string `uri` param." }
+    });
+  }
+  const contents = readAppResource(appResources, uri);
+  if (contents === null) {
+    return jsonResponse({
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32602, message: `Resource not found: ${uri}` }
+    });
+  }
+  return jsonResponse({ jsonrpc: "2.0", id, result: contents });
+}
+async function handleMcpJsonRpc(mod, name, body, appResources = []) {
   if (!isJsonRpcRequest(body)) {
     return jsonResponse({
       jsonrpc: "2.0",
@@ -75,23 +105,31 @@ function handleMcpJsonRpc(mod, name, body, appResources = []) {
   }
   const { id, method, params } = body;
   try {
-    const entry = toEntry(name, mod);
+    const compiled = compileAgentModule(mod, `mcp server for "${name}"`);
     if (method === "initialize") {
-      const info = mcpServerInfo(entry);
       const capabilities = { tools: {} };
       if (appResources.length > 0) capabilities.resources = {};
       return jsonResponse({
         jsonrpc: "2.0",
         id,
         result: {
-          protocolVersion: info.protocolVersion,
+          protocolVersion: MCP_PROTOCOL_VERSION,
           capabilities,
-          serverInfo: { name: info.name, version: info.version }
+          serverInfo: { name, version: "1.0" }
         }
       });
     }
     if (method === "tools/list") {
-      return jsonResponse({ jsonrpc: "2.0", id, result: { tools: buildMcpToolDescriptors(entry) } });
+      return jsonResponse({
+        jsonrpc: "2.0",
+        id,
+        result: { tools: toolDescriptors(compiled.tools) }
+      });
+    }
+    if (method === "tools/call") {
+      const p = params;
+      const result = await callTool(compiled.tools, p?.name, p?.arguments ?? {});
+      return jsonResponse({ jsonrpc: "2.0", id, result });
     }
     if (method === "resources/list") {
       return jsonResponse({
@@ -101,23 +139,7 @@ function handleMcpJsonRpc(mod, name, body, appResources = []) {
       });
     }
     if (method === "resources/read") {
-      const uri = params?.uri;
-      if (typeof uri !== "string") {
-        return jsonResponse({
-          jsonrpc: "2.0",
-          id,
-          error: { code: -32602, message: "resources/read requires a string `uri` param." }
-        });
-      }
-      const contents = readAppResource(appResources, uri);
-      if (contents === null) {
-        return jsonResponse({
-          jsonrpc: "2.0",
-          id,
-          error: { code: -32602, message: `Resource not found: ${uri}` }
-        });
-      }
-      return jsonResponse({ jsonrpc: "2.0", id, result: contents });
+      return handleResourcesRead(id, params, appResources);
     }
     return jsonResponse({
       jsonrpc: "2.0",
@@ -138,4 +160,4 @@ export {
   isMcpPath,
   handleMcpJsonRpc
 };
-//# sourceMappingURL=chunk-DMC6HYUR.js.map
+//# sourceMappingURL=chunk-VS6LJM2V.js.map

package/dist/chunk-VS6LJM2V.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/agent/mcp-app-resources.ts","../src/server/agent/mcp-handler.ts"],"sourcesContent":["/**\n * M30 (ADR-0041) — MCP Apps: `ui://` HTML resources for the MCP server (M16).\n *\n * A tool can declare a `ui://` HTML resource; the MCP server advertises it via `resources/list` and\n * serves the HTML via `resources/read`. The client renders it in a SANDBOXED iframe (see\n * `mcp-app-host.ts`). Pure data transforms here — no LLM, no runtime (ADR-0040 § D2 home concern).\n *\n * Security: only the `ui://` scheme is accepted (an app UI resource), never `http(s)://` — the HTML\n * is rendered sandboxed on the client, and the scheme gate keeps a tool from smuggling a remote URL\n * into the app surface.\n */\n\n/** A declared `ui://` app resource. */\nexport interface AppResource {\n  uri: string\n  name: string\n  mimeType: 'text/html'\n  html: string\n  description?: string\n}\n\n/** Input to {@link defineAppResource}. */\nexport interface AppResourceInput {\n  /** MUST start with `ui://`. */\n  uri: string\n  name: string\n  html: string\n  description?: string\n}\n\n/** An MCP `resources/list` descriptor (no HTML body — that comes from `resources/read`). */\nexport interface McpResourceDescriptor {\n  uri: string\n  name: string\n  mimeType: 'text/html'\n  description?: string\n}\n\n/** An MCP `resources/read` result. */\nexport interface McpResourceContents {\n  contents: { uri: string; mimeType: 'text/html'; text: string }[]\n}\n\n/**\n * Declare a `ui://` HTML app resource. Fails fast if the uri is not a `ui://` scheme or the HTML is\n * empty (error-handling.md) — a misconfigured resource is caught at definition time.\n */\nexport function defineAppResource(input: AppResourceInput): AppResource {\n  if (!input.uri.startsWith('ui://')) {\n    throw new Error(\n      `defineAppResource: uri must use the ui:// scheme (an app UI resource). Got: ${JSON.stringify(input.uri)}`,\n    )\n  }\n  if (input.html.length === 0) {\n    throw new Error(`defineAppResource(${JSON.stringify(input.uri)}): html must be non-empty.`)\n  }\n  return {\n    uri: input.uri,\n    name: input.name,\n    mimeType: 'text/html',\n    html: input.html,\n    ...(input.description !== undefined ? { description: input.description } : {}),\n  }\n}\n\n/** Map app resources to MCP `resources/list` descriptors (the HTML body is omitted from the list). */\nexport function buildResourceDescriptors(\n  resources: readonly AppResource[],\n): McpResourceDescriptor[] {\n  return resources.map((r) => ({\n    uri: r.uri,\n    name: r.name,\n    mimeType: r.mimeType,\n    ...(r.description !== undefined ? { description: r.description } : {}),\n  }))\n}\n\n/** Serve the HTML for `uri` as an MCP `resources/read` result, or `null` when unknown. */\nexport function readAppResource(\n  resources: readonly AppResource[],\n  uri: string,\n): McpResourceContents | null {\n  const found = resources.find((r) => r.uri === uri)\n  if (!found) return null\n  return { contents: [{ uri: found.uri, mimeType: 'text/html', text: found.html }] }\n}\n\n/** True when `v` is a well-formed {@link AppResource} (from `defineAppResource`). */\nfunction isAppResource(v: unknown): v is AppResource {\n  if (typeof v !== 'object' || v === null) return false\n  const r = v as Record<string, unknown>\n  return (\n    typeof r.uri === 'string' &&\n    r.uri.startsWith('ui://') &&\n    r.mimeType === 'text/html' &&\n    typeof r.html === 'string'\n  )\n}\n\n/**\n * M30 wiring — extract the App resources an agent module declares via a named `appResources` export\n * (`export const appResources = [defineAppResource(...)]`). Returns only the well-formed entries; a\n * module without the export (or with a malformed one) yields `[]`. This is how per-agent `ui://`\n * resources reach the MCP server's `resources/list` + `resources/read` without a runtime dependency\n * from `@theokit/agents` on this theo-side type (the module exports them; the serving path reads them).\n */\nexport function extractAppResources(mod: unknown): AppResource[] {\n  const raw = (mod as { appResources?: unknown } | null | undefined)?.appResources\n  if (!Array.isArray(raw)) return []\n  return raw.filter(isAppResource)\n}\n","/**\n * M16 (theokit-ai-first) — serve an agent as an MCP server over HTTP at `/api/agents/<name>/mcp`.\n *\n * Answers the two core MCP methods over JSON-RPC 2.0: `initialize` (server info + capabilities) and\n * `tools/list` (the agent's tools as MCP descriptors, via `buildMcpToolDescriptors`). M30 adds\n * `resources/list` + `resources/read` for `ui://` App resources. Unknown methods return `-32601`\n * (method not found). Web Standards Response (G8). The stdio transport + full method set stay\n * SDK-side (sdk-runtime.md); this exposes the agent over the app's own HTTP route.\n */\nimport { type CompiledTool, compileAgentModule } from '@theokit/agents'\n\nimport { type AppResource, buildResourceDescriptors, readAppResource } from './mcp-app-resources.js'\n\nconst MCP_PATH = /^\\/api\\/agents\\/([^/]+)\\/mcp$/\n\n/**\n * The MCP protocol revision THIS server transport implements (M34). The protocol version is a\n * property of the server that speaks it (this handler), not of the manifest data generator — so the\n * handler owns it. Current MCP revision (`2025-06-18`); replaces the stale `2024-11-05` the manifest\n * generator carried.\n */\nconst MCP_PROTOCOL_VERSION = '2025-06-18'\n\n/** An MCP `tools/list` descriptor with the tool's REAL input schema retained (M34 — no longer dropped). */\ninterface McpToolDescriptor {\n  name: string\n  description: string\n  inputSchema: Record<string, unknown>\n}\n\n/** Build tool descriptors from the compiled tools, retaining each tool's real JSON-Schema input (M34). */\nfunction toolDescriptors(tools: readonly CompiledTool[]): McpToolDescriptor[] {\n  return tools.map((t) => ({\n    name: t.name,\n    description: t.description,\n    // The compiled tool already carries a JSON Schema (via `z.toJSONSchema()` in defineAgentTool).\n    // Fall back to a permissive object only when a tool genuinely declared no schema.\n    inputSchema:\n      t.inputSchema && typeof t.inputSchema === 'object'\n        ? (t.inputSchema as Record<string, unknown>)\n        : { type: 'object', properties: {} },\n  }))\n}\n\n/** An MCP `CallToolResult` — `content[]` + `isError` (the shape MCP clients expect). */\ninterface CallToolResult {\n  content: { type: 'text'; text: string }[]\n  isError?: boolean\n}\n\n/** Return the agent name when `urlPath` is the MCP endpoint, else `null`. */\nexport function isMcpPath(urlPath: string): string | null {\n  const match = MCP_PATH.exec(urlPath)\n  return match ? decodeURIComponent(match[1]) : null\n}\n\ninterface JsonRpcRequest {\n  jsonrpc: '2.0'\n  id: number | string | null\n  method: string\n  params?: unknown\n}\n\nfunction isJsonRpcRequest(body: unknown): body is JsonRpcRequest {\n  return (\n    typeof body === 'object' &&\n    body !== null &&\n    (body as { jsonrpc?: unknown }).jsonrpc === '2.0' &&\n    typeof (body as { method?: unknown }).method === 'string'\n  )\n}\n\nfunction jsonResponse(payload: unknown): Response {\n  return new Response(JSON.stringify(payload), {\n    status: 200,\n    headers: { 'content-type': 'application/json; charset=utf-8' },\n  })\n}\n\n/**\n * Execute an MCP `tools/call` against the compiled tools (M34). Finds the tool by name, runs its\n * handler with the supplied `arguments`, and shapes the result into a `CallToolResult`. An unknown\n * tool or a throwing handler yields `{ isError: true }` (MCP convention — the model sees the failure)\n * rather than a JSON-RPC crash.\n */\nasync function callTool(\n  tools: readonly CompiledTool[],\n  toolName: unknown,\n  args: unknown,\n): Promise<CallToolResult> {\n  if (typeof toolName !== 'string') {\n    return {\n      content: [{ type: 'text', text: 'tools/call requires a string `name`.' }],\n      isError: true,\n    }\n  }\n  const tool = tools.find((t) => t.name === toolName)\n  if (!tool) {\n    return { content: [{ type: 'text', text: `Unknown tool: ${toolName}` }], isError: true }\n  }\n  try {\n    const result = await tool.handler(args)\n    const text = typeof result === 'string' ? result : JSON.stringify(result)\n    return { content: [{ type: 'text', text }] }\n  } catch (err) {\n    return {\n      content: [\n        { type: 'text', text: err instanceof Error ? err.message : 'Tool execution failed' },\n      ],\n      isError: true,\n    }\n  }\n}\n\n/** `resources/read` (M30) — extracted to keep `handleMcpJsonRpc` within the complexity budget. */\nfunction handleResourcesRead(\n  id: number | string | null,\n  params: unknown,\n  appResources: readonly AppResource[],\n): Response {\n  const uri = (params as { uri?: unknown } | undefined)?.uri\n  if (typeof uri !== 'string') {\n    return jsonResponse({\n      jsonrpc: '2.0',\n      id,\n      error: { code: -32602, message: 'resources/read requires a string `uri` param.' },\n    })\n  }\n  const contents = readAppResource(appResources, uri)\n  if (contents === null) {\n    return jsonResponse({\n      jsonrpc: '2.0',\n      id,\n      error: { code: -32602, message: `Resource not found: ${uri}` },\n    })\n  }\n  return jsonResponse({ jsonrpc: '2.0', id, result: contents })\n}\n\n/**\n * Handle one MCP JSON-RPC request for an agent module. Always returns a 200 JSON-RPC envelope.\n *\n * M30 — `appResources` (optional) are the agent's declared `ui://` App resources; when present the\n * server advertises `capabilities.resources` and answers `resources/list` + `resources/read`.\n */\nexport async function handleMcpJsonRpc(\n  mod: unknown,\n  name: string,\n  body: unknown,\n  appResources: readonly AppResource[] = [],\n): Promise<Response> {\n  if (!isJsonRpcRequest(body)) {\n    return jsonResponse({\n      jsonrpc: '2.0',\n      id: null,\n      error: { code: -32600, message: 'Invalid Request' },\n    })\n  }\n  const { id, method, params } = body\n  try {\n    const compiled = compileAgentModule(mod, `mcp server for \"${name}\"`)\n    if (method === 'initialize') {\n      const capabilities: Record<string, unknown> = { tools: {} }\n      if (appResources.length > 0) capabilities.resources = {}\n      return jsonResponse({\n        jsonrpc: '2.0',\n        id,\n        result: {\n          protocolVersion: MCP_PROTOCOL_VERSION,\n          capabilities,\n          serverInfo: { name, version: '1.0' },\n        },\n      })\n    }\n    if (method === 'tools/list') {\n      return jsonResponse({\n        jsonrpc: '2.0',\n        id,\n        result: { tools: toolDescriptors(compiled.tools) },\n      })\n    }\n    if (method === 'tools/call') {\n      const p = params as { name?: unknown; arguments?: unknown } | undefined\n      const result = await callTool(compiled.tools, p?.name, p?.arguments ?? {})\n      return jsonResponse({ jsonrpc: '2.0', id, result })\n    }\n    if (method === 'resources/list') {\n      return jsonResponse({\n        jsonrpc: '2.0',\n        id,\n        result: { resources: buildResourceDescriptors(appResources) },\n      })\n    }\n    if (method === 'resources/read') {\n      return handleResourcesRead(id, params, appResources)\n    }\n    return jsonResponse({\n      jsonrpc: '2.0',\n      id,\n      error: { code: -32601, message: `Method not found: ${method}` },\n    })\n  } catch (err) {\n    return jsonResponse({\n      jsonrpc: '2.0',\n      id,\n      error: { code: -32603, message: err instanceof Error ? err.message : 'Internal error' },\n    })\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/cli/index.js

@@ -5,12 +5,12 @@ import "tsx/esm";
 import cac from "cac";
 var cli = cac("theokit");
 cli.command("dev", "Start development server").option("--port <port>", "Port number").action(async (options) => {
-  const { devCommand } = await import("../dev-NHHTXOA4.js");
+  const { devCommand } = await import("../dev-7AW7FBNH.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-TBV4KVXI.js");
+    const { buildCommand } = await import("../build-2JDQBBWN.js");
     await buildCommand({ target: options.target });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -22,7 +22,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-ILT6E25Q.js");
+    const { startCommand } = await import("../start-4VHDT4TN.js");
     await startCommand({ port: options.port ? Number(options.port) : void 0 });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -52,7 +52,7 @@ cli.command(
   "Run an agent in the terminal (stream + tool calls + approval)"
 ).action(async (name, message) => {
   try {
-    const { agentCommand } = await import("../agent-76WK2CZJ.js");
+    const { agentCommand } = await import("../agent-GXPTQTCU.js");
     const { sawError } = await agentCommand(name, message);
     if (sawError) process.exit(1);
   } catch (err) {
@@ -65,7 +65,7 @@ cli.command(
 });
 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-HP5RVOOZ.js");
+    const { mcpCommand } = await import("../mcp-MOKIIMJ6.js");
     await mcpCommand(agent);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);

package/dist/{dev-NHHTXOA4.js → dev-7AW7FBNH.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-D7D6V6FN.js";
+import "./chunk-4QXVTX3X.js";
+import "./chunk-VS6LJM2V.js";
 import "./chunk-M6NMS5LR.js";
 import "./chunk-IEES3CHD.js";
 import {
@@ -111,4 +111,4 @@ export {
   devCommand,
   startDevServer
 };
-//# sourceMappingURL=dev-NHHTXOA4.js.map
+//# sourceMappingURL=dev-7AW7FBNH.js.map

package/dist/index.js

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

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

@@ -2,11 +2,11 @@
 import "tsx/esm";
 import {
   createAgentSsrLoader
-} from "./chunk-23T4CO4M.js";
+} from "./chunk-JRYP7KNS.js";
 import {
   extractAppResources,
   handleMcpJsonRpc
-} from "./chunk-DMC6HYUR.js";
+} from "./chunk-VS6LJM2V.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-MOKIIMJ6.js.map

package/dist/{mcp-HP5RVOOZ.js.map → mcp-MOKIIMJ6.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-FO2KMFAE.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,