@theokit/agents 9.2.1 → 9.4.0

package/dist/chunk-CAXGTLRU.js

@@ -0,0 +1,1110 @@
+import {
+  createHitlPlugin,
+  createSdkAgentStream
+} from "./chunk-W6TABP2S.js";
+import {
+  compileAgentDefinition,
+  defineAgent,
+  isAgentDefinition
+} from "./chunk-4VHCH6IZ.js";
+import {
+  __name
+} from "./chunk-Z4QWC7IK.js";
+
+// src/errors.ts
+import { ConfigurationError } from "@theokit/sdk/errors";
+
+// src/bridge/compile-context-window.ts
+var STRATEGY_KNOBS = [
+  "compactionStrategy",
+  "preserveLastN",
+  "preserveToolResults",
+  "preserveSystemPrompt"
+];
+function compileContextWindow(options) {
+  const context = {};
+  if (typeof options.maxTokens === "number") {
+    context.maxTokens = options.maxTokens;
+  }
+  const opts = options;
+  const metadataOnlyKnobs = STRATEGY_KNOBS.filter((knob) => opts[knob] !== void 0);
+  return {
+    context,
+    metadataOnlyKnobs
+  };
+}
+__name(compileContextWindow, "compileContextWindow");
+
+// src/bridge/compile-skills.ts
+function compileSkills(options) {
+  if (options.autoDiscover) {
+    return {
+      autoInject: true
+    };
+  }
+  return {
+    enabled: options.include,
+    autoInject: true
+  };
+}
+__name(compileSkills, "compileSkills");
+
+// src/bridge/agent-compiler.ts
+var SDK_TOOL_NAME = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+var SDK_TOOL_NAME_MAX_LENGTH = 64;
+var SDK_TOOL_NAME_CHARSET = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+var SDK_RESERVED_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "shell",
+  "memory_search",
+  "memory_get"
+]);
+var SDK_RESERVED_TOOL_PREFIX = "mcp_";
+function toolRuntimeName(namespace, toolName) {
+  if (toolName.trim().length === 0) {
+    const where = namespace ? ` in namespace "${namespace}"` : "";
+    throw new ConfigurationError(`tool: empty name${where} \u2014 declare a non-empty name for the tool`);
+  }
+  const name = namespace ? `${namespace}_${toolName}` : toolName;
+  if (!SDK_TOOL_NAME.test(name)) {
+    if (SDK_TOOL_NAME_CHARSET.test(name)) {
+      throw new ConfigurationError(`tool: name "${name}" has length ${name.length} \u2014 the composition namespace + "_" + tool exceeds the maximum of ${SDK_TOOL_NAME_MAX_LENGTH} the SDK accepts`);
+    }
+    throw new ConfigurationError(`tool: invalid name "${name}" \u2014 it must match ${String(SDK_TOOL_NAME)} (the SDK rejects the rest; check the namespace and the tool name)`);
+  }
+  if (SDK_RESERVED_TOOL_NAMES.has(name) || name.startsWith(SDK_RESERVED_TOOL_PREFIX)) {
+    throw new ConfigurationError(`tool: reserved name "${name}" \u2014 the SDK reserves ${[
+      ...SDK_RESERVED_TOOL_NAMES
+    ].join(", ")} and the prefix "${SDK_RESERVED_TOOL_PREFIX}"`);
+  }
+  return name;
+}
+__name(toolRuntimeName, "toolRuntimeName");
+function compileHitlGates(toolboxes) {
+  const gates = /* @__PURE__ */ new Map();
+  for (const tb of toolboxes) {
+    for (const tool of tb.tools) {
+      if (tool.hitl) {
+        gates.set(toolRuntimeName(tb.namespace, tool.config.name), tool.hitl);
+      }
+    }
+  }
+  return gates;
+}
+__name(compileHitlGates, "compileHitlGates");
+function compileTools(toolboxes, toolboxInstances) {
+  const tools = [];
+  for (const tb of toolboxes) {
+    const instance = toolboxInstances.get(tb.class);
+    if (!instance) {
+      throw new ConfigurationError(`toolbox: ${tb.class.name} was not instantiated \u2014 pass the instance in \`toolboxInstances\``);
+    }
+    for (const tool of tb.tools) {
+      const handler = instance[tool.propertyKey];
+      if (typeof handler !== "function") {
+        throw new ConfigurationError(`toolbox: ${tb.class.name}.${String(tool.propertyKey)} is not a method (tool "${tool.config.name}")`);
+      }
+      const name = toolRuntimeName(tb.namespace, tool.config.name);
+      tools.push({
+        name,
+        description: tool.config.description,
+        inputSchema: tool.config.input,
+        handler: /* @__PURE__ */ __name((input) => handler.call(instance, input), "handler")
+      });
+    }
+  }
+  return tools;
+}
+__name(compileTools, "compileTools");
+
+// src/bridge/agent-execution-context.ts
+function createAgentExecutionContext(base, agent, run, toolCall) {
+  return {
+    getRequest: /* @__PURE__ */ __name(() => base.getRequest(), "getRequest"),
+    getUrl: /* @__PURE__ */ __name(() => base.getUrl(), "getUrl"),
+    getClass: /* @__PURE__ */ __name(() => base.getClass(), "getClass"),
+    getMethodName: /* @__PURE__ */ __name(() => base.getMethodName(), "getMethodName"),
+    getAgent: /* @__PURE__ */ __name(() => agent, "getAgent"),
+    getRun: /* @__PURE__ */ __name(() => run, "getRun"),
+    getToolCall: /* @__PURE__ */ __name(() => toolCall ?? null, "getToolCall"),
+    isAgentContext: /* @__PURE__ */ __name(() => true, "isAgentContext")
+  };
+}
+__name(createAgentExecutionContext, "createAgentExecutionContext");
+function isAgentContext(ctx) {
+  return "isAgentContext" in ctx && ctx.isAgentContext();
+}
+__name(isAgentContext, "isAgentContext");
+
+// src/bridge/agent-sse-handler.ts
+var encoder = new TextEncoder();
+function streamAgentResponse(eventStream) {
+  const stream = new ReadableStream({
+    async start(controller) {
+      let closed = false;
+      const safeEnqueue = /* @__PURE__ */ __name((chunk) => {
+        if (closed) return;
+        try {
+          controller.enqueue(chunk);
+        } catch {
+          closed = true;
+        }
+      }, "safeEnqueue");
+      try {
+        for await (const event of eventStream) {
+          if (closed) break;
+          const data = JSON.stringify(event);
+          const frame = `event: ${event.type}
+data: ${data}
+
+`;
+          safeEnqueue(encoder.encode(frame));
+        }
+      } catch (err) {
+        if (!closed) {
+          const errorEvent = {
+            type: "error",
+            error: {
+              message: err instanceof Error ? err.message : "Internal agent error"
+            }
+          };
+          const frame = `event: error
+data: ${JSON.stringify(errorEvent)}
+
+`;
+          safeEnqueue(encoder.encode(frame));
+        }
+      } finally {
+        controller.close();
+      }
+    }
+  });
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "content-type": "text/event-stream",
+      "cache-control": "no-cache",
+      connection: "keep-alive"
+    }
+  });
+}
+__name(streamAgentResponse, "streamAgentResponse");
+
+// src/bridge/agent-stream-events.ts
+function isTextDelta(e) {
+  return e.type === "text_delta";
+}
+__name(isTextDelta, "isTextDelta");
+function isToolCall(e) {
+  return e.type === "tool_call";
+}
+__name(isToolCall, "isToolCall");
+function isPartialToolCall(e) {
+  return e.type === "partial_tool_call";
+}
+__name(isPartialToolCall, "isPartialToolCall");
+function isToolResult(e) {
+  return e.type === "tool_result";
+}
+__name(isToolResult, "isToolResult");
+function isDone(e) {
+  return e.type === "done";
+}
+__name(isDone, "isDone");
+function isError(e) {
+  return e.type === "error";
+}
+__name(isError, "isError");
+function isApprovalRequired(e) {
+  return e.type === "approval_required";
+}
+__name(isApprovalRequired, "isApprovalRequired");
+
+// src/bridge/agent-route-generator.ts
+function generateAgentRoutes(ctx) {
+  const { walkResult, createRun, getRun } = ctx;
+  const basePath = walkResult.route.replace(/\/$/, "");
+  const routes = [];
+  routes.push({
+    method: "POST",
+    path: `${basePath}/chat`,
+    handler: /* @__PURE__ */ __name(async (request) => {
+      let body = null;
+      try {
+        body = await request.json();
+      } catch {
+      }
+      const message = body?.message;
+      if (typeof message !== "string" || message.length === 0) {
+        return new Response(JSON.stringify({
+          error: {
+            code: "BAD_REQUEST",
+            message: "message field required"
+          }
+        }), {
+          status: 400,
+          headers: {
+            "content-type": "application/json"
+          }
+        });
+      }
+      const rawSessionId = body?.sessionId;
+      const sessionId = typeof rawSessionId === "string" ? rawSessionId : `session-${Date.now()}`;
+      return streamAgentResponse(createRun(message, sessionId));
+    }, "handler")
+  });
+  if (getRun) {
+    routes.push({
+      method: "GET",
+      path: `${basePath}/runs/:runId`,
+      handler: /* @__PURE__ */ __name(async (request) => {
+        const url = new URL(request.url);
+        const runId = url.pathname.split("/").pop() ?? "";
+        const run = await getRun(runId);
+        if (!run) {
+          return new Response(JSON.stringify({
+            error: {
+              code: "NOT_FOUND",
+              message: `Run ${runId} not found`
+            }
+          }), {
+            status: 404,
+            headers: {
+              "content-type": "application/json"
+            }
+          });
+        }
+        return new Response(JSON.stringify(run), {
+          status: 200,
+          headers: {
+            "content-type": "application/json"
+          }
+        });
+      }, "handler")
+    });
+  }
+  return routes;
+}
+__name(generateAgentRoutes, "generateAgentRoutes");
+
+// src/bridge/present-ui-message-stream.ts
+import { UIMessageStreamPresenter } from "@theokit/presenter";
+function toAgentOutputEvent(e) {
+  switch (e.type) {
+    case "text_delta":
+      return {
+        type: "text",
+        text: e.content
+      };
+    case "thinking":
+      return {
+        type: "reasoning",
+        text: e.content
+      };
+    case "tool_call":
+      return {
+        type: "tool-call",
+        callId: e.callId,
+        name: e.toolName,
+        input: e.input
+      };
+    case "tool_result":
+      return {
+        type: "tool-result",
+        callId: e.callId,
+        name: e.toolName,
+        result: e.output,
+        isError: e.isError
+      };
+    default:
+      return null;
+  }
+}
+__name(toAgentOutputEvent, "toAgentOutputEvent");
+function doneToMetadata(event) {
+  return event.cost === void 0 ? {
+    usage: event.usage,
+    durationMs: event.durationMs
+  } : {
+    usage: event.usage,
+    durationMs: event.durationMs,
+    cost: event.cost
+  };
+}
+__name(doneToMetadata, "doneToMetadata");
+var ERROR_CODE_DATA_PART = "data-error-code";
+var INPUT_REQUESTED_DATA_PART = "data-input-requested";
+var TASK_PROGRESS_DATA_PART = "data-task-progress";
+var SHELL_OUTPUT_DATA_PART = "data-shell-output";
+function dataPart(type, data) {
+  return {
+    type,
+    data,
+    transient: true
+  };
+}
+__name(dataPart, "dataPart");
+function* errorChunks(errorText, code) {
+  if (code !== void 0) yield dataPart(ERROR_CODE_DATA_PART, {
+    code
+  });
+  yield {
+    type: "error",
+    errorText
+  };
+}
+__name(errorChunks, "errorChunks");
+function diagnosticDataPart(event) {
+  switch (event.type) {
+    case "checkpoint_saved":
+      return dataPart("data-checkpoint", {
+        checkpointId: event.checkpointId,
+        resumeToken: event.resumeToken,
+        step: event.step
+      });
+    // theokit#141 — without these cases the three restored events would be dropped by the loop's
+    // catch-all, which is the reported defect one layer down: translating an event and never
+    // presenting it leaves the consumer just as blind, minus even the warning.
+    case "input_requested":
+      return dataPart(INPUT_REQUESTED_DATA_PART, {
+        requestId: event.requestId
+      });
+    case "task_progress":
+      return dataPart(TASK_PROGRESS_DATA_PART, {
+        ...event.status !== void 0 ? {
+          status: event.status
+        } : {},
+        ...event.text !== void 0 ? {
+          text: event.text
+        } : {}
+      });
+    case "shell_output":
+      return dataPart(SHELL_OUTPUT_DATA_PART, {
+        event: event.event
+      });
+    default:
+      return null;
+  }
+}
+__name(diagnosticDataPart, "diagnosticDataPart");
+async function* presentUIMessageStream(events, opts) {
+  const presenter = new UIMessageStreamPresenter({
+    textId: opts.textId
+  });
+  yield {
+    type: "start"
+  };
+  let turnMetadata;
+  try {
+    for await (const event of events) {
+      const output = toAgentOutputEvent(event);
+      if (output !== null) {
+        yield* presenter.present(output);
+        continue;
+      }
+      if (event.type === "approval_required") {
+        yield* presenter.closeBlock();
+        if (!presenter.hasSeen(event.callId)) {
+          presenter.markSeen(event.callId);
+          yield {
+            type: "tool-input-available",
+            toolCallId: event.callId,
+            toolName: event.toolName,
+            input: event.input ?? {},
+            dynamic: true
+          };
+        }
+        yield {
+          type: "tool-approval-request",
+          approvalId: event.callId,
+          toolCallId: event.callId
+        };
+        continue;
+      }
+      const diagnostic = diagnosticDataPart(event);
+      if (diagnostic !== null) {
+        yield* presenter.closeBlock();
+        yield diagnostic;
+        continue;
+      }
+      if (event.type === "error") {
+        yield* errorChunks(event.message, event.code);
+        break;
+      }
+      if (event.type === "done") {
+        turnMetadata = doneToMetadata(event);
+        break;
+      }
+    }
+  } catch (err) {
+    const code = err.code;
+    yield* errorChunks(String(err), typeof code === "string" ? code : void 0);
+  }
+  yield* presenter.finish(turnMetadata);
+}
+__name(presentUIMessageStream, "presentUIMessageStream");
+
+// src/bridge/agent-builder.ts
+var ContextualTool = {
+  /**
+  * Tag a {@link CustomTool} with a literal name (so `.tool()` can accumulate the tool-name union)
+  * and, optionally, a required run-context type. The `requiredContext` argument is a type-only
+  * witness — pass `undefined as C` or a sample value; it is never read at runtime.
+  */
+  of(tool, _requiredContext) {
+    return tool;
+  }
+};
+function makeBuilder(config) {
+  const runtime = {
+    input: /* @__PURE__ */ __name((schema) => makeBuilder({
+      ...config,
+      input: schema
+    }), "input"),
+    model: /* @__PURE__ */ __name((id) => makeBuilder({
+      ...config,
+      model: id
+    }), "model"),
+    system: /* @__PURE__ */ __name((prompt) => makeBuilder({
+      ...config,
+      system: prompt
+    }), "system"),
+    reasoningEffort: /* @__PURE__ */ __name((effort) => makeBuilder({
+      ...config,
+      reasoningEffort: effort
+    }), "reasoningEffort"),
+    context: /* @__PURE__ */ __name((value) => makeBuilder({
+      ...config,
+      context: value
+    }), "context"),
+    tool: /* @__PURE__ */ __name((tool) => makeBuilder({
+      ...config,
+      tools: [
+        ...config.tools ?? [],
+        tool
+      ]
+    }), "tool"),
+    tools: /* @__PURE__ */ __name((list) => makeBuilder({
+      ...config,
+      tools: [
+        ...config.tools ?? [],
+        ...list
+      ]
+    }), "tools"),
+    // `when` is deliberately not a conditional-typed return: the branch runs or it does not, and
+    // either way the caller gets a builder carrying the same accumulated state. Returning `builder`
+    // unchanged on `false` is what makes it a true no-op rather than a reset.
+    when: /* @__PURE__ */ __name((condition, apply) => {
+      const builder = makeBuilder(config);
+      return condition ? apply(builder) : builder;
+    }, "when"),
+    guardrail: /* @__PURE__ */ __name((g) => makeBuilder({
+      ...config,
+      guardrails: [
+        ...config.guardrails ?? [],
+        g
+      ]
+    }), "guardrail"),
+    guardrails: /* @__PURE__ */ __name((gs) => makeBuilder({
+      ...config,
+      guardrails: gs
+    }), "guardrails"),
+    approval: /* @__PURE__ */ __name((toolName, options) => makeBuilder({
+      ...config,
+      approvals: {
+        ...config.approvals ?? {},
+        [toolName]: options
+      }
+    }), "approval"),
+    approvals: /* @__PURE__ */ __name((map) => makeBuilder({
+      ...config,
+      approvals: map
+    }), "approvals"),
+    skills: /* @__PURE__ */ __name((selection) => makeBuilder({
+      ...config,
+      skills: selection
+    }), "skills"),
+    settingSources: /* @__PURE__ */ __name((selection) => makeBuilder({
+      ...config,
+      settingSources: selection
+    }), "settingSources"),
+    memory: /* @__PURE__ */ __name((settings) => makeBuilder({
+      ...config,
+      memory: settings
+    }), "memory"),
+    hooks: /* @__PURE__ */ __name((map) => makeBuilder({
+      ...config,
+      hooks: map
+    }), "hooks"),
+    plugins: /* @__PURE__ */ __name((list) => makeBuilder({
+      ...config,
+      plugins: list
+    }), "plugins"),
+    mcp: /* @__PURE__ */ __name((servers) => makeBuilder({
+      ...config,
+      mcpServers: servers
+    }), "mcp"),
+    use: /* @__PURE__ */ __name((preset) => preset(runtime), "use"),
+    build: /* @__PURE__ */ __name(() => defineAgent(config), "build")
+  };
+  return runtime;
+}
+__name(makeBuilder, "makeBuilder");
+var AgentBuilder = {
+  /**
+  * Start a fluent agent definition. Chain `.model()` (required) + `.context()` / `.system()` /
+  * `.input()` / `.tool()` / `.use()`, then `.build()` to get the branded {@link AgentDefinition}.
+  */
+  create() {
+    return makeBuilder({});
+  }
+};
+
+// src/bridge/agent-endpoint.ts
+import { TheokitAgentError } from "@theokit/sdk/errors";
+var AgentDefinitionError = class extends TheokitAgentError {
+  static {
+    __name(this, "AgentDefinitionError");
+  }
+  name = "AgentDefinitionError";
+  constructor(source) {
+    super(`[@theokit/agents] ${source}: an agents/ file must default-export a defineAgent(...) value or an @Agent-decorated class.`, {
+      code: "AGENT_DEFINITION_INVALID",
+      // a malformed module does not become well-formed by being loaded twice.
+      isRetryable: false
+    });
+  }
+};
+function extractDefaultExport(mod) {
+  if (typeof mod === "object" && mod !== null && "default" in mod) {
+    return mod.default;
+  }
+  return mod;
+}
+__name(extractDefaultExport, "extractDefaultExport");
+function isCompiledAgentOptions(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return Array.isArray(v.tools) && typeof v.agents === "object" && v.agents !== null;
+}
+__name(isCompiledAgentOptions, "isCompiledAgentOptions");
+function compileAgentModule(mod, source = "agent module") {
+  const def = extractDefaultExport(mod);
+  if (isAgentDefinition(def)) {
+    return compileAgentDefinition(def);
+  }
+  if (isCompiledAgentOptions(def)) return def;
+  throw new AgentDefinitionError(source);
+}
+__name(compileAgentModule, "compileAgentModule");
+async function* asAgentStream(events) {
+  for await (const e of events) yield e;
+}
+__name(asAgentStream, "asAgentStream");
+var EventQueue = class EventQueue2 {
+  static {
+    __name(this, "EventQueue");
+  }
+  #items = [];
+  #resolvers = [];
+  #closed = false;
+  push(item) {
+    if (this.#closed) return;
+    const r = this.#resolvers.shift();
+    if (r) r({
+      value: item,
+      done: false
+    });
+    else this.#items.push(item);
+  }
+  close() {
+    this.#closed = true;
+    for (const r of this.#resolvers.splice(0)) r({
+      value: void 0,
+      done: true
+    });
+  }
+  async *drain() {
+    for (; ; ) {
+      if (this.#items.length > 0) {
+        yield this.#items.shift();
+        continue;
+      }
+      if (this.#closed) return;
+      const next = await new Promise((resolve) => this.#resolvers.push(resolve));
+      if (next.done) return;
+      yield next.value;
+    }
+  }
+};
+async function* appendCheckpointSaved(source, sessionId) {
+  let emitted = false;
+  const checkpoint = /* @__PURE__ */ __name(() => ({
+    type: "checkpoint_saved",
+    checkpointId: crypto.randomUUID(),
+    step: 0,
+    resumeToken: sessionId
+  }), "checkpoint");
+  for await (const ev of source) {
+    if (ev.type === "done" && !emitted) {
+      emitted = true;
+      yield checkpoint();
+    }
+    yield ev;
+  }
+  if (!emitted) yield checkpoint();
+}
+__name(appendCheckpointSaved, "appendCheckpointSaved");
+function streamAgentUIMessages(compiled, apiKey, input) {
+  const textId = crypto.randomUUID();
+  const overrides = {};
+  if (input.cwd !== void 0) overrides.cwd = input.cwd;
+  if (input.baseDir !== void 0) overrides.baseDir = input.baseDir;
+  if (input.images !== void 0) overrides.images = input.images;
+  if (input.onRunEvent !== void 0) overrides.onRunEvent = input.onRunEvent;
+  let source;
+  if (!input.hitl || input.hitl.gated.size === 0) {
+    const events2 = createSdkAgentStream(compiled, compiled.tools, apiKey, overrides)(input.message, input.sessionId);
+    source = asAgentStream(events2);
+  } else {
+    const queue = new EventQueue();
+    input.signal?.addEventListener("abort", () => {
+      queue.close();
+    }, {
+      once: true
+    });
+    const plugin = createHitlPlugin({
+      gated: input.hitl.gated,
+      emit: /* @__PURE__ */ __name((e) => {
+        queue.push(e);
+      }, "emit"),
+      awaitApproval: input.hitl.awaitApproval
+    });
+    const sdkStream = createSdkAgentStream(compiled, compiled.tools, apiKey, {
+      ...overrides,
+      // The HITL plugin is a structural @theokit/sdk Plugin (createHitlPlugin returns the
+      // { name, register } shape); the RuntimeOverrides.plugins union is widened at the SDK edge.
+      plugins: [
+        plugin
+      ]
+    })(input.message, input.sessionId);
+    void (async () => {
+      try {
+        for await (const e of sdkStream) queue.push(e);
+      } catch (err) {
+        queue.push({
+          type: "error",
+          code: "SDK_STREAM_ERROR",
+          message: err instanceof Error ? err.message : String(err),
+          retryable: false
+        });
+      } finally {
+        queue.close();
+      }
+    })();
+    source = queue.drain();
+  }
+  const durableCheckpoint = compiled.checkpoint?.storage === "filesystem";
+  const events = durableCheckpoint ? appendCheckpointSaved(source, input.sessionId) : source;
+  return presentUIMessageStream(events, {
+    textId
+  });
+}
+__name(streamAgentUIMessages, "streamAgentUIMessages");
+
+// src/bridge/api-error-handler.ts
+var DEFAULT_MAX_ATTEMPTS = 3;
+async function runWithApiErrorHandling(thunk, policy) {
+  const maxAttempts = policy.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  let attempt = 0;
+  for (; ; ) {
+    attempt += 1;
+    try {
+      return await thunk();
+    } catch (error) {
+      const decision = await policy.processApiError({
+        error,
+        attempt
+      });
+      if (decision.retry && attempt < maxAttempts) continue;
+      if (!decision.retry && "fallback" in decision && decision.fallback !== void 0) {
+        return decision.fallback;
+      }
+      throw error;
+    }
+  }
+}
+__name(runWithApiErrorHandling, "runWithApiErrorHandling");
+function createApiErrorHandler(policy) {
+  return (thunk) => runWithApiErrorHandling(thunk, policy);
+}
+__name(createApiErrorHandler, "createApiErrorHandler");
+
+// src/bridge/mcp-resolver.ts
+async function resolveMcpServers(selection, ctx) {
+  if (selection === void 0) return void 0;
+  if (typeof selection !== "function") return selection;
+  const resolved = await selection(ctx);
+  if (typeof resolved !== "object" || resolved === null) {
+    throw new Error("[@theokit/agents] MCP resolver must return an McpServersMap object");
+  }
+  return resolved;
+}
+__name(resolveMcpServers, "resolveMcpServers");
+function mcpRegistry(config) {
+  const registry = config.registry;
+  if (registry === "composio") {
+    const apps = config.apps ?? [];
+    return {
+      composio: {
+        command: "npx",
+        args: [
+          "-y",
+          "@composio/mcp",
+          ...apps.length > 0 ? [
+            "--apps",
+            apps.join(",")
+          ] : []
+        ],
+        env: {
+          COMPOSIO_API_KEY: config.apiKey
+        }
+      }
+    };
+  }
+  if (registry === "mcp.run") {
+    return {
+      "mcp.run": {
+        command: "npx",
+        args: [
+          "-y",
+          "@mcp.run/cli",
+          "serve",
+          ...config.profile ? [
+            "--profile",
+            config.profile
+          ] : []
+        ],
+        env: {
+          MCP_RUN_API_KEY: config.apiKey
+        }
+      }
+    };
+  }
+  throw new Error(`mcpRegistry: unknown registry ${JSON.stringify(registry)} (supported: 'composio', 'mcp.run').`);
+}
+__name(mcpRegistry, "mcpRegistry");
+function mcpToolApprovals(specs) {
+  const out = {};
+  for (const [tool, spec] of Object.entries(specs)) {
+    out[tool] = typeof spec === "string" ? {
+      question: spec
+    } : spec;
+  }
+  return out;
+}
+__name(mcpToolApprovals, "mcpToolApprovals");
+
+// src/bridge/mcp-file.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { TheokitAgentError as TheokitAgentError2 } from "@theokit/sdk/errors";
+function warningChannel(opts) {
+  return opts.onWarn ?? ((warning) => {
+    process.stderr.write(`[@theokit/agents] ${warning}
+`);
+  });
+}
+__name(warningChannel, "warningChannel");
+var McpFileError = class extends TheokitAgentError2 {
+  static {
+    __name(this, "McpFileError");
+  }
+  name = "McpFileError";
+  constructor(message) {
+    super(`[@theokit/agents] ${message}`);
+  }
+};
+var MCP_FILENAME = ".mcp.json";
+function loadMcpJson(cwd, opts = {}) {
+  const path = join(cwd, MCP_FILENAME);
+  if (!existsSync(path)) return {};
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (err) {
+    throw new McpFileError(`failed to read ${path}: ${describeIt(err)}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new McpFileError(`${path} is not valid JSON: ${describeIt(err)}`);
+  }
+  return parseMcpJson(parsed, path, warningChannel(opts));
+}
+__name(loadMcpJson, "loadMcpJson");
+function parseMcpJson(raw, source, onWarn) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new McpFileError(`${source}: root must be a JSON object with an "mcpServers" key.`);
+  }
+  const serversRaw = raw.mcpServers;
+  if (serversRaw === void 0) return {};
+  if (typeof serversRaw !== "object" || serversRaw === null || Array.isArray(serversRaw)) {
+    throw new McpFileError(`${source}: "mcpServers" must be an object keyed by server name.`);
+  }
+  const out = {};
+  for (const [name, entryRaw] of Object.entries(serversRaw)) {
+    const reason = validateEntry(name, entryRaw);
+    if (reason !== void 0) {
+      onWarn(`${source}: server "${name}" ignored \u2014 ${reason}`);
+      continue;
+    }
+    out[name] = buildEntry(entryRaw);
+  }
+  return out;
+}
+__name(parseMcpJson, "parseMcpJson");
+function validateEntry(name, entryRaw) {
+  if (typeof entryRaw !== "object" || entryRaw === null || Array.isArray(entryRaw)) {
+    return "the entry must be an object.";
+  }
+  const entry = entryRaw;
+  const hasUrl = entry.url !== void 0;
+  const hasCommand = entry.command !== void 0;
+  if (hasUrl && hasCommand) return 'declares both "command" and "url" \u2014 pick one transport.';
+  if (!hasUrl && !hasCommand) return 'requires "command" (stdio) or "url" (http/sse).';
+  return hasUrl ? validateRemote(entry) : validateStdio(entry);
+}
+__name(validateEntry, "validateEntry");
+function validateStdio(entry) {
+  if (typeof entry.command !== "string" || entry.command.length === 0) {
+    return 'field "command" must be a non-empty string.';
+  }
+  if (entry.args !== void 0 && !isStringArray(entry.args)) return 'field "args" must be an array of strings.';
+  if (entry.env !== void 0 && !isStringRecord(entry.env)) return 'field "env" must be a map of strings.';
+  if (entry.cwd !== void 0 && typeof entry.cwd !== "string") return 'field "cwd" must be a string.';
+  return void 0;
+}
+__name(validateStdio, "validateStdio");
+function validateRemote(entry) {
+  if (typeof entry.url !== "string" || entry.url.length === 0) {
+    return 'field "url" must be a non-empty string.';
+  }
+  try {
+    new URL(entry.url);
+  } catch {
+    return 'field "url" is not a valid URL.';
+  }
+  if (entry.type !== void 0 && entry.type !== "http" && entry.type !== "sse") {
+    return 'field "type" must be "http" or "sse".';
+  }
+  if (entry.headers !== void 0 && !isStringRecord(entry.headers)) {
+    return 'field "headers" must be a map of strings.';
+  }
+  if (entry.requestTimeoutMs !== void 0 && typeof entry.requestTimeoutMs !== "number") {
+    return 'field "requestTimeoutMs" must be a number.';
+  }
+  return void 0;
+}
+__name(validateRemote, "validateRemote");
+function buildEntry(entry) {
+  if (entry.url !== void 0) {
+    const remote = {
+      url: entry.url
+    };
+    if (entry.type !== void 0) remote.type = entry.type;
+    if (entry.headers !== void 0) remote.headers = entry.headers;
+    if (entry.auth !== void 0) remote.auth = entry.auth;
+    if (entry.requestTimeoutMs !== void 0) remote.requestTimeoutMs = entry.requestTimeoutMs;
+    return remote;
+  }
+  const stdio = {
+    command: entry.command
+  };
+  if (entry.args !== void 0) stdio.args = entry.args;
+  if (entry.env !== void 0) stdio.env = entry.env;
+  if (entry.cwd !== void 0) stdio.cwd = entry.cwd;
+  return stdio;
+}
+__name(buildEntry, "buildEntry");
+function describeIt(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+__name(describeIt, "describeIt");
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+__name(isStringArray, "isStringArray");
+function isStringRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
+}
+__name(isStringRecord, "isStringRecord");
+
+// src/manifest/agent-manifest.ts
+function generateAgentManifest(sources) {
+  return {
+    version: "1.0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    agents: sources.map((r) => ({
+      name: r.agentConfig.name,
+      route: r.route,
+      model: r.agentConfig.model,
+      stream: r.agentConfig.stream ?? true,
+      mainLoop: {
+        method: String(r.mainLoop.propertyKey),
+        strategy: r.mainLoop.strategy
+      },
+      guards: r.guards.map((g) => g.name),
+      interceptors: r.interceptors.map((i) => i.name),
+      tools: r.toolboxes.flatMap((tb) => tb.tools.map((t) => ({
+        name: tb.namespace ? `${tb.namespace}.${t.config.name}` : t.config.name,
+        description: t.config.description,
+        risk: t.config.risk,
+        approval: t.approval !== void 0,
+        capabilities: t.capabilities,
+        trace: t.trace,
+        audit: t.audit
+      }))),
+      gateway: r.gateway ? {
+        platforms: r.gateway.platforms,
+        sessionStrategy: r.gateway.sessionStrategy ?? "per-user"
+      } : void 0,
+      subAgents: r.subAgentClasses.map((cls) => cls.name),
+      memory: r.memory ? {
+        provider: r.memory.provider ?? "built-in",
+        embeddings: r.memory.embeddings ?? false,
+        fts: r.memory.fts ?? false,
+        scope: r.memory.scope ?? "per-user"
+      } : void 0,
+      skills: r.skills?.include,
+      mcpServers: r.mcpServers ? Object.keys(r.mcpServers) : void 0
+    }))
+  };
+}
+__name(generateAgentManifest, "generateAgentManifest");
+
+// src/theokit-plugin.ts
+function validateUniqueRoutes(results) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    const existing = seen.get(r.route);
+    if (existing !== void 0) {
+      throw new Error(`[@theokit/agents] Duplicate agent route '${r.route}': both '${existing}' and '${r.agentConfig.name}' declare it.`);
+    }
+    seen.set(r.route, r.agentConfig.name);
+  }
+}
+__name(validateUniqueRoutes, "validateUniqueRoutes");
+function agentsPlugin(opts) {
+  let routes = null;
+  return {
+    name: "@theokit/agents",
+    register(app) {
+      app.addHook("onRequest", async (pluginCtx) => {
+        routes ??= initRoutes(opts);
+        const request = pluginCtx.request;
+        const url = new URL(request.url);
+        const method = request.method.toUpperCase();
+        const matched = matchRoute(routes, method, url.pathname);
+        if (!matched) return;
+        return matched.handler(request);
+      });
+    }
+  };
+}
+__name(agentsPlugin, "agentsPlugin");
+function initRoutes(opts) {
+  const allRoutes = [];
+  const routeIdentities = [];
+  for (const entry of opts.agents) {
+    routeIdentities.push({
+      route: entry.route,
+      agentConfig: {
+        name: entry.name
+      }
+    });
+    const createRun = opts.createRunFactory ? opts.createRunFactory(entry.compiled) : defaultCreateRun(entry.compiled);
+    allRoutes.push(...generateAgentRoutes({
+      walkResult: {
+        route: entry.route
+      },
+      compiledOptions: entry.compiled,
+      createRun
+    }));
+  }
+  validateUniqueRoutes(routeIdentities);
+  return compileRoutePatterns(allRoutes);
+}
+__name(initRoutes, "initRoutes");
+function defaultCreateRun(compiled) {
+  return async function* (_message, _sessionId) {
+    await Promise.resolve();
+    yield {
+      type: "run_started",
+      runId: `run-${Date.now()}`,
+      agentName: compiled.model ?? "unknown"
+    };
+    yield {
+      type: "error",
+      code: "SDK_NOT_WIRED",
+      message: "No createRunFactory provided \u2014 wire @theokit/sdk Agent.create() to enable real agent execution.",
+      retryable: false
+    };
+  };
+}
+__name(defaultCreateRun, "defaultCreateRun");
+function compileRoutePatterns(routes) {
+  return routes.map((r) => {
+    if (!r.path.includes(":")) return r;
+    const regexSource = r.path.replace(/:[^/]+/g, "[^/]+");
+    return {
+      ...r,
+      regex: RegExp(`^${regexSource}$`)
+    };
+  });
+}
+__name(compileRoutePatterns, "compileRoutePatterns");
+function matchRoute(routes, method, pathname) {
+  return routes.find((r) => {
+    if (r.method !== method) return false;
+    if (r.regex) return r.regex.test(pathname);
+    return r.path === pathname;
+  });
+}
+__name(matchRoute, "matchRoute");
+
+export {
+  ConfigurationError,
+  compileContextWindow,
+  compileSkills,
+  toolRuntimeName,
+  compileHitlGates,
+  compileTools,
+  createAgentExecutionContext,
+  isAgentContext,
+  streamAgentResponse,
+  isTextDelta,
+  isToolCall,
+  isPartialToolCall,
+  isToolResult,
+  isDone,
+  isError,
+  isApprovalRequired,
+  generateAgentRoutes,
+  presentUIMessageStream,
+  ContextualTool,
+  AgentBuilder,
+  AgentDefinitionError,
+  compileAgentModule,
+  streamAgentUIMessages,
+  runWithApiErrorHandling,
+  createApiErrorHandler,
+  resolveMcpServers,
+  mcpRegistry,
+  mcpToolApprovals,
+  McpFileError,
+  loadMcpJson,
+  generateAgentManifest,
+  agentsPlugin
+};
+//# sourceMappingURL=chunk-CAXGTLRU.js.map