@ziggs-ai/agent-sdk 0.1.11 → 0.2.0

package/dist/runtime/runTurn.js

@@ -0,0 +1,800 @@
+import { outcomeFromActionResult } from './buildOutcome.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { safeParseJSON } from '../utils/jsonExtractor.js';
+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, toolManager) {
+    if (!name)
+        return false;
+    if (toolManager?.getTool?.(name)?.isAgreementCreation === true)
+        return true;
+    return LEGACY_AGREEMENT_CREATION_NAMES.has(name);
+}
+function isGenericFallbackTool(name, toolManager) {
+    if (!name)
+        return false;
+    if (toolManager?.getTool?.(name)?.isGenericFallback === true)
+        return true;
+    return LEGACY_GENERIC_FALLBACK_NAMES.has(name);
+}
+/**
+ * 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) {
+    const { stateId, statePrompt, actions, incomingEvent, ctx, eff, toolManager, promptBuilder, memory, definition } = input;
+    // Default on (ZIG-838); ENABLE_LLM_STREAMING=false is the deployment
+    // kill-switch. Any other value (unset, 'true', …) streams.
+    const streamRespondActions = input.streamRespondActions ?? process.env.ENABLE_LLM_STREAMING !== 'false';
+    const sessionId = ctx.identity.sessionId;
+    const runId = crypto.randomUUID();
+    // Wrap eff to stamp runId + stateId onto llm-call and tool-call effects.
+    const effWithTrace = (effect) => {
+        if (effect.kind === 'llm-call' || effect.kind === 'tool-call') {
+            return eff({ ...effect, runId, stateId });
+        }
+        return eff(effect);
+    };
+    const emitThought = async (text) => {
+        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.message}`);
+        }
+    };
+    runtimeLog.info('runTurn', `enter state=${stateId} runId=${runId}`);
+    // 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 = await Promise.resolve(toolManager?.getAvailableTools?.() ?? []);
+    const allowedToolNames = new Set(Object.values(actions).map(a => a.tool).filter((t) => !!t));
+    const toolName = (t) => {
+        const fn = t.schema.function;
+        return (fn?.name ?? t.schema.name);
+    };
+    const tools = allowedToolNames.size > 0
+        ? allTools.filter(t => {
+            const n = toolName(t);
+            return n != null && allowedToolNames.has(n);
+        })
+        : [];
+    const serverContext = await effWithTrace({ kind: 'read-context', sessionId, opts: {} });
+    const ctxObj = normalizeContextSnapshot(serverContext);
+    // A message wake whose chat no longer resolves (deleted, or never visible
+    // to this agent) has no world to decide over — deciding anyway means
+    // reasoning about a fabricated empty history plus whatever stale scraps
+    // other fetches returned. Skip the LLM and park. Gated on message wakes
+    // only: agreement-keyed task lanes (sessionId = agreementId) always trip
+    // chatMissing and must still run.
+    if (ctxObj.chatMissing && ctx.lastOutcome?.kind === 'message-received') {
+        runtimeLog.warn('runTurn', `chat ${sessionId} not found on backend — skipping message wake (state=${stateId})`);
+        return {
+            outcome: { kind: 'wait' },
+            toolResults: [],
+            llmCalls: 0,
+            tokens: { total: 0, input: 0, output: 0 },
+        };
+    }
+    const prompt = promptBuilder.buildFromState({
+        statePrompt, actions,
+        serverContext: { context: ctxObj, tools: tools },
+        incomingEvent, definition,
+        chatId: sessionId, stateId, ctx,
+        omitMessageFromRespond: streamRespondActions,
+    });
+    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 = [
+        { role: 'system', content: systemContent },
+        { role: 'user', content: prompt },
+    ];
+    const allEmittedEvents = [];
+    let lastAction = null;
+    let lastActionDef = null;
+    let lastArgs = null;
+    let llmCallsTotal = 0;
+    let tokensTotal = 0, tokensInput = 0, tokensOutput = 0;
+    // Fold a tool's nested LLM usage (llmTool) into the turn's authoritative
+    // token count so tool-internal spend reaches result.metrics (ZIG-813).
+    const addToolUsage = (u) => {
+        if (!u)
+            return;
+        llmCallsTotal++;
+        tokensTotal += (u.total_tokens ?? u.totalTokens) || 0;
+        tokensInput += (u.prompt_tokens ?? u.promptTokens) || 0;
+        tokensOutput += (u.completion_tokens ?? u.completionTokens) || 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;
+    // Hard failure at the decision/send boundary. When set, the turn's outcome
+    // is forced to kind 'error' regardless of partial events accumulated — the
+    // FSM must see the failure, not a best-effort inference over half-finished
+    // work. Causes are stable strings so workflow transitions can match them.
+    let turnError = null;
+    // One corrective retry when the LLM's non-tool output cannot be turned into
+    // an executable decision (parse failure, or missing message/receiverId).
+    let repromptedForDecision = 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 = await effWithTrace({
+            kind: 'llm-call',
+            messages,
+            tools: tools,
+            sessionId,
+        });
+        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 = [];
+            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 = 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 = {};
+                try {
+                    args = JSON.parse(tc.function.arguments || '{}');
+                }
+                catch { }
+                const decision = { action: matchingAction, tool: toolName, args };
+                const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, null, addToolUsage);
+                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]);
+                allEmittedEvents.push(...events);
+                lastAction = matchingAction;
+                lastActionDef = actionDef;
+                lastArgs = args;
+                const firstEvent = (events[0] || {});
+                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) || actionDef?.terminatesLoop)
+                    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 parsed = parseLLMDecision(llmResponse, actionNames, actions);
+            if (!parsed.ok) {
+                if (repromptedForDecision) {
+                    runtimeLog.error('runTurn', `unparseable decision after reprompt: ${parsed.error}`);
+                    turnError = { source: 'llm', cause: 'unparseable-decision' };
+                    break;
+                }
+                repromptedForDecision = true;
+                runtimeLog.warn('runTurn', `unparseable decision — reprompting once: ${parsed.error}`);
+                messages.push({ role: 'assistant', content: llmResponse.content ?? '' });
+                messages.push({ role: 'user', content: `Your last output was not a valid action: ${parsed.error}. Respond with exactly one action from the schema.` });
+                continue;
+            }
+            const decision = parsed.decision;
+            const chosenAction = decision.action;
+            const actionDef = actions[chosenAction];
+            if (decision.thought)
+                await emitThought(decision.thought);
+            // 2-call streaming: if this is a respond action (has receiverId, no bound tool),
+            // use the streaming effect to generate text and send chunks to the client.
+            // Streaming is a user-delivery optimization (chunks go to a user's socket).
+            // For agent-to-agent replies (e.g. an orchestrator's pool dispatch captured
+            // via ConnectionPool.requestFrom) there is no streaming channel — the chunk
+            // send fails with empty content and, critically, no `send-message` effect is
+            // emitted, so the caller's requestFrom never resolves and times out. Skip
+            // streaming whenever the inbound message came from another agent.
+            const inboundFromAgent = String(incomingEvent?.senderType || '').toUpperCase() === 'AGENT';
+            runtimeLog.info('runTurn', `streaming check: enabled=${streamRespondActions} receiverId=${decision.receiverId ?? 'none'} tool=${actionDef?.tool ?? 'none'} action=${chosenAction} inboundFromAgent=${inboundFromAgent}`);
+            if (streamRespondActions && !inboundFromAgent && decision.receiverId && !actionDef?.tool && chosenAction !== 'wait') {
+                const streamMessageId = crypto.randomUUID();
+                runtimeLog.info('runTurn', `stream-text start action=${chosenAction} receiverId=${decision.receiverId} msgId=${streamMessageId}`);
+                const streamMessages = [
+                    ...messages,
+                    {
+                        role: 'assistant',
+                        content: JSON.stringify({ thought: decision.thought, action: decision.action, receiverId: decision.receiverId }),
+                    },
+                    {
+                        role: 'user',
+                        content: 'Write your reply now. Output ONLY the message text — no JSON wrapping, no preamble.',
+                    },
+                ];
+                let replyText = '';
+                try {
+                    const streamResult = await eff({ kind: 'stream-text', sessionId, receiverId: decision.receiverId, messageId: streamMessageId, messages: streamMessages });
+                    replyText = streamResult.text ?? '';
+                    // Count the streamed reply only when it actually produced the text we
+                    // send (an empty resolve falls through to the llm-call fallback below,
+                    // which counts itself). The streamed reply is a real billed completion
+                    // (call 2 of ZIG-471 2-call streaming) — count it or the largest single
+                    // output of the turn leaks from every usage/cost sink (ZIG-813).
+                    if (replyText) {
+                        llmCallsTotal++;
+                        const su = streamResult.usage;
+                        tokensTotal += (su?.total_tokens ?? su?.totalTokens) || 0;
+                        tokensInput += (su?.prompt_tokens ?? su?.promptTokens) || 0;
+                        tokensOutput += (su?.completion_tokens ?? su?.completionTokens) || 0;
+                        runtimeLog.info('runTurn', `stream-text done chars=${replyText.length} tokens=${(su?.total_tokens ?? su?.totalTokens) || 0}`);
+                    }
+                }
+                catch (err) {
+                    // Streaming transport failed before the reply text existed (call 2
+                    // runs inside the stream-text effect). Fall back to a plain
+                    // llm-call + send-message below so the user still gets a reply.
+                    runtimeLog.error('runTurn', `stream-text failed: ${err.message} — falling back to non-streaming send`);
+                }
+                try {
+                    if (!replyText) {
+                        const fallbackResponse = await effWithTrace({ kind: 'llm-call', messages: streamMessages, tools: [], sessionId });
+                        llmCallsTotal++;
+                        const fu = fallbackResponse?.usage;
+                        tokensTotal += (fu?.total_tokens ?? fu?.totalTokens) || 0;
+                        tokensInput += (fu?.prompt_tokens ?? fu?.promptTokens) || 0;
+                        tokensOutput += (fu?.completion_tokens ?? fu?.completionTokens) || 0;
+                        replyText = (fallbackResponse?.content ?? '').trim();
+                        if (!replyText)
+                            throw new Error('fallback llm-call returned empty reply text');
+                    }
+                    const safeText = truncateMsg(replyText);
+                    // Reuse streamMessageId so any partial chunks already streamed to
+                    // the client reconcile against the final persisted message.
+                    await eff({ kind: 'send-message', sessionId, receiverId: decision.receiverId, text: safeText, messageId: streamMessageId });
+                    allEmittedEvents.push({ type: 'message_sent', receiverId: decision.receiverId, chatId: sessionId, message: safeText, senderId: 'system' });
+                    lastAction = chosenAction;
+                    lastActionDef = actionDef;
+                }
+                catch (err) {
+                    // Both the streaming path AND the non-streaming fallback failed —
+                    // the user got nothing. End the turn with a loud send-failed error.
+                    runtimeLog.error('runTurn', `respond send failed after stream fallback: ${err.message}`);
+                    turnError = { source: 'protocol', cause: 'send-failed' };
+                }
+                break;
+            }
+            let result;
+            try {
+                result = await executeDecision(decision, actionDef, eff, sessionId, memory, null, addToolUsage);
+            }
+            catch (err) {
+                // Only outbound sends can throw out of executeDecision — executeTool
+                // traps its own errors into tool_error events. A throw here means the
+                // message never reached the backend; the turn must end loudly.
+                runtimeLog.error('runTurn', `action "${chosenAction}" send failed: ${err.message}`);
+                turnError = { source: 'protocol', cause: 'send-failed' };
+                break;
+            }
+            if (!result) {
+                // The decision parsed but could not be executed — e.g. a respond
+                // action missing message/receiverId. Same defect class as a parse
+                // failure. Nothing was executed for this decision, so a single
+                // reprompt is safe (no duplicate side effects).
+                if (repromptedForDecision) {
+                    runtimeLog.error('runTurn', `unexecutable decision after reprompt: action "${chosenAction}"`);
+                    turnError = { source: 'llm', cause: 'unparseable-decision' };
+                    break;
+                }
+                repromptedForDecision = true;
+                runtimeLog.warn('runTurn', `unexecutable decision — reprompting once: action "${chosenAction}" missing required fields`);
+                messages.push({ role: 'assistant', content: llmResponse.content ?? '' });
+                messages.push({ role: 'user', content: `Your last output was not a valid action: action "${chosenAction}" was missing required fields (for a message this means both "receiverId" and "message"). Respond with exactly one action from the schema.` });
+                continue;
+            }
+            const events = (Array.isArray(result) ? result : [result]);
+            allEmittedEvents.push(...events);
+            lastAction = chosenAction;
+            lastActionDef = actionDef;
+            lastArgs = decision.args;
+            if (actionDef?.tool) {
+                const firstEvent = (events[0] || {});
+                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;
+        }
+    }
+    if (!turnError) {
+        await echoOptInToolSummaryIfNeeded({
+            allEmittedEvents, eff, sessionId,
+            context: ctxObj, toolManager, incomingEvent,
+        });
+    }
+    const toolResults = [];
+    let outcome = outcomeFromActionResult(lastAction, lastActionDef, lastArgs, allEmittedEvents, toolResults);
+    if (turnError) {
+        // A hard failure at the decision/send boundary outranks whatever partial
+        // (always non-terminal — terminal protocol events break the loop before
+        // the JSON-decision path) events accumulated this turn.
+        outcome = { kind: 'error', source: turnError.source, cause: turnError.cause, retryable: false };
+    }
+    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 extractIncomingMessageText(event) {
+    if (!event)
+        return '';
+    const parts = [];
+    const push = (v) => {
+        if (typeof v === 'string' && v.trim())
+            parts.push(v.trim());
+    };
+    push(event.text);
+    push(event.message);
+    const agreement = event.agreement;
+    if (agreement) {
+        const terms = agreement.terms;
+        push(terms?.description);
+        push(JSON.stringify(agreement));
+    }
+    const task = event.task;
+    if (task)
+        push(JSON.stringify(task));
+    return parts.join('\n');
+}
+function normalizeContextSnapshot(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return { history: [], agreements: [], agents: [], users: [] };
+    }
+    const out = { ...raw };
+    for (const key of ['history', 'agreements', 'agents', 'users']) {
+        if (!Array.isArray(out[key]))
+            out[key] = [];
+    }
+    return out;
+}
+function eventsAreTerminal(events) {
+    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 || {};
+            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));
+            const task = (r.task || (r.taskId ? r : null));
+            // Agreement's own status lives flat as `proposalStatus` (see api-client
+            // Agreement type) — not nested under `.proposal.status`. Check both so
+            // a successful agreement_propose is recognized as terminal instead of
+            // being re-issued by the LLM on the next loop iteration.
+            const agProposal = ag?.proposal;
+            const taskProposal = task?.proposal;
+            const proposalStatus = ag?.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) {
+    return events.some(e => {
+        if (!e || e.type !== 'tool_result')
+            return false;
+        const r = e.result || {};
+        if (r.success === false || r.error)
+            return false;
+        // Support both nested { agreement: {...} } and flat Agreement objects.
+        const ag = (r.agreement ?? (r.agreementId ? r : null));
+        // See eventsAreTerminal above: proposalStatus is flat on Agreement, not nested.
+        const agProposal = ag?.proposal;
+        const task = r.task;
+        const taskProposal = task?.proposal;
+        const proposalStatus = ag?.proposalStatus ?? agProposal?.status ?? taskProposal?.status;
+        return proposalStatus === 'pending' || proposalStatus === 'approved';
+    });
+}
+function annotateToolCallDedup(toolCalls, toolManager, initialSawCreate = false) {
+    let sawCreate = initialSawCreate;
+    const seenUpdateTaskIds = new Set();
+    return (toolCalls || []).map((tc) => {
+        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 = 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, allowedActionNames, actions) {
+    if (llmResponse?.tool_calls?.length) {
+        const tc = llmResponse.tool_calls[0];
+        if (!tc?.function?.name)
+            return { ok: false, error: 'tool call had no function name' };
+        let args = {};
+        try {
+            args = JSON.parse(tc.function.arguments || '{}');
+        }
+        catch { }
+        const matchingAction = findActionForTool(tc.function.name, allowedActionNames, actions);
+        if (!matchingAction)
+            return { ok: false, error: `tool "${tc.function.name}" is not bound to any action in this state` };
+        return { ok: true, decision: { thought: `Using tool: ${tc.function.name}`, action: matchingAction, tool: tc.function.name, args } };
+    }
+    const parsed = safeParseJSON(llmResponse?.content || '', null);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ok: false, error: 'output was not a JSON object' };
+    }
+    if (!parsed['action'] || !allowedActionNames.includes(parsed['action'])) {
+        return { ok: false, error: `missing or unknown "action" — allowed: ${allowedActionNames.join(', ')}` };
+    }
+    return { ok: true, decision: parsed };
+}
+function findActionForTool(toolName, allowedActionNames, actions) {
+    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, actionDef, eff, sessionId, memory, incomingEvent = null, onUsage) {
+    const boundTool = actionDef?.tool || null;
+    if (boundTool) {
+        decision.tool = boundTool;
+        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
+    }
+    if (decision.action === '_genericDiscoveryTool' && decision.tool) {
+        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
+    }
+    if (decision.tool)
+        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
+    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);
+    }
+    // Fallback: LLM may place message/receiverId inside args due to format ambiguity
+    // between prompt.format ("args: { receiverId, message }") and the top-level schema.
+    if (!decision.message && !decision.receiverId && decision.args) {
+        const a = decision.args;
+        if (typeof a.message === 'string' && typeof a.receiverId === 'string') {
+            return await executeSendMessage({ ...decision, message: a.message, receiverId: a.receiverId }, eff, sessionId);
+        }
+    }
+    // An action with no tool and no message that is named "wait" OR statically
+    // declares `produces: 'wait'` (e.g. "pause"/"hold") is an explicit
+    // do-nothing — emit `waited` so the turn ends honestly instead of falling
+    // through to the unexecutable-decision reprompt.
+    if (decision.action === 'wait' || actionDef?.produces === 'wait')
+        return { type: 'waited' };
+    return null;
+}
+function truncateMsg(msg) {
+    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, eff, sessionId) {
+    // Callers (executeDecision) guarantee message + receiverId, and sessionId is
+    // always ctx.identity.sessionId. A send failure throws to the turn loop,
+    // which converts it into the 'send-failed' error outcome — no silent nulls,
+    // and message_sent is only emitted after the send effect resolved.
+    // `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(decision.message);
+    await eff({ kind: 'send-message', sessionId: targetSessionId, receiverId: decision.receiverId, text: safeMessage });
+    const events = [{ type: 'message_sent', receiverId: decision.receiverId, chatId: targetSessionId, message: safeMessage, senderId: 'system' }];
+    if (targetSessionId !== sessionId)
+        events.push({ type: 'report_sent', message: 'Reported to owner.', senderId: 'system' });
+    return events;
+}
+/**
+ * Multi-message send. `message_sent` is emitted ONLY for sends that actually
+ * succeeded. Malformed entries (missing receiverId/message) and transport
+ * failures are collected: if nothing was even attempted the caller sees null
+ * and reprompts (LLM output defect); if every attempted send failed the whole
+ * action throws (→ 'send-failed' error outcome); a partial failure keeps the
+ * successful sends and logs loudly — reprompting after partial execution
+ * would risk duplicate messages.
+ */
+async function executeSendMessages(decision, eff, sessionId) {
+    const events = [];
+    const failures = [];
+    let attempted = 0;
+    for (const msg of decision.messages ?? []) {
+        if (!msg.receiverId || !msg.message) {
+            failures.push({ receiverId: msg.receiverId || '<missing>', error: 'missing receiverId or message' });
+            continue;
+        }
+        const targetSessionId = msg.chatId || sessionId;
+        const safeMessage = truncateMsg(msg.message);
+        attempted++;
+        try {
+            await eff({ kind: 'send-message', sessionId: targetSessionId, receiverId: msg.receiverId, text: safeMessage });
+        }
+        catch (err) {
+            // Scenario: backend rejected or transport dropped this one send. Record
+            // it and keep going — remaining recipients must still get their message.
+            failures.push({ receiverId: msg.receiverId, error: err.message });
+            continue;
+        }
+        events.push({ type: 'message_sent', receiverId: msg.receiverId, chatId: targetSessionId, message: safeMessage, senderId: 'system' });
+        if (targetSessionId !== sessionId)
+            events.push({ type: 'report_sent', message: 'Reported to owner.', senderId: 'system' });
+    }
+    if (attempted === 0)
+        return null; // every entry malformed — LLM output defect, caller reprompts
+    if (events.length === 0) {
+        throw new Error(`all ${failures.length} send(s) failed: ${failures.map(f => `${f.receiverId}: ${f.error}`).join('; ')}`);
+    }
+    if (failures.length > 0) {
+        runtimeLog.error('runTurn', `partial send failure (${failures.length} of ${(decision.messages ?? []).length} entries): ${failures.map(f => `${f.receiverId}: ${f.error}`).join('; ')}`);
+    }
+    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, eff, sessionId, memory, incomingEvent = null, onUsage) {
+    const { tool, args } = decision;
+    if (!tool)
+        return null;
+    try {
+        const r = await eff({
+            kind: 'tool-call',
+            sessionId,
+            name: tool,
+            args: args || {},
+            memory,
+            senderId: incomingEvent?.senderId != null ? String(incomingEvent.senderId) : undefined,
+            senderType: incomingEvent?.senderType != null ? String(incomingEvent.senderType) : undefined,
+            // ZIG-831: the subcontract agreement this wake is under (task events carry
+            // it under `result.agreementId`) so a delegated per-user MCP call can
+            // resolve the originating end-user, not the delegating agent (senderId).
+            onBehalfOfAgreementId: (() => {
+                const aid = incomingEvent?.result?.agreementId;
+                return typeof aid === 'string' && aid ? aid : undefined;
+            })(),
+        });
+        if (r.usage)
+            onUsage?.(r.usage);
+        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.length > 0)
+            return r.events;
+        return { type: 'tool_result', tool, result: r.result, senderId: 'system' };
+    }
+    catch (error) {
+        return { type: 'tool_error', tool, error: error?.message ?? String(error), senderId: 'system' };
+    }
+}
+function shouldEchoToolSummaryToUser(result) {
+    if (!result || typeof result !== 'object')
+        return false;
+    const r = result;
+    if (typeof r.message !== 'string' || !r.message.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 }) {
+    if (!eff || !sessionId || !context || !toolManager?.getTool)
+        return;
+    if (allEmittedEvents.some((e) => e?.type === 'message_sent'))
+        return;
+    let summary = 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.message;
+    }
+    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 = { type: 'message_sent', receiverId, chatId: sessionId, message: safe, senderId: 'system' };
+    if (wasTruncated) {
+        event['truncated'] = true;
+        event['originalLength'] = summary.length;
+    }
+    allEmittedEvents.push(event);
+}
+function pickReceiverForEcho(context, incomingEvent) {
+    const senderId = incomingEvent?.senderId;
+    const senderType = String(incomingEvent?.senderType || '').toUpperCase();
+    if (senderId && senderType === 'USER')
+        return String(senderId);
+    return pickPrimaryUserIdFromContext(context);
+}
+function pickPrimaryUserIdFromContext(context) {
+    const users = context?.users || [];
+    for (const u of users) {
+        const id = (u?.userId || u?.id);
+        if (id && typeof id === 'string')
+            return id;
+    }
+    const hist = context?.history || [];
+    for (let i = hist.length - 1; i >= 0; i--) {
+        const row = hist[i];
+        const sender = row?.sender;
+        const type = String(sender?.type || row?.senderType || '').toUpperCase();
+        const id = (sender?.id ?? row?.senderId);
+        if (type === 'USER' && id)
+            return id;
+    }
+    return null;
+}