theokit 0.15.2 → 0.17.0

package/dist/chunk-4JDYVNSY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/transformer.ts","../src/server/agent/approve-agent.ts","../src/server/agent/mount-agent.ts","../src/server/define/ui-message-stream-response.ts","../src/server/http/node-web-adapter.ts"],"sourcesContent":["import superjson from 'superjson'\n\n/**\n * T5.2 — pluggable response/request transformer.\n *\n * `superjson` is the default, preserving Date/Map/Set/BigInt/etc.\n * `json` is the lightweight option (plain JSON.stringify/parse).\n * Users can supply a custom object implementing this contract.\n */\nexport interface TheoTransformer {\n  name: string\n  serialize: (value: unknown) => string\n  deserialize: (raw: string) => unknown\n}\n\nexport const superjsonTransformer: TheoTransformer = {\n  name: 'superjson',\n  serialize: (v) => JSON.stringify(superjson.serialize(v)),\n  deserialize: (raw) => {\n    const parsed = JSON.parse(raw) as Parameters<typeof superjson.deserialize>[0]\n    return superjson.deserialize(parsed)\n  },\n}\n\nexport const jsonTransformer: TheoTransformer = {\n  name: 'json',\n  serialize: (v) => JSON.stringify(v),\n  deserialize: (raw) => JSON.parse(raw) as unknown,\n}\n\nconst BUILT_INS: Record<string, TheoTransformer> = {\n  superjson: superjsonTransformer,\n  json: jsonTransformer,\n}\n\nexport function resolveTransformer(\n  selector: 'json' | 'superjson' | TheoTransformer,\n): TheoTransformer {\n  if (typeof selector === 'string') {\n    // selector is 'json' | 'superjson' literal — both keys exist in\n    // BUILT_INS by construction. Type system guarantees a hit; we keep\n    // a defensive fallback that the compiler cannot see is unreachable\n    // at runtime, just in case someone adds a new literal to the union\n    // but forgets to register the built-in.\n    const built = BUILT_INS[selector]\n    // Defensive: the public union ensures `built` is defined, but if a\n    // future contributor extends the union without registering the impl,\n    // the cast keeps the failure mode loud.\n    if ((built as TheoTransformer | undefined) === undefined) {\n      throw new Error(\n        `Unknown transformer \"${selector}\". Built-in options: ${Object.keys(BUILT_INS).join(', ')}.`,\n      )\n    }\n    return built\n  }\n  if (\n    typeof selector !== 'object' ||\n    typeof selector.serialize !== 'function' ||\n    typeof selector.deserialize !== 'function'\n  ) {\n    throw new Error(\n      `Custom transformer must have serialize and deserialize functions. Got: ${JSON.stringify(selector)}`,\n    )\n  }\n  return selector\n}\n","/**\n * M4 (theokit-ai-first) — the HITL approve endpoint: `POST /api/agents/<name>/approve/<approvalId>`.\n *\n * The counterpart to `mountAgent`'s HITL pause. While a gated tool holds the SDK run paused (the\n * awaited `pre_tool_call` hook), the client POSTs here with `{ approved }`; this resolves the\n * pending approval in the shared registry, which un-pauses the run (allow) or vetoes the tool (deny).\n *\n * Web-Standard `Request` → `Response`, one wiring point shared by dev (vite middleware) and prod\n * (built server) so the two never drift (EC-4 parity with `mountAgent`). The registry is INJECTED —\n * dev/prod pass the process singleton (`getApprovalRegistry`), tests pass a fresh instance.\n */\nimport { validateCsrfRequest, type CsrfMode } from '../security/csrf.js'\n\nimport type { ApprovalDecision, ApprovalRegistry } from './approval-registry.js'\n\n/** The path segment separating the agent name from the approval id. */\nconst APPROVE_SEGMENT = '/approve/'\n\n/**\n * Extract the `<approvalId>` from a `/api/agents/<name>/approve/<approvalId>` path.\n * Returns `null` when the path has no `/approve/` segment or an empty / nested id.\n */\nexport function parseApprovalId(urlPath: string): string | null {\n  const at = urlPath.indexOf(APPROVE_SEGMENT)\n  if (at === -1) return null\n  const id = urlPath.slice(at + APPROVE_SEGMENT.length)\n  return id.length > 0 && !id.includes('/') ? id : null\n}\n\n/** True when `urlPath` targets a HITL approve endpoint (used by dev/prod routing to branch early). */\nexport function isApprovalPath(urlPath: string): boolean {\n  return urlPath.includes(APPROVE_SEGMENT)\n}\n\nfunction jsonError(status: number, code: string, message: string): Response {\n  return new Response(JSON.stringify({ error: { code, message } }), {\n    status,\n    headers: { 'content-type': 'application/json' },\n  })\n}\n\n/**\n * M20 — cap on the serialized custom payload (16 KiB). A payload is a small structured note\n * (edited args, a reviewer comment), not a data channel — an oversized one is rejected fail-fast\n * rather than silently truncated (Rule 8).\n */\nconst MAX_PAYLOAD_BYTES = 16 * 1024\n\n/**\n * Extract an {@link ApprovalDecision} from an untrusted body; `null` when the shape is wrong.\n *\n * M20 — accepts an optional `reason` (string) and `payload` (object, capped at\n * {@link MAX_PAYLOAD_BYTES}). Backward-compatible: `{ approved }` and `{ approved, reason }` parse\n * unchanged. A non-object or oversized `payload` is rejected (returns `null` → the route 400s).\n *\n * @public\n */\nexport function parseApprovalBody(body: unknown): ApprovalDecision | null {\n  if (typeof body !== 'object' || body === null) return null\n  const b = body as Record<string, unknown>\n  if (typeof b.approved !== 'boolean') return null\n  const decision: ApprovalDecision = { approved: b.approved }\n  if (b.reason !== undefined) {\n    if (typeof b.reason !== 'string') return null\n    decision.reason = b.reason\n  }\n  if (b.payload !== undefined) {\n    if (typeof b.payload !== 'object' || b.payload === null || Array.isArray(b.payload)) return null\n    if (JSON.stringify(b.payload).length > MAX_PAYLOAD_BYTES) return null\n    decision.payload = b.payload\n  }\n  return decision\n}\n\n/**\n * Resolve a pending HITL approval. CSRF-guarded like `mountAgent` (the custom `X-Theo-Action`\n * header + Origin match) — a cross-origin POST must not approve a paused tool. Returns:\n *   403 CSRF_FAILED  — strict CSRF check failed\n *   400 BAD_REQUEST  — no `/approve/<id>` in the path, or body lacks a boolean `approved`\n *   404 NOT_PENDING  — the id is unknown or already settled (idempotent double-submit)\n *   200 { resolved:true } — the approval was settled by this call\n */\nexport async function handleAgentApproval(\n  request: Request,\n  urlPath: string,\n  registry: ApprovalRegistry,\n  csrfMode: CsrfMode = 'strict',\n): Promise<Response> {\n  if (csrfMode !== 'off') {\n    const csrf = validateCsrfRequest(request)\n    if (!csrf.valid && csrfMode === 'strict') {\n      return jsonError(403, 'CSRF_FAILED', `CSRF check failed: ${csrf.reason}`)\n    }\n  }\n\n  const approvalId = parseApprovalId(urlPath)\n  if (approvalId === null) {\n    return jsonError(400, 'BAD_REQUEST', 'Approval path must be /api/agents/<name>/approve/<id>.')\n  }\n\n  let body: unknown = null\n  try {\n    body = await request.json()\n  } catch {\n    /* invalid/empty JSON → handled below as a 400 */\n  }\n  const parsed = parseApprovalBody(body)\n  if (parsed === null) {\n    return jsonError(400, 'BAD_REQUEST', 'Request body must contain a boolean `approved`.')\n  }\n\n  const resolved = registry.resolve(approvalId, parsed)\n  if (!resolved) {\n    return jsonError(404, 'NOT_PENDING', `No pending approval for id '${approvalId}'.`)\n  }\n  return new Response(JSON.stringify({ resolved: true }), {\n    status: 200,\n    headers: { 'content-type': 'application/json' },\n  })\n}\n","/**\n * M2 (theokit-ai-first) — mount a scanned `agents/<name>.ts` module as an SSE endpoint.\n *\n * The SINGLE wiring point shared by dev (vite middleware) and prod (built server), so the\n * two never drift (EC-4). Web-Standard `Request` → `Response`: parse the chat body, compile\n * the module (`compileAgentModule`, converges both surfaces), stream via the M0/M1 canonical\n * protocol (`streamAgentUIMessages` → `uiMessageStreamResponse`).\n *\n * Request body — accepts the `@ai-sdk/react` `useChat` shape (`{ id, messages: UIMessage[] }`,\n * the typed-client path) AND a simple `{ message, sessionId? }` shape (M0/M1-style clients).\n */\nimport {\n  compileAgentModule,\n  resolveEnabledSkills,\n  streamAgentUIMessages,\n  type HumanInTheLoopOptions,\n} from '@theokit/agents'\n\nimport { uiMessageStreamResponse } from '../define/ui-message-stream-response.js'\nimport { validateCsrfRequest, type CsrfMode } from '../security/csrf.js'\n\nimport { getApprovalRegistry } from './approval-registry.js'\n\n/** The message + session extracted from a chat request, or `null` when the body is invalid. */\nexport interface AgentRequestInput {\n  message: string\n  sessionId: string\n}\n\n/** Extract the text of a `{ type: 'text', text: string }` part from an untrusted value. */\nfunction partText(part: unknown): string {\n  if (typeof part !== 'object' || part === null) return ''\n  const p = part as Record<string, unknown>\n  return p.type === 'text' && typeof p.text === 'string' ? p.text : ''\n}\n\nfunction jsonError(status: number, code: string, message: string): Response {\n  return new Response(JSON.stringify({ error: { code, message } }), {\n    status,\n    headers: { 'content-type': 'application/json' },\n  })\n}\n\n/**\n * Extract `{ message, sessionId }` from a chat request body. Returns `null` when neither the\n * ai-sdk `messages` shape nor the simple `message` shape yields non-empty user text.\n */\nexport function parseAgentRequestBody(body: unknown): AgentRequestInput | null {\n  if (typeof body !== 'object' || body === null) return null\n  const b = body as Record<string, unknown>\n\n  // ai-sdk useChat shape: { id, messages: UIMessage[] } — take the last message's text parts.\n  if (Array.isArray(b.messages) && b.messages.length > 0) {\n    const last = b.messages[b.messages.length - 1] as Record<string, unknown>\n    const parts = Array.isArray(last.parts) ? last.parts : []\n    const text = parts.map(partText).join('')\n    if (text.length === 0) return null\n    const sessionId = typeof b.id === 'string' && b.id.length > 0 ? b.id : crypto.randomUUID()\n    return { message: text, sessionId }\n  }\n\n  // Simple shape: { message, sessionId? }.\n  if (typeof b.message === 'string' && b.message.length > 0) {\n    const sessionId =\n      typeof b.sessionId === 'string' && b.sessionId.length > 0 ? b.sessionId : crypto.randomUUID()\n    return { message: b.message, sessionId }\n  }\n\n  return null\n}\n\n/**\n * Mount a loaded agent module as a `Response`. `apiKey` is resolved by the caller\n * (`resolveProvider`). `source` labels a fail-fast `AgentDefinitionError` (the file path).\n */\nexport async function mountAgent(\n  mod: unknown,\n  request: Request,\n  apiKey: string,\n  source = 'agent module',\n  csrfMode: CsrfMode = 'strict',\n): Promise<Response> {\n  // Enforce CSRF BEFORE any work — an agent run spends real LLM tokens, so a cross-origin\n  // POST must be rejected before it reaches the SDK (parity with actions/routes). The custom\n  // `X-Theo-Action` header + Origin match is the same defense `executeRoute`/`executeAction`\n  // apply; the `useAgent` client sends the header. `off` skips; `warn` never blocks.\n  if (csrfMode !== 'off') {\n    const csrf = validateCsrfRequest(request)\n    if (!csrf.valid && csrfMode === 'strict') {\n      return jsonError(403, 'CSRF_FAILED', `CSRF check failed: ${csrf.reason}`)\n    }\n  }\n\n  const compiled = compileAgentModule(mod, source)\n\n  // M13 — resolve a per-request skills selector (from `defineAgent({ skills: (ctx) => [...] })`)\n  // against the M7 run-context, setting `skills.enabled` before the SDK runs. `undefined` ⇒ the\n  // SDK enables every discovered skill. `compiled` is fresh per request, so mutation is safe.\n  if (compiled.skillsResolver) {\n    const enabled = await resolveEnabledSkills(compiled.skillsResolver, compiled.runContext ?? {})\n    if (enabled !== undefined) compiled.skills = { enabled, autoInject: true }\n  }\n\n  let body: unknown = null\n  try {\n    body = await request.json()\n  } catch {\n    /* invalid/empty JSON → handled below as a 400 */\n  }\n\n  const input = parseAgentRequestBody(body)\n  if (input === null) {\n    return jsonError(400, 'BAD_REQUEST', 'Request must contain a non-empty message or messages[].')\n  }\n\n  // When the agent has @HumanInTheLoop-gated tools (M4), wire the pause: the plugin's `awaitApproval`\n  // registers a pending approval in the shared registry (the Promise that PAUSES the run); the\n  // approve route (`handleAgentApproval`) resolves it. No gated tools ⇒ the M2 stream path unchanged.\n  const gated = compiled.hitl\n  const registry = getApprovalRegistry()\n  const hitl =\n    gated && gated.size > 0\n      ? {\n          gated,\n          awaitApproval: (approvalId: string, opts: HumanInTheLoopOptions, toolName: string) =>\n            registry.register(approvalId, {\n              timeoutMs: opts.timeout ?? 300_000,\n              onTimeout: opts.onTimeout ?? 'abort',\n              // M14 — surface toolName + question in GET /approvals (the plugin forwards c.name).\n              toolName,\n              question: opts.question,\n              // M20 — carry the declared custom-payload schema into GET /approvals.\n              ...(opts.payloadSchema !== undefined ? { payloadSchema: opts.payloadSchema } : {}),\n            }),\n        }\n      : undefined\n\n  return uiMessageStreamResponse(\n    streamAgentUIMessages(compiled, apiKey, { ...input, hitl, signal: request.signal }),\n  )\n}\n","import type { UIMessageChunk } from 'ai'\n\n/**\n * M0 (theokit-ai-first) — serialize a stream of ai-sdk `UIMessageChunk`s into a\n * Web-Standards `Response` on the UIMessageStream wire so `@ai-sdk/react`'s\n * `useChat` consumes it WITHOUT a custom adapter.\n *\n * Wire contract (must match ai-sdk's consumer transport exactly):\n * - `content-type: text/event-stream`\n * - `x-vercel-ai-ui-message-stream: v1` — the version marker `useChat` checks\n * - each chunk framed as `data: ${JSON.stringify(chunk)}\\n\\n`\n * - a terminal `data: [DONE]\\n\\n` after the last chunk (ignored by the parser)\n *\n * Web Standards only — `Response` + `ReadableStream` (G8, no node:http). The\n * headers commit before the stream starts.\n *\n * Fail-clear (error-handling.md): if the source iterable throws mid-stream, the\n * `[DONE]` terminal is still flushed and the stream is closed — never left\n * hanging. (The translator upstream already closes gracefully; this is defense\n * in depth for any other chunk source.)\n */\nconst UI_MESSAGE_STREAM_HEADERS = {\n  'content-type': 'text/event-stream',\n  'x-vercel-ai-ui-message-stream': 'v1',\n} as const\n\nconst DONE_FRAME = 'data: [DONE]\\n\\n'\n\nfunction encode(text: string): Uint8Array {\n  return new TextEncoder().encode(text)\n}\n\nexport function uiMessageStreamResponse(chunks: AsyncIterable<UIMessageChunk>): Response {\n  const stream = new ReadableStream<Uint8Array>({\n    async start(controller) {\n      try {\n        for await (const chunk of chunks) {\n          controller.enqueue(encode(`data: ${JSON.stringify(chunk)}\\n\\n`))\n        }\n      } catch {\n        // The source iterable aborted mid-stream. The upstream translator owns\n        // error semantics (it surfaces failures as chunks + closes gracefully);\n        // this transport's sole guarantee is a terminated stream — fall through\n        // to the DONE terminal rather than re-throw and error an open stream.\n      } finally {\n        controller.enqueue(encode(DONE_FRAME))\n        controller.close()\n      }\n    },\n  })\n  return new Response(stream, { headers: UI_MESSAGE_STREAM_HEADERS })\n}\n","/**\n * T5a.2 Phase G slice 5/N — Node adapter shim for the Web request handler.\n *\n * Bridges Node's `IncomingMessage` + `ServerResponse` shape to the\n * Web-Standards `executeWebRequest` (Phase A → G slices 1-4). Per\n * ADR-0028 R3a, the Node adapter is the ONLY place IncomingMessage ↔\n * Request conversion happens — every other layer of `server/` flows\n * through Web `Request`/`Response`.\n *\n * **Two conversions:**\n *\n *   1. `incomingMessageToWebRequest(req)` — Node → Web. Reads\n *      `req.method`, `req.url`, `req.headers`, and (for POST/PUT/etc.)\n *      drains the Node Readable body into a Web `ReadableStream`. The\n *      request URL is resolved to absolute form using `req.headers.host`\n *      (Web Request guarantees absolute URL).\n *\n *   2. `writeWebResponseToServerResponse(response, res)` — Web → Node.\n *      Sets status code + status text, copies headers (including all\n *      `Set-Cookie` values via `getSetCookie()`), then drains the Web\n *      `ReadableStream` body into the Node ServerResponse.\n *\n * Plus the convenience composer `executeWebRequestFromNode(req, res,\n * routeModule, opts?)` that wires both ends — exactly what api-middleware\n * (and the prod CLI start path) need to migrate from the legacy\n * `executeRoute` to `executeWebRequest` without touching call sites.\n *\n * Per `docs/plans/t5a2-incoming-message-to-request-shape-refactor-plan.md`\n * v1.0 § Phase G slice 5/N (closes the executor bridge surface).\n */\nimport type { IncomingMessage, ServerResponse } from 'node:http'\nimport { Readable } from 'node:stream'\n\nimport { executeWebRequest, type ExecuteWebRequestOptions } from '../web-handler.js'\n\n/**\n * Build a Web `Request` from a Node `IncomingMessage`. The Web Request\n * spec requires an absolute URL; we synthesize one from\n * `req.headers.host` (or fall back to `localhost` for test doubles).\n *\n * For methods with a body (POST/PUT/PATCH/DELETE), the Node Readable\n * stream is wrapped as a Web ReadableStream via `Readable.toWeb()` so\n * downstream consumers can call `request.json()` / `request.formData()`\n * / `request.text()` natively.\n *\n * EC-1: Node sometimes provides headers as `string | string[]`. Web\n * `Headers` collapses to single-comma-joined strings — we do the join\n * manually for repeated headers because `Headers.append` would create\n * multi-value entries which behave differently on `.get()`.\n */\nexport function incomingMessageToWebRequest(req: IncomingMessage): Request {\n  const host = pickHeaderString(req.headers.host) ?? 'localhost'\n  const url = `http://${host}${req.url ?? '/'}`\n\n  const headers = new Headers()\n  for (const [key, value] of Object.entries(req.headers)) {\n    if (value === undefined) continue\n    if (Array.isArray(value)) {\n      headers.set(key, value.join(', '))\n    } else {\n      headers.set(key, value)\n    }\n  }\n\n  const method = (req.method ?? 'GET').toUpperCase()\n  const hasBody = method !== 'GET' && method !== 'HEAD'\n\n  if (!hasBody) {\n    return new Request(url, { method, headers })\n  }\n\n  // Drain Node's Readable into a Web ReadableStream. `Readable.toWeb` is\n  // available in Node 18+ (theokit's engines.node floor is 22+, so safe).\n  const webStream = Readable.toWeb(req) as ReadableStream\n  return new Request(url, {\n    method,\n    headers,\n    body: webStream,\n    // EC-2: Node 18+ requires `duplex: 'half'` when body is a stream.\n    // The `RequestInit` type omits it (Web spec gap); cast accordingly.\n    ...({ duplex: 'half' } as { duplex: 'half' }),\n  })\n}\n\n/**\n * Write a Web `Response` into a Node `ServerResponse`. Mirrors the Node\n * `res.writeHead` + `res.end` pattern.\n *\n * Set-Cookie is the only multi-value header the Web spec exposes via\n * `getSetCookie()`. We append each entry individually so Node emits\n * separate `Set-Cookie:` lines per the HTTP spec.\n *\n * If the Response body is a `ReadableStream`, it's piped chunk-by-chunk\n * to `res`. Empty body (null) → just close.\n */\nexport async function writeWebResponseToServerResponse(\n  response: Response,\n  res: ServerResponse,\n): Promise<void> {\n  // Status + headers FIRST (writeHead locks them).\n  // EC-3: Set-Cookie needs special handling (writeHead's plain object\n  // shape conflicts with multi-value headers; we set them via setHeader\n  // BEFORE writeHead so the array form is preserved).\n  const setCookies = response.headers.getSetCookie()\n  if (setCookies.length > 0) {\n    res.setHeader('Set-Cookie', setCookies)\n  }\n  const otherHeaders: Record<string, string> = {}\n  for (const [key, value] of response.headers.entries()) {\n    if (key.toLowerCase() === 'set-cookie') continue\n    otherHeaders[key] = value\n  }\n  res.writeHead(response.status, response.statusText, otherHeaders)\n\n  // Body — drain ReadableStream OR just end() for null body.\n  if (response.body === null) {\n    res.end()\n    return\n  }\n  const reader = response.body.getReader()\n  try {\n    for (;;) {\n      const { done, value } = await reader.read()\n      if (done) break\n      // Node's res.write accepts Uint8Array natively (no conversion needed).\n      res.write(value)\n    }\n    res.end()\n  } finally {\n    reader.releaseLock()\n  }\n}\n\n/**\n * Convenience composer — full request lifecycle Node → Web → Node.\n *\n * Use case: existing api-middleware (and the prod CLI start path)\n * receive Node `(req, res)` from `http.createServer`. To migrate to the\n * Web-Standards executor without rewriting every call site, wrap with\n * this composer:\n *\n *   import * as users from './app/users/route.js'\n *   await executeWebRequestFromNode(req, res, users, { csrfMode: 'strict' })\n *\n * The Web request is built, dispatched through executeWebRequest, and\n * the Response is drained back into `res`. Caller does NOT need to call\n * `res.end()` afterwards — this composer handles it.\n */\nexport async function executeWebRequestFromNode(\n  req: IncomingMessage,\n  res: ServerResponse,\n  routeModule: Parameters<typeof executeWebRequest>[1],\n  opts?: ExecuteWebRequestOptions,\n): Promise<void> {\n  const webRequest = incomingMessageToWebRequest(req)\n  const webResponse = await executeWebRequest(webRequest, routeModule, opts)\n  await writeWebResponseToServerResponse(webResponse, res)\n}\n\n/** Pick the first usable string from Node's `string | string[] | undefined` headers. */\nfunction pickHeaderString(value: string | string[] | undefined): string | undefined {\n  if (typeof value === 'string') return value\n  if (Array.isArray(value)) {\n    for (const v of value) if (typeof v === 'string' && v.length > 0) return v\n  }\n  return undefined\n}\n"],"mappings":";;;;;;;;;;AAAA,OAAO,eAAe;AAef,IAAM,uBAAwC;AAAA,EACnD,MAAM;AAAA,EACN,WAAW,CAAC,MAAM,KAAK,UAAU,UAAU,UAAU,CAAC,CAAC;AAAA,EACvD,aAAa,CAAC,QAAQ;AACpB,UAAM,SAAS,KAAK,MAAM,GAAG;AAC7B,WAAO,UAAU,YAAY,MAAM;AAAA,EACrC;AACF;AAEO,IAAM,kBAAmC;AAAA,EAC9C,MAAM;AAAA,EACN,WAAW,CAAC,MAAM,KAAK,UAAU,CAAC;AAAA,EAClC,aAAa,CAAC,QAAQ,KAAK,MAAM,GAAG;AACtC;AAEA,IAAM,YAA6C;AAAA,EACjD,WAAW;AAAA,EACX,MAAM;AACR;AAEO,SAAS,mBACd,UACiB;AACjB,MAAI,OAAO,aAAa,UAAU;AAMhC,UAAM,QAAQ,UAAU,QAAQ;AAIhC,QAAK,UAA0C,QAAW;AACxD,YAAM,IAAI;AAAA,QACR,wBAAwB,QAAQ,wBAAwB,OAAO,KAAK,SAAS,EAAE,KAAK,IAAI,CAAC;AAAA,MAC3F;AAAA,IACF;AACA,WAAO;AAAA,EACT;AACA,MACE,OAAO,aAAa,YACpB,OAAO,SAAS,cAAc,cAC9B,OAAO,SAAS,gBAAgB,YAChC;AACA,UAAM,IAAI;AAAA,MACR,0EAA0E,KAAK,UAAU,QAAQ,CAAC;AAAA,IACpG;AAAA,EACF;AACA,SAAO;AACT;;;ACjDA,IAAM,kBAAkB;AAMjB,SAAS,gBAAgB,SAAgC;AAC9D,QAAM,KAAK,QAAQ,QAAQ,eAAe;AAC1C,MAAI,OAAO,GAAI,QAAO;AACtB,QAAM,KAAK,QAAQ,MAAM,KAAK,gBAAgB,MAAM;AACpD,SAAO,GAAG,SAAS,KAAK,CAAC,GAAG,SAAS,GAAG,IAAI,KAAK;AACnD;AAGO,SAAS,eAAe,SAA0B;AACvD,SAAO,QAAQ,SAAS,eAAe;AACzC;AAEA,SAAS,UAAU,QAAgB,MAAc,SAA2B;AAC1E,SAAO,IAAI,SAAS,KAAK,UAAU,EAAE,OAAO,EAAE,MAAM,QAAQ,EAAE,CAAC,GAAG;AAAA,IAChE;AAAA,IACA,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,EAChD,CAAC;AACH;AAOA,IAAM,oBAAoB,KAAK;AAWxB,SAAS,kBAAkB,MAAwC;AACxE,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,QAAM,IAAI;AACV,MAAI,OAAO,EAAE,aAAa,UAAW,QAAO;AAC5C,QAAM,WAA6B,EAAE,UAAU,EAAE,SAAS;AAC1D,MAAI,EAAE,WAAW,QAAW;AAC1B,QAAI,OAAO,EAAE,WAAW,SAAU,QAAO;AACzC,aAAS,SAAS,EAAE;AAAA,EACtB;AACA,MAAI,EAAE,YAAY,QAAW;AAC3B,QAAI,OAAO,EAAE,YAAY,YAAY,EAAE,YAAY,QAAQ,MAAM,QAAQ,EAAE,OAAO,EAAG,QAAO;AAC5F,QAAI,KAAK,UAAU,EAAE,OAAO,EAAE,SAAS,kBAAmB,QAAO;AACjE,aAAS,UAAU,EAAE;AAAA,EACvB;AACA,SAAO;AACT;AAUA,eAAsB,oBACpB,SACA,SACA,UACA,WAAqB,UACF;AACnB,MAAI,aAAa,OAAO;AACtB,UAAM,OAAO,oBAAoB,OAAO;AACxC,QAAI,CAAC,KAAK,SAAS,aAAa,UAAU;AACxC,aAAO,UAAU,KAAK,eAAe,sBAAsB,KAAK,MAAM,EAAE;AAAA,IAC1E;AAAA,EACF;AAEA,QAAM,aAAa,gBAAgB,OAAO;AAC1C,MAAI,eAAe,MAAM;AACvB,WAAO,UAAU,KAAK,eAAe,wDAAwD;AAAA,EAC/F;AAEA,MAAI,OAAgB;AACpB,MAAI;AACF,WAAO,MAAM,QAAQ,KAAK;AAAA,EAC5B,QAAQ;AAAA,EAER;AACA,QAAM,SAAS,kBAAkB,IAAI;AACrC,MAAI,WAAW,MAAM;AACnB,WAAO,UAAU,KAAK,eAAe,iDAAiD;AAAA,EACxF;AAEA,QAAM,WAAW,SAAS,QAAQ,YAAY,MAAM;AACpD,MAAI,CAAC,UAAU;AACb,WAAO,UAAU,KAAK,eAAe,+BAA+B,UAAU,IAAI;AAAA,EACpF;AACA,SAAO,IAAI,SAAS,KAAK,UAAU,EAAE,UAAU,KAAK,CAAC,GAAG;AAAA,IACtD,QAAQ;AAAA,IACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,EAChD,CAAC;AACH;;;AC5GA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAEK;;;ACKP,IAAM,4BAA4B;AAAA,EAChC,gBAAgB;AAAA,EAChB,iCAAiC;AACnC;AAEA,IAAM,aAAa;AAEnB,SAAS,OAAO,MAA0B;AACxC,SAAO,IAAI,YAAY,EAAE,OAAO,IAAI;AACtC;AAEO,SAAS,wBAAwB,QAAiD;AACvF,QAAM,SAAS,IAAI,eAA2B;AAAA,IAC5C,MAAM,MAAM,YAAY;AACtB,UAAI;AACF,yBAAiB,SAAS,QAAQ;AAChC,qBAAW,QAAQ,OAAO,SAAS,KAAK,UAAU,KAAK,CAAC;AAAA;AAAA,CAAM,CAAC;AAAA,QACjE;AAAA,MACF,QAAQ;AAAA,MAKR,UAAE;AACA,mBAAW,QAAQ,OAAO,UAAU,CAAC;AACrC,mBAAW,MAAM;AAAA,MACnB;AAAA,IACF;AAAA,EACF,CAAC;AACD,SAAO,IAAI,SAAS,QAAQ,EAAE,SAAS,0BAA0B,CAAC;AACpE;;;ADrBA,SAAS,SAAS,MAAuB;AACvC,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,QAAM,IAAI;AACV,SAAO,EAAE,SAAS,UAAU,OAAO,EAAE,SAAS,WAAW,EAAE,OAAO;AACpE;AAEA,SAASA,WAAU,QAAgB,MAAc,SAA2B;AAC1E,SAAO,IAAI,SAAS,KAAK,UAAU,EAAE,OAAO,EAAE,MAAM,QAAQ,EAAE,CAAC,GAAG;AAAA,IAChE;AAAA,IACA,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,EAChD,CAAC;AACH;AAMO,SAAS,sBAAsB,MAAyC;AAC7E,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,QAAM,IAAI;AAGV,MAAI,MAAM,QAAQ,EAAE,QAAQ,KAAK,EAAE,SAAS,SAAS,GAAG;AACtD,UAAM,OAAO,EAAE,SAAS,EAAE,SAAS,SAAS,CAAC;AAC7C,UAAM,QAAQ,MAAM,QAAQ,KAAK,KAAK,IAAI,KAAK,QAAQ,CAAC;AACxD,UAAM,OAAO,MAAM,IAAI,QAAQ,EAAE,KAAK,EAAE;AACxC,QAAI,KAAK,WAAW,EAAG,QAAO;AAC9B,UAAM,YAAY,OAAO,EAAE,OAAO,YAAY,EAAE,GAAG,SAAS,IAAI,EAAE,KAAK,OAAO,WAAW;AACzF,WAAO,EAAE,SAAS,MAAM,UAAU;AAAA,EACpC;AAGA,MAAI,OAAO,EAAE,YAAY,YAAY,EAAE,QAAQ,SAAS,GAAG;AACzD,UAAM,YACJ,OAAO,EAAE,cAAc,YAAY,EAAE,UAAU,SAAS,IAAI,EAAE,YAAY,OAAO,WAAW;AAC9F,WAAO,EAAE,SAAS,EAAE,SAAS,UAAU;AAAA,EACzC;AAEA,SAAO;AACT;AAMA,eAAsB,WACpB,KACA,SACA,QACA,SAAS,gBACT,WAAqB,UACF;AAKnB,MAAI,aAAa,OAAO;AACtB,UAAM,OAAO,oBAAoB,OAAO;AACxC,QAAI,CAAC,KAAK,SAAS,aAAa,UAAU;AACxC,aAAOA,WAAU,KAAK,eAAe,sBAAsB,KAAK,MAAM,EAAE;AAAA,IAC1E;AAAA,EACF;AAEA,QAAM,WAAW,mBAAmB,KAAK,MAAM;AAK/C,MAAI,SAAS,gBAAgB;AAC3B,UAAM,UAAU,MAAM,qBAAqB,SAAS,gBAAgB,SAAS,cAAc,CAAC,CAAC;AAC7F,QAAI,YAAY,OAAW,UAAS,SAAS,EAAE,SAAS,YAAY,KAAK;AAAA,EAC3E;AAEA,MAAI,OAAgB;AACpB,MAAI;AACF,WAAO,MAAM,QAAQ,KAAK;AAAA,EAC5B,QAAQ;AAAA,EAER;AAEA,QAAM,QAAQ,sBAAsB,IAAI;AACxC,MAAI,UAAU,MAAM;AAClB,WAAOA,WAAU,KAAK,eAAe,yDAAyD;AAAA,EAChG;AAKA,QAAM,QAAQ,SAAS;AACvB,QAAM,WAAW,oBAAoB;AACrC,QAAM,OACJ,SAAS,MAAM,OAAO,IAClB;AAAA,IACE;AAAA,IACA,eAAe,CAAC,YAAoB,MAA6B,aAC/D,SAAS,SAAS,YAAY;AAAA,MAC5B,WAAW,KAAK,WAAW;AAAA,MAC3B,WAAW,KAAK,aAAa;AAAA;AAAA,MAE7B;AAAA,MACA,UAAU,KAAK;AAAA;AAAA,MAEf,GAAI,KAAK,kBAAkB,SAAY,EAAE,eAAe,KAAK,cAAc,IAAI,CAAC;AAAA,IAClF,CAAC;AAAA,EACL,IACA;AAEN,SAAO;AAAA,IACL,sBAAsB,UAAU,QAAQ,EAAE,GAAG,OAAO,MAAM,QAAQ,QAAQ,OAAO,CAAC;AAAA,EACpF;AACF;;;AE7GA,SAAS,gBAAgB;AAmBlB,SAAS,4BAA4B,KAA+B;AACzE,QAAM,OAAO,iBAAiB,IAAI,QAAQ,IAAI,KAAK;AACnD,QAAM,MAAM,UAAU,IAAI,GAAG,IAAI,OAAO,GAAG;AAE3C,QAAM,UAAU,IAAI,QAAQ;AAC5B,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,OAAO,GAAG;AACtD,QAAI,UAAU,OAAW;AACzB,QAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,cAAQ,IAAI,KAAK,MAAM,KAAK,IAAI,CAAC;AAAA,IACnC,OAAO;AACL,cAAQ,IAAI,KAAK,KAAK;AAAA,IACxB;AAAA,EACF;AAEA,QAAM,UAAU,IAAI,UAAU,OAAO,YAAY;AACjD,QAAM,UAAU,WAAW,SAAS,WAAW;AAE/C,MAAI,CAAC,SAAS;AACZ,WAAO,IAAI,QAAQ,KAAK,EAAE,QAAQ,QAAQ,CAAC;AAAA,EAC7C;AAIA,QAAM,YAAY,SAAS,MAAM,GAAG;AACpC,SAAO,IAAI,QAAQ,KAAK;AAAA,IACtB;AAAA,IACA;AAAA,IACA,MAAM;AAAA;AAAA;AAAA,IAGN,GAAI,EAAE,QAAQ,OAAO;AAAA,EACvB,CAAC;AACH;AAaA,eAAsB,iCACpB,UACA,KACe;AAKf,QAAM,aAAa,SAAS,QAAQ,aAAa;AACjD,MAAI,WAAW,SAAS,GAAG;AACzB,QAAI,UAAU,cAAc,UAAU;AAAA,EACxC;AACA,QAAM,eAAuC,CAAC;AAC9C,aAAW,CAAC,KAAK,KAAK,KAAK,SAAS,QAAQ,QAAQ,GAAG;AACrD,QAAI,IAAI,YAAY,MAAM,aAAc;AACxC,iBAAa,GAAG,IAAI;AAAA,EACtB;AACA,MAAI,UAAU,SAAS,QAAQ,SAAS,YAAY,YAAY;AAGhE,MAAI,SAAS,SAAS,MAAM;AAC1B,QAAI,IAAI;AACR;AAAA,EACF;AACA,QAAM,SAAS,SAAS,KAAK,UAAU;AACvC,MAAI;AACF,eAAS;AACP,YAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK;AAC1C,UAAI,KAAM;AAEV,UAAI,MAAM,KAAK;AAAA,IACjB;AACA,QAAI,IAAI;AAAA,EACV,UAAE;AACA,WAAO,YAAY;AAAA,EACrB;AACF;AA6BA,SAAS,iBAAiB,OAA0D;AAClF,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,eAAW,KAAK,MAAO,KAAI,OAAO,MAAM,YAAY,EAAE,SAAS,EAAG,QAAO;AAAA,EAC3E;AACA,SAAO;AACT;","names":["jsonError"]}

package/dist/{chunk-KGFNWIMS.js → chunk-CWVBDUDC.js}

@@ -52,12 +52,25 @@ function defineAgentTool(spec) {
     name: spec.name,
     description: spec.description,
     inputSchema,
-    handler: async (input) => {
+    handler: async (input, ctx) => {
       const parsed = spec.inputSchema.parse(input);
-      return await spec.handler(parsed);
-    }
+      const result = await spec.handler(parsed, ctx);
+      if (spec.toModelOutput) return spec.toModelOutput(result);
+      if (typeof result !== "string") {
+        throw new Error(
+          `defineAgentTool(${JSON.stringify(spec.name)}): handler returned a non-string; provide toModelOutput to map it to a string for the model.`
+        );
+      }
+      return result;
+    },
+    // M18 — carry the per-target formatters for the app (ignored by the SDK wire).
+    ...spec.transform !== void 0 ? { transform: spec.transform } : {}
   };
 }
+function applyTransform(tool, result, target) {
+  const fn = tool.transform?.[target];
+  return fn ? fn(result) : result;
+}
 
 // src/server/define/define-websocket.ts
 function defineWebSocket(handler) {
@@ -85,10 +98,11 @@ export {
   defineAction,
   defineMiddleware,
   defineAgentTool,
+  applyTransform,
   defineWebSocket,
   defineWebSocketWeb,
   defineChannel,
   defineWebChannel,
   defineTheoPlugin
 };
-//# sourceMappingURL=chunk-KGFNWIMS.js.map
+//# sourceMappingURL=chunk-CWVBDUDC.js.map

package/dist/chunk-CWVBDUDC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/define/define-route.ts","../src/server/define/define-action.ts","../src/server/define/define-middleware.ts","../src/server/define/define-agent-tool.ts","../src/server/define/define-websocket.ts","../src/server/define/define-channel.ts","../src/server/define/define-plugin.ts"],"sourcesContent":["import type { z } from 'zod'\n\n// T2.2 (architecture-cleanup) — RouteConfig type moved to core/contracts/\n// (canonical home per ADR-0001 v3). Re-export preserves the public path\n// `import { type RouteConfig } from 'theokit/server'`.\nexport type { RouteConfig } from '../../core/contracts/route-config.js'\n\nimport type { RouteConfig } from '../../core/contracts/route-config.js'\n\n/**\n * Define a typed HTTP route.\n * Identity function — provides type inference for route handlers.\n */\nexport function defineRoute<\n  TQuery extends z.ZodType = z.ZodUndefined,\n  TBody extends z.ZodType = z.ZodUndefined,\n  TParams extends z.ZodType = z.ZodUndefined,\n  TCtx = unknown,\n  TResponse = unknown,\n>(\n  config: RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>,\n): RouteConfig<TQuery, TBody, TParams, TCtx, TResponse> {\n  return config\n}\n","import type { z } from 'zod'\n\n/**\n * Action wire-protocol accept mode per plan g3-server-actions-and-useaction\n * v1.2 ADR D1. Default behavior (when omitted) is `'json'`. `'form'` opts the\n * action into FormData multipart parsing for progressive-enhancement forms;\n * the runtime in `server/http/action-execute.ts` will coerce FormData entries\n * against the `input` schema via `formDataToObject` (Astro pattern).\n */\nexport type ActionAccept = 'form' | 'json'\n\nexport interface ActionConfig<TInput extends z.ZodType, TCtx = unknown> {\n  /**\n   * Zod input schema. Required: every action declares its input contract via\n   * Zod (architecture rule: zod-is-SSOT). The shape becomes the handler's\n   * typed `input` parameter via `z.infer<TInput>`.\n   */\n  input: TInput\n  /**\n   * Wire-protocol accept mode. Defaults to `'json'` when omitted. Setting\n   * `'form'` switches the runtime to FormData multipart parsing — the input\n   * schema MUST be `z.object(...)` so field-by-field coercion can drive\n   * boolean string / number / array coercion (Astro pattern).\n   */\n  accept?: ActionAccept\n  /**\n   * Opt OUT of CSRF enforcement for this action. Default (omitted) keeps the\n   * multi-header CSRF gate active. Set `false` for endpoints intentionally\n   * callable without the `X-Theo-Action` header (e.g. public webhooks). The\n   * runtime in `server/http/action-execute.ts` reads this flag.\n   */\n  csrf?: false\n  handler: (ctx: { input: z.infer<TInput>; ctx: TCtx }) => unknown\n}\n\n/**\n * Define a typed server action.\n *\n * Identity function — provides type inference for action handlers. The\n * runtime that consumes the config (validation + invocation + serialization)\n * lives in `server/http/action-execute.ts`.\n *\n * Per plan g3-server-actions-and-useaction v1.2 § Phase 1 / T1.2: the new\n * `accept?: 'form' | 'json'` field is the only contract change vs the\n * pre-G3 identity. Existing callsites (`defineAction({input, handler})`)\n * continue to compile — `accept` is opt-in.\n */\nexport function defineAction<TInput extends z.ZodType, TCtx = unknown>(\n  config: ActionConfig<TInput, TCtx>,\n): ActionConfig<TInput, TCtx> {\n  return config\n}\n","export type MiddlewareHandler = (\n  request: Request,\n  next: (request: Request) => Promise<Response>,\n) => Response | Promise<Response>\n\n/**\n * Define a middleware handler.\n * Identity function — provides type annotation for middleware.\n */\nexport function defineMiddleware(handler: MiddlewareHandler): MiddlewareHandler {\n  return handler\n}\n","import { z } from 'zod'\n\n/**\n * Item #4 — `defineAgentTool`\n *\n * Sugar over the `@theokit/sdk` `CustomTool` contract. Takes a Zod schema +\n * handler and produces a structurally-compatible `CustomTool` that\n * `Agent.create({ tools: [...] })` accepts.\n *\n * Uses Zod v4's native `z.toJSONSchema()` to convert the input schema to\n * JSON Schema for LLM providers.\n *\n * Handler error propagation:\n *   `defineAgentTool` parses the input via the Zod schema BEFORE calling the\n *   user handler. Invalid input throws a `ZodError`, which the SDK's tool-\n *   dispatcher treats as a tool failure and surfaces to the model as a tool\n *   error (the SDK owns the wire; ADR D3).\n */\n\n/**\n * Local mirror of the SDK's `CustomTool` interface. We don't `import type`\n * from `@theokit/sdk` because the SDK is an optional peer (consumers who\n * never call `defineAgentTool` shouldn't need it installed). The shape is\n * the wire contract; any structurally-matching object is accepted by\n * `Agent.create({ tools })`.\n *\n * @public\n */\nexport interface CustomTool {\n  name: string\n  description: string\n  inputSchema: Record<string, unknown>\n  handler: (\n    input: Record<string, unknown>,\n    ctx?: { signal?: AbortSignal; context?: unknown },\n  ) => string | Promise<string>\n  /** M18 — optional per-target formatters for the app's UI/transcript (ignored by the SDK wire). */\n  transform?: ToolTransform\n}\n\n/**\n * M18 — per-target formatters. `display` shapes the rich handler result for the UI; `transcript`\n * shapes it for a saved transcript. Applied by {@link applyTransform}, never by the model wire.\n */\nexport interface ToolTransform<R = unknown> {\n  display?: (result: R) => unknown\n  transcript?: (result: R) => unknown\n}\n\n/**\n * Spec accepted by {@link defineAgentTool}. `inputSchema` is a Zod 3 schema\n * rooted in `z.object(...)`. The `handler` argument type is inferred via\n * `z.infer<T>`.\n *\n * @public\n */\nexport interface DefineAgentToolSpec<T extends z.ZodType, R = string> {\n  /** Tool name surfaced to the LLM. Must match `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`. */\n  name: string\n  /** Description surfaced to the LLM. Required — drives tool-selection accuracy. */\n  description: string\n  /** Zod schema describing the input. Must be `z.object(...)` at the root. */\n  inputSchema: T\n  /**\n   * Handler invoked with the parsed input and, optionally, the run `ctx` (M7). `ctx.context`\n   * is the object supplied once at the agent level (`defineAgent({ context })`) or per-run —\n   * read it for shared config like `projectRoot` instead of baking it into the factory.\n   * `ctx.signal` is the abort signal. Optional so existing one-arg handlers keep working.\n   *\n   * M18 — the handler may return RICH data `R` (not just a string) when `toModelOutput` is\n   * provided to map it to the model-visible string.\n   */\n  handler: (\n    input: z.infer<T>,\n    ctx?: { signal?: AbortSignal; context?: unknown },\n  ) => R | Promise<R>\n  /**\n   * M18 — map the rich handler result `R` to the string the model sees. Required (in practice)\n   * when `handler` returns a non-string; absent ⇒ the handler must return a string.\n   */\n  toModelOutput?: (result: R) => string\n  /** M18 — per-target formatters (`display` / `transcript`) for the app, applied by {@link applyTransform}. */\n  transform?: ToolTransform<R>\n}\n\nconst TOOL_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/\n\nfunction isZodObject(schema: z.ZodType): boolean {\n  // Refinements (`.refine`), transforms (`.transform`), and defaults wrap the\n  // underlying schema — walk the chain until we hit a ZodObject (or give up).\n  // Supports both zod 4 (`instanceof z.ZodObject`, `def.type === 'object'`,\n  // wrappers via `def.innerType` / pipe via `def.in`) and zod 3\n  // (`_def.typeName === 'ZodObject'`, wrappers via `_def.schema`/`_def.innerType`).\n  let current: unknown = schema\n  for (let depth = 0; depth < 10; depth++) {\n    if (current instanceof z.ZodObject) return true\n    const z4 = (current as { def?: { type?: string; innerType?: unknown; in?: unknown } }).def\n    if (z4?.type === 'object') return true\n    const z3 = (current as { _def?: { typeName?: string; schema?: unknown; innerType?: unknown } })\n      ._def\n    if (z3?.typeName === 'ZodObject') return true\n    const next = z4?.innerType ?? z4?.in ?? z3?.schema ?? z3?.innerType\n    if (next !== undefined) {\n      current = next\n      continue\n    }\n    return false\n  }\n  return false\n}\n\n/**\n * Build a {@link CustomTool} from a Zod 3 schema + handler.\n *\n * Behavior:\n * - Validates `name` matches the LLM tool-name regex.\n * - Requires `inputSchema` to be a `ZodObject` (Anthropic + SDK contract).\n * - Warns (not throws) if `description` is empty — empty descriptions\n *   degrade LLM tool selection.\n * - Converts the Zod schema to JSON Schema 7 inline (no `$ref`s — LLMs handle\n *   inline schemas more reliably).\n * - Strips the top-level `$schema` field (Anthropic rejects schemas with\n *   `$schema` at root in some provider modes).\n * - Wraps the handler to parse the input via the Zod schema BEFORE invoking\n *   the user code — bad LLM-supplied input throws `ZodError`, which the SDK\n *   converts to `tool_result(isError)`.\n *\n * @public\n */\nexport function defineAgentTool<T extends z.ZodType, R = string>(\n  spec: DefineAgentToolSpec<T, R>,\n): CustomTool {\n  if (!TOOL_NAME_REGEX.test(spec.name)) {\n    throw new Error(\n      `defineAgentTool: name must match ${TOOL_NAME_REGEX.source}. Got: ${JSON.stringify(spec.name)}`,\n    )\n  }\n  if (!isZodObject(spec.inputSchema)) {\n    throw new Error('defineAgentTool: inputSchema must be a ZodObject (z.object({...}))')\n  }\n  if (spec.description.length === 0) {\n    console.warn(\n      `defineAgentTool(${JSON.stringify(spec.name)}): empty description degrades LLM tool selection — provide a one-sentence summary.`,\n    )\n  }\n\n  // Zod v4 native JSON Schema conversion — replaces zod-to-json-schema dep.\n  // Strip $schema (Anthropic + some providers reject it).\n  const { $schema: _$schema, ...inputSchema } = z.toJSONSchema(spec.inputSchema) as Record<\n    string,\n    unknown\n  > & {\n    $schema?: unknown\n  }\n\n  return {\n    name: spec.name,\n    description: spec.description,\n    inputSchema,\n    handler: async (\n      input: Record<string, unknown>,\n      ctx?: { signal?: AbortSignal; context?: unknown },\n    ): Promise<string> => {\n      const parsed = spec.inputSchema.parse(input)\n      // M7 — forward the run ctx so the handler can read `ctx.context` (e.g. projectRoot).\n      const result = await spec.handler(parsed, ctx)\n      // M18 — shape the (possibly rich) result into the model-visible string.\n      if (spec.toModelOutput) return spec.toModelOutput(result)\n      if (typeof result !== 'string') {\n        throw new Error(\n          `defineAgentTool(${JSON.stringify(spec.name)}): handler returned a non-string; provide toModelOutput to map it to a string for the model.`,\n        )\n      }\n      return result\n    },\n    // M18 — carry the per-target formatters for the app (ignored by the SDK wire).\n    ...(spec.transform !== undefined ? { transform: spec.transform as ToolTransform } : {}),\n  }\n}\n\n/**\n * M18 — apply a tool's `transform` for a target (`display` / `transcript`). Returns the formatted\n * value, or the raw `result` when the tool declares no transform for that target.\n */\nexport function applyTransform(\n  tool: CustomTool,\n  result: unknown,\n  target: 'display' | 'transcript',\n): unknown {\n  const fn = tool.transform?.[target]\n  return fn ? fn(result) : result\n}\n","import type { IncomingMessage } from 'node:http'\n\nexport interface WebSocketLike {\n  send(data: string | Buffer): void\n  close(code?: number, reason?: string): void\n}\n\nexport interface WebSocketHandler {\n  onOpen?: (ws: WebSocketLike, req: IncomingMessage) => void\n  onMessage?: (ws: WebSocketLike, data: string | Buffer) => void\n  onClose?: (ws: WebSocketLike, code: number, reason: Buffer) => void\n  onError?: (ws: WebSocketLike, error: Error) => void\n}\n\n/**\n * Define a WebSocket endpoint handler.\n * Identity function — provides type inference for WebSocket handlers.\n */\nexport function defineWebSocket(handler: WebSocketHandler): WebSocketHandler {\n  return handler\n}\n\n/**\n * T5a.2 Phase F slice 3/3 — Web-Standards WebSocket endpoint handler.\n *\n * Mirror of `WebSocketHandler` for the Web `Request` shape. `onOpen`\n * receives `request: Request` instead of `req: IncomingMessage`. The\n * rest of the lifecycle (onMessage, onClose, onError) is shape-agnostic\n * (`WebSocketLike` is already Web-standards-compatible per the existing\n * design — `send(string | Buffer)` works on both Node `ws` and Web\n * `WebSocket` instances; CF Workers / Bun / Deno coerce as needed at\n * the adapter boundary).\n *\n * Per `docs/plans/t5a2-incoming-message-to-request-shape-refactor-plan.md`\n * v1.0 § Phase F (closes Phase F).\n *\n * **Architectural note — WebSocket upgrade semantics differ across runtimes:**\n *   - Node + `ws`: `WebSocketServer.handleUpgrade(req, socket, head, cb)` —\n *     `req` is `IncomingMessage`. Use `WebSocketHandler`.\n *   - CF Workers: `new WebSocketPair()` + `request.headers` (the upgrade\n *     handshake IS a Web Request). Use `WebSocketHandlerWeb`.\n *   - Bun: `server.upgrade(request, { data })` — same Web Request shape.\n *   - Deno: `Deno.upgradeWebSocket(request)` — same Web Request shape.\n *\n * Cross-runtime WebSocket endpoints ship BOTH `WebSocketHandler` +\n * `WebSocketHandlerWeb` exports; the runtime adapter picks the matching\n * one. This is the canonical Hono / Nitric pattern.\n */\nexport interface WebSocketHandlerWeb {\n  onOpen?: (ws: WebSocketLike, request: Request) => void\n  onMessage?: (ws: WebSocketLike, data: string | Uint8Array) => void\n  onClose?: (ws: WebSocketLike, code: number, reason: string) => void\n  onError?: (ws: WebSocketLike, error: Error) => void\n}\n\n/**\n * Web-Standards `defineWebSocket` sibling. Identity function — provides\n * type inference for Web WebSocket handlers.\n *\n * **Type difference note vs Node path:**\n *   - `onMessage` data is `string | Uint8Array` instead of `string | Buffer`\n *     (Web standards have no `Buffer`; Node's Buffer is a Uint8Array\n *     subclass so the Node path's Buffer values flow through unchanged\n *     when adapters wrap them).\n *   - `onClose` reason is `string` instead of `Buffer` (Web `CloseEvent`\n *     exposes the reason as a UTF-8 string natively).\n */\nexport function defineWebSocketWeb(handler: WebSocketHandlerWeb): WebSocketHandlerWeb {\n  return handler\n}\n","import type { IncomingMessage } from 'node:http'\n\nimport type { WebSocketLike } from './define-websocket.js'\n\nexport interface ChannelHandler<TMessage = unknown> {\n  onSubscribe?: (ws: WebSocketLike, room: string, req: IncomingMessage) => void\n  onMessage?: (ws: WebSocketLike, room: string, data: TMessage) => void\n  onUnsubscribe?: (ws: WebSocketLike, room: string) => void\n}\n\n/**\n * Define a channel handler for WebSocket rooms.\n * Identity function — provides type inference for channel handlers.\n */\nexport function defineChannel<TMessage = unknown>(\n  handler: ChannelHandler<TMessage>,\n): ChannelHandler<TMessage> {\n  return handler\n}\n\n/**\n * T5a.2 Phase F slice 2/3 — Web-Standards channel handler.\n *\n * Mirror of `ChannelHandler<TMessage>` for the Web `Request` shape.\n * `onSubscribe` receives `request: Request` instead of `req: IncomingMessage`\n * — the rest of the surface (onMessage, onUnsubscribe) is shape-agnostic\n * (WebSocketLike is already Web-standards-compatible per `define-websocket.ts`).\n *\n * Per `docs/plans/t5a2-incoming-message-to-request-shape-refactor-plan.md`\n * v1.0 § Phase F.\n *\n * **Architectural note:** WebSocket upgrade semantics differ across\n * runtimes:\n *   - Node: `WebSocketServer.handleUpgrade(req, socket, head, cb)` —\n *     hands you `req: IncomingMessage` at the upgrade handshake.\n *   - CF Workers: `new WebSocketPair()` + `request.headers` (the upgrade\n *     handshake IS a Web Request) — hands you `request: Request`.\n *   - Bun: `server.upgrade(request, { data })` — same Web Request shape.\n *   - Deno: `Deno.upgradeWebSocket(request)` — same Web Request shape.\n *\n * Channel handlers targeting CF/Bun/Deno use `WebChannelHandler`; legacy\n * Node consumers stay on `ChannelHandler`. Cross-runtime channels ship\n * both shapes.\n */\nexport interface WebChannelHandler<TMessage = unknown> {\n  onSubscribe?: (ws: WebSocketLike, room: string, request: Request) => void\n  onMessage?: (ws: WebSocketLike, room: string, data: TMessage) => void\n  onUnsubscribe?: (ws: WebSocketLike, room: string) => void\n}\n\n/**\n * Web-Standards `defineChannel` sibling. Identity function — provides\n * type inference for Web channel handlers.\n */\nexport function defineWebChannel<TMessage = unknown>(\n  handler: WebChannelHandler<TMessage>,\n): WebChannelHandler<TMessage> {\n  return handler\n}\n","import type { TheoPlugin } from '../plugin-types.js'\n\n/**\n * Identity function for defining a Theo plugin.\n *\n * **Note:** Prefer `definePlugin` (shorter, canonical name per ADR-0008 D6).\n * Both functions are identical — `defineTheoPlugin` is kept as an alias for\n * existing in-tree consumers without forcing a migration sweep.\n */\nexport function defineTheoPlugin(plugin: TheoPlugin): TheoPlugin {\n  return plugin\n}\n"],"mappings":";AAaO,SAAS,YAOd,QACsD;AACtD,SAAO;AACT;;;ACwBO,SAAS,aACd,QAC4B;AAC5B,SAAO;AACT;;;AC1CO,SAAS,iBAAiB,SAA+C;AAC9E,SAAO;AACT;;;ACXA,SAAS,SAAS;AAqFlB,IAAM,kBAAkB;AAExB,SAAS,YAAY,QAA4B;AAM/C,MAAI,UAAmB;AACvB,WAAS,QAAQ,GAAG,QAAQ,IAAI,SAAS;AACvC,QAAI,mBAAmB,EAAE,UAAW,QAAO;AAC3C,UAAM,KAAM,QAA2E;AACvF,QAAI,IAAI,SAAS,SAAU,QAAO;AAClC,UAAM,KAAM,QACT;AACH,QAAI,IAAI,aAAa,YAAa,QAAO;AACzC,UAAM,OAAO,IAAI,aAAa,IAAI,MAAM,IAAI,UAAU,IAAI;AAC1D,QAAI,SAAS,QAAW;AACtB,gBAAU;AACV;AAAA,IACF;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAoBO,SAAS,gBACd,MACY;AACZ,MAAI,CAAC,gBAAgB,KAAK,KAAK,IAAI,GAAG;AACpC,UAAM,IAAI;AAAA,MACR,oCAAoC,gBAAgB,MAAM,UAAU,KAAK,UAAU,KAAK,IAAI,CAAC;AAAA,IAC/F;AAAA,EACF;AACA,MAAI,CAAC,YAAY,KAAK,WAAW,GAAG;AAClC,UAAM,IAAI,MAAM,oEAAoE;AAAA,EACtF;AACA,MAAI,KAAK,YAAY,WAAW,GAAG;AACjC,YAAQ;AAAA,MACN,mBAAmB,KAAK,UAAU,KAAK,IAAI,CAAC;AAAA,IAC9C;AAAA,EACF;AAIA,QAAM,EAAE,SAAS,UAAU,GAAG,YAAY,IAAI,EAAE,aAAa,KAAK,WAAW;AAO7E,SAAO;AAAA,IACL,MAAM,KAAK;AAAA,IACX,aAAa,KAAK;AAAA,IAClB;AAAA,IACA,SAAS,OACP,OACA,QACoB;AACpB,YAAM,SAAS,KAAK,YAAY,MAAM,KAAK;AAE3C,YAAM,SAAS,MAAM,KAAK,QAAQ,QAAQ,GAAG;AAE7C,UAAI,KAAK,cAAe,QAAO,KAAK,cAAc,MAAM;AACxD,UAAI,OAAO,WAAW,UAAU;AAC9B,cAAM,IAAI;AAAA,UACR,mBAAmB,KAAK,UAAU,KAAK,IAAI,CAAC;AAAA,QAC9C;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA;AAAA,IAEA,GAAI,KAAK,cAAc,SAAY,EAAE,WAAW,KAAK,UAA2B,IAAI,CAAC;AAAA,EACvF;AACF;AAMO,SAAS,eACd,MACA,QACA,QACS;AACT,QAAM,KAAK,KAAK,YAAY,MAAM;AAClC,SAAO,KAAK,GAAG,MAAM,IAAI;AAC3B;;;AC7KO,SAAS,gBAAgB,SAA6C;AAC3E,SAAO;AACT;AA+CO,SAAS,mBAAmB,SAAmD;AACpF,SAAO;AACT;;;ACvDO,SAAS,cACd,SAC0B;AAC1B,SAAO;AACT;AAoCO,SAAS,iBACd,SAC6B;AAC7B,SAAO;AACT;;;ACjDO,SAAS,iBAAiB,QAAgC;AAC/D,SAAO;AACT;","names":[]}

package/dist/{chunk-NBWB4S46.js → chunk-M6NMS5LR.js}

@@ -52,24 +52,34 @@ function createInProcessApprovalRegistry() {
   return {
     register(approvalId, opts) {
       return new Promise((resolve) => {
-        const settle = (approved) => {
+        const settle = (decision) => {
           const entry = pending.get(approvalId);
           if (!entry) return;
           clearTimeout(entry.timer);
           pending.delete(approvalId);
-          resolve(approved);
+          resolve(decision);
         };
         const timer = setTimeout(() => {
-          settle(opts.onTimeout === "proceed");
+          settle({ approved: opts.onTimeout === "proceed" });
         }, opts.timeoutMs);
-        pending.set(approvalId, { settle, timer });
+        const info = {
+          approvalId,
+          toolName: opts.toolName,
+          question: opts.question,
+          expiresAt: Date.now() + opts.timeoutMs,
+          ...opts.payloadSchema !== void 0 ? { payloadSchema: opts.payloadSchema } : {}
+        };
+        pending.set(approvalId, { settle, timer, info });
       });
     },
-    resolve(approvalId, approved) {
+    resolve(approvalId, decision) {
       const entry = pending.get(approvalId);
       if (!entry) return false;
-      entry.settle(approved);
+      entry.settle(typeof decision === "boolean" ? { approved: decision } : decision);
       return true;
+    },
+    list() {
+      return [...pending.values()].map((p) => p.info);
     }
   };
 }
@@ -78,4 +88,4 @@ export {
   getApprovalRegistry,
   resolveProvider
 };
-//# sourceMappingURL=chunk-NBWB4S46.js.map
+//# sourceMappingURL=chunk-M6NMS5LR.js.map

package/dist/{chunk-NBWB4S46.js.map → chunk-M6NMS5LR.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/server/agent/provider-resolver.ts","../src/server/agent/approval-registry.ts"],"sourcesContent":["/**\n * Provider Resolver — Strategy + Registry pattern (FAANG-grade).\n *\n * Inspiração: Dapr Conversation Registry (`dapr/pkg/components/conversation/registry.go`)\n * + Encore Manager provider array (`encore/runtimes/go/pubsub/manager_internal.go`).\n *\n * Princípio: provider routing é responsabilidade do FRAMEWORK, não do consumer.\n * Consumer template usa `model: { id: 'gpt-4o-mini' }` puro — sem conditionals.\n *\n * Wire protocol: OpenAI Chat Completions (universal — implementado por todos\n * os providers: OpenRouter, Groq, Mistral, Together, Anthropic via proxy, etc).\n *\n * Resolução por prioridade (FIRST match wins):\n *   1. OPENROUTER_API_KEY → baseUrl=openrouter.ai (gateway multi-modelo)\n *   2. OPENAI_API_KEY     → baseUrl=api.openai.com\n *   3. ANTHROPIC_API_KEY  → direct Anthropic (Messages API, não OpenAI-compat)\n *\n * Escape hatch: `options.apiKey` explícito SOBREPÕE auto-resolution\n * (consumer pode forçar provider específico se quiser).\n */\n\n/**\n * Provider configuration descriptor — Registry entry shape.\n *\n * @public\n */\nexport interface ProviderDescriptor {\n  /** Stable name used internally — não exposto no wire. */\n  name: string\n  /** Environment variable that holds the API key for this provider. */\n  envKey: string\n  /** Base URL for the provider's OpenAI-compatible (or native) API. */\n  baseUrl: string\n  /** Resolution priority (lower = higher priority). FIRST match wins. */\n  priority: number\n}\n\n/**\n * Resolved provider configuration — output of `resolveProvider()`.\n *\n * @public\n */\nexport interface ResolvedProvider {\n  name: string\n  apiKey: string\n  baseUrl: string\n}\n\n/**\n * Default provider registry. Order = priority (first = highest).\n *\n * Adding a new provider:\n *   1. Append entry below (or register via `registerProvider()`).\n *   2. Set `envKey` matching the user's env var convention.\n *   3. Set `baseUrl` to the OpenAI-compat endpoint (or native if not compat).\n *   4. Provider name used in telemetry/logs only — never wire-exposed.\n */\nconst DEFAULT_REGISTRY: ProviderDescriptor[] = [\n  {\n    name: 'openrouter',\n    envKey: 'OPENROUTER_API_KEY',\n    baseUrl: 'https://openrouter.ai/api/v1',\n    priority: 1,\n  },\n  {\n    name: 'openai',\n    envKey: 'OPENAI_API_KEY',\n    baseUrl: 'https://api.openai.com/v1',\n    priority: 2,\n  },\n  {\n    name: 'anthropic',\n    envKey: 'ANTHROPIC_API_KEY',\n    baseUrl: 'https://api.anthropic.com',\n    priority: 3,\n  },\n]\n\n/**\n * Runtime registry — copy of DEFAULT_REGISTRY mutable via registerProvider().\n * Sorted by priority on every resolve (stable, O(n log n) — n <= ~10 providers).\n */\nconst registry: ProviderDescriptor[] = [...DEFAULT_REGISTRY]\n\n/**\n * Register a new provider (Registry pattern — runtime extension point).\n * Useful for self-hosted endpoints or custom providers without touching theokit src.\n *\n * @example\n * registerProvider({\n *   name: 'self-hosted',\n *   envKey: 'SELF_HOSTED_API_KEY',\n *   baseUrl: 'https://llm.internal.acme.com/v1',\n *   priority: 0, // highest priority\n * })\n *\n * @public\n */\nexport function registerProvider(descriptor: ProviderDescriptor): void {\n  // Idempotent — replace existing by name.\n  const idx = registry.findIndex((p) => p.name === descriptor.name)\n  if (idx >= 0) registry[idx] = descriptor\n  else registry.push(descriptor)\n}\n\n/**\n * Reset registry to DEFAULT_REGISTRY (test-only / dev escape hatch).\n *\n * @public\n */\nexport function resetProviderRegistry(): void {\n  registry.length = 0\n  registry.push(...DEFAULT_REGISTRY)\n}\n\n/**\n * Get current registry snapshot (read-only — inspection).\n *\n * @public\n */\nexport function listProviders(): readonly ProviderDescriptor[] {\n  return [...registry].sort((a, b) => a.priority - b.priority)\n}\n\n/**\n * Resolve provider from env vars by priority. FIRST env var found wins.\n *\n * @returns ResolvedProvider with apiKey + baseUrl + name\n * @throws Error if NO provider env var is set (actionable message)\n *\n * @public\n */\nexport function resolveProvider(): ResolvedProvider {\n  const sorted = [...registry].sort((a, b) => a.priority - b.priority)\n  for (const desc of sorted) {\n    const apiKey = process.env[desc.envKey]\n    if (apiKey && apiKey.length > 0) {\n      return {\n        name: desc.name,\n        apiKey,\n        baseUrl: desc.baseUrl,\n      }\n    }\n  }\n  // No env var found — emit actionable error.\n  const envKeys = sorted.map((p) => p.envKey).join(' OR ')\n  throw new Error(\n    `No LLM provider API key found in environment. Set one of: ${envKeys}. ` +\n      `Get a free OpenRouter key at https://openrouter.ai/keys (recommended — one key, many models).`,\n  )\n}\n\n/**\n * Try to resolve — does NOT throw. Returns null if no provider available.\n * Useful for graceful degradation (e.g., mock mode).\n *\n * @public\n */\nexport function tryResolveProvider(): ResolvedProvider | null {\n  try {\n    return resolveProvider()\n  } catch {\n    return null\n  }\n}\n","/**\n * M4 (theokit-ai-first) — the in-process HITL approval registry.\n *\n * The HITL plugin's `awaitApproval` calls `register(approvalId)` and awaits the returned Promise\n * (this is what genuinely PAUSES the SDK run — the SDK `pre_tool_call` hook is awaited). The\n * approve route calls `resolve(approvalId, approved)` to settle it. A per-approval timeout settles\n * the Promise deterministically per the `@HumanInTheLoop` `onTimeout` policy so a hung approval\n * never leaks the paused stream.\n *\n * Single-process contract (ADR 0038 / plan Drawback 2): a multi-instance deploy needs a shared\n * registry — the interface is injectable so a durable impl (Redis, etc.) slots in without touching\n * the harness. We do NOT build a durable store now (YAGNI).\n */\n// The timeout policy vocabulary is owned by the `@HumanInTheLoop` decorator (DRY / G12) — reuse it\n// rather than re-declaring the union, so the two can never drift.\nimport type { TimeoutAction } from '@theokit/agents'\n\nexport type { TimeoutAction }\n\nexport interface RegisterOptions {\n  /** Milliseconds before the approval auto-settles per `onTimeout`. */\n  timeoutMs: number\n  /**\n   * What a timeout means. Only `'proceed'` auto-approves; `'abort'` and `'retry'` both deny — the\n   * registry does NOT implement retry semantics (a timed-out `'retry'` is a deny, not a re-prompt).\n   */\n  onTimeout: TimeoutAction\n}\n\nexport interface ApprovalRegistry {\n  /** Register a pending approval; the returned Promise settles on `resolve` or timeout. */\n  register(approvalId: string, opts: RegisterOptions): Promise<boolean>\n  /** Settle a pending approval. Returns false if the id is unknown or already settled. */\n  resolve(approvalId: string, approved: boolean): boolean\n}\n\ninterface Pending {\n  settle: (approved: boolean) => void\n  timer: ReturnType<typeof setTimeout>\n}\n\n/**\n * The one process-wide registry the stream mount (`mountAgent`) and the approve route share.\n *\n * The in-process impl holds LIVE Promise resolvers in memory — the approval a request awaits and\n * the approval the route resolves MUST be the same object, so a single instance per process is not\n * a convenience but a correctness requirement. Lazily created; a durable/multi-instance deploy\n * swaps this accessor for a shared-store impl (ADR 0038 / plan Drawback 2) without touching callers.\n * Tests use {@link createInProcessApprovalRegistry} directly — never this singleton.\n */\nlet serverRegistry: ApprovalRegistry | undefined\nexport function getApprovalRegistry(): ApprovalRegistry {\n  serverRegistry ??= createInProcessApprovalRegistry()\n  return serverRegistry\n}\n\nexport function createInProcessApprovalRegistry(): ApprovalRegistry {\n  const pending = new Map<string, Pending>()\n\n  return {\n    register(approvalId, opts) {\n      return new Promise<boolean>((resolve) => {\n        const settle = (approved: boolean): void => {\n          const entry = pending.get(approvalId)\n          if (!entry) return\n          clearTimeout(entry.timer)\n          pending.delete(approvalId)\n          resolve(approved)\n        }\n        // 'proceed' → allow on timeout; 'abort'/'retry' → deny on timeout.\n        const timer = setTimeout(() => {\n          settle(opts.onTimeout === 'proceed')\n        }, opts.timeoutMs)\n        pending.set(approvalId, { settle, timer })\n      })\n    },\n    resolve(approvalId, approved) {\n      const entry = pending.get(approvalId)\n      if (!entry) return false\n      entry.settle(approved)\n      return true\n    },\n  }\n}\n"],"mappings":";;;;AAyDA,IAAM,mBAAyC;AAAA,EAC7C;AAAA,IACE,MAAM;AAAA,IACN,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,UAAU;AAAA,EACZ;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,UAAU;AAAA,EACZ;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,UAAU;AAAA,EACZ;AACF;AAMA,IAAM,WAAiC,CAAC,GAAG,gBAAgB;AAkDpD,SAAS,kBAAoC;AAClD,QAAM,SAAS,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,WAAW,EAAE,QAAQ;AACnE,aAAW,QAAQ,QAAQ;AACzB,UAAM,SAAS,QAAQ,IAAI,KAAK,MAAM;AACtC,QAAI,UAAU,OAAO,SAAS,GAAG;AAC/B,aAAO;AAAA,QACL,MAAM,KAAK;AAAA,QACX;AAAA,QACA,SAAS,KAAK;AAAA,MAChB;AAAA,IACF;AAAA,EACF;AAEA,QAAM,UAAU,OAAO,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,MAAM;AACvD,QAAM,IAAI;AAAA,IACR,6DAA6D,OAAO;AAAA,EAEtE;AACF;;;ACpGA,IAAI;AACG,SAAS,sBAAwC;AACtD,qBAAmB,gCAAgC;AACnD,SAAO;AACT;AAEO,SAAS,kCAAoD;AAClE,QAAM,UAAU,oBAAI,IAAqB;AAEzC,SAAO;AAAA,IACL,SAAS,YAAY,MAAM;AACzB,aAAO,IAAI,QAAiB,CAAC,YAAY;AACvC,cAAM,SAAS,CAAC,aAA4B;AAC1C,gBAAM,QAAQ,QAAQ,IAAI,UAAU;AACpC,cAAI,CAAC,MAAO;AACZ,uBAAa,MAAM,KAAK;AACxB,kBAAQ,OAAO,UAAU;AACzB,kBAAQ,QAAQ;AAAA,QAClB;AAEA,cAAM,QAAQ,WAAW,MAAM;AAC7B,iBAAO,KAAK,cAAc,SAAS;AAAA,QACrC,GAAG,KAAK,SAAS;AACjB,gBAAQ,IAAI,YAAY,EAAE,QAAQ,MAAM,CAAC;AAAA,MAC3C,CAAC;AAAA,IACH;AAAA,IACA,QAAQ,YAAY,UAAU;AAC5B,YAAM,QAAQ,QAAQ,IAAI,UAAU;AACpC,UAAI,CAAC,MAAO,QAAO;AACnB,YAAM,OAAO,QAAQ;AACrB,aAAO;AAAA,IACT;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/server/agent/provider-resolver.ts","../src/server/agent/approval-registry.ts"],"sourcesContent":["/**\n * Provider Resolver — Strategy + Registry pattern (FAANG-grade).\n *\n * Inspiração: Dapr Conversation Registry (`dapr/pkg/components/conversation/registry.go`)\n * + Encore Manager provider array (`encore/runtimes/go/pubsub/manager_internal.go`).\n *\n * Princípio: provider routing é responsabilidade do FRAMEWORK, não do consumer.\n * Consumer template usa `model: { id: 'gpt-4o-mini' }` puro — sem conditionals.\n *\n * Wire protocol: OpenAI Chat Completions (universal — implementado por todos\n * os providers: OpenRouter, Groq, Mistral, Together, Anthropic via proxy, etc).\n *\n * Resolução por prioridade (FIRST match wins):\n *   1. OPENROUTER_API_KEY → baseUrl=openrouter.ai (gateway multi-modelo)\n *   2. OPENAI_API_KEY     → baseUrl=api.openai.com\n *   3. ANTHROPIC_API_KEY  → direct Anthropic (Messages API, não OpenAI-compat)\n *\n * Escape hatch: `options.apiKey` explícito SOBREPÕE auto-resolution\n * (consumer pode forçar provider específico se quiser).\n */\n\n/**\n * Provider configuration descriptor — Registry entry shape.\n *\n * @public\n */\nexport interface ProviderDescriptor {\n  /** Stable name used internally — não exposto no wire. */\n  name: string\n  /** Environment variable that holds the API key for this provider. */\n  envKey: string\n  /** Base URL for the provider's OpenAI-compatible (or native) API. */\n  baseUrl: string\n  /** Resolution priority (lower = higher priority). FIRST match wins. */\n  priority: number\n}\n\n/**\n * Resolved provider configuration — output of `resolveProvider()`.\n *\n * @public\n */\nexport interface ResolvedProvider {\n  name: string\n  apiKey: string\n  baseUrl: string\n}\n\n/**\n * Default provider registry. Order = priority (first = highest).\n *\n * Adding a new provider:\n *   1. Append entry below (or register via `registerProvider()`).\n *   2. Set `envKey` matching the user's env var convention.\n *   3. Set `baseUrl` to the OpenAI-compat endpoint (or native if not compat).\n *   4. Provider name used in telemetry/logs only — never wire-exposed.\n */\nconst DEFAULT_REGISTRY: ProviderDescriptor[] = [\n  {\n    name: 'openrouter',\n    envKey: 'OPENROUTER_API_KEY',\n    baseUrl: 'https://openrouter.ai/api/v1',\n    priority: 1,\n  },\n  {\n    name: 'openai',\n    envKey: 'OPENAI_API_KEY',\n    baseUrl: 'https://api.openai.com/v1',\n    priority: 2,\n  },\n  {\n    name: 'anthropic',\n    envKey: 'ANTHROPIC_API_KEY',\n    baseUrl: 'https://api.anthropic.com',\n    priority: 3,\n  },\n]\n\n/**\n * Runtime registry — copy of DEFAULT_REGISTRY mutable via registerProvider().\n * Sorted by priority on every resolve (stable, O(n log n) — n <= ~10 providers).\n */\nconst registry: ProviderDescriptor[] = [...DEFAULT_REGISTRY]\n\n/**\n * Register a new provider (Registry pattern — runtime extension point).\n * Useful for self-hosted endpoints or custom providers without touching theokit src.\n *\n * @example\n * registerProvider({\n *   name: 'self-hosted',\n *   envKey: 'SELF_HOSTED_API_KEY',\n *   baseUrl: 'https://llm.internal.acme.com/v1',\n *   priority: 0, // highest priority\n * })\n *\n * @public\n */\nexport function registerProvider(descriptor: ProviderDescriptor): void {\n  // Idempotent — replace existing by name.\n  const idx = registry.findIndex((p) => p.name === descriptor.name)\n  if (idx >= 0) registry[idx] = descriptor\n  else registry.push(descriptor)\n}\n\n/**\n * Reset registry to DEFAULT_REGISTRY (test-only / dev escape hatch).\n *\n * @public\n */\nexport function resetProviderRegistry(): void {\n  registry.length = 0\n  registry.push(...DEFAULT_REGISTRY)\n}\n\n/**\n * Get current registry snapshot (read-only — inspection).\n *\n * @public\n */\nexport function listProviders(): readonly ProviderDescriptor[] {\n  return [...registry].sort((a, b) => a.priority - b.priority)\n}\n\n/**\n * Resolve provider from env vars by priority. FIRST env var found wins.\n *\n * @returns ResolvedProvider with apiKey + baseUrl + name\n * @throws Error if NO provider env var is set (actionable message)\n *\n * @public\n */\nexport function resolveProvider(): ResolvedProvider {\n  const sorted = [...registry].sort((a, b) => a.priority - b.priority)\n  for (const desc of sorted) {\n    const apiKey = process.env[desc.envKey]\n    if (apiKey && apiKey.length > 0) {\n      return {\n        name: desc.name,\n        apiKey,\n        baseUrl: desc.baseUrl,\n      }\n    }\n  }\n  // No env var found — emit actionable error.\n  const envKeys = sorted.map((p) => p.envKey).join(' OR ')\n  throw new Error(\n    `No LLM provider API key found in environment. Set one of: ${envKeys}. ` +\n      `Get a free OpenRouter key at https://openrouter.ai/keys (recommended — one key, many models).`,\n  )\n}\n\n/**\n * Try to resolve — does NOT throw. Returns null if no provider available.\n * Useful for graceful degradation (e.g., mock mode).\n *\n * @public\n */\nexport function tryResolveProvider(): ResolvedProvider | null {\n  try {\n    return resolveProvider()\n  } catch {\n    return null\n  }\n}\n","/**\n * M4 (theokit-ai-first) — the in-process HITL approval registry.\n *\n * The HITL plugin's `awaitApproval` calls `register(approvalId)` and awaits the returned Promise\n * (this is what genuinely PAUSES the SDK run — the SDK `pre_tool_call` hook is awaited). The\n * approve route calls `resolve(approvalId, approved)` to settle it. A per-approval timeout settles\n * the Promise deterministically per the `@HumanInTheLoop` `onTimeout` policy so a hung approval\n * never leaks the paused stream.\n *\n * Single-process contract (ADR 0038 / plan Drawback 2): a multi-instance deploy needs a shared\n * registry — the interface is injectable so a durable impl (Redis, etc.) slots in without touching\n * the harness. We do NOT build a durable store now (YAGNI).\n */\n// The timeout policy vocabulary is owned by the `@HumanInTheLoop` decorator (DRY / G12) — reuse it\n// rather than re-declaring the union, so the two can never drift.\nimport type { TimeoutAction } from '@theokit/agents'\n\nexport type { TimeoutAction }\n\nexport interface RegisterOptions {\n  /** Milliseconds before the approval auto-settles per `onTimeout`. */\n  timeoutMs: number\n  /**\n   * What a timeout means. Only `'proceed'` auto-approves; `'abort'` and `'retry'` both deny — the\n   * registry does NOT implement retry semantics (a timed-out `'retry'` is a deny, not a re-prompt).\n   */\n  onTimeout: TimeoutAction\n  /** M14 — the gated tool name, surfaced by `list()` (optional; absent for legacy callers). */\n  toolName?: string\n  /** M14 — the approval question, surfaced by `list()` (optional). */\n  question?: string\n  /**\n   * M20 — an optional JSON-schema descriptor of the custom payload the approver may attach. Carried\n   * verbatim into `list()` + the `approval_required` event so the UI knows what to collect. Kept as\n   * a plain JSON object (not a live Zod schema) so the registry stays serializable and SDK-free.\n   */\n  payloadSchema?: Record<string, unknown>\n}\n\n/**\n * M20 — a settled HITL decision. `approved` is the allow/deny bit (backward-compatible with the\n * legacy boolean); `reason` + `payload` are the optional approver-attached extras that surface to\n * the model (on denial, via the veto message) and to the app/UI.\n */\nexport interface ApprovalDecision {\n  approved: boolean\n  reason?: string\n  payload?: unknown\n}\n\n/** M14 — a pending approval as surfaced by {@link ApprovalRegistry.list}. */\nexport interface PendingApproval {\n  approvalId: string\n  toolName?: string\n  question?: string\n  /** Epoch millis when the pending approval auto-settles (registeredAt + timeoutMs). */\n  expiresAt: number\n  /** M20 — the declared custom-payload schema, if the gated tool declares one. */\n  payloadSchema?: Record<string, unknown>\n}\n\nexport interface ApprovalRegistry {\n  /**\n   * Register a pending approval; the returned Promise settles with the full {@link ApprovalDecision}\n   * on `resolve` or timeout (M20 — was a bare boolean pre-M20).\n   */\n  register(approvalId: string, opts: RegisterOptions): Promise<ApprovalDecision>\n  /**\n   * Settle a pending approval. Accepts a full {@link ApprovalDecision} OR a bare boolean (coerced to\n   * `{ approved }` — backward-compatible). Returns false if the id is unknown or already settled.\n   */\n  resolve(approvalId: string, decision: boolean | ApprovalDecision): boolean\n  /** M14 — list the currently-pending approvals (process-wide; single-process contract). */\n  list(): PendingApproval[]\n}\n\ninterface Pending {\n  settle: (decision: ApprovalDecision) => void\n  timer: ReturnType<typeof setTimeout>\n  info: PendingApproval\n}\n\n/**\n * The one process-wide registry the stream mount (`mountAgent`) and the approve route share.\n *\n * The in-process impl holds LIVE Promise resolvers in memory — the approval a request awaits and\n * the approval the route resolves MUST be the same object, so a single instance per process is not\n * a convenience but a correctness requirement. Lazily created; a durable/multi-instance deploy\n * swaps this accessor for a shared-store impl (ADR 0038 / plan Drawback 2) without touching callers.\n * Tests use {@link createInProcessApprovalRegistry} directly — never this singleton.\n */\nlet serverRegistry: ApprovalRegistry | undefined\nexport function getApprovalRegistry(): ApprovalRegistry {\n  serverRegistry ??= createInProcessApprovalRegistry()\n  return serverRegistry\n}\n\nexport function createInProcessApprovalRegistry(): ApprovalRegistry {\n  const pending = new Map<string, Pending>()\n\n  return {\n    register(approvalId, opts) {\n      return new Promise<ApprovalDecision>((resolve) => {\n        const settle = (decision: ApprovalDecision): void => {\n          const entry = pending.get(approvalId)\n          if (!entry) return\n          clearTimeout(entry.timer)\n          pending.delete(approvalId)\n          resolve(decision)\n        }\n        // 'proceed' → allow on timeout; 'abort'/'retry' → deny on timeout.\n        const timer = setTimeout(() => {\n          settle({ approved: opts.onTimeout === 'proceed' })\n        }, opts.timeoutMs)\n        const info: PendingApproval = {\n          approvalId,\n          toolName: opts.toolName,\n          question: opts.question,\n          expiresAt: Date.now() + opts.timeoutMs,\n          ...(opts.payloadSchema !== undefined ? { payloadSchema: opts.payloadSchema } : {}),\n        }\n        pending.set(approvalId, { settle, timer, info })\n      })\n    },\n    resolve(approvalId, decision) {\n      const entry = pending.get(approvalId)\n      if (!entry) return false\n      // M20 — coerce the legacy bare-boolean form to a decision object.\n      entry.settle(typeof decision === 'boolean' ? { approved: decision } : decision)\n      return true\n    },\n    list() {\n      return [...pending.values()].map((p) => p.info)\n    },\n  }\n}\n"],"mappings":";;;;AAyDA,IAAM,mBAAyC;AAAA,EAC7C;AAAA,IACE,MAAM;AAAA,IACN,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,UAAU;AAAA,EACZ;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,UAAU;AAAA,EACZ;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,UAAU;AAAA,EACZ;AACF;AAMA,IAAM,WAAiC,CAAC,GAAG,gBAAgB;AAkDpD,SAAS,kBAAoC;AAClD,QAAM,SAAS,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,WAAW,EAAE,QAAQ;AACnE,aAAW,QAAQ,QAAQ;AACzB,UAAM,SAAS,QAAQ,IAAI,KAAK,MAAM;AACtC,QAAI,UAAU,OAAO,SAAS,GAAG;AAC/B,aAAO;AAAA,QACL,MAAM,KAAK;AAAA,QACX;AAAA,QACA,SAAS,KAAK;AAAA,MAChB;AAAA,IACF;AAAA,EACF;AAEA,QAAM,UAAU,OAAO,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,MAAM;AACvD,QAAM,IAAI;AAAA,IACR,6DAA6D,OAAO;AAAA,EAEtE;AACF;;;AC3DA,IAAI;AACG,SAAS,sBAAwC;AACtD,qBAAmB,gCAAgC;AACnD,SAAO;AACT;AAEO,SAAS,kCAAoD;AAClE,QAAM,UAAU,oBAAI,IAAqB;AAEzC,SAAO;AAAA,IACL,SAAS,YAAY,MAAM;AACzB,aAAO,IAAI,QAA0B,CAAC,YAAY;AAChD,cAAM,SAAS,CAAC,aAAqC;AACnD,gBAAM,QAAQ,QAAQ,IAAI,UAAU;AACpC,cAAI,CAAC,MAAO;AACZ,uBAAa,MAAM,KAAK;AACxB,kBAAQ,OAAO,UAAU;AACzB,kBAAQ,QAAQ;AAAA,QAClB;AAEA,cAAM,QAAQ,WAAW,MAAM;AAC7B,iBAAO,EAAE,UAAU,KAAK,cAAc,UAAU,CAAC;AAAA,QACnD,GAAG,KAAK,SAAS;AACjB,cAAM,OAAwB;AAAA,UAC5B;AAAA,UACA,UAAU,KAAK;AAAA,UACf,UAAU,KAAK;AAAA,UACf,WAAW,KAAK,IAAI,IAAI,KAAK;AAAA,UAC7B,GAAI,KAAK,kBAAkB,SAAY,EAAE,eAAe,KAAK,cAAc,IAAI,CAAC;AAAA,QAClF;AACA,gBAAQ,IAAI,YAAY,EAAE,QAAQ,OAAO,KAAK,CAAC;AAAA,MACjD,CAAC;AAAA,IACH;AAAA,IACA,QAAQ,YAAY,UAAU;AAC5B,YAAM,QAAQ,QAAQ,IAAI,UAAU;AACpC,UAAI,CAAC,MAAO,QAAO;AAEnB,YAAM,OAAO,OAAO,aAAa,YAAY,EAAE,UAAU,SAAS,IAAI,QAAQ;AAC9E,aAAO;AAAA,IACT;AAAA,IACA,OAAO;AACL,aAAO,CAAC,GAAG,QAAQ,OAAO,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI;AAAA,IAChD;AAAA,EACF;AACF;","names":[]}