theokit 0.48.14 → 0.50.1

package/dist/{chunk-WYHYOYRH.js → chunk-2COPDKIG.js}

@@ -2,18 +2,38 @@
 import "tsx/esm";
 import {
   getApprovalRegistry
-} from "./chunk-DQIPV7L5.js";
+} from "./chunk-5YPXXSYY.js";
 import {
+  createWebRequestSource,
   dispatchCsrfWarn,
   enforceCsrf,
   incomingMessageToHandlerRequest,
-  parseRequestBody,
   safeAudit,
   sendError,
   sendJson,
-  validateCsrfRequest,
+  validateCsrfRequest
+} from "./chunk-FMTRNQQ7.js";
+import {
+  buildSecurityHeaders
+} from "./chunk-RPET332G.js";
+import {
+  getObservabilityAdapter,
+  newSpanId,
+  newTraceId,
+  requestTrace
+} from "./chunk-H53KNS6Q.js";
+import {
+  RequestBodyConsumedError,
+  createLogger,
+  parseRequestBody,
   warnOnce
-} from "./chunk-T5C46IIU.js";
+} from "./chunk-RARK7JBR.js";
+import {
+  compareByCodeUnit
+} from "./chunk-FD4ZDTQ6.js";
+import {
+  importUserModule
+} from "./chunk-U5PWXS3J.js";
 import {
   TheoError,
   serverErrorToEnvelope
@@ -186,6 +206,24 @@ function isAuthRequiredError(err) {
   return e.code === "AUTH_REQUIRED" && e.status === 401;
 }
 
+// src/core/contracts/route-policy.ts
+function subjectFromContext(context) {
+  if (context === null || typeof context !== "object") return null;
+  const candidate = context.subject;
+  if (candidate === null || candidate === void 0 || typeof candidate !== "object") return null;
+  const id = candidate.id;
+  return typeof id === "string" && id.length > 0 ? candidate : null;
+}
+async function evaluateRoutePolicy(policy, input) {
+  if (policy === void 0) return { allowed: true };
+  if (policy === "public") return { allowed: true };
+  const verdict = await policy(input);
+  if (typeof verdict === "boolean") {
+    return verdict ? { allowed: true } : { allowed: false, reason: "access denied by route policy" };
+  }
+  return verdict;
+}
+
 // src/server/jobs/duplicate-context-key-error.ts
 var DuplicateContextKeyError = class extends Error {
   constructor(key, opts) {
@@ -301,6 +339,10 @@ async function parseQueryAndBody(req, res, requestId) {
       body = void 0;
     }
   } catch (err) {
+    if (err instanceof RequestBodyConsumedError) {
+      sendError(res, "INTERNAL_ERROR", err.message, err.status, void 0, requestId);
+      return { ok: false };
+    }
     const message = err.message;
     const status = message.includes("Unsupported Content-Type") ? 415 : 400;
     sendError(res, "VALIDATION_ERROR", message, status, void 0, requestId);
@@ -364,6 +406,9 @@ function runZodValidation(routeConfig, res, requestId, input) {
 import { existsSync as existsSync2 } from "fs";
 import { join as join2 } from "path";
 
+// src/server/define/define-middleware.ts
+var WEB_SHAPED_MIDDLEWARE = /* @__PURE__ */ Symbol.for("theokit.middleware.web-shaped");
+
 // src/server/scan/middleware-scan.ts
 import { readdirSync, existsSync, statSync } from "fs";
 import { join, extname } from "path";
@@ -382,10 +427,70 @@ function scanMiddlewares(serverDir) {
     if (!MW_EXTENSIONS.has(ext)) continue;
     files.push(join(mwDir, entry.name));
   }
-  files.sort((a, b) => a.localeCompare(b));
+  files.sort(compareByCodeUnit);
   return files;
 }
 
+// src/core/contracts/envelope-code-to-status.ts
+var CODE_TO_STATUS2 = {
+  // 4xx — client errors
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  CONFLICT: 409,
+  PRECONDITION_FAILED: 412,
+  PAYLOAD_TOO_LARGE: 413,
+  UNSUPPORTED_MEDIA_TYPE: 415,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+  RATE_LIMITED: 429,
+  // 5xx — server errors
+  INTERNAL_SERVER_ERROR: 500,
+  NOT_IMPLEMENTED: 501,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+  GATEWAY_TIMEOUT: 504,
+  // SDK-domain codes — intentionally 500
+  AGENT_RUN_ERROR: 500,
+  PROVIDER_KEY_MISSING: 500,
+  BUDGET_EXCEEDED: 500,
+  CREDENTIAL_POOL_EXHAUSTED: 500
+};
+function envelopeCodeToStatus(code) {
+  return CODE_TO_STATUS2[code] ?? 500;
+}
+
+// src/server/http/node-web-adapter.ts
+async function writeWebResponseToServerResponse(response, res) {
+  const setCookies = response.headers.getSetCookie();
+  if (setCookies.length > 0) {
+    res.setHeader("Set-Cookie", setCookies);
+  }
+  const otherHeaders = {};
+  for (const [key, value] of response.headers.entries()) {
+    if (key.toLowerCase() === "set-cookie") continue;
+    otherHeaders[key] = value;
+  }
+  res.writeHead(response.status, response.statusText, otherHeaders);
+  if (response.body === null) {
+    res.end();
+    return;
+  }
+  const reader = response.body.getReader();
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      res.write(value);
+    }
+    res.end();
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 // src/server/http/middleware-runner.ts
 var middlewareCache = /* @__PURE__ */ new Map();
 function getCachedScan(serverDir) {
@@ -401,6 +506,24 @@ function getCachedScan(serverDir) {
   }
   return cached;
 }
+async function runWebShapedMiddleware(mw, req, res, context) {
+  const request = createWebRequestSource(req).toRequest();
+  const result = await mw(request, context);
+  if (!(result instanceof Response)) return { shortCircuited: false };
+  await writeWebResponseToServerResponse(result, res);
+  return { shortCircuited: true };
+}
+function isWebShaped(mw) {
+  return WEB_SHAPED_MIDDLEWARE in mw;
+}
+async function runScannedMiddleware(mw, req, res, context) {
+  if (isWebShaped(mw)) {
+    const { shortCircuited } = await runWebShapedMiddleware(mw, req, res, context);
+    return { aborted: shortCircuited };
+  }
+  const { nextCalled } = await runOneMiddleware(mw, req, res);
+  return { aborted: !nextCalled || res.writableEnded };
+}
 async function runOneMiddleware(mw, req, res) {
   const state = { nextCalled: false };
   await mw(req, res, () => {
@@ -411,6 +534,7 @@ async function runOneMiddleware(mw, req, res) {
 async function runMiddlewareAndContext(req, res, loadModule, serverDir) {
   const { singleFilePath, singleFileExists, dirMiddlewares } = getCachedScan(serverDir);
   const dirExists = dirMiddlewares.length > 0;
+  const middlewareCtx = {};
   if (singleFileExists && dirExists) {
     throw new Error(
       "Ambiguous middleware configuration: found both server/middleware.ts and server/middleware/ directory. Use one or the other, not both."
@@ -421,36 +545,54 @@ async function runMiddlewareAndContext(req, res, loadModule, serverDir) {
       const mod = await loadModule(mwPath);
       const mw = mod.default;
       if (typeof mw !== "function") continue;
-      const { nextCalled } = await runOneMiddleware(mw, req, res);
-      if (!nextCalled || res.writableEnded) {
-        return { ctx: {}, aborted: true };
-      }
+      const { aborted } = await runScannedMiddleware(mw, req, res, middlewareCtx);
+      if (aborted) return { ctx: middlewareCtx, aborted: true };
     }
   }
   if (singleFileExists) {
     const mod = await loadModule(singleFilePath);
     const mw = mod.default;
     if (typeof mw === "function") {
-      const { nextCalled } = await runOneMiddleware(mw, req, res);
-      if (!nextCalled || res.writableEnded) {
-        return { ctx: {}, aborted: true };
-      }
+      const { aborted } = await runScannedMiddleware(mw, req, res, middlewareCtx);
+      if (aborted) return { ctx: middlewareCtx, aborted: true };
     }
   }
-  let ctx = {};
-  const contextPath = join2(serverDir, "context.ts");
-  if (existsSync2(contextPath)) {
-    const mod = await loadModule(contextPath);
-    const createContext = mod.createContext;
-    if (typeof createContext === "function") {
-      ctx = await createContext({ request: req, response: res });
-    }
+  const factoryCtx = await createServerContext(req, res, loadModule, serverDir);
+  if (factoryCtx === null || typeof factoryCtx !== "object") {
+    return { ctx: middlewareCtx, aborted: false };
   }
-  return { ctx, aborted: false };
+  return { ctx: { ...middlewareCtx, ...factoryCtx }, aborted: false };
+}
+async function createServerContext(req, res, loadModule, serverDir) {
+  const contextPath = join2(serverDir, "context.ts");
+  if (!existsSync2(contextPath)) return {};
+  const mod = await loadModule(contextPath);
+  const createContext = mod.createContext;
+  if (typeof createContext !== "function") return {};
+  return await createContext({ request: req, response: res });
 }
 
 // src/server/http/execute.ts
 var CSRF_PROTECTED_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+async function waitForDrain(res) {
+  if (typeof res.once !== "function") return;
+  await new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      if (typeof res.off === "function") {
+        res.off("drain", finish);
+        res.off("close", finish);
+        res.off("error", finish);
+      }
+      resolve();
+    };
+    res.once("drain", finish);
+    res.once("close", finish);
+    res.once("error", finish);
+  });
+}
 async function pipeWebStreamToResponse(body, res, ctx) {
   const reader = body.getReader();
   try {
@@ -458,7 +600,7 @@ async function pipeWebStreamToResponse(body, res, ctx) {
     while (!done) {
       const chunk = await reader.read();
       done = chunk.done;
-      if (!done) res.write(chunk.value);
+      if (!done && res.write(chunk.value) === false) await waitForDrain(res);
     }
   } catch (streamErr) {
     warnOnce(`stream-error:${ctx.routePath}:${ctx.method}`, {
@@ -474,12 +616,15 @@ async function pipeWebStreamToResponse(body, res, ctx) {
       } catch {
       }
     }
+    res.destroy(streamErr instanceof Error ? streamErr : new Error(String(streamErr)));
+    return false;
   } finally {
     try {
       reader.releaseLock();
     } catch {
     }
   }
+  return true;
 }
 async function executeRoute(ctx) {
   const {
@@ -595,6 +740,23 @@ async function executeRoute(ctx) {
       if (preResult.shortCircuited) return;
     }
     const callableHandler = handler;
+    const accessDecision = await evaluateRoutePolicy(rc.policy, {
+      subject: subjectFromContext(ctx2),
+      query,
+      body,
+      params
+    });
+    if (!accessDecision.allowed) {
+      sendError(
+        res,
+        "FORBIDDEN",
+        `Access denied: ${accessDecision.reason}`,
+        403,
+        void 0,
+        requestId
+      );
+      return;
+    }
     const handlerResult = await callableHandler({ query, body, params, request: webRequest, ctx: ctx2 });
     if (handlerResult === void 0 || handlerResult === null) {
       sendJson(res, null, rc.status ?? 204, transformer);
@@ -611,8 +773,9 @@ async function executeRoute(ctx) {
         res.setHeader("Set-Cookie", setCookies);
       }
       res.writeHead(handlerResult.status, headersBag);
+      let bodyCompleted = true;
       if (handlerResult.body) {
-        await pipeWebStreamToResponse(handlerResult.body, res, {
+        bodyCompleted = await pipeWebStreamToResponse(handlerResult.body, res, {
           buildPluginCtx,
           ctx: ctx2,
           method,
@@ -621,7 +784,7 @@ async function executeRoute(ctx) {
           routePath: route.routePath
         });
       }
-      res.end();
+      if (bodyCompleted) res.end();
       if (pluginRunner) await pluginRunner.runOnResponse(buildPluginCtx(ctx2));
       return;
     }
@@ -768,37 +931,6 @@ function coerceBoolean(formData, key) {
   return Boolean(val);
 }
 
-// src/core/contracts/envelope-code-to-status.ts
-var CODE_TO_STATUS2 = {
-  // 4xx — client errors
-  BAD_REQUEST: 400,
-  UNAUTHORIZED: 401,
-  FORBIDDEN: 403,
-  NOT_FOUND: 404,
-  METHOD_NOT_ALLOWED: 405,
-  CONFLICT: 409,
-  PRECONDITION_FAILED: 412,
-  PAYLOAD_TOO_LARGE: 413,
-  UNSUPPORTED_MEDIA_TYPE: 415,
-  UNPROCESSABLE_ENTITY: 422,
-  TOO_MANY_REQUESTS: 429,
-  RATE_LIMITED: 429,
-  // 5xx — server errors
-  INTERNAL_SERVER_ERROR: 500,
-  NOT_IMPLEMENTED: 501,
-  BAD_GATEWAY: 502,
-  SERVICE_UNAVAILABLE: 503,
-  GATEWAY_TIMEOUT: 504,
-  // SDK-domain codes — intentionally 500
-  AGENT_RUN_ERROR: 500,
-  PROVIDER_KEY_MISSING: 500,
-  BUDGET_EXCEEDED: 500,
-  CREDENTIAL_POOL_EXHAUSTED: 500
-};
-function envelopeCodeToStatus(code) {
-  return CODE_TO_STATUS2[code] ?? 500;
-}
-
 // src/server/http/handle-request-error.ts
 async function handleRequestError(err, c) {
   if (c.pluginRunner) {
@@ -1017,7 +1149,11 @@ async function readActionBody(req, res, requestId, actionConfig) {
 function synthesizeFormData(parsed) {
   const fd = new FormData();
   for (const [name, value] of Object.entries(parsed.fields)) {
-    fd.append(name, value);
+    if (Array.isArray(value)) {
+      for (const single of value) fd.append(name, single);
+    } else {
+      fd.append(name, value);
+    }
   }
   for (const file of parsed.files) {
     const blob = new Blob([file.buffer], {
@@ -1328,44 +1464,6 @@ function createCorsHandler(config) {
   };
 }
 
-// src/server/http/trace-context.ts
-var TRACE_HEADER = "x-trace-id";
-var TRACE_PARENT_HEADER = "traceparent";
-var REQUEST_ID_HEADER = "x-request-id";
-var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
-function parseTraceparent(value) {
-  if (!value) return null;
-  const m = TRACEPARENT_RE.exec(value);
-  if (!m) return null;
-  const traceId = m[1];
-  if (/^0+$/.test(traceId)) return null;
-  return traceId;
-}
-function pickHeader(value) {
-  if (Array.isArray(value)) {
-    for (const v of value) {
-      if (typeof v === "string" && v.length > 0) return v;
-    }
-    return null;
-  }
-  if (typeof value === "string" && value.length > 0) return value;
-  return null;
-}
-function resolveTraceIdFromHeaders(traceparent, requestId) {
-  if (traceparent !== null) {
-    const parsed = parseTraceparent(traceparent);
-    if (parsed !== null) return parsed;
-  }
-  if (requestId !== null) return requestId;
-  return globalThis.crypto.randomUUID();
-}
-function extractTraceId(req) {
-  return resolveTraceIdFromHeaders(
-    pickHeader(req.headers[TRACE_PARENT_HEADER]),
-    pickHeader(req.headers[REQUEST_ID_HEADER])
-  );
-}
-
 // src/server/observability/suggest.ts
 function levenshtein(a, b) {
   const m = a.length;
@@ -1757,19 +1855,226 @@ function resultFromState(state, config) {
 // src/server/agent/mount-agent.ts
 import { compileAgentModule as compileAgentModule2, resolveEnabledSkills as resolveEnabledSkills2, streamAgentUIMessages as streamAgentUIMessages2 } from "@theokit/agents";
 
+// src/server/agent/agent-access.ts
+var AgentPolicyTypeError = class extends Error {
+  constructor(source, actual) {
+    super(
+      `Agent "${source}" exports a \`policy\` of type ${actual}. A policy is the string 'public' or a function ({ subject, body, params }) => boolean | AccessDecision. Import \`requireOwner\` from 'theokit/server/define' to write the owner check.`
+    );
+    this.name = "AgentPolicyTypeError";
+  }
+};
+function readAgentPolicy(mod, source) {
+  const declared = typeof mod === "object" && mod !== null ? mod.policy : void 0;
+  if (declared === void 0) return void 0;
+  if (declared !== "public" && typeof declared !== "function") {
+    throw new AgentPolicyTypeError(source, declared === null ? "null" : typeof declared);
+  }
+  return declared;
+}
+var log = createLogger({ context: { scope: "theokit:agent-access" } });
+async function admitAgentRequest(policy, resolveSubject, params, body) {
+  if (policy === void 0 || policy === "public") return { allowed: true };
+  const subject = resolveSubject === void 0 ? null : await resolveSubject();
+  return evaluateRoutePolicy(policy, { subject, query: void 0, body, params });
+}
+function agentAccessDenied(decision, params) {
+  if (!decision.allowed) {
+    log.warn("agent endpoint refused a caller", {
+      agent: params.agent,
+      endpoint: params.endpoint,
+      reason: decision.reason
+    });
+  }
+  return new Response(
+    JSON.stringify({
+      error: {
+        code: "FORBIDDEN",
+        message: `Access denied by the policy exported from agent "${params.agent}". Send the credential your app turns into \`ctx.subject\` in server/context.ts; the server log records which check refused this request.`
+      }
+    }),
+    { status: 403, headers: { "content-type": "application/json; charset=utf-8" } }
+  );
+}
+
 // src/server/agent/build-agent-streamer.ts
 import {
   compileAgentModule,
   resolveEnabledSkills,
   streamAgentUIMessages
 } from "@theokit/agents";
-function buildAgentHitl(compiled) {
+
+// src/server/agent/hitl-pause-spans.ts
+var pauseSpans = /* @__PURE__ */ new Map();
+function registerPauseSpan(approvalId, span) {
+  pauseSpans.set(approvalId, span);
+}
+function closePauseSpan(approvalId, { resumeObserved }) {
+  const span = pauseSpans.get(approvalId);
+  if (span === void 0) return;
+  pauseSpans.delete(approvalId);
+  span.setAttribute("hitl.resume_observed", resumeObserved);
+  if (resumeObserved) span.setStatus("ok");
+  else
+    span.setStatus("error", "HITL pause never observed to resume; duration is not the human wait");
+  span.end();
+}
+
+// src/server/agent/observe-agent-run.ts
+var TOKEN_FIELDS = [
+  ["inputTokens", "tokens.input"],
+  ["outputTokens", "tokens.output"],
+  ["totalTokens", "tokens.total"],
+  ["reasoningTokens", "tokens.reasoning"],
+  ["cacheReadTokens", "tokens.cache_read"],
+  ["cacheWriteTokens", "tokens.cache_write"]
+];
+var STOP_REASONS = /* @__PURE__ */ new Set(["step_limit", "no_progress"]);
+var GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
+function recordModel(span, metadata) {
+  if (metadata === null || typeof metadata !== "object") return;
+  const model = metadata.model;
+  if (typeof model === "string" && model.length > 0) span.setAttribute(GEN_AI_REQUEST_MODEL, model);
+}
+function recordStopReason(span, metadata) {
+  if (metadata === null || typeof metadata !== "object") return;
+  const reason = metadata.stopReason;
+  if (typeof reason === "string" && STOP_REASONS.has(reason)) {
+    span.setAttribute("stop.reason", reason);
+  }
+}
+function recordTokenUsage(span, metadata) {
+  if (metadata === null || typeof metadata !== "object") return;
+  const bag = metadata;
+  if (typeof bag.cost === "number") span.setAttribute("cost.usd", bag.cost);
+  const usage = bag.usage;
+  if (usage === null || usage === void 0 || typeof usage !== "object") return;
+  const fields = usage;
+  for (const [field, attribute] of TOKEN_FIELDS) {
+    const value = fields[field];
+    if (typeof value === "number") span.setAttribute(attribute, value);
+  }
+}
+function childOf(state) {
+  return { traceId: state.traceId, parentSpanId: state.runSpanId };
+}
+function openToolSpan(state, adapter, chunk) {
+  const id = chunk.toolCallId;
+  if (id === void 0) return;
+  const tool = chunk.toolName ?? "unknown";
+  state.toolNames.set(id, tool);
+  state.tools.set(
+    id,
+    adapter.startSpan("agent.tool", { agent: state.agent, tool, toolCallId: id }, childOf(state))
+  );
+}
+function openPauseSpan(state, adapter, chunk) {
+  const id = chunk.toolCallId;
+  const approvalId = chunk.approvalId;
+  if (id === void 0 || approvalId === void 0) return;
+  const pauseSpan = adapter.startSpan(
+    "agent.hitl",
+    {
+      agent: state.agent,
+      tool: state.toolNames.get(id) ?? "unknown",
+      approvalId,
+      toolCallId: id
+    },
+    childOf(state)
+  );
+  state.pauses.set(id, approvalId);
+  registerPauseSpan(approvalId, pauseSpan);
+}
+function closeToolSpan(state, chunk) {
+  const id = chunk.toolCallId;
+  if (id === void 0) return;
+  const pausedApprovalId = state.pauses.get(id);
+  if (pausedApprovalId !== void 0) {
+    closePauseSpan(pausedApprovalId, { resumeObserved: true });
+    state.pauses.delete(id);
+  }
+  const span = state.tools.get(id);
+  if (span === void 0) return;
+  if (chunk.type === "tool-output-error") span.setStatus("error", chunk.errorText);
+  else span.setStatus("ok");
+  span.end();
+  state.tools.delete(id);
+}
+async function* observeAgentRun(chunks, adapter, context) {
+  const runAttributes = { agent: context.agent };
+  if (context.sessionId !== void 0) runAttributes.sessionId = context.sessionId;
+  const traceId = context.traceId ?? newTraceId();
+  const runSpanId = newSpanId();
+  const runContext = context.traceId !== void 0 && context.parentSpanId !== void 0 ? { traceId, spanId: runSpanId, parentSpanId: context.parentSpanId } : { traceId, spanId: runSpanId };
+  const state = {
+    run: adapter.startSpan("agent.run", runAttributes, runContext),
+    tools: /* @__PURE__ */ new Map(),
+    pauses: /* @__PURE__ */ new Map(),
+    toolNames: /* @__PURE__ */ new Map(),
+    agent: context.agent,
+    traceId,
+    runSpanId
+  };
+  let settled = false;
+  function closeAll(status, message) {
+    if (settled) return;
+    settled = true;
+    for (const approvalId of state.pauses.values()) {
+      closePauseSpan(approvalId, { resumeObserved: false });
+    }
+    for (const span of state.tools.values()) {
+      span.setStatus(status, message);
+      span.end();
+    }
+    state.pauses.clear();
+    state.tools.clear();
+    state.run.setStatus(status, message);
+    state.run.end();
+  }
+  try {
+    for await (const chunk of chunks) {
+      const observed = chunk;
+      if (observed.type === "tool-input-available") openToolSpan(state, adapter, observed);
+      else if (observed.type === "tool-approval-request") openPauseSpan(state, adapter, observed);
+      else if (observed.type === "tool-output-available" || observed.type === "tool-output-error")
+        closeToolSpan(state, observed);
+      else if (observed.type === "finish") {
+        recordTokenUsage(state.run, observed.messageMetadata);
+        recordStopReason(state.run, observed.messageMetadata);
+        recordModel(state.run, observed.messageMetadata);
+      }
+      yield chunk;
+    }
+    closeAll("ok");
+  } catch (error) {
+    closeAll("error", error instanceof Error ? error.message : "unknown error");
+    throw error;
+  } finally {
+    closeAll("error", "agent run stream abandoned by its consumer");
+  }
+}
+
+// src/server/agent/observe-served-run.ts
+function observeServedRun(stream, options) {
+  const adapter = getObservabilityAdapter();
+  if (adapter === void 0) return stream;
+  const trace = requestTrace(options.request);
+  const context = { agent: options.agentName, traceId: trace.traceId };
+  if (options.sessionId !== void 0) context.sessionId = options.sessionId;
+  const parentSpanId = trace.outermostSpanId ?? trace.parentSpanId;
+  if (parentSpanId !== void 0) context.parentSpanId = parentSpanId;
+  return observeAgentRun(stream, adapter, context);
+}
+
+// src/server/agent/build-agent-streamer.ts
+function buildAgentHitl(compiled, owner) {
   const gated = compiled.hitl;
   if (gated === void 0 || gated.size === 0) return void 0;
   const registry = getApprovalRegistry();
   return {
     gated,
     awaitApproval: (approvalId, opts, toolName) => registry.register(approvalId, {
+      ...owner !== void 0 ? { owner } : {},
       timeoutMs: opts.timeout ?? 3e5,
       onTimeout: opts.onTimeout ?? "abort",
       toolName,
@@ -1778,7 +2083,7 @@ function buildAgentHitl(compiled) {
     })
   };
 }
-function makeThreadStartRun(mod, apiKey, source) {
+function makeThreadStartRun(mod, apiKey, source, agentName, request) {
   return (sessionId, message) => (async function* () {
     const compiled = compileAgentModule(mod, source);
     if (compiled.skillsResolver) {
@@ -1790,13 +2095,16 @@ function makeThreadStartRun(mod, apiKey, source) {
     }
     const hitl = buildAgentHitl(compiled);
     const resolvedApiKey = typeof apiKey === "function" ? apiKey(compiled.model) : apiKey;
-    yield* streamAgentUIMessages(compiled, resolvedApiKey, { message, sessionId, hitl });
+    const stream = streamAgentUIMessages(compiled, resolvedApiKey, { message, sessionId, hitl });
+    yield* observeServedRun(stream, { agentName, sessionId, request });
   })();
 }
 
 // src/server/agent/durable-ui-message-stream-response.ts
 var SSE_BASE_HEADERS = {
   "content-type": "text/event-stream",
+  "cache-control": "no-cache",
+  "x-accel-buffering": "no",
   "x-vercel-ai-ui-message-stream": "v1"
 };
 var RUN_ID_HEADER = "x-theokit-run-id";
@@ -1942,38 +2250,70 @@ function parseAgentRequestBody(body) {
   }
   return null;
 }
-async function mountAgent(mod, request, apiKey, { source = "agent module", csrfMode = "strict", projectRoot } = {}) {
+function memoizeSubject(resolveSubject) {
+  if (resolveSubject === void 0) return void 0;
+  let resolved;
+  return async () => {
+    resolved ??= { subject: await resolveSubject() };
+    return resolved.subject;
+  };
+}
+async function resolveApprovalOwner(declaredPolicy, resolveOnce) {
+  if (declaredPolicy === void 0 || declaredPolicy === "public") return void 0;
+  return (await resolveOnce?.() ?? void 0)?.id;
+}
+async function admitRequest(request, policy, resolveSubject, agentName) {
+  let body = null;
+  try {
+    body = await request.json();
+  } catch {
+  }
+  const input = parseAgentRequestBody(body);
+  if (input === null) {
+    return jsonError(400, "BAD_REQUEST", "Request must contain a non-empty message or messages[].");
+  }
+  const params = { agent: agentName, endpoint: "run", sessionId: input.sessionId };
+  const decision = await admitAgentRequest(policy, resolveSubject, params, input);
+  if (!decision.allowed) return agentAccessDenied(decision, params);
+  return input;
+}
+async function mountAgent(mod, request, apiKey, {
+  source = "agent module",
+  csrfMode = "strict",
+  projectRoot,
+  agentName,
+  policy,
+  resolveSubject
+} = {}) {
   if (csrfMode !== "off") {
     const csrf = validateCsrfRequest(request);
     if (!csrf.valid && csrfMode === "strict") {
       return jsonError(403, "CSRF_FAILED", `CSRF check failed: ${csrf.reason}`);
     }
   }
+  const identity = agentName ?? source;
+  const declaredPolicy = policy ?? readAgentPolicy(mod, source);
+  const resolveOnce = memoizeSubject(resolveSubject);
+  const admitted = await admitRequest(request, declaredPolicy, resolveOnce, identity);
+  if (admitted instanceof Response) return admitted;
+  const input = admitted;
   const compiled = compileAgentModule2(mod, source);
   const resolvedApiKey = typeof apiKey === "function" ? apiKey(compiled.model) : apiKey;
   if (compiled.skillsResolver) {
     const enabled = await resolveEnabledSkills2(compiled.skillsResolver, compiled.runContext ?? {});
     if (enabled !== void 0) compiled.skills = { enabled, autoInject: true };
   }
-  let body = null;
-  try {
-    body = await request.json();
-  } catch {
-  }
-  const input = parseAgentRequestBody(body);
-  if (input === null) {
-    return jsonError(400, "BAD_REQUEST", "Request must contain a non-empty message or messages[].");
-  }
-  const hitl = buildAgentHitl(compiled);
+  const hitl = buildAgentHitl(compiled, await resolveApprovalOwner(declaredPolicy, resolveOnce));
   const runId = mintRunId();
+  const stream = streamAgentUIMessages2(compiled, resolvedApiKey, {
+    ...input,
+    hitl,
+    signal: request.signal,
+    cwd: resolveDiscoveryCwd(compiled, projectRoot),
+    baseDir: resolveSessionBaseDir(projectRoot)
+  });
   return durableUiMessageStreamResponse(
-    streamAgentUIMessages2(compiled, resolvedApiKey, {
-      ...input,
-      hitl,
-      signal: request.signal,
-      cwd: resolveDiscoveryCwd(compiled, projectRoot),
-      baseDir: resolveSessionBaseDir(projectRoot)
-    }),
+    observeServedRun(stream, { agentName: identity, request }),
     { runId, cache: getRunEventCache() }
   );
 }
@@ -1992,21 +2332,17 @@ function resolveSessionBaseDir(projectRoot) {
 }
 
 // src/server/scan/module-loader.ts
-import { pathToFileURL } from "url";
 function createViteLoader(vite) {
   return (path) => vite.ssrLoadModule(path);
 }
 function createProductionLoader() {
-  return async (path) => {
-    const url = pathToFileURL(path).href;
-    return import(url);
-  };
+  return (path) => importUserModule(path);
 }
 
 // src/server/security/csp-report.ts
 var CSP_REPORT_PATH = "/__theo/csp-report";
 var MAX_BODY = 16 * 1024;
-function pickHeader2(value) {
+function pickHeader(value) {
   if (typeof value === "string") return value;
   if (Array.isArray(value) && value.length > 0) return value[0];
   return "";
@@ -2069,7 +2405,7 @@ async function readBody(req, maxBytes) {
 }
 async function handleCspReport(req, res, opts) {
   const ctHeader = req.headers["content-type"];
-  const ct = pickHeader2(ctHeader);
+  const ct = pickHeader(ctHeader);
   let raw;
   try {
     raw = await readBody(req, MAX_BODY);
@@ -2225,50 +2561,6 @@ var CsrfReadinessStore = class _CsrfReadinessStore {
 };
 
 // src/server/security/security-headers.ts
-var DEFAULT_CSP = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' ws: wss:; frame-ancestors 'none'; report-uri /__theo/csp-report";
-var DEFAULT_PERMISSIONS_POLICY = "geolocation=(), camera=(), microphone=(), payment=(), usb=(), accelerometer=(), gyroscope=()";
-var DEFAULT_HSTS = "max-age=31536000; includeSubDomains";
-function applyNonceToCsp(policy, nonce) {
-  return policy.split(";").map((directive) => {
-    const trimmed = directive.trim();
-    if (!trimmed.startsWith("script-src")) return directive;
-    if (trimmed.includes("'unsafe-inline'")) {
-      return directive.replace("'unsafe-inline'", `'nonce-${nonce}'`);
-    }
-    return `${directive} 'nonce-${nonce}'`;
-  }).join(";");
-}
-function applyCsp(out, config, effectiveNonce) {
-  if (config.csp === false || config.cspMode === "off") return;
-  let policy = typeof config.csp === "string" ? config.csp : DEFAULT_CSP;
-  if (effectiveNonce) {
-    policy = applyNonceToCsp(policy, effectiveNonce);
-  }
-  const mode = config.cspMode ?? "enforce";
-  if (mode === "enforce") {
-    out["Content-Security-Policy"] = policy;
-  } else {
-    out["Content-Security-Policy-Report-Only"] = policy;
-  }
-}
-function buildSecurityHeaders(config, env, options = {}) {
-  const out = {};
-  const effectiveNonce = options.prerender ? void 0 : options.nonce;
-  applyCsp(out, config, effectiveNonce);
-  out["X-Frame-Options"] = config.frameOptions ?? "DENY";
-  out["X-Content-Type-Options"] = config.contentTypeOptions ?? "nosniff";
-  out["Referrer-Policy"] = config.referrerPolicy ?? "strict-origin-when-cross-origin";
-  if (config.permissionsPolicy !== false) {
-    out["Permissions-Policy"] = typeof config.permissionsPolicy === "string" ? config.permissionsPolicy : DEFAULT_PERMISSIONS_POLICY;
-  }
-  if (env.production && config.hsts !== false) {
-    out["Strict-Transport-Security"] = typeof config.hsts === "string" ? config.hsts : DEFAULT_HSTS;
-  }
-  if (effectiveNonce) {
-    out["Cache-Control"] = "private, no-store";
-  }
-  return out;
-}
 function applySecurityHeaders(res, config, env, options = {}) {
   const headers = buildSecurityHeaders(config, env, options);
   for (const [key, value] of Object.entries(headers)) {
@@ -2276,48 +2568,23 @@ function applySecurityHeaders(res, config, env, options = {}) {
   }
 }
 
-// src/server/auth/nonce.ts
-function bytesToBase64(bytes) {
-  if (typeof Buffer !== "undefined") {
-    return Buffer.from(bytes).toString("base64");
-  }
-  let binary = "";
-  for (const b of bytes) {
-    binary += String.fromCharCode(b);
-  }
-  return btoa(binary);
-}
-var cachedWebCrypto;
-function getWebCrypto() {
-  if (cachedWebCrypto === void 0) {
-    const candidate = globalThis.crypto;
-    cachedWebCrypto = candidate && typeof candidate.getRandomValues === "function" ? candidate : null;
-  }
-  if (!cachedWebCrypto) {
-    throw new Error(
-      "generateNonce: Web Crypto unavailable. TheoKit requires Node.js 19+, Bun, Deno, or any modern Edge runtime where `globalThis.crypto.getRandomValues` is present."
-    );
-  }
-  return cachedWebCrypto;
-}
-function generateNonce() {
-  const buf = new Uint8Array(16);
-  getWebCrypto().getRandomValues(buf);
-  return bytesToBase64(buf);
-}
-
 export {
+  subjectFromContext,
+  writeWebResponseToServerResponse,
+  createServerContext,
   executeRoute,
   executeAction,
   BATCH_PATH,
   handleBatchRequest,
   createCorsHandler,
-  TRACE_HEADER,
-  extractTraceId,
   findSuggestion,
   createPluginRunnerFromConfig,
   InMemoryStore,
   createRateLimiter,
+  readAgentPolicy,
+  admitAgentRequest,
+  agentAccessDenied,
+  closePauseSpan,
   makeThreadStartRun,
   SSE_BASE_HEADERS,
   RUN_ID_HEADER,
@@ -2334,8 +2601,6 @@ export {
   handleCspReport,
   handleCsrfReadiness,
   CsrfReadinessStore,
-  buildSecurityHeaders,
-  applySecurityHeaders,
-  generateNonce
+  applySecurityHeaders
 };
-//# sourceMappingURL=chunk-WYHYOYRH.js.map
+//# sourceMappingURL=chunk-2COPDKIG.js.map