@theokit/agents 0.2.0 → 0.4.0

package/dist/{chunk-YSQAZWGW.js → chunk-NC5EE7HN.js}

@@ -2,12 +2,12 @@ import {
   AGENT_CONFIG,
   AGENT_MAIN_LOOP,
   Audit,
+  Budget,
   RequiresApproval,
   TOOLBOX_CONFIG,
   TOOL_CONFIG,
   TOOL_METHODS,
   Trace,
-  __name,
   getAgentConfig,
   getGatewayConfig,
   getMcpConfig,
@@ -16,7 +16,10 @@ import {
   getMixins,
   getSkillsConfig,
   getSubAgents
-} from "./chunk-3LCIXX3T.js";
+} from "./chunk-O4UG4RXE.js";
+import {
+  __name
+} from "./chunk-7QVYU63E.js";
 
 // src/bridge/agent-execution-context.ts
 function createAgentExecutionContext(base, agent, run, toolCall) {
@@ -39,11 +42,16 @@ __name(isAgentContext, "isAgentContext");
 
 // src/bridge/walk-agent-metadata.ts
 import "reflect-metadata";
-import { Reflector } from "@theokit/http-decorators";
-var reflectorInstance = new Reflector();
+import { Reflector } from "@theokit/http";
 var USE_GUARDS = /* @__PURE__ */ Symbol.for("theokit:http-decorators:use-guards");
 var USE_INTERCEPTORS = /* @__PURE__ */ Symbol.for("theokit:http-decorators:use-interceptors");
 var USE_FILTERS = /* @__PURE__ */ Symbol.for("theokit:http-decorators:use-filters");
+var AgentWarningCode = {
+  INTERCEPTOR_METADATA_ONLY: "THEO_AGENT_INTERCEPTOR_METADATA_ONLY",
+  FILTER_METADATA_ONLY: "THEO_AGENT_FILTER_METADATA_ONLY",
+  BUDGET_TOP_LEVEL_METADATA_ONLY: "THEO_AGENT_BUDGET_TOP_LEVEL_METADATA_ONLY"
+};
+var reflectorInstance = new Reflector();
 function walkToolbox(ToolboxClass) {
   const config = getMeta(TOOLBOX_CONFIG, ToolboxClass) ?? {};
   const methods = getMeta(TOOL_METHODS, ToolboxClass) ?? [];
@@ -96,7 +104,17 @@ function walkAgentMetadata(AgentClass, toolboxClasses = []) {
   }
   const guards = getMeta(USE_GUARDS, AgentClass) ?? [];
   const interceptors = getMeta(USE_INTERCEPTORS, AgentClass) ?? [];
+  if (interceptors.length > 0) {
+    console.warn(`[${AgentWarningCode.INTERCEPTOR_METADATA_ONLY}] Agent ${AgentClass.name}: @UseInterceptors is metadata-only on agents and will not execute. Agent pipeline shares guards with HTTP but uses a distinct execution model. Interceptors are reserved for future agent-specific lifecycle hooks.`);
+  }
   const filters = getMeta(USE_FILTERS, AgentClass) ?? [];
+  if (filters.length > 0) {
+    console.warn(`[${AgentWarningCode.FILTER_METADATA_ONLY}] Agent ${AgentClass.name}: @UseFilters is metadata-only on agents and will not catch agent runtime errors. Agent errors flow through SSE error events, not HTTP exception filters. Filters are reserved for future agent-specific error handling.`);
+  }
+  const agentBudget = reflectorInstance.get(Budget, AgentClass);
+  if (agentBudget) {
+    console.warn(`[${AgentWarningCode.BUDGET_TOP_LEVEL_METADATA_ONLY}] Agent ${AgentClass.name}: @Budget on top-level agents is metadata-only in this version. Budget enforcement currently applies to delegate() calls only. Top-level run enforcement will be wired through SDK cost tracking in a future release.`);
+  }
   const toolboxes = toolboxClasses.map(walkToolbox);
   const gateway = getGatewayConfig(AgentClass);
   const subAgentClasses = getSubAgents(AgentClass);
@@ -299,7 +317,8 @@ function generateAgentRoutes(ctx) {
           }
         });
       }
-      const sessionId = body?.sessionId ?? `session-${Date.now()}`;
+      const rawSessionId = body?.sessionId;
+      const sessionId = typeof rawSessionId === "string" ? rawSessionId : `session-${Date.now()}`;
       return streamAgentResponse(createRun(message, sessionId));
     }, "handler")
   });
@@ -337,253 +356,308 @@ function generateAgentRoutes(ctx) {
 }
 __name(generateAgentRoutes, "generateAgentRoutes");
 
-// src/bridge/llm-runner.ts
-import { z } from "zod";
-var OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions";
-var sessions = /* @__PURE__ */ new Map();
-setInterval(() => {
-  const now = Date.now();
-  for (const [id, s] of sessions) {
-    if (now - s.createdAt > 36e5) sessions.delete(id);
+// src/bridge/event-translator.ts
+function asString(value, fallback) {
+  if (typeof value === "string") return value;
+  return fallback;
+}
+__name(asString, "asString");
+function translateSystemEvent(msg, runId) {
+  return [
+    {
+      type: "run_started",
+      runId,
+      agentName: asString(msg.agent_id, "agent"),
+      model: asString(msg.model, "unknown")
+    }
+  ];
+}
+__name(translateSystemEvent, "translateSystemEvent");
+function translateAssistantEvent(msg) {
+  const events = [];
+  const content = msg.content;
+  if (!Array.isArray(content)) return events;
+  for (const block of content) {
+    const b = block;
+    if (b.type === "text" && b.text) {
+      events.push({
+        type: "text_delta",
+        content: b.text
+      });
+    }
+    if (b.type === "tool_use") {
+      events.push({
+        type: "tool_call",
+        callId: b.id ?? `tc-${Date.now()}`,
+        toolName: b.name ?? "unknown",
+        input: b.input ?? {}
+      });
+    }
   }
-}, 3e5).unref();
-function resolveModel(decorator, env) {
-  const m = env ?? decorator ?? "openai/gpt-4o-mini";
-  return m.includes("/") ? m : `anthropic/${m}`;
-}
-__name(resolveModel, "resolveModel");
-var sanitize = /* @__PURE__ */ __name((n) => n.replace(/\./g, "_"), "sanitize");
-function createRealAgentStream(agentWalk, compiledTools, apiKey, envModel) {
-  const model = resolveModel(agentWalk.agentConfig.model, envModel);
-  const nameMap = /* @__PURE__ */ new Map();
-  const toolMap = /* @__PURE__ */ new Map();
-  const orTools = compiledTools.map((t) => {
-    const s = sanitize(t.name);
-    nameMap.set(s, t.name);
-    toolMap.set(s, t);
-    return {
-      type: "function",
-      function: {
-        name: s,
-        description: t.description,
-        parameters: convertZodToJsonSchema(t.inputSchema)
+  return events;
+}
+__name(translateAssistantEvent, "translateAssistantEvent");
+function translateToolCallEvent(msg) {
+  const status = msg.status;
+  if (status === "completed") {
+    return [
+      {
+        type: "tool_result",
+        callId: asString(msg.id, `tc-${Date.now()}`),
+        toolName: asString(msg.name, "unknown"),
+        output: asString(msg.result, ""),
+        durationMs: 0,
+        isError: false
       }
-    };
-  });
-  return (message, sessionId) => ({
+    ];
+  }
+  if (status === "error") {
+    return [
+      {
+        type: "tool_result",
+        callId: asString(msg.id, `tc-${Date.now()}`),
+        toolName: asString(msg.name, "unknown"),
+        output: asString(msg.error, "Tool failed"),
+        durationMs: 0,
+        isError: true
+      }
+    ];
+  }
+  return [];
+}
+__name(translateToolCallEvent, "translateToolCallEvent");
+function translateStatusEvent(msg) {
+  const s = msg.status;
+  if (s === "done" || s === "completed") {
+    return [
+      {
+        type: "done",
+        result: "",
+        usage: {
+          inputTokens: 0,
+          outputTokens: 0,
+          totalTokens: 0
+        },
+        durationMs: 0,
+        cost: 0
+      }
+    ];
+  }
+  if (s === "error") {
+    return [
+      {
+        type: "error",
+        code: "AGENT_ERROR",
+        message: asString(msg.error, "Agent error"),
+        retryable: false
+      }
+    ];
+  }
+  return [];
+}
+__name(translateStatusEvent, "translateStatusEvent");
+function translateSdkEvent(msg, runId) {
+  switch (msg.type) {
+    case "system":
+      return translateSystemEvent(msg, runId);
+    case "assistant":
+      return translateAssistantEvent(msg);
+    case "tool_call":
+      return translateToolCallEvent(msg);
+    case "thinking":
+      return [
+        {
+          type: "thinking",
+          content: asString(msg.content, "")
+        }
+      ];
+    case "status":
+      return translateStatusEvent(msg);
+    default:
+      return [];
+  }
+}
+__name(translateSdkEvent, "translateSdkEvent");
+
+// src/bridge/sdk-adapter.ts
+function createSdkAgentStream(agentWalk, compiledTools, apiKey, envModel) {
+  const model = envModel ?? agentWalk.agentConfig.model ?? "openai/gpt-4o-mini";
+  return (message, _sessionId) => ({
     async *[Symbol.asyncIterator]() {
       const runId = `run-${Date.now()}`;
       const t0 = Date.now();
-      if (!sessions.has(sessionId)) {
-        sessions.set(sessionId, {
-          messages: [
-            {
-              role: "system",
-              content: agentWalk.agentConfig.systemPrompt ?? "You are a helpful assistant."
-            }
-          ],
-          createdAt: Date.now(),
-          totalCostUsd: 0
-        });
-      }
-      const session = sessions.get(sessionId);
-      session.messages.push({
-        role: "user",
-        content: message
-      });
-      yield {
-        type: "run_started",
-        runId,
-        agentName: agentWalk.agentConfig.name,
-        model
-      };
-      const maxIter = agentWalk.mainLoop.maxIterations ?? 5;
-      let inTok = 0, outTok = 0;
-      for (let iter = 1; iter <= maxIter; iter++) {
+      let Agent;
+      let defineTool;
+      try {
+        const sdk = await import("@theokit/sdk");
+        Agent = sdk.Agent;
+        defineTool = sdk.defineTool;
+      } catch {
         yield {
-          type: "iteration",
-          step: iter,
-          totalSteps: maxIter
+          type: "error",
+          code: "SDK_NOT_INSTALLED",
+          message: "Install @theokit/sdk: pnpm add @theokit/sdk",
+          retryable: false
         };
-        const res = await fetch(OPENROUTER_URL, {
-          method: "POST",
-          headers: {
-            "Authorization": `Bearer ${apiKey}`,
-            "Content-Type": "application/json"
+        return;
+      }
+      const sdkTools = compiledTools.map((t) => defineTool({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+        handler: t.handler
+      }));
+      try {
+        const agent = await Agent.create({
+          apiKey,
+          model: {
+            id: model
           },
-          body: JSON.stringify({
-            model,
-            messages: session.messages,
-            tools: orTools.length ? orTools : void 0,
-            max_tokens: 1e3,
-            stream: true
-          })
+          tools: sdkTools,
+          systemPrompt: agentWalk.agentConfig.systemPrompt
         });
-        if (!res.ok) {
-          yield {
-            type: "error",
-            code: "LLM_ERROR",
-            message: `OpenRouter ${res.status}: ${await res.text()}`,
-            retryable: res.status === 429
-          };
-          return;
-        }
-        const reader = res.body.getReader();
-        const dec = new TextDecoder();
-        let buf = "";
-        let content = "";
-        let tcs = [];
-        let finish = "";
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          buf += dec.decode(value, {
-            stream: true
-          });
-          const lines = buf.split("\n");
-          buf = lines.pop() ?? "";
-          for (const line of lines) {
-            if (!line.startsWith("data: ")) continue;
-            const d = line.slice(6).trim();
-            if (d === "[DONE]") continue;
-            try {
-              const c = JSON.parse(d);
-              const delta = c.choices?.[0]?.delta;
-              if (delta?.content) {
-                content += delta.content;
-                yield {
-                  type: "text_delta",
-                  content: delta.content
-                };
-              }
-              if (delta?.tool_calls) {
-                for (const tc of delta.tool_calls) {
-                  if (tc.id) tcs[tc.index] = {
-                    id: tc.id,
-                    type: "function",
-                    function: {
-                      name: tc.function?.name ?? "",
-                      arguments: ""
-                    }
-                  };
-                  if (tc.function?.arguments && tcs[tc.index]) tcs[tc.index].function.arguments += tc.function.arguments;
-                  if (tc.function?.name && tcs[tc.index]) tcs[tc.index].function.name = tc.function.name;
-                }
-              }
-              if (c.choices[0]?.finish_reason) finish = c.choices[0].finish_reason;
-              if (c.usage) {
-                inTok += c.usage.prompt_tokens;
-                outTok += c.usage.completion_tokens;
-                if (c.usage.cost) session.totalCostUsd += c.usage.cost;
-              }
-            } catch {
-            }
-          }
-        }
-        if (finish === "tool_calls" && tcs.length > 0) {
-          session.messages.push({
-            role: "assistant",
-            content: null,
-            tool_calls: tcs
-          });
-          for (const tc of tcs) {
-            const orig = nameMap.get(tc.function.name) ?? tc.function.name;
-            const tool = toolMap.get(tc.function.name);
-            yield {
-              type: "tool_call",
-              callId: tc.id,
-              toolName: orig,
-              input: JSON.parse(tc.function.arguments || "{}")
-            };
-            if (!tool) {
-              session.messages.push({
-                role: "tool",
-                content: "Tool not found",
-                tool_call_id: tc.id
-              });
-              yield {
-                type: "tool_result",
-                callId: tc.id,
-                toolName: orig,
-                output: "Not found",
-                durationMs: 0,
-                isError: true
-              };
-              continue;
-            }
-            const s = Date.now();
-            try {
-              const r = await tool.handler(JSON.parse(tc.function.arguments || "{}"));
-              session.messages.push({
-                role: "tool",
-                content: r,
-                tool_call_id: tc.id
-              });
-              yield {
-                type: "tool_result",
-                callId: tc.id,
-                toolName: orig,
-                output: r.substring(0, 200),
-                durationMs: Date.now() - s,
-                isError: false
-              };
-            } catch (e) {
-              const m = e instanceof Error ? e.message : "Failed";
-              session.messages.push({
-                role: "tool",
-                content: `Error: ${m}`,
-                tool_call_id: tc.id
-              });
-              yield {
-                type: "tool_result",
-                callId: tc.id,
-                toolName: orig,
-                output: m,
-                durationMs: Date.now() - s,
-                isError: true
-              };
-            }
+        const run = await agent.send(message);
+        for await (const sdkEvent of run.stream()) {
+          const translated = translateSdkEvent(sdkEvent, runId);
+          for (const event of translated) {
+            yield event;
           }
-          tcs = [];
-          content = "";
-          continue;
         }
-        if (content) session.messages.push({
-          role: "assistant",
-          content
-        });
         yield {
           type: "done",
-          result: content,
+          result: "",
           usage: {
-            inputTokens: inTok,
-            outputTokens: outTok,
-            totalTokens: inTok + outTok
+            inputTokens: 0,
+            outputTokens: 0,
+            totalTokens: 0
           },
           durationMs: Date.now() - t0,
-          cost: session.totalCostUsd
+          cost: 0
+        };
+        await agent.dispose();
+      } catch (err) {
+        yield {
+          type: "error",
+          code: "SDK_ERROR",
+          message: err instanceof Error ? err.message : "SDK agent error",
+          retryable: false
         };
-        return;
       }
-      yield {
-        type: "error",
-        code: "MAX_ITERATIONS",
-        message: `Max iterations (${maxIter})`,
-        retryable: false
-      };
     }
   });
 }
-__name(createRealAgentStream, "createRealAgentStream");
-function convertZodToJsonSchema(schema) {
-  if (!schema || typeof schema !== "object") return {
-    type: "object",
-    properties: {}
+__name(createSdkAgentStream, "createSdkAgentStream");
+
+// src/bridge/agent-orchestrator.ts
+var BudgetExceededError = class extends Error {
+  static {
+    __name(this, "BudgetExceededError");
+  }
+  agentName;
+  actualCost;
+  budgetLimit;
+  constructor(agentName, actualCost, budgetLimit) {
+    super(`Agent "${agentName}" exceeded budget: $${actualCost.toFixed(4)} > $${budgetLimit.toFixed(4)}`), this.agentName = agentName, this.actualCost = actualCost, this.budgetLimit = budgetLimit;
+    this.name = "BudgetExceededError";
+  }
+};
+var DelegationError = class extends Error {
+  static {
+    __name(this, "DelegationError");
+  }
+  agentName;
+  cause;
+  constructor(agentName, cause) {
+    super(`Delegation to agent "${agentName}" failed: ${cause instanceof Error ? cause.message : String(cause)}`), this.agentName = agentName, this.cause = cause;
+    this.name = "DelegationError";
+  }
+};
+function asString2(value, fallback) {
+  if (typeof value === "string") return value;
+  return fallback;
+}
+__name(asString2, "asString");
+function asNumber(value, fallback) {
+  if (typeof value === "number") return value;
+  return fallback;
+}
+__name(asNumber, "asNumber");
+function requireApiKey(opts, agentName) {
+  const apiKey = opts.apiKey ?? "";
+  if (!apiKey) {
+    throw new DelegationError(agentName, "No API key provided. Pass apiKey in DelegateOptions.");
+  }
+  return apiKey;
+}
+__name(requireApiKey, "requireApiKey");
+function mergeTools(parentTools, subTools) {
+  const subToolNames = new Set(subTools.map((t) => t.name));
+  const inherited = parentTools.filter((t) => !subToolNames.has(t.name));
+  return [
+    ...inherited,
+    ...subTools
+  ];
+}
+__name(mergeTools, "mergeTools");
+function processStreamEvent(event, acc, budget, agentName) {
+  if (event.type === "text_delta" && typeof event.content === "string") {
+    acc.response += event.content;
+    return;
+  }
+  if (event.type === "tool_result") {
+    acc.toolCalls.push({
+      name: asString2(event.toolName, "unknown"),
+      input: event.input ?? {},
+      output: asString2(event.output, "")
+    });
+    return;
+  }
+  if (event.type === "done") {
+    acc.cost = asNumber(event.cost, 0);
+    const usage = event.usage;
+    acc.tokens = usage?.totalTokens ?? 0;
+    if (Number.isFinite(budget) && acc.cost > budget) {
+      throw new BudgetExceededError(agentName, acc.cost, budget);
+    }
+    return;
+  }
+  if (event.type === "error") {
+    throw new DelegationError(agentName, asString2(event.message, "Unknown agent error"));
+  }
+}
+__name(processStreamEvent, "processStreamEvent");
+async function delegate(SubAgentClass, message, opts = {}) {
+  const apiKey = requireApiKey(opts, SubAgentClass.name);
+  const walk = walkAgentMetadata(SubAgentClass, []);
+  const toolboxInstances = new Map(walk.toolboxes.map((tb) => [
+    tb.class,
+    new tb.class()
+  ]));
+  const compiled = compileAgent(walk, toolboxInstances);
+  const allTools = mergeTools(opts.parentTools ?? [], compiled.tools);
+  const budget = Math.min(opts.budget ?? Infinity, opts.parentBudgetRemaining ?? Infinity);
+  const streamFactory = createSdkAgentStream(walk, allTools, apiKey, walk.agentConfig.model);
+  const sessionId = opts.sessionId ?? `sub-${crypto.randomUUID()}`;
+  const acc = {
+    response: "",
+    toolCalls: [],
+    cost: 0,
+    tokens: 0
   };
-  const { $schema: _, ...rest } = z.toJSONSchema(schema);
-  return rest;
+  try {
+    for await (const event of streamFactory(message, sessionId)) {
+      processStreamEvent(event, acc, budget, SubAgentClass.name);
+    }
+  } catch (err) {
+    if (err instanceof BudgetExceededError || err instanceof DelegationError) throw err;
+    throw new DelegationError(SubAgentClass.name, err);
+  }
+  if (Number.isFinite(budget) && acc.cost > budget) {
+    throw new BudgetExceededError(SubAgentClass.name, acc.cost, budget);
+  }
+  return acc;
 }
-__name(convertZodToJsonSchema, "convertZodToJsonSchema");
+__name(delegate, "delegate");
 
 // src/manifest/agent-manifest.ts
 function generateAgentManifest(walkResults) {
@@ -636,7 +710,7 @@ function agentsPlugin(opts) {
     name: "@theokit/agents",
     register(app) {
       app.addHook("onRequest", async (pluginCtx) => {
-        if (!routes) routes = initRoutes(opts);
+        routes ??= initRoutes(opts);
         const request = pluginCtx.request;
         const url = new URL(request.url);
         const method = request.method.toUpperCase();
@@ -669,11 +743,12 @@ function initRoutes(opts) {
     allRoutes.push(...agentRoutes);
   }
   validateUniqueRoutes(walkResults);
-  return allRoutes;
+  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()}`,
@@ -688,13 +763,21 @@ function defaultCreateRun(compiled) {
   };
 }
 __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.path.includes(":")) {
-      const pattern = r.path.replace(/:[^/]+/g, "[^/]+");
-      return new RegExp(`^${pattern}$`).test(pathname);
-    }
+    if (r.regex) return r.regex.test(pathname);
     return r.path === pathname;
   });
 }
@@ -703,6 +786,7 @@ __name(matchRoute, "matchRoute");
 export {
   createAgentExecutionContext,
   isAgentContext,
+  AgentWarningCode,
   walkAgentMetadata,
   validateUniqueRoutes,
   compileTools,
@@ -715,8 +799,12 @@ export {
   isError,
   isApprovalRequired,
   generateAgentRoutes,
-  createRealAgentStream,
+  translateSdkEvent,
+  createSdkAgentStream,
+  BudgetExceededError,
+  DelegationError,
+  delegate,
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-YSQAZWGW.js.map
+//# sourceMappingURL=chunk-NC5EE7HN.js.map