@tangle-network/agent-runtime 0.43.0 → 0.45.0

package/dist/index.js

@@ -1,3 +1,14 @@
+import {
+  mcpToolsForRuntimeMcp,
+  mcpToolsForRuntimeMcpSubset
+} from "./chunk-KSMX62JF.js";
+import {
+  INTELLIGENCE_WIRE_VERSION,
+  buildLoopOtelSpans,
+  createOtelExporter,
+  exportEvalRuns,
+  loopEventToOtelSpan
+} from "./chunk-IJGS6J7X.js";
 import {
   DELEGATED_LOOP_MODES,
   auditLoopRunner,
@@ -10,25 +21,17 @@ import {
   runDelegatedLoop,
   runLoopRunnerCli,
   selfImproveLoopRunner
-} from "./chunk-C5HMTTNY.js";
-import "./chunk-XBUG326M.js";
-import "./chunk-VOX6Z3II.js";
-import {
-  mcpToolsForRuntimeMcp,
-  mcpToolsForRuntimeMcpSubset
-} from "./chunk-NRZOXCJK.js";
-import {
-  INTELLIGENCE_WIRE_VERSION,
-  buildLoopOtelSpans,
-  createOtelExporter,
-  exportEvalRuns,
-  loopEventToOtelSpan
-} from "./chunk-HVYOHJHK.js";
+} from "./chunk-NYN5RTLP.js";
 import "./chunk-FNMGYYSS.js";
-import "./chunk-MJDGCRAT.js";
-import "./chunk-EKBSQYZE.js";
-import "./chunk-3HMHSN22.js";
-import "./chunk-PY6NMZYX.js";
+import "./chunk-IJ6FGOPO.js";
+import "./chunk-QR4UUC5P.js";
+import "./chunk-FK53TXOP.js";
+import {
+  composeRuntimeHooks,
+  defineRuntimeHooks,
+  notifyRuntimeDecisionPoint,
+  notifyRuntimeHookEvent
+} from "./chunk-KEWO4KI6.js";
 import {
   AgentEvalError,
   BackendTransportError,
@@ -39,7 +42,7 @@ import {
   RuntimeRunStateError,
   SessionMismatchError,
   ValidationError
-} from "./chunk-SQSCRJ7U.js";
+} from "./chunk-PRX45WE2.js";
 import "./chunk-DGUM43GV.js";
 
 // src/sessions.ts
@@ -2729,6 +2732,385 @@ function runtimeStreamServerSentEvent(event, options = {}) {
 function stripNewlines(value) {
   return value.replace(/[\r\n]/g, " ");
 }
+
+// src/tool-loop.ts
+var DEFAULT_MAX_TOOL_TURNS = 8;
+var DEFAULT_DECISION_CONTEXT_CHARS = 12e3;
+var FAILURE_RECOVERY_ACTIONS = ["retry", "verify", "continue", "stop"];
+function defaultRender(label, outcome) {
+  if (outcome.ok) return `- ${label} \u2192 ok: ${JSON.stringify(outcome.result)}`;
+  return `- ${label} \u2192 failed (${outcome.code}): ${outcome.message}`;
+}
+async function runToolLoop(opts) {
+  const maxTurns = opts.maxToolTurns ?? DEFAULT_MAX_TOOL_TURNS;
+  const render = opts.renderResult ?? defaultRender;
+  const labelFor = opts.labelFor ?? ((c) => c.toolName);
+  const runId = opts.runId ?? `agent-run-${randomSuffix2()}`;
+  const messages = [
+    { role: "system", content: opts.systemPrompt },
+    ...opts.priorMessages ?? [],
+    { role: "user", content: opts.userMessage }
+  ];
+  const observer = createToolLoopObserver(opts.hooks, runId, opts.scenarioId);
+  const toolResults = [];
+  let finalText = "";
+  let turns = 0;
+  observer.loopBefore(maxTurns, messages.length);
+  for (let toolTurn = 0; ; toolTurn++) {
+    turns++;
+    let turnText = "";
+    const pending = [];
+    const turnEventId = observer.turnBefore(toolTurn, messages.length);
+    for await (const ev of opts.streamTurn([...messages])) {
+      if (ev.type === "text") {
+        turnText += ev.text;
+        finalText += ev.text;
+      } else if (ev.type === "tool_call" && opts.isExecutableTool(ev.call.toolName)) {
+        pending.push(ev.call);
+      }
+    }
+    if (pending.length === 0) {
+      observer.turnAfter(toolTurn, turnEventId, {
+        pendingToolCalls: 0,
+        finalTextChars: finalText.length
+      });
+      break;
+    }
+    if (toolTurn >= maxTurns) {
+      observer.turnAfter(toolTurn, turnEventId, {
+        pendingToolCalls: pending.length,
+        cappedOut: true
+      });
+      observer.loopAfter({ turns, toolResults: toolResults.length, cappedOut: true });
+      return { finalText, toolResults, turns, cappedOut: true };
+    }
+    if (turnText.trim()) messages.push({ role: "assistant", content: turnText });
+    const lines = [];
+    const outcomes = [];
+    for (const [callIndex, call] of pending.entries()) {
+      const callEventId = observer.toolCallBefore(toolTurn, turnEventId, callIndex, call);
+      let outcome;
+      try {
+        outcome = await opts.executeToolCall(call);
+      } catch (err) {
+        outcome = {
+          ok: false,
+          code: "executor_error",
+          message: err instanceof Error ? err.message : String(err)
+        };
+      }
+      const label = labelFor(call);
+      const rendered = render(label, outcome);
+      toolResults.push({ call, label, outcome });
+      lines.push(rendered);
+      outcomes.push({ call, label, outcome, rendered });
+      observer.toolCallAfter(toolTurn, callEventId, call, outcome);
+    }
+    observer.failureRecovery({
+      toolTurn,
+      messages,
+      turnText,
+      outcomes
+    });
+    observer.turnAfter(toolTurn, turnEventId, {
+      pendingToolCalls: pending.length,
+      toolResults: outcomes.map((item) => ({
+        toolName: item.call.toolName,
+        toolCallId: item.call.toolCallId,
+        ok: item.outcome.ok
+      })),
+      failedToolCalls: outcomes.filter((item) => !item.outcome.ok).length
+    });
+    messages.push({ role: "user", content: `Tool results:
+${lines.join("\n")}` });
+  }
+  observer.loopAfter({ turns, toolResults: toolResults.length, cappedOut: false });
+  return { finalText, toolResults, turns, cappedOut: false };
+}
+async function* streamToolLoop(opts) {
+  const maxTurns = opts.maxToolTurns ?? DEFAULT_MAX_TOOL_TURNS;
+  const render = opts.renderResult ?? defaultRender;
+  const labelFor = opts.labelFor ?? ((c) => c.toolName);
+  const runId = opts.runId ?? `agent-run-${randomSuffix2()}`;
+  const messages = [
+    { role: "system", content: opts.systemPrompt },
+    ...opts.priorMessages ?? [],
+    { role: "user", content: opts.userMessage }
+  ];
+  const observer = createToolLoopObserver(opts.hooks, runId, opts.scenarioId);
+  observer.loopBefore(maxTurns, messages.length);
+  for (let toolTurn = 0; ; toolTurn++) {
+    let turnText = "";
+    const pending = [];
+    const turnEventId = observer.turnBefore(toolTurn, messages.length);
+    for await (const event of opts.streamTurn([...messages])) {
+      yield { kind: "event", event };
+      turnText += opts.extractText(event);
+      const call = opts.extractToolCall(event);
+      if (call && opts.isExecutableTool(call.toolName)) pending.push(call);
+    }
+    if (pending.length === 0) {
+      observer.turnAfter(toolTurn, turnEventId, { pendingToolCalls: 0 });
+      observer.loopAfter({ turns: toolTurn + 1, cappedOut: false });
+      return;
+    }
+    if (toolTurn >= maxTurns) {
+      observer.turnAfter(toolTurn, turnEventId, {
+        pendingToolCalls: pending.length,
+        cappedOut: true
+      });
+      observer.loopAfter({ turns: toolTurn + 1, cappedOut: true });
+      yield { kind: "capped", pending: pending.length };
+      return;
+    }
+    if (turnText.trim()) messages.push({ role: "assistant", content: turnText });
+    const lines = [];
+    const outcomes = [];
+    for (const [callIndex, call] of pending.entries()) {
+      const callEventId = observer.toolCallBefore(toolTurn, turnEventId, callIndex, call);
+      let outcome;
+      try {
+        outcome = await opts.executeToolCall(call);
+      } catch (err) {
+        outcome = {
+          ok: false,
+          code: "executor_error",
+          message: err instanceof Error ? err.message : String(err)
+        };
+      }
+      const label = labelFor(call);
+      yield {
+        kind: "tool_result",
+        toolName: call.toolName,
+        toolCallId: call.toolCallId,
+        label,
+        outcome
+      };
+      const rendered = render(label, outcome);
+      lines.push(rendered);
+      outcomes.push({ call, label, outcome, rendered });
+      observer.toolCallAfter(toolTurn, callEventId, call, outcome);
+    }
+    observer.failureRecovery({
+      toolTurn,
+      messages,
+      turnText,
+      outcomes
+    });
+    observer.turnAfter(toolTurn, turnEventId, {
+      pendingToolCalls: pending.length,
+      toolResults: outcomes.map((item) => ({
+        toolName: item.call.toolName,
+        toolCallId: item.call.toolCallId,
+        ok: item.outcome.ok
+      })),
+      failedToolCalls: outcomes.filter((item) => !item.outcome.ok).length
+    });
+    messages.push({ role: "user", content: `Tool results:
+${lines.join("\n")}` });
+  }
+}
+function createToolLoopObserver(hooks, runId, scenarioId) {
+  const loopEventId = `${runId}:agent.run`;
+  return {
+    loopBefore: (maxToolTurns, messageCount) => {
+      notifyToolLoopEvent({
+        hooks,
+        runId,
+        scenarioId,
+        target: "agent.run",
+        phase: "before",
+        id: `${loopEventId}:before`,
+        payload: { maxToolTurns, messageCount }
+      });
+    },
+    loopAfter: (payload) => {
+      notifyToolLoopEvent({
+        hooks,
+        runId,
+        scenarioId,
+        target: "agent.run",
+        phase: "after",
+        id: `${loopEventId}:after`,
+        payload
+      });
+    },
+    turnBefore: (toolTurn, messageCount) => {
+      const turnEventId = `${loopEventId}:${toolTurn}`;
+      notifyToolLoopEvent({
+        hooks,
+        runId,
+        scenarioId,
+        target: "agent.turn",
+        phase: "before",
+        id: turnEventId,
+        stepIndex: toolTurn,
+        parentId: loopEventId,
+        payload: { messageCount }
+      });
+      return turnEventId;
+    },
+    turnAfter: (toolTurn, turnEventId, payload) => {
+      notifyToolLoopEvent({
+        hooks,
+        runId,
+        scenarioId,
+        target: "agent.turn",
+        phase: "after",
+        id: `${turnEventId}:after`,
+        stepIndex: toolTurn,
+        parentId: turnEventId,
+        payload
+      });
+    },
+    toolCallBefore: (toolTurn, turnEventId, callIndex, call) => {
+      const callEventId = `${turnEventId}:tool-call:${callIndex}`;
+      notifyToolLoopEvent({
+        hooks,
+        runId,
+        scenarioId,
+        target: "agent.tool_call",
+        phase: "before",
+        id: callEventId,
+        stepIndex: toolTurn,
+        parentId: turnEventId,
+        payload: toolCallPayload(call)
+      });
+      return callEventId;
+    },
+    toolCallAfter: (toolTurn, callEventId, call, outcome) => {
+      notifyToolLoopEvent({
+        hooks,
+        runId,
+        scenarioId,
+        target: "agent.tool_call",
+        phase: "after",
+        id: `${callEventId}:after`,
+        stepIndex: toolTurn,
+        parentId: callEventId,
+        payload: { ...toolCallPayload(call), outcome: outcomePayload(outcome) }
+      });
+    },
+    failureRecovery: (options) => {
+      notifyToolFailureRecovery({
+        hooks,
+        runId,
+        scenarioId,
+        stepIndex: options.toolTurn,
+        messages: options.messages,
+        turnText: options.turnText,
+        outcomes: options.outcomes
+      });
+    }
+  };
+}
+function notifyToolLoopEvent(options) {
+  notifyRuntimeHookEvent(options.hooks, {
+    id: options.id ?? `${options.runId}:${options.target}:${options.phase}`,
+    runId: options.runId,
+    scenarioId: options.scenarioId,
+    target: options.target,
+    phase: options.phase,
+    timestamp: Date.now(),
+    stepIndex: options.stepIndex,
+    parentId: options.parentId,
+    payload: options.payload,
+    metadata: { producer: "tool-loop", ...options.metadata }
+  });
+}
+function notifyToolFailureRecovery(options) {
+  const failed = options.outcomes.filter((item) => !item.outcome.ok);
+  if (failed.length === 0) return;
+  const evidence = [];
+  for (const item of failed) {
+    const id = item.call.toolCallId ?? `${options.stepIndex}:${item.label}`;
+    evidence.push({
+      source: "tool_call",
+      id,
+      detail: `${item.call.toolName} ${stringifySafe(item.call.args, 2e3)}`,
+      metadata: { toolName: item.call.toolName, label: item.label }
+    });
+    evidence.push({
+      source: "tool_result",
+      id: `${id}:result`,
+      detail: item.rendered,
+      metadata: failureMetadata(item.outcome)
+    });
+  }
+  notifyRuntimeDecisionPoint(options.hooks, {
+    id: `${options.runId}:agent.turn:${options.stepIndex}:failure-recovery`,
+    runId: options.runId,
+    scenarioId: options.scenarioId,
+    stepIndex: options.stepIndex,
+    kind: "retry",
+    candidateActions: [...FAILURE_RECOVERY_ACTIONS],
+    context: renderDecisionContext(options.messages, options.turnText, options.outcomes),
+    evidence,
+    metadata: {
+      target: "failure-recovery",
+      source: "agent.turn",
+      failedToolCount: failed.length,
+      toolNames: failed.map((item) => item.call.toolName)
+    }
+  });
+}
+function toolCallPayload(call) {
+  return {
+    toolName: call.toolName,
+    toolCallId: call.toolCallId,
+    argsPreview: stringifySafe(call.args, 2e3)
+  };
+}
+function outcomePayload(outcome) {
+  if (!outcome.ok) {
+    return {
+      ok: false,
+      code: outcome.code,
+      message: trimText(outcome.message, 2e3),
+      status: outcome.status
+    };
+  }
+  return {
+    ok: true,
+    resultPreview: stringifySafe(outcome.result, 2e3)
+  };
+}
+function failureMetadata(outcome) {
+  if (outcome.ok) return void 0;
+  return {
+    code: outcome.code,
+    message: outcome.message,
+    status: outcome.status
+  };
+}
+function renderDecisionContext(messages, turnText, outcomes) {
+  const recent = messages.slice(-6).map((message) => `[${message.role}]
+${message.content}`);
+  const assistant = turnText.trim() ? [`[assistant]
+${turnText}`] : [];
+  const toolResults = [`[tool results]
+${outcomes.map((item) => item.rendered).join("\n")}`];
+  return trimText(
+    [...recent, ...assistant, ...toolResults].join("\n\n"),
+    DEFAULT_DECISION_CONTEXT_CHARS
+  );
+}
+function stringifySafe(value, max) {
+  let text;
+  try {
+    text = JSON.stringify(value) ?? String(value);
+  } catch {
+    text = String(value);
+  }
+  return trimText(text, max);
+}
+function trimText(text, max) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\u2026`;
+}
+function randomSuffix2(len = 8) {
+  return Math.random().toString(36).slice(2, 2 + len);
+}
 export {
   AgentEvalError,
   BackendTransportError,
@@ -2756,6 +3138,7 @@ export {
   buildLoopOtelSpans,
   cleanModelId,
   coderLoopRunner,
+  composeRuntimeHooks,
   computeBackoff,
   createConversationBackend,
   createIterableBackend,
@@ -2768,6 +3151,7 @@ export {
   decideKnowledgeReadiness,
   defaultIsRetryable,
   defineConversation,
+  defineRuntimeHooks,
   deriveExecutionId,
   dynamicLoopRunner,
   exportEvalRuns,
@@ -2779,6 +3163,8 @@ export {
   makePerAttemptSignal,
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset,
+  notifyRuntimeDecisionPoint,
+  notifyRuntimeHookEvent,
   parseLoopRunnerArgv,
   readDepth,
   readinessServerSentEvent,
@@ -2792,6 +3178,7 @@ export {
   runConversationStream,
   runDelegatedLoop,
   runLoopRunnerCli,
+  runToolLoop,
   runtimeStreamServerSentEvent,
   sanitizeAgentRuntimeEvent,
   sanitizeKnowledgeReadinessReport,
@@ -2800,6 +3187,7 @@ export {
   sleep2 as sleep,
   slugifySpeaker,
   startRuntimeRun,
+  streamToolLoop,
   turnId,
   validateChatModelId
 };