@theokit/agents 0.5.0 → 0.7.0

package/dist/{chunk-2MI27XCA.js → chunk-2MYIZ4OT.js}

@@ -477,7 +477,8 @@ function translateSystemEvent(msg, runId) {
 __name(translateSystemEvent, "translateSystemEvent");
 function translateAssistantEvent(msg) {
   const events = [];
-  const content = msg.content;
+  const message = msg.message;
+  const content = message?.content;
   if (!Array.isArray(content)) return events;
   for (const block of content) {
     const b = block;
@@ -501,12 +502,14 @@ function translateAssistantEvent(msg) {
 __name(translateAssistantEvent, "translateAssistantEvent");
 function translateToolCallEvent(msg) {
   const status = msg.status;
+  const callId = asString(msg.call_id, `tc-${Date.now()}`);
+  const toolName = asString(msg.name, "unknown");
   if (status === "completed") {
     return [
       {
         type: "tool_result",
-        callId: asString(msg.id, `tc-${Date.now()}`),
-        toolName: asString(msg.name, "unknown"),
+        callId,
+        toolName,
         output: asString(msg.result, ""),
         durationMs: 0,
         isError: false
@@ -517,9 +520,9 @@ function translateToolCallEvent(msg) {
     return [
       {
         type: "tool_result",
-        callId: asString(msg.id, `tc-${Date.now()}`),
-        toolName: asString(msg.name, "unknown"),
-        output: asString(msg.error, "Tool failed"),
+        callId,
+        toolName,
+        output: asString(msg.result, "Tool failed"),
         durationMs: 0,
         isError: true
       }
@@ -530,7 +533,7 @@ function translateToolCallEvent(msg) {
 __name(translateToolCallEvent, "translateToolCallEvent");
 function translateStatusEvent(msg) {
   const s = msg.status;
-  if (s === "done" || s === "completed") {
+  if (s === "FINISHED" || s === "CANCELLED") {
     return [
       {
         type: "done",
@@ -545,12 +548,12 @@ function translateStatusEvent(msg) {
       }
     ];
   }
-  if (s === "error") {
+  if (s === "ERROR" || s === "EXPIRED") {
     return [
       {
         type: "error",
         code: "AGENT_ERROR",
-        message: asString(msg.error, "Agent error"),
+        message: asString(msg.message, "Agent error"),
         retryable: false
       }
     ];
@@ -570,7 +573,7 @@ function translateSdkEvent(msg, runId) {
       return [
         {
           type: "thinking",
-          content: asString(msg.content, "")
+          content: asString(msg.text, "")
         }
       ];
     case "status":
@@ -656,23 +659,27 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, envModel) {
           ...m8
         });
         const run = await agent.send(message);
+        let sawTerminal = false;
         for await (const sdkEvent of run.stream()) {
           const translated = translateSdkEvent(sdkEvent, runId);
           for (const event of translated) {
+            if (event.type === "done" || event.type === "error") sawTerminal = true;
             yield event;
           }
         }
-        yield {
-          type: "done",
-          result: "",
-          usage: {
-            inputTokens: 0,
-            outputTokens: 0,
-            totalTokens: 0
-          },
-          durationMs: Date.now() - t0,
-          cost: 0
-        };
+        if (!sawTerminal) {
+          yield {
+            type: "done",
+            result: "",
+            usage: {
+              inputTokens: 0,
+              outputTokens: 0,
+              totalTokens: 0
+            },
+            durationMs: Date.now() - t0,
+            cost: 0
+          };
+        }
         await agent.dispose();
       } catch (err) {
         yield {
@@ -687,7 +694,66 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, envModel) {
 }
 __name(createSdkAgentStream, "createSdkAgentStream");
 
-// src/bridge/agent-orchestrator.ts
+// src/loop/loop-strategy.ts
+import { z } from "zod";
+var DEFAULT_MAX_ITERATIONS = 8;
+var loopStrategyConfigSchema = z.object({
+  name: z.enum([
+    "simple-chat",
+    "plan-act-reflect",
+    "react"
+  ]),
+  maxIterations: z.number().int().min(1)
+});
+function resolveLoopStrategy(strategy, maxIterations = DEFAULT_MAX_ITERATIONS) {
+  const cfg = loopStrategyConfigSchema.parse({
+    name: strategy,
+    maxIterations
+  });
+  if (cfg.name === "simple-chat") {
+    return {
+      name: cfg.name,
+      maxIterations: cfg.maxIterations,
+      shouldContinue: /* @__PURE__ */ __name(() => false, "shouldContinue")
+    };
+  }
+  return {
+    name: cfg.name,
+    maxIterations: cfg.maxIterations,
+    shouldContinue: /* @__PURE__ */ __name((outcome) => outcome.finishReason === "tool-calls" && outcome.round < cfg.maxIterations, "shouldContinue")
+  };
+}
+__name(resolveLoopStrategy, "resolveLoopStrategy");
+
+// src/loop/reflection-strategy.ts
+import { z as z2 } from "zod";
+var reflectionStrategyConfigSchema = z2.object({
+  name: z2.string().min(1)
+});
+var ladderReflectionStrategy = {
+  name: "ladder",
+  reflect(outcome) {
+    if (outcome.finishReason === "tool-calls") {
+      return {
+        feedback: `Tool results received (round ${outcome.round}). Reflect on whether the goal is met; if not, refine the approach and continue.`,
+        continue: true
+      };
+    }
+    return {
+      continue: false
+    };
+  }
+};
+var noopReflectionStrategy = {
+  name: "noop",
+  reflect() {
+    return {
+      continue: true
+    };
+  }
+};
+
+// src/bridge/delegation-types.ts
 var BudgetExceededError = class extends Error {
   static {
     __name(this, "BudgetExceededError");
@@ -711,16 +777,235 @@ var DelegationError = class extends Error {
     this.name = "DelegationError";
   }
 };
+
+// src/loop/run-reflective-loop.ts
 function asString2(value, fallback) {
-  if (typeof value === "string") return value;
-  return fallback;
+  return typeof value === "string" ? value : fallback;
 }
 __name(asString2, "asString");
 function asNumber(value, fallback) {
-  if (typeof value === "number") return value;
-  return fallback;
+  return typeof value === "number" ? value : fallback;
 }
 __name(asNumber, "asNumber");
+var NO_PROGRESS_THRESHOLD = 2;
+var MAINLOOP_METRIC = "[THEO_AGENT_MAINLOOP_RUNTIME_APPLIED]";
+var TOOL_CALLS = "tool-calls";
+var STEP_LIMIT_HINT = "This is your final round \u2014 do not call any more tools; summarize the work done so far and list any remaining tasks.";
+function stableStringify(value) {
+  if (value === void 0) return "undefined";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const obj = value;
+  const entries = Object.keys(obj).sort((a, b) => a.localeCompare(b)).map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+  return `{${entries.join(",")}}`;
+}
+__name(stableStringify, "stableStringify");
+function roundSignature(toolCalls, text) {
+  const calls = toolCalls.map((tc) => `${tc.name}:${stableStringify(tc.input)}`).sort((a, b) => a.localeCompare(b)).join(",");
+  return `${calls}|${text}`;
+}
+__name(roundSignature, "roundSignature");
+function terminalReason(reflectionContinue, roundReason, round, maxIterations) {
+  if (reflectionContinue && roundReason === TOOL_CALLS && round >= maxIterations) return "step_limit";
+  if (roundReason === TOOL_CALLS) return "stop";
+  return roundReason;
+}
+__name(terminalReason, "terminalReason");
+function buildPrompt(round, maxIterations, message, feedback) {
+  const hint = round === maxIterations ? `${STEP_LIMIT_HINT}
+
+` : "";
+  const body = round === 1 || !feedback ? message : `${message}
+
+[reflection] ${feedback}`;
+  return hint + body;
+}
+__name(buildPrompt, "buildPrompt");
+async function consumeRoundOrThrow(factory, prompt, sessionId, signal, agentName) {
+  try {
+    return await consumeOneRound(factory, prompt, sessionId, signal);
+  } catch (err) {
+    if (err instanceof BudgetExceededError || err instanceof DelegationError) throw err;
+    throw new DelegationError(agentName, err);
+  }
+}
+__name(consumeRoundOrThrow, "consumeRoundOrThrow");
+function finalize(acc, round, reason, strategyName) {
+  acc.rounds = round;
+  acc.finishReason = reason;
+  console.debug(MAINLOOP_METRIC, {
+    strategy: strategyName,
+    rounds: round,
+    terminal: reason
+  });
+  return acc;
+}
+__name(finalize, "finalize");
+function deriveFinishReason(signals) {
+  if (signals.sawError) return "error";
+  if (signals.sawDone && signals.doneFinishReason === TOOL_CALLS) return TOOL_CALLS;
+  if (signals.sawToolResult) return TOOL_CALLS;
+  return "stop";
+}
+__name(deriveFinishReason, "deriveFinishReason");
+async function consumeOneRound(factory, prompt, sessionId, signal) {
+  const r = {
+    responseText: "",
+    toolCalls: [],
+    cost: 0,
+    tokens: 0,
+    finishReason: "stop",
+    errorMessage: ""
+  };
+  const signals = {
+    sawError: false,
+    sawDone: false,
+    doneFinishReason: "",
+    sawToolResult: false
+  };
+  for await (const event of factory(prompt, sessionId)) {
+    if (signal?.aborted) break;
+    if (event.type === "text_delta" && typeof event.content === "string") {
+      r.responseText += event.content;
+    } else if (event.type === "tool_result") {
+      signals.sawToolResult = true;
+      r.toolCalls.push({
+        name: asString2(event.toolName, "unknown"),
+        input: event.input ?? {},
+        output: asString2(event.output, "")
+      });
+    } else if (event.type === "done") {
+      signals.sawDone = true;
+      signals.doneFinishReason = asString2(event.finishReason, "");
+      r.cost = asNumber(event.cost, 0);
+      r.tokens = event.usage?.totalTokens ?? 0;
+    } else if (event.type === "error") {
+      signals.sawError = true;
+      r.errorMessage = asString2(event.message, "Unknown agent error");
+    }
+  }
+  r.finishReason = deriveFinishReason(signals);
+  return r;
+}
+__name(consumeOneRound, "consumeOneRound");
+async function runReflectiveLoop(factory, message, sessionId, config) {
+  const { loop, reflection, budget = Number.POSITIVE_INFINITY, signal, agentName = loop.name } = config;
+  const acc = {
+    response: "",
+    toolCalls: [],
+    cost: 0,
+    tokens: 0,
+    rounds: 0
+  };
+  let round = 1;
+  let feedback;
+  let prevSig;
+  let stuck = 0;
+  while (!signal?.aborted) {
+    const prompt = buildPrompt(round, loop.maxIterations, message, feedback);
+    const r = await consumeRoundOrThrow(factory, prompt, sessionId, signal, agentName);
+    acc.response += r.responseText;
+    acc.toolCalls.push(...r.toolCalls);
+    acc.cost += r.cost;
+    acc.tokens += r.tokens;
+    if (r.finishReason === "error") throw new DelegationError(agentName, r.errorMessage);
+    if (Number.isFinite(budget) && acc.cost > budget) {
+      throw new BudgetExceededError(agentName, acc.cost, budget);
+    }
+    if (r.finishReason === TOOL_CALLS) {
+      const sig = roundSignature(r.toolCalls, r.responseText);
+      stuck = sig === prevSig ? stuck + 1 : 0;
+      if (stuck >= NO_PROGRESS_THRESHOLD) return finalize(acc, round, "no_progress", loop.name);
+      prevSig = sig;
+    }
+    const outcome = {
+      finishReason: r.finishReason,
+      round,
+      toolCalls: r.toolCalls,
+      responseText: r.responseText
+    };
+    const reflectionResult = reflection.reflect(outcome);
+    if (!(reflectionResult.continue && loop.shouldContinue(outcome))) {
+      const reason = terminalReason(reflectionResult.continue, r.finishReason, round, loop.maxIterations);
+      return finalize(acc, round, reason, loop.name);
+    }
+    feedback = reflectionResult.feedback;
+    round += 1;
+  }
+  acc.rounds = round - 1;
+  return acc;
+}
+__name(runReflectiveLoop, "runReflectiveLoop");
+
+// src/loop/agent-runner.ts
+var AgentRunner = class {
+  static {
+    __name(this, "AgentRunner");
+  }
+  compiled;
+  agentName;
+  loopStrategy;
+  reflectionStrategy;
+  streamEnabled;
+  constructor(compiled, agentName, loopStrategy, reflectionStrategy, streamEnabled) {
+    this.compiled = compiled;
+    this.agentName = agentName;
+    this.loopStrategy = loopStrategy;
+    this.reflectionStrategy = reflectionStrategy;
+    this.streamEnabled = streamEnabled;
+  }
+  /** Start a fluent builder for `AgentClass`. */
+  static builder(AgentClass) {
+    return new AgentRunnerBuilder(AgentClass);
+  }
+  /** Run the agent to a terminal result via the shared reflective loop. */
+  run(message, opts) {
+    const streamFactory = createSdkAgentStream(this.compiled, this.compiled.tools, opts.apiKey, this.compiled.model);
+    const sessionId = opts.sessionId ?? `runner-${crypto.randomUUID()}`;
+    return runReflectiveLoop(streamFactory, message, sessionId, {
+      loop: this.loopStrategy,
+      reflection: this.reflectionStrategy,
+      budget: opts.budget,
+      agentName: this.agentName,
+      signal: opts.signal
+    });
+  }
+};
+var AgentRunnerBuilder = class {
+  static {
+    __name(this, "AgentRunnerBuilder");
+  }
+  AgentClass;
+  reflectionOverride;
+  streamEnabled = true;
+  constructor(AgentClass) {
+    this.AgentClass = AgentClass;
+  }
+  /** Override the default reflection strategy (OCP — plan Drawback #2). No arg ⇒ keep default. */
+  reflection(strategy) {
+    if (strategy) this.reflectionOverride = strategy;
+    return this;
+  }
+  /** Record the streaming preference (see {@link AgentRunner.streamEnabled}). */
+  stream(enabled = true) {
+    this.streamEnabled = enabled;
+    return this;
+  }
+  /** Walk + compile + resolve strategies — the compile→execute boundary (no I/O). */
+  build() {
+    const walk = walkAgentMetadata(this.AgentClass, []);
+    const toolboxInstances = new Map(walk.toolboxes.map((tb) => [
+      tb.class,
+      new tb.class()
+    ]));
+    const compiled = compileAgent(walk, toolboxInstances);
+    const loopStrategy = resolveLoopStrategy(walk.mainLoop.strategy, walk.mainLoop.maxIterations);
+    const reflectionStrategy = this.reflectionOverride ?? (walk.mainLoop.strategy === "plan-act-reflect" ? ladderReflectionStrategy : noopReflectionStrategy);
+    return new AgentRunner(compiled, walk.agentConfig.name, loopStrategy, reflectionStrategy, this.streamEnabled);
+  }
+};
+
+// src/bridge/agent-orchestrator.ts
 function requireApiKey(opts, agentName) {
   const apiKey = opts.apiKey ?? "";
   if (!apiKey) {
@@ -738,33 +1023,6 @@ function mergeTools(parentTools, 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, []);
@@ -777,24 +1035,15 @@ async function delegate(SubAgentClass, message, opts = {}) {
   const budget = Math.min(opts.budget ?? Infinity, opts.parentBudgetRemaining ?? Infinity);
   const streamFactory = createSdkAgentStream(compiled, allTools, apiKey, walk.agentConfig.model);
   const sessionId = opts.sessionId ?? `sub-${crypto.randomUUID()}`;
-  const acc = {
-    response: "",
-    toolCalls: [],
-    cost: 0,
-    tokens: 0
-  };
-  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;
+  const loopStrategy = resolveLoopStrategy(walk.mainLoop.strategy, walk.mainLoop.maxIterations);
+  const reflection = loopStrategy.name === "plan-act-reflect" ? ladderReflectionStrategy : noopReflectionStrategy;
+  return runReflectiveLoop(streamFactory, message, sessionId, {
+    loop: loopStrategy,
+    reflection,
+    budget,
+    agentName: SubAgentClass.name,
+    signal: opts.signal
+  });
 }
 __name(delegate, "delegate");
 
@@ -944,10 +1193,18 @@ export {
   generateAgentRoutes,
   translateSdkEvent,
   createSdkAgentStream,
+  DEFAULT_MAX_ITERATIONS,
+  loopStrategyConfigSchema,
+  resolveLoopStrategy,
+  reflectionStrategyConfigSchema,
+  ladderReflectionStrategy,
+  noopReflectionStrategy,
   BudgetExceededError,
   DelegationError,
+  AgentRunner,
+  AgentRunnerBuilder,
   delegate,
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-2MI27XCA.js.map
+//# sourceMappingURL=chunk-2MYIZ4OT.js.map