@theokit/agents 0.5.0 → 0.6.0

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
 import { ExecutionContext } from '@theokit/http';
-import { A as AgentOptions, T as ToolOptions, e as MainLoopMeta, a as ApprovalOptions, B as BudgetOptions, d as GatewayOptions, j as MemoryOptions, q as SkillsOptions, c as ContextWindowOptions, o as ProjectContextOptions, h as McpServersMap } from './skills-DnfvEUSg.js';
+import { A as AgentOptions, T as ToolOptions, M as MainLoopMeta, a as ApprovalOptions, B as BudgetOptions, d as GatewayOptions, j as MemoryOptions, q as SkillsOptions, c as ContextWindowOptions, o as ProjectContextOptions, h as McpServersMap } from './skills-DmN1HGUb.js';
 import { SkillsSettings, ContextSettings, SystemPromptResolver } from '@theokit/sdk';
 import 'zod';
 
@@ -407,25 +407,14 @@ interface SdkMessage {
 declare function translateSdkEvent(msg: SdkMessage, runId: string): StreamEvent[];
 
 /**
- * Multi-agent orchestration runtime.
+ * Shared delegation value types + typed errors.
  *
- * Provides `delegate()` — a function that lets a parent agent invoke a
- * sub-agent and receive its result. Handles budget clamping (D4),
- * tool sharing, and toolbox auto-instantiation (EC-1).
+ * Extracted from `agent-orchestrator.ts` so BOTH the orchestrator (`delegate`)
+ * and the loop driver (`loop/run-reflective-loop.ts`) can import them WITHOUT a
+ * cycle (orchestrator → loop → delegation-types; orchestrator → delegation-types;
+ * delegation-types depends on nothing — Acyclic Dependencies Principle, G1).
+ * `agent-orchestrator.ts` re-exports these for backward compatibility.
  */
-
-interface DelegateOptions {
-    /** Max USD for this sub-agent call. */
-    budget?: number;
-    /** Parent's remaining budget (for clamping). */
-    parentBudgetRemaining?: number;
-    /** Parent's tools (for sharing — sub-agent inherits these). */
-    parentTools?: CompiledTool[];
-    /** LLM API key (inherited from parent). */
-    apiKey?: string;
-    /** Session ID override (default: crypto.randomUUID for isolation). */
-    sessionId?: string;
-}
 interface DelegationResult {
     response: string;
     toolCalls: {
@@ -435,6 +424,8 @@ interface DelegationResult {
     }[];
     cost: number;
     tokens: number;
+    /** Rounds the reflective loop ran (set by `runReflectiveLoop`; absent for the single-shot path). */
+    rounds?: number;
 }
 declare class BudgetExceededError extends Error {
     readonly agentName: string;
@@ -447,6 +438,21 @@ declare class DelegationError extends Error {
     readonly cause: unknown;
     constructor(agentName: string, cause: unknown);
 }
+
+interface DelegateOptions {
+    /** Max USD for this sub-agent call. */
+    budget?: number;
+    /** Parent's remaining budget (for clamping). */
+    parentBudgetRemaining?: number;
+    /** Parent's tools (for sharing — sub-agent inherits these). */
+    parentTools?: CompiledTool[];
+    /** LLM API key (inherited from parent). */
+    apiKey?: string;
+    /** Session ID override (default: crypto.randomUUID for isolation). */
+    sessionId?: string;
+    /** Cancellation — aborts stop the reflective loop from re-entering. */
+    signal?: AbortSignal;
+}
 /**
  * Delegate a task to a sub-agent and collect its result.
  *
@@ -454,6 +460,10 @@ declare class DelegationError extends Error {
  * - Tool sharing: parent tools merged with sub-agent tools (sub wins on collision)
  * - Toolbox auto-instantiation: sub-agent toolboxes instantiated without DI (EC-1)
  * - Session isolation: each delegation gets a unique session ID (EC-4)
+ * - `@MainLoop` strategy runtime: routes through `runReflectiveLoop` (the same loop
+ *   `AgentRunner.run` uses — one runtime for both on-ramps, ADR D4). The runtime
+ *   metric (`THEO_AGENT_MAINLOOP_RUNTIME_APPLIED`) + typed-error + cumulative budget
+ *   all live in the shared driver, so they fire identically on both paths.
  */
 declare function delegate(SubAgentClass: Function, message: string, opts?: DelegateOptions): Promise<DelegationResult>;
 

package/dist/bridge.js

@@ -25,7 +25,7 @@ import {
   translateSdkEvent,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-2MI27XCA.js";
+} from "./chunk-KTYBQ7HY.js";
 import "./chunk-MVEY7HEY.js";
 import "./chunk-7QVYU63E.js";
 export {

package/dist/{chunk-2MI27XCA.js → chunk-KTYBQ7HY.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,185 @@ 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");
+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;
+  while (!signal?.aborted) {
+    const prompt = round === 1 || !feedback ? message : `${message}
+
+[reflection] ${feedback}`;
+    let r;
+    try {
+      r = await consumeOneRound(factory, prompt, sessionId, signal);
+    } catch (err) {
+      if (err instanceof BudgetExceededError || err instanceof DelegationError) throw err;
+      throw new DelegationError(agentName, err);
+    }
+    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);
+    }
+    const outcome = {
+      finishReason: r.finishReason,
+      round,
+      toolCalls: r.toolCalls,
+      responseText: r.responseText
+    };
+    const reflectionResult = reflection.reflect(outcome);
+    if (!(reflectionResult.continue && loop.shouldContinue(outcome))) {
+      acc.rounds = round;
+      console.debug("[THEO_AGENT_MAINLOOP_RUNTIME_APPLIED]", {
+        strategy: loop.name,
+        rounds: round
+      });
+      return acc;
+    }
+    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 +973,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 +985,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 +1143,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-KTYBQ7HY.js.map