theokit 0.4.0-beta.0 → 0.4.0

package/dist/server/index.js

@@ -1,16 +1,131 @@
+import {
+  serverErrorToEnvelope
+} from "../chunk-TQYSPYKU.js";
+import {
+  BodyTooLargeError,
+  DEFAULT_MAX_BODY_BYTES,
+  defineWebhook,
+  dispatchWebhook,
+  readRawBody,
+  timingSafeEqual
+} from "../chunk-UUFYP2UM.js";
+import {
+  DuplicateJobNameError,
+  InMemoryJobBackend,
+  JOB_MANIFEST_SCHEMA_VERSION,
+  NonRetryableError,
+  PostgresJobBackend,
+  buildJobManifest,
+  createJobRunner,
+  defineJob,
+  scanJobs,
+  writeJobManifest
+} from "../chunk-4S6YHNG2.js";
+import {
+  ConsoleObservabilityAdapter,
+  NoopObservabilityAdapter,
+  NoopSpan,
+  SpanImpl,
+  TheoCloudObservabilityAdapter,
+  createObservabilityPlugin,
+  defineObservabilityAdapter,
+  resolveAdapter,
+  serializeSpansToOtlp
+} from "../chunk-KI7OWQUX.js";
+import "../chunk-NPMCKOX4.js";
+import {
+  createRouteRateLimiter,
+  createRouteRateLimiterWeb,
+  deriveKey,
+  deriveKeyFromRequest,
+  matchRoutePattern
+} from "../chunk-ASDXVRJD.js";
+import {
+  ChannelManager
+} from "../chunk-NM4WF3XD.js";
+import "../chunk-E3JH6YUM.js";
 import {
   generateManifest,
   loadManifest,
   writeManifest
-} from "../chunk-2VQKDRVF.js";
+} from "../chunk-MR7OLIC6.js";
+import "../chunk-JHEAWR3L.js";
+import {
+  StorageManager,
+  getStorageManager,
+  useDatabase,
+  useUnstorage
+} from "../chunk-ESC54TAK.js";
+import {
+  _resetEnvCache,
+  jsonTransformer,
+  loadEnv,
+  resolveTransformer,
+  superjsonTransformer
+} from "../chunk-PIVX3DYW.js";
+import {
+  findSuggestion,
+  levenshtein
+} from "../chunk-5QW7IQQU.js";
+import {
+  DuplicateDecorationError,
+  DuplicatePluginError,
+  InvalidPluginShapeError,
+  PluginRunner,
+  createPluginRunnerFromConfig
+} from "../chunk-IAJ2JVEH.js";
+import {
+  InMemoryStore,
+  createRateLimiter,
+  createRateLimiterWeb
+} from "../chunk-VMEWD57H.js";
+import {
+  createProductionLoader,
+  createViteLoader
+} from "../chunk-JQSKBMXP.js";
+import {
+  compilePattern,
+  matchRoute,
+  scanServerRoutes,
+  scanWebSocketRoutes
+} from "../chunk-OLPB36O2.js";
+import {
+  ActionScanError,
+  scanServerActions,
+  scanServerActionsEnriched
+} from "../chunk-R7OC6UDK.js";
+import "../chunk-WSJKACWB.js";
+import {
+  CSP_REPORT_PATH,
+  CSRF_READINESS_PATH,
+  CSRF_READINESS_RESET_PATH,
+  CsrfReadinessStore,
+  DEFAULT_CSP,
+  DEFAULT_PERMISSIONS_POLICY,
+  applySecurityHeaders,
+  buildSecurityHeaders,
+  handleCspReport,
+  handleCspReportRequest,
+  handleCsrfReadiness,
+  handleCsrfReadinessRequest,
+  normalizeLegacy,
+  normalizeNew
+} from "../chunk-B3L3TJVF.js";
+import {
+  __resetSdkForTests,
+  __setSdkForTests,
+  createConversationHistory,
+  errorToEvent,
+  streamAgentRun
+} from "../chunk-RESN62GB.js";
 import {
   _resetKeyCacheForTests,
   assertProductionSecret,
   checkThrottle,
   clearOidcCache,
   createSessionManager,
+  createSessionManagerWeb,
   decrypt,
-  deleteCookie,
   discoverOidcProvider,
   encrypt,
   generateBackupCodes,
@@ -18,22 +133,23 @@ import {
   generatePkceChallenge,
   generateTotp,
   generateTotpSecret,
-  getCookie,
-  parseCookieHeader,
   pkceChallengeFromVerifier,
   recordAttempt,
   rotateIfNeeded,
-  setCookie,
+  rotateIfNeededWeb,
   totpUri,
   verifyBackupCode,
   verifyOAuthState,
   verifyTotp
-} from "../chunk-VRHXOKRP.js";
+} from "../chunk-NZXH2LQQ.js";
+import {
+  generateNonce
+} from "../chunk-C3ZZ56YZ.js";
 import {
   InMemoryUsageStorage,
   trackAgentRun,
   trackAgentTools
-} from "../chunk-64JI5LTO.js";
+} from "../chunk-RMU7EBRO.js";
 import {
   CRON_MANIFEST_SCHEMA_VERSION,
   DuplicateCronNameError,
@@ -49,1144 +165,176 @@ import {
   translateCronToVercel,
   validateCronSchedule,
   writeCronManifest
-} from "../chunk-4QTKSLTO.js";
+} from "../chunk-K4M64WD6.js";
+import "../chunk-Y4H3JNVK.js";
+import "../chunk-6NEXVBPY.js";
+import "../chunk-7MQOHNHE.js";
+import "../chunk-X2VVCJ4V.js";
 import {
-  DuplicateJobNameError,
-  InMemoryJobBackend,
-  JOB_MANIFEST_SCHEMA_VERSION,
-  NonRetryableError,
-  PostgresJobBackend,
-  buildJobManifest,
-  createJobRunner,
-  defineJob,
-  scanJobs,
-  writeJobManifest
-} from "../chunk-C52GSJPF.js";
+  defineAction,
+  defineAgentEndpoint,
+  defineAgentTool,
+  defineChannel,
+  defineMiddleware,
+  defineRoute,
+  defineTheoPlugin,
+  defineWebChannel,
+  defineWebSocket,
+  defineWebSocketWeb
+} from "../chunk-H4J2LECY.js";
 import {
-  extractTraceContext,
-  generateNewTraceContext
-} from "../chunk-YLBSSEHX.js";
+  MAX_ERROR_HTML_BYTES,
+  loadCustomErrorPages,
+  serveStaticFile
+} from "../chunk-FI7MPTJW.js";
 import {
   ActionError,
   ActionInputError,
   BATCH_PATH,
   BatchPathConflictError,
-  CSP_REPORT_PATH,
-  CSRF_READINESS_PATH,
-  CSRF_READINESS_RESET_PATH,
-  CSRF_WARN_CODE,
-  CSRF_WARN_DOCS_URL,
-  CsrfReadinessStore,
-  DEFAULT_CSP,
-  DEFAULT_PERMISSIONS_POLICY,
-  DuplicateDecorationError,
-  DuplicatePluginError,
-  FileTooLargeError,
-  InMemoryStore,
-  InvalidPluginShapeError,
-  JsonStdoutSink,
-  PluginRunner,
   STRIPPED_HEADERS,
   TRACE_HEADER,
   TRACE_PARENT_HEADER,
-  _resetEnvCache,
   _resetMiddlewareCacheForTests,
-  _resetWarnOnceForTests,
-  applySecurityHeaders,
-  buildSecurityHeaders,
   createCorsHandler,
-  createLogger,
-  createNoOpLogger,
-  createPluginRunnerFromConfig,
-  createProductionLoader,
-  createRateLimiter,
-  createViteLoader,
-  enforceCsrf,
+  createCorsWebHandler,
   executeAction,
   executeRoute,
   extractTraceId,
+  extractTraceIdFromRequest,
   extractUniversalIssues,
-  findSuggestion,
   handleBatchRequest,
-  handleCspReport,
-  handleCsrfReadiness,
   isActionError,
   isInputError,
-  jsonTransformer,
-  levenshtein,
-  loadEnv,
-  logRequest,
-  matchDisallowed,
   matchesOrigin,
-  normalizeLegacy,
-  normalizeNew,
-  parseRequestBody,
   parseTraceparent,
-  resolveTransformer,
   runMiddlewareAndContext,
-  safeAudit,
-  scanMiddlewares,
   sendError,
-  sendJson,
-  superjsonTransformer,
-  validateCsrf,
-  warnOnce
-} from "../chunk-CZM6WWWS.js";
-import {
-  compilePattern,
-  matchRoute,
-  scanServerRoutes,
-  scanWebSocketRoutes
-} from "../chunk-B6RP57M3.js";
-import {
-  ActionScanError,
-  scanServerActions,
-  scanServerActionsEnriched
-} from "../chunk-7TOMTMHT.js";
-import {
-  AuthRequiredError,
-  generateNonce,
-  requireAuth
-} from "../chunk-PB4GR7EP.js";
+  sendJson
+} from "../chunk-5Z2727GV.js";
 import {
   DuplicateContextKeyError,
   createOutbox,
   createOutboxDispatcher,
   createQueueClient
 } from "../chunk-GY5Q27BJ.js";
-import "../chunk-X2VVCJ4V.js";
-import "../chunk-WSJKACWB.js";
 import {
-  __require
-} from "../chunk-DGUM43GV.js";
-
-// src/server/define/define-route.ts
-function defineRoute(config) {
-  return config;
-}
-
-// src/server/define/define-action.ts
-function defineAction(config) {
-  return config;
-}
-
-// src/server/define/define-middleware.ts
-function defineMiddleware(handler) {
-  return handler;
-}
-
-// src/server/define/define-agent-endpoint.ts
-var SSE_HEADERS = {
-  "content-type": "text/event-stream",
-  "cache-control": "no-cache, no-transform",
-  connection: "keep-alive"
-};
-function encodeSSE(event) {
-  return new TextEncoder().encode(`data: ${JSON.stringify(event)}
-
-`);
-}
-function resolveAbortSignal(request) {
-  if (typeof request !== "object" || request === null) {
-    return new AbortController().signal;
-  }
-  const r = request;
-  if (typeof r.signal === "object" && r.signal !== null && "aborted" in r.signal && typeof r.signal.addEventListener === "function") {
-    return r.signal;
-  }
-  const controller = new AbortController();
-  if (r.aborted === true) controller.abort();
-  if (typeof r.on === "function") {
-    r.on("close", () => {
-      if (!controller.signal.aborted) controller.abort();
-    });
-    r.on("aborted", () => {
-      if (!controller.signal.aborted) controller.abort();
-    });
-  }
-  return controller.signal;
-}
-function defineAgentEndpoint(config) {
-  return {
-    handler: async ({ request, ctx, body, query, params }) => {
-      const cookieHeaders = new Headers();
-      const signal = resolveAbortSignal(request);
-      const generator = config.handler({
-        request,
-        ctx,
-        body,
-        query,
-        params,
-        cookieHeaders,
-        signal
-      });
-      let firstResult;
-      let primeError;
-      try {
-        firstResult = await generator.next();
-      } catch (err) {
-        primeError = err;
-        firstResult = { value: void 0, done: true };
-      }
-      const responseHeaders = new Headers(SSE_HEADERS);
-      for (const value of cookieHeaders.getSetCookie()) {
-        responseHeaders.append("set-cookie", value);
-      }
-      const stream = new ReadableStream({
-        async start(controller) {
-          const onAbort = () => {
-            void generator.return(void 0);
-          };
-          if (signal.aborted) {
-            controller.close();
-            return;
-          }
-          signal.addEventListener("abort", onAbort, { once: true });
-          try {
-            if (primeError !== void 0) {
-              let message;
-              if (primeError instanceof Error) {
-                message = primeError.message;
-              } else if (typeof primeError === "string") {
-                message = primeError;
-              } else {
-                message = "agent handler failed during setup";
-              }
-              controller.enqueue(encodeSSE({ type: "error", message }));
-              return;
-            }
-            if (firstResult.done !== true) {
-              controller.enqueue(encodeSSE(firstResult.value));
-            } else {
-              return;
-            }
-            for await (const event of generator) {
-              if (signal.aborted) break;
-              controller.enqueue(encodeSSE(event));
-            }
-          } catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            controller.enqueue(encodeSSE({ type: "error", message }));
-          } finally {
-            signal.removeEventListener("abort", onAbort);
-            controller.close();
-          }
-        },
-        cancel() {
-          void generator.return(void 0);
-        }
-      });
-      return new Response(stream, { headers: responseHeaders });
-    }
-  };
-}
-
-// src/server/define/define-agent-tool.ts
-import { zodToJsonSchema } from "zod-to-json-schema";
-var TOOL_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
-function isZodObject(schema) {
-  let current = schema;
-  for (let depth = 0; depth < 10; depth++) {
-    const def = current._def;
-    if (def?.typeName === "ZodObject") return true;
-    if (def?.schema !== void 0) {
-      current = def.schema;
-      continue;
-    }
-    if (def?.innerType !== void 0) {
-      current = def.innerType;
-      continue;
-    }
-    return false;
-  }
-  return false;
-}
-function defineAgentTool(spec) {
-  if (!TOOL_NAME_REGEX.test(spec.name)) {
-    throw new Error(
-      `defineAgentTool: name must match ${TOOL_NAME_REGEX.source}. Got: ${JSON.stringify(spec.name)}`
-    );
-  }
-  if (!isZodObject(spec.inputSchema)) {
-    throw new Error("defineAgentTool: inputSchema must be a ZodObject (z.object({...}))");
-  }
-  if (spec.description.length === 0) {
-    console.warn(
-      `defineAgentTool(${JSON.stringify(spec.name)}): empty description degrades LLM tool selection \u2014 provide a one-sentence summary.`
-    );
-  }
-  const rawSchema = zodToJsonSchema(spec.inputSchema, {
-    target: "jsonSchema7",
-    $refStrategy: "none"
-  });
-  const { $schema: _$schema, ...inputSchema } = rawSchema;
-  return {
-    name: spec.name,
-    description: spec.description,
-    inputSchema,
-    handler: async (input) => {
-      const parsed = spec.inputSchema.parse(input);
-      return await spec.handler(parsed);
-    }
-  };
-}
-
-// src/server/define/define-websocket.ts
-function defineWebSocket(handler) {
-  return handler;
-}
-
-// src/server/define/define-channel.ts
-function defineChannel(handler) {
-  return handler;
-}
-
-// src/server/define/define-plugin.ts
-function defineTheoPlugin(plugin) {
-  return plugin;
-}
+  FileTooLargeError,
+  _resetWarnOnceForTests,
+  createLogger,
+  logRequest,
+  parseRequestBody,
+  warnOnce
+} from "../chunk-Z5IGLBWE.js";
+import {
+  scanMiddlewares
+} from "../chunk-ZEGYW52B.js";
+import {
+  CSRF_WARN_CODE,
+  CSRF_WARN_DOCS_URL,
+  enforceCsrf,
+  matchDisallowed,
+  validateCsrf,
+  validateCsrfRequest
+} from "../chunk-TSLSIRBR.js";
+import {
+  JsonStdoutSink,
+  createNoOpLogger,
+  safeAudit
+} from "../chunk-UD3LFGDL.js";
+import {
+  appendCookieToHeaders,
+  appendDeleteCookieToHeaders,
+  deleteCookie,
+  getCookie,
+  getCookieFromRequest,
+  parseCookieHeader,
+  serializeCookie,
+  setCookie
+} from "../chunk-ZJQ4O76G.js";
+import {
+  AuthRequiredError,
+  requireAuth
+} from "../chunk-4HBI7DHP.js";
+import "../chunk-DGUM43GV.js";
 
-// src/server/http/error-pages.ts
+// src/server/openapi/serve-docs.ts
 import { existsSync, readFileSync, statSync } from "fs";
 import { resolve } from "path";
-var MAX_ERROR_HTML_BYTES = 1048576;
-function loadIfSafe(dir, name) {
-  const path = resolve(dir, name);
-  if (!existsSync(path)) return void 0;
-  try {
-    const stat = statSync(path);
-    if (stat.size > MAX_ERROR_HTML_BYTES) {
-      console.warn(
-        `[theokit] Custom error page ${name} is ${stat.size} bytes (max ${MAX_ERROR_HTML_BYTES}); skipping.`
-      );
-      return void 0;
-    }
-    return readFileSync(path, "utf-8");
-  } catch (err) {
-    console.warn(`[theokit] Failed to read ${name}: ${err.message}`);
-    return void 0;
-  }
-}
-function loadCustomErrorPages(clientDir) {
-  return {
-    custom404Html: loadIfSafe(clientDir, "404.html"),
-    custom500Html: loadIfSafe(clientDir, "500.html")
-  };
-}
-
-// src/server/http/static.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, statSync as statSync2 } from "fs";
-import { resolve as resolve2, extname } from "path";
-var MIME_TYPES = {
-  ".html": "text/html",
-  ".js": "application/javascript",
-  ".mjs": "application/javascript",
-  ".css": "text/css",
-  ".json": "application/json",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".svg": "image/svg+xml",
-  ".ico": "image/x-icon",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-  ".ttf": "font/ttf",
-  ".txt": "text/plain",
-  ".map": "application/json"
-};
-function serveStaticFile(req, res, clientDir) {
-  const urlPath = (req.url ?? "/").split("?")[0];
-  const filePath = resolve2(clientDir, "." + urlPath);
-  if (!filePath.startsWith(clientDir)) {
-    res.writeHead(403);
-    res.end("Forbidden");
-    return true;
-  }
-  if (!existsSync2(filePath)) return false;
-  const stat = statSync2(filePath);
-  if (!stat.isFile()) return false;
-  const ext = extname(filePath);
-  const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
-  const content = readFileSync2(filePath);
-  res.writeHead(200, {
-    "Content-Type": contentType,
-    "Content-Length": content.length
-  });
-  res.end(content);
-  return true;
-}
-
-// src/server/agent/stream-agent-run.ts
-function safeJsonStringify(value) {
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return "[Unserializable]";
-  }
-}
-function safeArgs(args) {
-  if (typeof args === "object" && args !== null && !Array.isArray(args)) {
-    return args;
-  }
-  return {};
-}
-function isAssistant(msg) {
-  const m = msg;
-  return m.type === "assistant" && m.message != null && typeof m.message === "object" && Array.isArray(m.message.content);
-}
-function isToolCall(msg) {
-  const t = msg;
-  return t.type === "tool_call" && typeof t.name === "string" && typeof t.call_id === "string" && (t.status === "running" || t.status === "completed" || t.status === "error");
-}
-function isAgentRunError(err) {
-  if (!(err instanceof Error)) return false;
-  const e = err;
-  return "code" in e && typeof e.code === "string";
-}
-function errorToEvent(err, id) {
-  if (isAgentRunError(err)) {
-    const event2 = {
-      type: "error",
-      message: err.message,
-      code: err.code
-    };
-    if (err.provider !== void 0) event2.provider = err.provider;
-    if (err.retriable !== void 0) event2.retriable = err.retriable;
-    if (err.retryAfterMs !== void 0) event2.retryAfterMs = err.retryAfterMs;
-    if (id !== void 0) event2.id = id;
-    return event2;
-  }
-  let message;
-  if (err instanceof Error) {
-    message = err.message;
-  } else if (typeof err === "string") {
-    message = err;
-  } else if (err !== null && typeof err === "object" && "message" in err) {
-    const candidate = err.message;
-    message = typeof candidate === "string" ? candidate : "[object Object]";
-  } else if (err === null || err === void 0) {
-    message = String(err);
-  } else {
-    message = "[non-stringifiable error]";
-  }
-  const event = { type: "error", message };
-  if (id !== void 0) event.id = id;
-  return event;
-}
-function yieldFromToolCall(msg) {
-  if (msg.status === "running") {
-    return {
-      type: "tool_call",
-      name: msg.name,
-      args: safeArgs(msg.args),
-      id: msg.call_id
-    };
-  }
-  if (msg.status === "completed") {
-    const data = typeof msg.result === "string" ? msg.result : safeJsonStringify(msg.result);
-    return {
-      type: "tool_result",
-      name: msg.name,
-      data,
-      id: msg.call_id
-    };
-  }
-  const message = typeof msg.result === "string" ? msg.result : `Tool ${msg.name} failed`;
-  return { type: "error", message, id: msg.call_id };
-}
-async function* streamAgentRun(run) {
-  for await (const msg of run.stream()) {
-    if (isAssistant(msg)) {
-      for (const block of msg.message.content) {
-        if (block.type === "text" && typeof block.text === "string" && block.text.length > 0) {
-          yield { type: "message", content: block.text };
+var MAX_SPEC_BYTES = 10 * 1024 * 1024;
+var DEFAULT_CDN = "https://cdn.jsdelivr.net/npm/@scalar/api-reference";
+function createOpenApiHandler(opts = {}) {
+  const docsPath = opts.docsPath ?? "/api/docs";
+  const jsonPath = opts.openapiJsonPath ?? "/api/docs/openapi.json";
+  const specFile = resolve(opts.specFilePath ?? ".theo/openapi.json");
+  const title = opts.pageTitle ?? "API Reference";
+  const cdn = opts.cdnUrl ?? DEFAULT_CDN;
+  if (specFile.includes("..")) {
+    throw new Error(`[theokit:openapi] specFilePath must not contain ".." segments: ${specFile}`);
+  }
+  return (request) => {
+    if (request.method !== "GET") return null;
+    const url = new URL(request.url);
+    if (url.pathname === docsPath) {
+      const cdnHost = new URL(cdn).host;
+      return new Response(renderScalarHtml(title, jsonPath, cdn), {
+        status: 200,
+        headers: {
+          "content-type": "text/html; charset=utf-8",
+          "content-security-policy": `script-src 'self' 'unsafe-eval' ${cdnHost}; style-src 'self' 'unsafe-inline'; img-src 'self' data: ${cdnHost}; font-src 'self' data: ${cdnHost}; connect-src 'self' ${cdnHost}`
         }
-      }
-    } else if (isToolCall(msg)) {
-      yield yieldFromToolCall(msg);
+      });
     }
-  }
-  const result = await run.wait();
-  if (result.status === "error" && result.error !== void 0) {
-    yield errorToEvent(result.error);
-  }
-}
-
-// src/server/agent/provider-resolver.ts
-var DEFAULT_REGISTRY = [
-  {
-    name: "openrouter",
-    envKey: "OPENROUTER_API_KEY",
-    baseUrl: "https://openrouter.ai/api/v1",
-    priority: 1
-  },
-  {
-    name: "openai",
-    envKey: "OPENAI_API_KEY",
-    baseUrl: "https://api.openai.com/v1",
-    priority: 2
-  },
-  {
-    name: "anthropic",
-    envKey: "ANTHROPIC_API_KEY",
-    baseUrl: "https://api.anthropic.com",
-    priority: 3
-  }
-];
-var registry = [...DEFAULT_REGISTRY];
-function resolveProvider() {
-  const sorted = [...registry].sort((a, b) => a.priority - b.priority);
-  for (const desc of sorted) {
-    const apiKey = process.env[desc.envKey];
-    if (apiKey && apiKey.length > 0) {
-      return {
-        name: desc.name,
-        apiKey,
-        baseUrl: desc.baseUrl
-      };
+    if (url.pathname === jsonPath) {
+      return serveSpecFile(specFile);
     }
-  }
-  const envKeys = sorted.map((p) => p.envKey).join(" OR ");
-  throw new Error(
-    `No LLM provider API key found in environment. Set one of: ${envKeys}. Get a free OpenRouter key at https://openrouter.ai/keys (recommended \u2014 one key, many models).`
-  );
-}
-function tryResolveProvider() {
-  try {
-    return resolveProvider();
-  } catch {
     return null;
-  }
-}
-
-// src/server/agent/create-conversation-history.ts
-var sdkOverride = void 0;
-function __setSdkForTests(sdk) {
-  sdkOverride = sdk;
-}
-function __resetSdkForTests() {
-  sdkOverride = void 0;
-}
-async function loadSdk() {
-  if (sdkOverride === null) {
-    throw new Error(
-      "createConversationHistory requires @theokit/sdk. Install: pnpm add @theokit/sdk"
-    );
-  }
-  if (sdkOverride !== void 0) return sdkOverride;
-  try {
-    const { createRequire } = await import("module");
-    const requireFn = createRequire(import.meta.url);
-    const spec = "@theokit/sdk";
-    const mod = requireFn(spec);
-    return mod;
-  } catch (cause) {
-    throw new Error(
-      "createConversationHistory requires @theokit/sdk. Install: pnpm add @theokit/sdk",
-      { cause }
-    );
-  }
-}
-var DEFAULT_COOKIE_NAME = "theo_conversation";
-var DEFAULT_COOKIE_MAX_AGE = 60 * 60 * 24 * 30;
-var AGENT_ID_REGEX = /^[a-zA-Z0-9_-]{1,128}$/;
-function isValidAgentId(s) {
-  return typeof s === "string" && AGENT_ID_REGEX.test(s);
-}
-function readCookieValue(request, name) {
-  let raw;
-  const h = request.headers;
-  if (h === void 0) return void 0;
-  if (typeof h.get === "function") {
-    raw = h.get("cookie") ?? void 0;
-  } else {
-    raw = h.cookie;
-  }
-  if (raw === void 0 || raw.length === 0) return void 0;
-  const pairs = raw.split(/[;,]/);
-  for (const pair of pairs) {
-    const eq = pair.indexOf("=");
-    if (eq < 0) continue;
-    const k = pair.slice(0, eq).trim();
-    if (k === name) return pair.slice(eq + 1).trim();
-  }
-  return void 0;
-}
-function serializeCookie(name, value, options) {
-  const parts = [`${name}=${value}`];
-  if (options.path !== void 0) parts.push(`Path=${options.path}`);
-  if (options.maxAge !== void 0) parts.push(`Max-Age=${options.maxAge}`);
-  if (options.sameSite !== void 0) {
-    const v = options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1);
-    parts.push(`SameSite=${v}`);
-  }
-  if (options.httpOnly === true) parts.push("HttpOnly");
-  return parts.join("; ");
-}
-async function createConversationHistory(args) {
-  const cookieName = args.cookieName ?? DEFAULT_COOKIE_NAME;
-  const rawMaxAge = args.cookieMaxAge;
-  const cookieMaxAge = typeof rawMaxAge === "number" && rawMaxAge > 0 ? rawMaxAge : DEFAULT_COOKIE_MAX_AGE;
-  let conversationId;
-  let isNew = false;
-  const cookieOnRequest = readCookieValue(args.request, cookieName);
-  if (isValidAgentId(args.agentId)) {
-    conversationId = args.agentId;
-  } else if (args.session !== null && args.session !== void 0) {
-    const sId = args.session.conversationId;
-    if (isValidAgentId(sId)) conversationId = sId;
-  }
-  if (conversationId === void 0 && isValidAgentId(cookieOnRequest)) {
-    conversationId = cookieOnRequest;
-  }
-  if (conversationId === void 0) {
-    conversationId = crypto.randomUUID();
-    isNew = true;
-  }
-  const shouldIssueCookie = isNew || cookieOnRequest !== conversationId;
-  if (shouldIssueCookie && args.response !== void 0) {
-    const cookie = serializeCookie(cookieName, conversationId, {
-      httpOnly: true,
-      sameSite: "lax",
-      maxAge: cookieMaxAge,
-      path: "/"
-    });
-    args.response.headers.append("set-cookie", cookie);
-  }
-  const resolvedOptions = autoResolveProviderIfNeeded(args.options);
-  const sdk = await loadSdk();
-  const agent = await sdk.Agent.getOrCreate(conversationId, resolvedOptions);
-  return { agent, conversationId, isNew };
-}
-function autoResolveProviderIfNeeded(options) {
-  if (typeof options.apiKey === "string" && options.apiKey.length > 0) {
-    return options;
-  }
-  const resolved = tryResolveProvider();
-  if (resolved === null) {
-    throw new Error(
-      "No LLM provider API key found in environment. Set OPENROUTER_API_KEY (recommended \u2014 gateway to many models) OR OPENAI_API_KEY OR ANTHROPIC_API_KEY in your .env. Get a free OpenRouter key at https://openrouter.ai/keys. (Pass `options.apiKey` explicitly to bypass auto-resolution.)"
-    );
-  }
-  return {
-    ...options,
-    apiKey: resolved.apiKey,
-    providers: {
-      routes: [{ capability: "chat", provider: resolved.name, baseUrl: resolved.baseUrl }]
-    }
-  };
-}
-
-// src/server/rate-limit/rate-limit-per-route.ts
-import { createHash } from "crypto";
-function normalizePath(input) {
-  const noQuery = input.split("?")[0];
-  if (noQuery.length > 1 && noQuery.endsWith("/")) return noQuery.slice(0, -1);
-  return noQuery;
-}
-function matchRoutePattern(path, pattern) {
-  const canonical = normalizePath(path);
-  if (typeof pattern === "string") {
-    return canonical === normalizePath(pattern);
-  }
-  pattern.lastIndex = 0;
-  return pattern.test(canonical);
-}
-function hashFragment(input) {
-  return createHash("sha256").update(input).digest("base64url").slice(0, 16);
-}
-function readCookie(req, name) {
-  return parseCookieHeader(req.headers.cookie ?? void 0).get(name);
-}
-function deriveKey(req, keyBy, cookieName) {
-  if (typeof keyBy === "function") return keyBy(req);
-  const ip = req.socket?.remoteAddress ?? "unknown";
-  switch (keyBy) {
-    case "session": {
-      const cookie = readCookie(req, cookieName);
-      return cookie ? `session:${hashFragment(cookie)}` : `ip:${ip}`;
-    }
-    case "user": {
-      const userId = req.user?.id;
-      return userId ? `user:${userId}` : `ip:${ip}`;
-    }
-    case "ip":
-    default:
-      return `ip:${ip}`;
-  }
-}
-function createRouteRateLimiter(config) {
-  const isFlat = "windowMs" in config && "max" in config && !("default" in config) && !("routes" in config);
-  const cfg = isFlat ? { default: config } : config;
-  const store = cfg.store ?? new InMemoryStore();
-  if (!(store instanceof InMemoryStore)) {
-    throw new Error(
-      "createRouteRateLimiter: async RateLimitStore implementations require a dedicated async middleware path. Use the InMemoryStore default for the sync fa\xE7ade."
-    );
-  }
-  const inMemoryStore = store;
-  const keyBy = cfg.keyBy ?? "ip";
-  const cookieName = cfg.cookieName ?? "theo_session";
-  const patternList = [];
-  if (cfg.routes) {
-    for (const [pattern, c] of Object.entries(cfg.routes)) patternList.push([pattern, c]);
-  }
-  if (cfg.routePatterns) {
-    for (const tuple of cfg.routePatterns) patternList.push(tuple);
-  }
-  return function checkRouteRateLimit(req) {
-    const url = req.url ?? "";
-    let matched;
-    for (const [pattern, c] of patternList) {
-      if (matchRoutePattern(url, pattern)) {
-        matched = c;
-        break;
-      }
-    }
-    const effective = matched ?? cfg.default;
-    if (!effective) {
-      return { limited: false, headers: {} };
-    }
-    const bucketSuffix = typeof matched === "undefined" ? "*default*" : normalizePath(url);
-    const key = `${deriveKey(req, keyBy, cookieName)}|${bucketSuffix}`;
-    const state = inMemoryStore.incrSync(key, effective.windowMs);
-    if (state.count > effective.max) {
-      const retryAfter = Math.ceil((state.resetAt - Date.now()) / 1e3);
-      return {
-        limited: true,
-        headers: {
-          "X-RateLimit-Limit": String(effective.max),
-          "X-RateLimit-Remaining": "0",
-          "Retry-After": String(retryAfter)
-        }
-      };
-    }
-    return {
-      limited: false,
-      headers: {
-        "X-RateLimit-Limit": String(effective.max),
-        "X-RateLimit-Remaining": String(Math.max(0, effective.max - state.count))
-      }
-    };
   };
 }
-
-// src/server/realtime/channel-manager.ts
-var ChannelManager = class {
-  rooms = /* @__PURE__ */ new Map();
-  wsRooms = /* @__PURE__ */ new Map();
-  subscribe(ws, room) {
-    let roomSet = this.rooms.get(room);
-    if (!roomSet) {
-      roomSet = /* @__PURE__ */ new Set();
-      this.rooms.set(room, roomSet);
-    }
-    roomSet.add(ws);
-    let wsSet = this.wsRooms.get(ws);
-    if (!wsSet) {
-      wsSet = /* @__PURE__ */ new Set();
-      this.wsRooms.set(ws, wsSet);
-    }
-    wsSet.add(room);
-  }
-  unsubscribe(ws, room) {
-    this.rooms.get(room)?.delete(ws);
-    if (this.rooms.get(room)?.size === 0) this.rooms.delete(room);
-    this.wsRooms.get(ws)?.delete(room);
-    if (this.wsRooms.get(ws)?.size === 0) this.wsRooms.delete(ws);
-  }
-  broadcast(room, data, exclude) {
-    const clients = this.rooms.get(room);
-    if (!clients) return;
-    const msg = JSON.stringify(data);
-    for (const ws of clients) {
-      if (ws !== exclude) ws.send(msg);
-    }
-  }
-  broadcastAll(data) {
-    const msg = JSON.stringify(data);
-    const seen = /* @__PURE__ */ new Set();
-    for (const clients of this.rooms.values()) {
-      for (const ws of clients) {
-        if (!seen.has(ws)) {
-          ws.send(msg);
-          seen.add(ws);
-        }
-      }
-    }
-  }
-  getRoomSize(room) {
-    return this.rooms.get(room)?.size ?? 0;
-  }
-  cleanup(ws) {
-    const rooms = this.wsRooms.get(ws);
-    if (rooms) {
-      for (const room of rooms) {
-        this.rooms.get(room)?.delete(ws);
-        if (this.rooms.get(room)?.size === 0) this.rooms.delete(room);
-      }
-    }
-    this.wsRooms.delete(ws);
-  }
-};
-
-// src/server/storage/storage-manager.ts
-var StorageManager = class {
-  #config;
-  #dbPools = /* @__PURE__ */ new Map();
-  #redisClients = /* @__PURE__ */ new Map();
-  #genericClients = /* @__PURE__ */ new Map();
-  #adapters = /* @__PURE__ */ new Set();
-  #disposed = false;
-  /**
-   * Apply the storage config block from `theo.config.ts`. Second call warns
-   * and is ignored (D3). Reset only via `__resetForTests()`.
-   */
-  configure(config) {
-    if (this.#config !== void 0) {
-      console.warn("[theokit] StorageManager already configured; ignoring second configure() call");
-      return;
-    }
-    this.#config = config;
-  }
-  /**
-   * Generic cache + factory for ANY client (MySQL, Mongo, Turso, DynamoDB, …).
-   * Returns the cached client OR invokes the factory and caches its return.
-   *
-   * EC-1 FIX: cache-hit check uses `Map.has(name)`, NOT `cached !== undefined`.
-   * Factories returning `null` or `undefined` are valid (lazy connect, stubs);
-   * the `!== undefined` check would re-invoke the factory infinitely for
-   * undefined returns AND silently cache `null` cast as `T`.
-   *
-   * EC-2 (documented type hole): `useStorage<A>('x', fA)` followed by
-   * `useStorage<B>('x', fB)` returns the cached A cast as B. Same trade-off
-   * as `Map<string, unknown>` — caller is responsible for using unique names
-   * per type.
-   *
-   * Lifecycle: generic clients are NOT auto-drained by `dispose()`. Call
-   * `manager.register({ name, dispose })` separately to participate.
-   *
-   * Reserved name prefixes (do NOT use): `__pg:`, `__redis:`, `__unstorage:`,
-   * `__db0:` — these are used internally by the typed helpers.
-   */
-  useStorage(name, factory) {
-    if (this.#disposed) throw new Error("StorageManager is disposed");
-    if (this.#genericClients.has(name)) return this.#genericClients.get(name);
-    const client = factory();
-    this.#genericClients.set(name, client);
-    return client;
-  }
-  /**
-   * Return a Postgres pool for the named database. Lazy + cached. Factory
-   * invoked exactly once per `dbName` (D2).
-   *
-   * Throws if:
-   *   - manager is disposed
-   *   - `dbName` is not in `config.databases`
-   *   - the referenced server is not in `config.servers` (EC-2: deferred
-   *     cross-field validation surfaces here, not at configure time)
-   */
-  usePostgres(dbName, factory) {
-    if (this.#disposed) throw new Error("StorageManager is disposed");
-    const cached = this.#dbPools.get(dbName);
-    if (cached !== void 0) return cached;
-    const dbConfig = this.#config?.databases?.[dbName];
-    if (dbConfig === void 0) {
-      throw new Error(
-        `Database "${dbName}" not configured. Add it to theo.config.ts > storage.databases.`
-      );
-    }
-    const server = this.#config?.servers?.[dbConfig.server];
-    if (server === void 0) {
-      throw new Error(
-        `Server "${dbConfig.server}" referenced by database "${dbName}" not found in theo.config.ts > storage.servers.`
-      );
-    }
-    const pool = factory(server, dbConfig);
-    this.#dbPools.set(dbName, pool);
-    return pool;
-  }
-  /**
-   * Return a Redis client for the named server. Lazy + cached. Factory
-   * invoked exactly once per `serverName`.
-   */
-  useRedis(serverName, factory) {
-    if (this.#disposed) throw new Error("StorageManager is disposed");
-    const cached = this.#redisClients.get(serverName);
-    if (cached !== void 0) return cached;
-    const serverConfig = this.#config?.redis?.[serverName];
-    if (serverConfig === void 0) {
-      throw new Error(
-        `Redis server "${serverName}" not configured. Add it to theo.config.ts > storage.redis.`
-      );
-    }
-    const client = factory(serverConfig);
-    this.#redisClients.set(serverName, client);
-    return client;
-  }
-  /**
-   * Register an adapter for graceful shutdown coordination (D6).
-   *
-   * EC-4: throws if the manager is already disposed — prevents silent
-   * leaks in test seams that reset+reuse the manager.
-   */
-  register(adapter) {
-    if (this.#disposed) {
-      throw new Error(
-        "StorageManager is disposed; cannot register new adapter. Call __resetForTests() in test setup."
-      );
-    }
-    this.#adapters.add(adapter);
-  }
-  /**
-   * Drain in parallel — registered adapters, then PG pools, then Redis
-   * clients. Idempotent (D5). Errors per resource are logged and swallowed
-   * — they do NOT prevent shutdown of the remaining resources.
-   *
-   * Caller must wrap in a timeout if a bound is needed (EC-7: documented).
-   * In production, `start.ts` wraps the whole shutdown sequence in a 25 s
-   * force-exit timer.
-   */
-  async dispose() {
-    if (this.#disposed) return;
-    this.#disposed = true;
-    const adapterDrains = Array.from(this.#adapters).map(
-      (a) => a.dispose().catch((err) => {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`[theokit] adapter "${a.name}" dispose failed: ${msg}`);
-      })
-    );
-    await Promise.all(adapterDrains);
-    const poolCloses = Array.from(this.#dbPools.values()).map((pool) => {
-      if (pool.end === void 0) return Promise.resolve();
-      return pool.end().catch((err) => {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`[theokit] PG pool close failed: ${msg}`);
-      });
-    });
-    await Promise.all(poolCloses);
-    const redisCloses = Array.from(this.#redisClients.values()).map(
-      (c) => c.quit().catch((err) => {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`[theokit] Redis quit failed, falling back to disconnect: ${msg}`);
-        c.disconnect();
-      })
-    );
-    await Promise.all(redisCloses);
-    this.#dbPools.clear();
-    this.#redisClients.clear();
-    this.#genericClients.clear();
-    this.#adapters.clear();
-  }
-  /** @internal Testing seam — resets state so a single test file can re-use the singleton across `it` blocks (EC-3). */
-  __resetForTests() {
-    this.#config = void 0;
-    this.#dbPools.clear();
-    this.#redisClients.clear();
-    this.#genericClients.clear();
-    this.#adapters.clear();
-    this.#disposed = false;
-  }
-  /** @internal Introspection helper for tests. */
-  __isConfiguredForTests() {
-    return this.#config !== void 0;
-  }
-  /** @internal Introspection helper for tests. */
-  __isDisposedForTests() {
-    return this.#disposed;
-  }
-};
-var __singleton;
-function getStorageManager() {
-  __singleton ??= new StorageManager();
-  return __singleton;
-}
-function __resetSingletonForTests() {
-  __singleton = void 0;
-}
-
-// src/server/storage/use-unstorage.ts
-async function useUnstorage(name, driver) {
-  const mod = await import("unstorage").catch(() => null);
-  if (mod === null) {
-    throw new Error(
-      "useUnstorage requires the 'unstorage' package. Install via: pnpm add unstorage"
-    );
-  }
-  const manager = getStorageManager();
-  return manager.useStorage(`__unstorage:${name}`, () => {
-    const storage = mod.createStorage({ driver });
-    manager.register({
-      name: `unstorage:${name}`,
-      dispose: () => storage.dispose?.() ?? Promise.resolve()
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderScalarHtml(title, specUrl, cdnUrl) {
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>${escapeHtml(title)}</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+</head>
+<body>
+  <script id="api-reference" data-url="${escapeHtml(specUrl)}"></script>
+  <script src="${escapeHtml(cdnUrl)}"></script>
+</body>
+</html>`;
+}
+function serveSpecFile(filePath) {
+  if (!existsSync(filePath)) {
+    return jsonResponse(503, {
+      error: { code: "OPENAPI_NOT_EMITTED", message: "OpenAPI spec not generated yet. Start the dev server and visit a route first." }
     });
-    return storage;
-  });
-}
-
-// src/server/storage/use-database.ts
-function detectUninvokedFactory(connector) {
-  if (typeof connector === "function") {
-    const fn = connector;
-    if ((fn.length ?? 0) > 0) {
-      const name = fn.name !== void 0 && fn.name !== "" ? fn.name : "connector";
-      return `useDatabase: connector argument looks like an un-invoked factory (function with ${String(fn.length)} parameter(s)). Did you forget to call the factory? Pass \`${name}({...})\` not \`${name}\`. Example: useDatabase('main', sqlite({ name: ':memory:' }))`;
-    }
   }
-  return null;
-}
-async function useDatabase(name, connector) {
-  const factoryError = detectUninvokedFactory(connector);
-  if (factoryError !== null) throw new Error(factoryError);
-  const mod = await import("db0").catch(() => null);
-  if (mod === null) {
-    throw new Error("useDatabase requires the 'db0' package. Install via: pnpm add db0");
-  }
-  const manager = getStorageManager();
-  return manager.useStorage(`__db0:${name}`, () => mod.createDatabase(connector));
-}
-
-// src/server/webhook/timing-safe-equal.ts
-var cachedNodeImpl;
-function resolveNodeImpl() {
-  if (cachedNodeImpl !== void 0) return cachedNodeImpl;
   try {
-    const cryptoMod = __require("crypto");
-    cachedNodeImpl = cryptoMod.timingSafeEqual ?? null;
-  } catch {
-    cachedNodeImpl = null;
-  }
-  return cachedNodeImpl;
-}
-function timingSafeEqual(a, b) {
-  if (!(a instanceof Uint8Array) || !(b instanceof Uint8Array)) {
-    throw new TypeError(
-      `timingSafeEqual expects Uint8Array arguments (got ${typeof a} and ${typeof b})`
-    );
-  }
-  if (a.length !== b.length) return false;
-  if (a.length === 0) return true;
-  const nodeImpl = resolveNodeImpl();
-  if (nodeImpl) return nodeImpl(a, b);
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) {
-    diff |= a[i] ^ b[i];
-  }
-  return diff === 0;
-}
-
-// src/server/webhook/raw-body.ts
-var DEFAULT_MAX_BODY_BYTES = 1e6;
-var BodyTooLargeError = class extends Error {
-  constructor(limit, actualSeen) {
-    super(`Request body exceeds maxBodyBytes: seen ${actualSeen} bytes, limit ${limit} bytes`);
-    this.limit = limit;
-    this.actualSeen = actualSeen;
-    this.name = "BodyTooLargeError";
-  }
-  limit;
-  actualSeen;
-  status = 413;
-  code = "BODY_TOO_LARGE";
-};
-async function readRawBody(request, options = {}) {
-  const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
-  const clone = request.clone();
-  if (clone.body === null) {
-    return { rawBody: "", bodyClone: request };
-  }
-  const reader = clone.body.getReader();
-  const chunks = [];
-  let total = 0;
-  try {
-    for (; ; ) {
-      const { value, done } = await reader.read();
-      if (done) break;
-      total += value.byteLength;
-      if (total > maxBodyBytes) {
-        void reader.cancel();
-        throw new BodyTooLargeError(maxBodyBytes, total);
-      }
-      chunks.push(value);
-    }
-  } finally {
-    try {
-      reader.releaseLock();
-    } catch {
-    }
-  }
-  const bytes = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    bytes.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  const rawBody = new TextDecoder().decode(bytes);
-  return { rawBody, bodyClone: request };
-}
-
-// src/server/webhook/define-webhook.ts
-function defineWebhook(opts) {
-  return {
-    verify: opts.verify,
-    handler: opts.handler,
-    maxBodyBytes: opts.maxBodyBytes,
-    __theokit_kind: "webhook"
-  };
-}
-async function dispatchWebhook(def, request) {
-  let rawBody;
-  let bodyClone;
-  try {
-    const result2 = await readRawBody(request, { maxBodyBytes: def.maxBodyBytes });
-    rawBody = result2.rawBody;
-    bodyClone = result2.bodyClone;
-  } catch (err) {
-    if (err instanceof BodyTooLargeError) {
-      return new Response(JSON.stringify({ error: err.code, message: err.message }), {
-        status: 413,
-        headers: { "content-type": "application/json" }
+    const stat = statSync(filePath);
+    if (stat.size > MAX_SPEC_BYTES) {
+      return jsonResponse(413, {
+        error: { code: "OPENAPI_TOO_LARGE", message: `Spec file exceeds ${MAX_SPEC_BYTES / 1024 / 1024}MB limit` }
       });
     }
-    return new Response(
-      JSON.stringify({
-        error: "BAD_REQUEST",
-        message: err instanceof Error ? err.message : "failed to read body"
-      }),
-      { status: 400, headers: { "content-type": "application/json" } }
-    );
-  }
-  const incomingTrace = extractTraceContext(request.headers);
-  const traceId = incomingTrace?.trace_id ?? generateNewTraceContext().trace_id;
-  let verifyResult;
-  try {
-    verifyResult = await def.verify(bodyClone);
+    const content = readFileSync(filePath, "utf-8");
+    return new Response(content, {
+      status: 200,
+      headers: { "content-type": "application/json", "cache-control": "no-cache" }
+    });
   } catch (err) {
-    verifyResult = {
-      ok: false,
-      reason: `verify threw: ${err instanceof Error ? err.message : String(err)}`
-    };
-  }
-  if (!verifyResult.ok) {
-    return new Response(
-      JSON.stringify({ error: "WEBHOOK_VERIFY_FAILED", message: verifyResult.reason }),
-      { status: 401, headers: { "content-type": "application/json" } }
-    );
-  }
-  const ctx = {
-    request: bodyClone,
-    rawBody,
-    traceId,
-    signal: request.signal
-  };
-  const result = await def.handler(ctx);
-  if (result instanceof Response) return result;
-  if (result === void 0 || result === null) {
-    return new Response(null, { status: 204 });
+    return jsonResponse(500, {
+      error: { code: "OPENAPI_READ_FAILED", message: "Failed to read OpenAPI spec file" }
+    });
   }
-  return new Response(JSON.stringify(result), {
-    status: 200,
+}
+function jsonResponse(status, body) {
+  return new Response(JSON.stringify(body), {
+    status,
     headers: { "content-type": "application/json" }
   });
 }
@@ -1601,8 +749,8 @@ function createCacheEngine(opts) {
   function claimAndRun(key, fn, options, skipWrite) {
     let resolveOuter;
     let rejectOuter;
-    const outerPromise = new Promise((resolve3, reject) => {
-      resolveOuter = resolve3;
+    const outerPromise = new Promise((resolve2, reject) => {
+      resolveOuter = resolve2;
       rejectOuter = reject;
     });
     void outerPromise.catch(() => {
@@ -1940,10 +1088,292 @@ function deserializeResponse(serialized) {
   return superjson.deserialize(serialized);
 }
 
+// src/server/web-handler.ts
+function searchParamsToObject(params) {
+  const out = {};
+  for (const [key, value] of params.entries()) {
+    if (!Object.hasOwn(out, key)) {
+      out[key] = value;
+      continue;
+    }
+    const existing = out[key];
+    if (Array.isArray(existing)) {
+      existing.push(value);
+    } else {
+      out[key] = [existing, value];
+    }
+  }
+  return out;
+}
+async function parseBodyInline(request) {
+  if (request.method === "GET" || request.method === "HEAD") return void 0;
+  const contentType = request.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    const text = await request.text();
+    if (text.length === 0) return void 0;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return void 0;
+    }
+  }
+  if (contentType.startsWith("text/")) {
+    const text = await request.text();
+    return text.length === 0 ? void 0 : text;
+  }
+  return void 0;
+}
+async function parseBodyFull(request) {
+  if (request.method === "GET" || request.method === "HEAD") return void 0;
+  const { parseWebRequestBody } = await import("../body-parser-web-MUWBKZ3F.js");
+  try {
+    const parsed = await parseWebRequestBody(request);
+    if (parsed.json === void 0 && Object.keys(parsed.fields).length === 0 && parsed.files.length === 0) {
+      return void 0;
+    }
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+function validationErrorResponse(zodError, field) {
+  const envelope = {
+    code: "BAD_REQUEST",
+    message: `Validation failed: ${field}`,
+    ext: {
+      fields: zodError.issues.map((issue) => ({
+        path: issue.path.join("."),
+        message: issue.message
+      }))
+    }
+  };
+  return new Response(JSON.stringify(envelope), {
+    status: 400,
+    headers: { "content-type": "application/json" }
+  });
+}
+async function runHandler(config, request, bodyParser = "inline") {
+  const url = new URL(request.url);
+  const queryRaw = searchParamsToObject(url.searchParams);
+  const bodyRaw = bodyParser === "full" ? await parseBodyFull(request) : await parseBodyInline(request);
+  const paramsRaw = {};
+  let query = queryRaw;
+  if (config.query !== void 0) {
+    const parsed = config.query.safeParse(queryRaw);
+    if (!parsed.success)
+      return { ok: false, response: validationErrorResponse(parsed.error, "query") };
+    query = parsed.data;
+  }
+  let body = bodyRaw;
+  if (config.body !== void 0) {
+    const parsed = config.body.safeParse(bodyRaw);
+    if (!parsed.success)
+      return { ok: false, response: validationErrorResponse(parsed.error, "body") };
+    body = parsed.data;
+  }
+  let params = paramsRaw;
+  if (config.params !== void 0) {
+    const parsed = config.params.safeParse(paramsRaw);
+    if (!parsed.success)
+      return { ok: false, response: validationErrorResponse(parsed.error, "params") };
+    params = parsed.data;
+  }
+  const result = await config.handler({ query, body, params, request });
+  return { ok: true, result };
+}
+function toResponse(result) {
+  if (result === void 0) {
+    return new Response(null, { status: 204 });
+  }
+  if (result instanceof Response) {
+    return result;
+  }
+  return new Response(JSON.stringify(result), {
+    status: 200,
+    headers: { "content-type": "application/json" }
+  });
+}
+function handlerErrorResponse(err) {
+  const envelope = serverErrorToEnvelope(err);
+  const status = envelopeCodeToStatus(envelope.code);
+  return new Response(JSON.stringify(envelope), {
+    status,
+    headers: { "content-type": "application/json" }
+  });
+}
+function envelopeCodeToStatus(code) {
+  switch (code) {
+    case "BAD_REQUEST":
+      return 400;
+    case "UNAUTHORIZED":
+      return 401;
+    case "FORBIDDEN":
+      return 403;
+    case "NOT_FOUND":
+      return 404;
+    case "METHOD_NOT_ALLOWED":
+      return 405;
+    case "PAYLOAD_TOO_LARGE":
+      return 413;
+    case "UNPROCESSABLE_ENTITY":
+      return 422;
+    case "TOO_MANY_REQUESTS":
+    case "RATE_LIMITED":
+      return 429;
+    case "BAD_GATEWAY":
+      return 502;
+    case "SERVICE_UNAVAILABLE":
+      return 503;
+    case "GATEWAY_TIMEOUT":
+      return 504;
+    case "INTERNAL_SERVER_ERROR":
+    default:
+      return 500;
+  }
+}
+var CSRF_PROTECTED_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+function mergeHookHeaders(response, hookHeaders) {
+  if ([...hookHeaders].length === 0) return response;
+  const merged = new Headers(response.headers);
+  for (const [k, v] of hookHeaders.entries()) {
+    if (k.toLowerCase() === "set-cookie") continue;
+    if (!merged.has(k)) merged.set(k, v);
+  }
+  for (const sc of hookHeaders.getSetCookie()) {
+    merged.append("Set-Cookie", sc);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: merged
+  });
+}
+function methodNotAllowedResponse(method) {
+  const envelope = {
+    code: "METHOD_NOT_ALLOWED",
+    message: `Method ${method} not allowed`
+  };
+  return new Response(JSON.stringify(envelope), {
+    status: 405,
+    headers: { "content-type": "application/json" }
+  });
+}
+function csrfFailedResponse(reason) {
+  const envelope = {
+    code: "FORBIDDEN",
+    message: `CSRF check failed: ${reason}`
+  };
+  return new Response(JSON.stringify(envelope), {
+    status: 403,
+    headers: { "content-type": "application/json" }
+  });
+}
+async function executeWebRequest(request, routeModule, opts = {}) {
+  const method = request.method.toUpperCase();
+  const config = routeModule[method];
+  if (opts.hooks === void 0) {
+    if (config === void 0 || typeof config.handler !== "function") {
+      return methodNotAllowedResponse(method);
+    }
+    if (opts.csrfMode === "strict" && CSRF_PROTECTED_METHODS.has(method)) {
+      const csrfCheck = validateCsrfRequest(request);
+      if (!csrfCheck.valid) return csrfFailedResponse(csrfCheck.reason);
+    }
+    try {
+      const outcome = await runHandler(config, request, opts.bodyParser ?? "inline");
+      if (!outcome.ok) return outcome.response;
+      return toResponse(outcome.result);
+    } catch (err) {
+      return handlerErrorResponse(err);
+    }
+  }
+  return runWithHooks(request, config, opts, opts.hooks);
+}
+async function runPreHandlerPipeline(hookCtx, request, config, opts, hooks) {
+  const method = request.method.toUpperCase();
+  const runList = async (list) => {
+    for (const hook of list) {
+      if (hookCtx.response !== void 0) return;
+      await hook(hookCtx);
+    }
+  };
+  if (hooks.onRequest) await runList(hooks.onRequest);
+  if (hookCtx.response === void 0 && opts.csrfMode === "strict" && CSRF_PROTECTED_METHODS.has(method)) {
+    const csrfCheck = validateCsrfRequest(request);
+    if (!csrfCheck.valid) hookCtx.response = csrfFailedResponse(csrfCheck.reason);
+  }
+  if (hookCtx.response === void 0 && hooks.preHandler) {
+    await runList(hooks.preHandler);
+  }
+  if (hookCtx.response === void 0) {
+    if (config === void 0 || typeof config.handler !== "function") {
+      hookCtx.response = methodNotAllowedResponse(method);
+      return;
+    }
+    const outcome = await runHandler(config, request, opts.bodyParser ?? "inline");
+    hookCtx.response = outcome.ok ? toResponse(outcome.result) : outcome.response;
+  }
+}
+async function runWithHooks(request, config, opts, hooks) {
+  const hookCtx = {
+    request,
+    responseHeaders: new Headers(),
+    ctx: {},
+    requestId: opts.requestId ?? globalThis.crypto.randomUUID()
+  };
+  try {
+    await runPreHandlerPipeline(hookCtx, request, config, opts, hooks);
+    if (hooks.onResponse) {
+      for (const hook of hooks.onResponse) {
+        await hook(hookCtx);
+      }
+    }
+    const finalResponse = hookCtx.response ?? new Response(
+      JSON.stringify({ code: "INTERNAL_SERVER_ERROR", message: "No response built" }),
+      {
+        status: 500,
+        headers: { "content-type": "application/json" }
+      }
+    );
+    return mergeHookHeaders(finalResponse, hookCtx.responseHeaders);
+  } catch (err) {
+    return runErrorHooks(err, hookCtx, hooks.onError);
+  }
+}
+async function runErrorHooks(err, hookCtx, onError) {
+  const errorResponse = handlerErrorResponse(err);
+  if (onError !== void 0) {
+    const errorCtx = {
+      ...hookCtx,
+      response: errorResponse,
+      error: err
+    };
+    for (const hook of onError) {
+      try {
+        await hook(errorCtx);
+      } catch {
+      }
+    }
+  }
+  return mergeHookHeaders(errorResponse, hookCtx.responseHeaders);
+}
+
 // src/server/plugin-types.ts
 function definePlugin(plugin) {
   return plugin;
 }
+
+// src/server/index.ts
+if (typeof globalThis !== "undefined") {
+  const WARN_KEY = "__theokit_server_umbrella_warn_emitted__";
+  const g = globalThis;
+  if (g[WARN_KEY] !== true) {
+    g[WARN_KEY] = true;
+    console.warn(
+      '[theokit] umbrella import "theokit/server" is DEPRECATED. Use sub-paths (theokit/server/<domain>): auth, jobs, http, security, observability, etc. See packages/theo/package.json#exports for the full list. Removal scheduled for 0.x+2.'
+    );
+  }
+}
 export {
   ActionError,
   ActionInputError,
@@ -1964,6 +1394,7 @@ export {
   CSRF_WARN_CODE,
   CSRF_WARN_DOCS_URL,
   ChannelManager,
+  ConsoleObservabilityAdapter,
   CsrfReadinessStore,
   DEFAULT_CSP,
   DEFAULT_EXCLUDED_QUERY_PARAMS,
@@ -1985,21 +1416,26 @@ export {
   JsonStdoutSink,
   MAX_ERROR_HTML_BYTES,
   NonRetryableError,
+  NoopObservabilityAdapter,
+  NoopSpan,
   PluginRunner,
   PostgresJobBackend,
   STRIPPED_HEADERS,
+  SpanImpl,
   StorageManager,
   THEO_T_PREFIX,
   TRACE_HEADER,
   TRACE_PARENT_HEADER,
+  TheoCloudObservabilityAdapter,
   __resetSdkForTests,
-  __resetSingletonForTests,
   __setSdkForTests,
   _resetCacheEngine,
   _resetEnvCache,
   _resetKeyCacheForTests,
   _resetMiddlewareCacheForTests,
   _resetWarnOnceForTests,
+  appendCookieToHeaders,
+  appendDeleteCookieToHeaders,
   applySecurityHeaders,
   assertProductionSecret,
   buildCronManifest,
@@ -2013,18 +1449,24 @@ export {
   createCacheEngine,
   createConversationHistory,
   createCorsHandler,
+  createCorsWebHandler,
   createCronScheduler,
   createJobRunner,
   createLogger,
   createNoOpLogger,
+  createObservabilityPlugin,
+  createOpenApiHandler,
   createOutbox,
   createOutboxDispatcher,
   createPluginRunnerFromConfig,
   createProductionLoader,
   createQueueClient,
   createRateLimiter,
+  createRateLimiterWeb,
   createRouteRateLimiter,
+  createRouteRateLimiterWeb,
   createSessionManager,
+  createSessionManagerWeb,
   createViteLoader,
   decrypt,
   defineAction,
@@ -2036,14 +1478,18 @@ export {
   defineCron,
   defineJob,
   defineMiddleware,
+  defineObservabilityAdapter,
   definePlugin,
   defineRoute,
   defineTheoPlugin,
+  defineWebChannel,
   defineWebSocket,
+  defineWebSocketWeb,
   defineWebhook,
   deleteCookie,
   deriveKey2 as deriveCacheKey,
   deriveKey,
+  deriveKeyFromRequest,
   deserializeResponse,
   discoverOidcProvider,
   dispatchWebhook,
@@ -2052,7 +1498,9 @@ export {
   errorToEvent,
   executeAction,
   executeRoute,
+  executeWebRequest,
   extractTraceId,
+  extractTraceIdFromRequest,
   extractUniversalIssues,
   findSuggestion,
   generateBackupCodes,
@@ -2065,10 +1513,13 @@ export {
   getCacheControlHeader,
   getCacheEngine,
   getCookie,
+  getCookieFromRequest,
   getStorageManager,
   handleBatchRequest,
   handleCspReport,
+  handleCspReportRequest,
   handleCsrfReadiness,
+  handleCsrfReadinessRequest,
   initCacheEngine,
   isActionError,
   isInputError,
@@ -2091,11 +1542,13 @@ export {
   readRawBody,
   recordAttempt,
   requireAuth,
+  resolveAdapter,
   resolveRouteRule,
   resolveTransformer,
   revalidatePath,
   revalidateTag,
   rotateIfNeeded,
+  rotateIfNeededWeb,
   runMiddlewareAndContext,
   safeAudit,
   scanCrons,
@@ -2107,7 +1560,9 @@ export {
   scanWebSocketRoutes,
   sendError,
   sendJson,
+  serializeCookie,
   serializeResponse,
+  serializeSpansToOtlp,
   serveStaticFile,
   setCookie,
   streamAgentRun,
@@ -2128,6 +1583,7 @@ export {
   validateTags as validateCacheTags,
   validateCronSchedule,
   validateCsrf,
+  validateCsrfRequest,
   verifyBackupCode,
   verifyOAuthState,
   verifyTotp,