@ziggs-ai/agent-sdk 0.1.3 → 0.1.4

package/src/runtime/runTurn.ts

@@ -0,0 +1,637 @@
+import type {
+  Action, Ctx, Outcome, ToolResultEntry,
+  EffectHandler, LlmMessage, LlmResponse, LlmToolSchema, LlmToolCall,
+  ContextSnapshot, ToolCallResult,
+} from '../types.js';
+import type { MemoryStore } from '../memory/MemoryStore.js';
+import { outcomeFromActionResult, type RawEvent, type EmittedEvent, type WireResult } from './buildOutcome.js';
+import { PromptBuilder } from './PromptBuilder.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { safeParseJSON } from '../utils/jsonExtractor.js';
+import type { ToolManager } from '../tools/ToolManager.js';
+import type { ToolDefinition } from '../tools/defineTool.js';
+
+type WireEvent = Record<string, unknown>;
+
+interface ParsedDecision {
+  action: string;
+  tool?: string;
+  thought?: string;
+  message?: string;
+  messages?: Array<{ receiverId: string; message: string; chatId?: string }>;
+  receiverId?: string;
+  chatId?: string;
+  args?: Record<string, unknown>;
+}
+
+const MAX_TOOL_LOOP_ITERS = 20;
+const MAX_MSG_CHARS = 3500;
+
+/**
+ * Legacy "name set" classifications. The runtime now prefers per-tool flags
+ * (`isAgreementCreation`, `isGenericFallback`) set via `defineTool` options,
+ * but these sets remain as a fallback so tools authored before the flag API
+ * existed continue to work without modification.
+ */
+const LEGACY_AGREEMENT_CREATION_NAMES = new Set([
+  'agreement_propose',
+  'agreement_subcontract',
+]);
+const LEGACY_GENERIC_FALLBACK_NAMES = new Set(['agent_network', 'task_board']);
+
+function isAgreementCreationTool(name: string, toolManager: ToolManager): boolean {
+  if (!name) return false;
+  if (toolManager?.getTool?.(name)?.isAgreementCreation === true) return true;
+  return LEGACY_AGREEMENT_CREATION_NAMES.has(name);
+}
+function isGenericFallbackTool(name: string, toolManager: ToolManager): boolean {
+  if (!name) return false;
+  if (toolManager?.getTool?.(name)?.isGenericFallback === true) return true;
+  return LEGACY_GENERIC_FALLBACK_NAMES.has(name);
+}
+
+interface RunTurnInput {
+  stateId: string;
+  statePrompt: import('../types.js').PromptDef;
+  actions: Record<string, Action>;
+  incomingEvent: RawEvent | null;
+  ctx: Ctx;
+  /** The only side channel. Every I/O — context, LLM, tools, send, record — flows through here. */
+  eff: EffectHandler;
+  /** Pure metadata: tool schemas, flags. Owned by the Agent. */
+  toolManager: ToolManager;
+  promptBuilder: PromptBuilder;
+  /**
+   * Agent-private long-term memory, threaded from AgentHost. Currently
+   * surfaced into `eff` as part of the tool-call effect payload so tools
+   * can read/write notes; the prompt builder doesn't consume it yet.
+   */
+  memory?: MemoryStore;
+  definition: { description?: string };
+}
+
+interface RunTurnResult {
+  outcome: Outcome;
+  toolResults: ToolResultEntry[];
+  llmCalls: number;
+  tokens: { total: number; input: number; output: number };
+}
+
+/**
+ * Run a single thinking-state turn.
+ *
+ * Reads context → builds prompt → tool loop with the LLM → executes one
+ * action → returns exactly one Outcome via outcomeFromActionResult.
+ *
+ * No direct service calls. Every impure operation goes through `eff`:
+ *   • eff('read-context')  — history/agreements/agents snapshot
+ *   • eff('llm-call')      — model invocation
+ *   • eff('tool-call')     — tool execution (Server runs the tool body)
+ *   • eff('send-message')  — outbound peer message
+ *   • eff('record-event')  — persist a thought / decision marker
+ *
+ * The Server is responsible for turning each effect into the right HTTP/WS
+ * call and (optionally) wrapping it in telemetry / dedup / retries.
+ */
+export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
+  const { stateId, statePrompt, actions, incomingEvent, ctx, eff, toolManager, promptBuilder, memory, definition } = input;
+  const sessionId = ctx.identity.sessionId;
+
+  const emitThought = async (text: unknown): Promise<void> => {
+    if (text == null) return;
+    const s = String(text).trim();
+    if (s.length === 0) return;
+    try {
+      await eff({ kind: 'record-event', sessionId, entry: { kind: 'thought', text: s } });
+    } catch (err) {
+      runtimeLog.warn('runTurn', `record-event:thought failed: ${(err as Error).message}`);
+    }
+  };
+
+  runtimeLog.info('runTurn', `enter state=${stateId}`);
+
+  // Parallel: read session context + collect tool schemas (pure).
+  // Filter tools to only those bound to an action in the current state — the
+  // runtime rejects tool calls that don't map to an allowed action (see
+  // findActionForTool), so don't advertise tools the LLM can't actually use.
+  const allTools: ToolDefinition[] = await Promise.resolve(toolManager?.getAvailableTools?.() ?? []);
+  const allowedToolNames = new Set(
+    Object.values(actions).map(a => a.tool).filter((t): t is string => !!t),
+  );
+  const toolName = (t: ToolDefinition): string | undefined => {
+    const fn = (t.schema as Record<string, unknown>).function as Record<string, unknown> | undefined;
+    return (fn?.name ?? (t.schema as Record<string, unknown>).name) as string | undefined;
+  };
+  const tools = allowedToolNames.size > 0
+    ? allTools.filter(t => {
+        const n = toolName(t);
+        return n != null && allowedToolNames.has(n);
+      })
+    : [];
+  const serverContext = await eff({ kind: 'read-context', sessionId, opts: {} });
+  const ctxObj = normalizeContextSnapshot(serverContext);
+
+  const probeDispatch = Object.entries(actions).find(([, a]) => a.tool === 'capability_probe_dispatch');
+  if (probeDispatch && incomingEvent) {
+    const [actionName, actionDef] = probeDispatch;
+    const messageText =
+      extractIncomingMessageText(incomingEvent, ctxObj as ContextSnapshot) ||
+      JSON.stringify(incomingEvent);
+    const toolResultsOut: ToolResultEntry[] = [];
+    const emitted = await executeTool(
+      { action: actionName, tool: 'capability_probe_dispatch', args: { messageText } },
+      eff,
+      sessionId,
+      memory,
+    );
+    const events = (Array.isArray(emitted) ? emitted : emitted ? [emitted] : []) as EmittedEvent[];
+    const outcome = outcomeFromActionResult(actionName, actionDef, {}, events, toolResultsOut);
+    return { outcome, toolResults: toolResultsOut, llmCalls: 0, tokens: { total: 0, input: 0, output: 0 } };
+  }
+
+  const prompt = promptBuilder.buildFromState({
+    statePrompt, actions,
+    serverContext: { context: ctxObj as Record<string, unknown>, tools: tools as unknown as Record<string, unknown>[] },
+    incomingEvent, definition,
+    chatId: sessionId, stateId, ctx,
+  });
+
+  const systemContent = tools.length > 0
+    ? 'You are a helpful AI agent. Use the available tools to complete your tasks. When you are finished using tools, respond with a valid JSON decision object.'
+    : 'Respond with valid JSON.';
+  const messages: LlmMessage[] = [
+    { role: 'system', content: systemContent },
+    { role: 'user', content: prompt },
+  ];
+
+  const allEmittedEvents: EmittedEvent[] = [];
+  let lastAction: string | null = null;
+  let lastActionDef: Action | null = null;
+  let lastArgs: unknown = null;
+  let llmCallsTotal = 0;
+  let tokensTotal = 0, tokensInput = 0, tokensOutput = 0;
+  // Tracks whether a successful agreement creation has already happened in
+  // this turn. Used by annotateToolCallDedup to reject any second creation
+  // attempt across iterations of the tool loop.
+  let turnHadAgreementCreation = false;
+  const actionNames = Object.keys(actions);
+
+  runtimeLog.info('runTurn', `calling LLM tools=${tools.length}`);
+
+  for (let iter = 0; iter < MAX_TOOL_LOOP_ITERS; iter++) {
+    const llmResponse: LlmResponse = await eff({ kind: 'llm-call', messages, tools: tools as unknown as LlmToolSchema[] });
+    llmCallsTotal++;
+    const usage = llmResponse?.usage;
+    tokensTotal  += (usage?.total_tokens  ?? usage?.totalTokens)  || 0;
+    tokensInput  += (usage?.prompt_tokens ?? usage?.promptTokens) || 0;
+    tokensOutput += (usage?.completion_tokens ?? usage?.completionTokens) || 0;
+
+    if (llmResponse?.tool_calls?.length) {
+      // Emit a thought for every tool-call turn so the chat timeline keeps
+      // showing the agent's reasoning. OpenAI's tool_call responses usually
+      // arrive with `content: null` (the standard "function calling"
+      // shape), so relying on `llmResponse.content` alone silently dropped
+      // the thought card whenever the agent chose to act via a tool —
+      // i.e. essentially every first turn that produces a proposal. Fall
+      // back to a deterministic "Calling tool: …" line so the user still
+      // sees that the agent decided on something, with the args appended
+      // when present.
+      const toolCallThought = (() => {
+        if (typeof llmResponse.content === 'string' && llmResponse.content.trim()) {
+          return llmResponse.content;
+        }
+        const fn = llmResponse.tool_calls[0]?.function;
+        if (!fn?.name) return null;
+        const argsBlob = (() => {
+          if (!fn.arguments) return '';
+          try {
+            const parsed = JSON.parse(fn.arguments);
+            const flat = JSON.stringify(parsed);
+            return flat.length > 240 ? ` ${flat.slice(0, 237)}…` : ` ${flat}`;
+          } catch {
+            return '';
+          }
+        })();
+        const suffix = llmResponse.tool_calls.length > 1
+          ? ` (+${llmResponse.tool_calls.length - 1} more)`
+          : '';
+        return `Calling tool: ${fn.name}${argsBlob}${suffix}`;
+      })();
+      await emitThought(toolCallThought);
+
+      const tcs = llmResponse.tool_calls;
+      const annotated = annotateToolCallDedup(tcs, toolManager, turnHadAgreementCreation);
+      const dupCount = annotated.filter(a => a.skipExecute).length;
+      if (dupCount > 0) {
+        runtimeLog.warn('runTurn', `iter=${iter} skipping ${dupCount} duplicate tool call(s) in same message`);
+      }
+
+      messages.push({ role: 'assistant', tool_calls: tcs });
+
+      const toolCallResults: Array<{ tc: LlmToolCall; matchingAction: string | null; result: unknown; skippedDuplicate?: boolean; skipReason?: string; args?: Record<string, unknown>; actionDef?: Action | null }> = [];
+      for (const ann of annotated) {
+        const { tc, skipExecute, skipReason } = ann;
+        if (skipExecute) {
+          toolCallResults.push({ tc, matchingAction: null, result: null, skippedDuplicate: true, skipReason });
+          continue;
+        }
+        const toolName = tc?.function?.name;
+        if (!toolName) {
+          toolCallResults.push({ tc, matchingAction: null, result: null });
+          continue;
+        }
+
+        let matchingAction = findActionForTool(toolName, actionNames, actions);
+        let actionDef: Action | null = matchingAction ? actions[matchingAction] : null;
+
+        if (!matchingAction && isGenericFallbackTool(toolName, toolManager) && toolManager.getTool?.(toolName)) {
+          matchingAction = '_genericDiscoveryTool';
+          actionDef = null;
+        } else if (!matchingAction) {
+          runtimeLog.info('runTurn', `iter=${iter} tool "${toolName}" not bound to any action — skipping`);
+          toolCallResults.push({ tc, matchingAction: null, result: null });
+          continue;
+        }
+
+        let args: Record<string, unknown> = {};
+        try { args = JSON.parse(tc.function.arguments || '{}'); } catch {}
+        const decision = { action: matchingAction, tool: toolName, args };
+
+        const result = await executeDecision(decision, actionDef, eff, sessionId, memory);
+        toolCallResults.push({ tc, matchingAction, result, args, actionDef });
+      }
+
+      let hasTerminal = false;
+      for (const item of toolCallResults) {
+        const { tc, matchingAction, result, skippedDuplicate, skipReason, args, actionDef } = item;
+        if (skippedDuplicate) {
+          messages.push({ role: 'tool', tool_call_id: tc.id, content: JSON.stringify({ skipped: true, reason: skipReason || 'deduplicated' }) });
+          continue;
+        }
+        if (!matchingAction || !result) {
+          messages.push({ role: 'tool', tool_call_id: tc.id, content: '{"error":"unknown tool or no result"}' });
+          continue;
+        }
+
+        const events = (Array.isArray(result) ? result : [result]) as EmittedEvent[];
+        allEmittedEvents.push(...events);
+        lastAction = matchingAction;
+        lastActionDef = actionDef as Action | null;
+        lastArgs = args;
+
+        const firstEvent = (events[0] || {}) as EmittedEvent;
+        const toolResultContent = JSON.stringify(firstEvent.result ?? firstEvent);
+        messages.push({ role: 'tool', tool_call_id: tc.id, content: toolResultContent });
+
+        if (!turnHadAgreementCreation && eventsContainAgreementCreation(events)) {
+          turnHadAgreementCreation = true;
+        }
+        if (eventsAreTerminal(events)) hasTerminal = true;
+      }
+
+      if (hasTerminal) break;
+      messages.push({ role: 'user', content: 'Tools done. Return your JSON decision now (follow the decision_schema). Do not write prose.' });
+
+    } else {
+      // — non-tool (JSON) response path —
+      const decision = parseLLMDecision(llmResponse, actionNames, actions);
+      if (!decision) break;
+      const chosenAction = decision.action;
+      const actionDef = actions[chosenAction];
+
+      if (decision.thought) await emitThought(decision.thought);
+
+      const result = await executeDecision(decision, actionDef, eff, sessionId, memory);
+      if (result) {
+        const events = (Array.isArray(result) ? result : [result]) as EmittedEvent[];
+        allEmittedEvents.push(...events);
+        lastAction = chosenAction;
+        lastActionDef = actionDef;
+        lastArgs = decision.args;
+
+        if (actionDef?.tool) {
+          const firstEvent = (events[0] || {}) as EmittedEvent;
+          const toolResultContent = JSON.stringify(firstEvent.result ?? firstEvent);
+          messages.push({ role: 'assistant', content: llmResponse.content });
+          messages.push({ role: 'user', content: `Tool "${actionDef.tool}" result:\n${toolResultContent}\n\nContinue with your next action.` });
+          if (!turnHadAgreementCreation && eventsContainAgreementCreation(events)) {
+            turnHadAgreementCreation = true;
+          }
+          if (eventsAreTerminal(events)) break;
+          continue;
+        }
+      }
+      break;
+    }
+  }
+
+  await echoOptInToolSummaryIfNeeded({
+    allEmittedEvents, eff, sessionId,
+    context: ctxObj, toolManager, incomingEvent,
+  });
+
+  const toolResults: ToolResultEntry[] = [];
+  const outcome = outcomeFromActionResult(lastAction, lastActionDef, lastArgs, allEmittedEvents, toolResults);
+
+  runtimeLog.info('runTurn', `done state=${stateId} action=${lastAction} outcome=${outcome.kind} llmCalls=${llmCallsTotal}`);
+
+  return { outcome, toolResults, llmCalls: llmCallsTotal, tokens: { total: tokensTotal, input: tokensInput, output: tokensOutput } };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+function normalizeContextSnapshot(raw: ContextSnapshot | undefined | null): ContextSnapshot {
+  if (!raw || typeof raw !== 'object') {
+    return { history: [], agreements: [], agents: [], users: [] };
+  }
+  const out = { ...raw } as Record<string, unknown>;
+  for (const key of ['history', 'agreements', 'agents', 'users']) {
+    if (!Array.isArray(out[key])) out[key] = [];
+  }
+  return out as unknown as ContextSnapshot;
+}
+
+function eventsAreTerminal(events: EmittedEvent[]): boolean {
+  return events.some(e => {
+    if (!e) return false;
+    const t = e.type;
+    if (t === 'message_sent' || t === 'message_duplicate_skipped' || t === 'waited') return true;
+    // Successful protocol-level state changes (agreement creation, task
+    // assignment/closure) end the turn. The next turn re-enters with the
+    // matching outcome and the workflow takes it from there. Without this,
+    // the LLM is nudged with "Continue with your next action." and often
+    // re-issues the same agreement_propose, producing duplicate proposal
+    // cards within a single user turn.
+    if (t === 'tool_result' || t === 'task_result') {
+      const r = (e.result as Record<string, unknown>) || {};
+      if (r.success === false || r.error) return false;
+      // Support both nested { agreement: {...} } and flat Agreement objects
+      // (api-client now returns Agreement directly, not wrapped in { agreement }).
+      const ag = (r.agreement ?? (r.agreementId ? r : null)) as Record<string, unknown> | null | undefined;
+      const task = (r.task || (r.taskId ? r : null)) as Record<string, unknown> | null | undefined;
+      const agProposal = ag?.proposal as Record<string, unknown> | undefined;
+      const taskProposal = task?.proposal as Record<string, unknown> | undefined;
+      const proposalStatus = agProposal?.status || taskProposal?.status;
+      if (proposalStatus === 'pending' || proposalStatus === 'approved') return true;
+      const state = task?.state || r.state;
+      if (state === 'active' || state === 'in-progress' ||
+          state === 'completed' || state === 'failed' || state === 'cancelled') {
+        return true;
+      }
+    }
+    return false;
+  });
+}
+
+function eventsContainAgreementCreation(events: EmittedEvent[]): boolean {
+  return events.some(e => {
+    if (!e || e.type !== 'tool_result') return false;
+    const r = (e.result as Record<string, unknown>) || {};
+    if (r.success === false || r.error) return false;
+    // Support both nested { agreement: {...} } and flat Agreement objects.
+    const ag = (r.agreement ?? (r.agreementId ? r : null)) as Record<string, unknown> | undefined;
+    const agProposal = ag?.proposal as Record<string, unknown> | undefined;
+    const task = r.task as Record<string, unknown> | undefined;
+    const taskProposal = task?.proposal as Record<string, unknown> | undefined;
+    const proposalStatus = agProposal?.status || taskProposal?.status;
+    return proposalStatus === 'pending' || proposalStatus === 'approved';
+  });
+}
+
+function annotateToolCallDedup(
+  toolCalls: LlmToolCall[],
+  toolManager: ToolManager,
+  initialSawCreate = false,
+): Array<{ tc: LlmToolCall; skipExecute: boolean; skipReason?: string }> {
+  let sawCreate = initialSawCreate;
+  const seenUpdateTaskIds = new Set<string>();
+  return (toolCalls || []).map((tc: LlmToolCall) => {
+    const name = tc?.function?.name;
+    if (name && isAgreementCreationTool(name, toolManager)) {
+      if (sawCreate) {
+        return {
+          tc,
+          skipExecute: true,
+          skipReason: initialSawCreate
+            ? 'agreement creation already executed earlier in this turn'
+            : 'duplicate agreement creation in same assistant message',
+        };
+      }
+      sawCreate = true;
+      return { tc, skipExecute: false };
+    }
+    if (name === 'task_update') {
+      let taskId: string | null = null;
+      try { const a = JSON.parse(tc.function.arguments || '{}'); taskId = typeof a.taskId === 'string' ? a.taskId : null; } catch {}
+      const key = taskId || tc.id || '_';
+      if (seenUpdateTaskIds.has(key)) return { tc, skipExecute: true, skipReason: 'duplicate task_update for same taskId' };
+      seenUpdateTaskIds.add(key);
+      return { tc, skipExecute: false };
+    }
+    return { tc, skipExecute: false };
+  });
+}
+
+function parseLLMDecision(llmResponse: LlmResponse, allowedActionNames: string[], actions: Record<string, Action>): ParsedDecision | null {
+  if (llmResponse?.tool_calls?.length) {
+    const tc = llmResponse.tool_calls[0];
+    if (!tc?.function?.name) return null;
+    let args: Record<string, unknown> = {};
+    try { args = JSON.parse(tc.function.arguments || '{}'); } catch {}
+    const matchingAction = findActionForTool(tc.function.name!, allowedActionNames, actions);
+    if (!matchingAction) return null;
+    return { thought: `Using tool: ${tc.function.name}`, action: matchingAction, tool: tc.function.name, args };
+  }
+
+  const parsed = safeParseJSON(llmResponse?.content || '', null) as Record<string, unknown> | null;
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  if (!parsed['action'] || !allowedActionNames.includes(parsed['action'] as string)) return null;
+  return parsed as unknown as ParsedDecision;
+}
+
+function findActionForTool(toolName: string, allowedActionNames: string[], actions: Record<string, Action>): string | null {
+  if (!toolName) return null;
+  const matches = allowedActionNames.filter(n => actions[n]?.tool === toolName);
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    runtimeLog.warn('runTurn', `ambiguous: ${matches.length} actions bind tool "${toolName}"`);
+    return null;
+  }
+  return null;
+}
+
+async function executeDecision(decision: ParsedDecision, actionDef: Action | null, eff: EffectHandler, sessionId: string, memory?: MemoryStore): Promise<EmittedEvent[] | EmittedEvent | null> {
+  const boundTool = actionDef?.tool || null;
+
+  if (boundTool) {
+    decision.tool = boundTool;
+    return await executeTool(decision, eff, sessionId, memory);
+  }
+  if (decision.action === '_genericDiscoveryTool' && decision.tool) return await executeTool(decision, eff, sessionId, memory);
+  if (decision.tool) return await executeTool(decision, eff, sessionId, memory);
+  if (decision.messages && Array.isArray(decision.messages) && decision.messages.length > 0) {
+    return await executeSendMessages(decision, eff, sessionId);
+  }
+  if (decision.message && decision.receiverId) {
+    return await executeSendMessage(decision, eff, sessionId);
+  }
+  if (decision.action === 'wait') return { type: 'waited' };
+  return null;
+}
+
+function truncateMsg(msg: unknown): string {
+  if (typeof msg !== 'string') return String(msg ?? '');
+  if (msg.length <= MAX_MSG_CHARS) return msg;
+  return msg.slice(0, MAX_MSG_CHARS) + `\n\n[truncated to ${MAX_MSG_CHARS} of ${msg.length} chars]`;
+}
+
+async function executeSendMessage(decision: ParsedDecision, eff: EffectHandler, sessionId: string | null): Promise<EmittedEvent[] | null> {
+  const { message, receiverId } = decision;
+  if (!message || !receiverId) return null;
+  // `decision.chatId` is what the LLM emitted in its JSON decision; honor it
+  // for cross-session sends (e.g. reporting to a parent task chat), fall back
+  // to the current session otherwise.
+  const targetSessionId = decision.chatId || sessionId;
+  const safeMessage = truncateMsg(message);
+  if (targetSessionId) {
+    await eff({ kind: 'send-message', sessionId: targetSessionId, receiverId: receiverId!, text: safeMessage });
+  }
+  const events: EmittedEvent[] = [{ type: 'message_sent', receiverId: receiverId!, chatId: targetSessionId ?? undefined, message: safeMessage, senderId: 'system' }];
+  if (targetSessionId !== sessionId) events.push({ type: 'report_sent', message: 'Reported to owner.', senderId: 'system' });
+  return events;
+}
+
+async function executeSendMessages(decision: ParsedDecision, eff: EffectHandler, sessionId: string | null): Promise<EmittedEvent[]> {
+  const events: EmittedEvent[] = [];
+  for (const msg of decision.messages ?? []) {
+    if (!msg.receiverId || !msg.message) continue;
+    const targetSessionId = msg.chatId || sessionId;
+    const safeMessage = truncateMsg(msg.message);
+    if (targetSessionId) {
+      try { await eff({ kind: 'send-message', sessionId: targetSessionId, receiverId: msg.receiverId, text: safeMessage }); } catch { continue; }
+    }
+    events.push({ type: 'message_sent', receiverId: msg.receiverId, chatId: targetSessionId ?? undefined, message: safeMessage, senderId: 'system' });
+    if (targetSessionId !== sessionId) events.push({ type: 'report_sent', message: 'Reported to owner.', senderId: 'system' } as unknown as EmittedEvent);
+  }
+  return events;
+}
+
+/**
+ * Tool execution becomes a single effect call. The Server is responsible for
+ * dispatching the named tool to its implementation, providing the impure
+ * dependencies (taskService, agreementService, agents list, etc.), and
+ * wrapping the call in telemetry / operation-record entries if it wants.
+ */
+async function executeTool(decision: ParsedDecision, eff: EffectHandler, sessionId: string, memory?: MemoryStore): Promise<EmittedEvent[] | EmittedEvent | null> {
+  const { tool, args } = decision;
+  if (!tool) return null;
+  try {
+    const r = await eff({ kind: 'tool-call', sessionId, name: tool, args: args || {}, memory }) as ToolCallResult;
+    if (!r.ok) return { type: 'tool_error', tool, error: r.error || 'unknown', senderId: 'system' };
+    // Tools may emit terminal markers (e.g. `message_sent`, `waited`) via
+    // `events` — propagate so the loop can detect terminal turns.
+    if (r.events && (r.events as unknown[]).length > 0) return r.events as unknown as EmittedEvent[];
+    return { type: 'tool_result', tool, result: r.result as WireResult | undefined, senderId: 'system' };
+  } catch (error: unknown) {
+    return { type: 'tool_error', tool, error: (error as Error)?.message ?? String(error), senderId: 'system' };
+  }
+}
+
+function shouldEchoToolSummaryToUser(result: unknown): boolean {
+  if (!result || typeof result !== 'object') return false;
+  const r = result as Record<string, unknown>;
+  if (typeof r.message !== 'string' || !(r.message as string).trim()) return false;
+  if (r.success === false) return false;
+  if (r.error) return false;
+  return true;
+}
+
+async function echoOptInToolSummaryIfNeeded({ allEmittedEvents, eff, sessionId, context, toolManager, incomingEvent }: {
+  allEmittedEvents: EmittedEvent[];
+  eff: EffectHandler;
+  sessionId: string;
+  context: ContextSnapshot;
+  toolManager: ToolManager;
+  incomingEvent: RawEvent | null;
+}): Promise<void> {
+  if (!eff || !sessionId || !context || !toolManager?.getTool) return;
+  if (allEmittedEvents.some((e) => e?.type === 'message_sent')) return;
+
+  let summary: string | null = null;
+  for (const ev of allEmittedEvents) {
+    if (ev?.type !== 'tool_result' || !ev.tool) continue;
+    const reg = toolManager.getTool(ev.tool);
+    if (!reg?.echoUserSummaryOnSuccess) continue;
+    if (!shouldEchoToolSummaryToUser(ev.result)) continue;
+    summary = (ev.result as Record<string, unknown>).message as string;
+  }
+  if (!summary) return;
+
+  const receiverId = pickReceiverForEcho(context, incomingEvent);
+  if (!receiverId) return;
+
+  const safe = truncateMsg(summary);
+  const wasTruncated = safe !== summary;
+  try {
+    await eff({ kind: 'send-message', sessionId, receiverId, text: safe });
+  } catch { return; }
+  const event: Record<string, unknown> = { type: 'message_sent', receiverId, chatId: sessionId, message: safe, senderId: 'system' };
+  if (wasTruncated) { event['truncated'] = true; event['originalLength'] = summary.length; }
+  allEmittedEvents.push(event as unknown as EmittedEvent);
+}
+
+function pickReceiverForEcho(context: ContextSnapshot, incomingEvent: RawEvent | null): string | null {
+  const senderId = incomingEvent?.senderId;
+  const senderType = String(incomingEvent?.senderType || '').toUpperCase();
+  if (senderId && senderType === 'USER') return String(senderId);
+  return pickPrimaryUserIdFromContext(context);
+}
+
+function extractIncomingMessageText(
+  incomingEvent: RawEvent | null,
+  ctx: ContextSnapshot,
+): string {
+  const parts: string[] = [];
+  const walk = (ev: RawEvent | null | undefined): void => {
+    if (!ev) return;
+    if (ev.text) parts.push(String(ev.text));
+    if (typeof ev.message === 'string') parts.push(ev.message);
+    const result = ev.result as Record<string, unknown> | undefined;
+    if (result) {
+      if (result.description) parts.push(String(result.description));
+      const ag = result.agreement as Record<string, unknown> | undefined;
+      if (ag) {
+        const terms = ag.terms as Record<string, unknown> | undefined;
+        if (terms?.description) parts.push(String(terms.description));
+        if (ag.agreementId) parts.push(String(ag.agreementId));
+      }
+      if (result.agreementId) parts.push(String(result.agreementId));
+    }
+    if (Array.isArray(ev.events)) (ev.events as RawEvent[]).forEach(walk);
+  };
+  walk(incomingEvent);
+  const hist = ctx.history as Array<Record<string, unknown>> | undefined;
+  if (hist?.length) {
+    const last = hist[hist.length - 1];
+    const text = last?.text ?? last?.content;
+    if (text) parts.push(String(text));
+  }
+  return parts.join('\n').trim();
+}
+
+function pickPrimaryUserIdFromContext(context: ContextSnapshot): string | null {
+  const users = context?.users || [];
+  for (const u of users as Record<string, unknown>[]) {
+    const id = (u?.userId || u?.id) as string | undefined;
+    if (id && typeof id === 'string') return id;
+  }
+  const hist = context?.history || [];
+  for (let i = hist.length - 1; i >= 0; i--) {
+    const row = hist[i] as Record<string, unknown>;
+    const sender = row?.sender as Record<string, unknown> | undefined;
+    const type = String(sender?.type || row?.senderType || '').toUpperCase();
+    const id = (sender?.id ?? row?.senderId) as string | undefined;
+    if (type === 'USER' && id) return id;
+  }
+  return null;
+}