@ziggs-ai/agent-sdk 0.1.10 → 0.1.12

package/src/runtime/runTurn.ts

@@ -68,7 +68,14 @@ interface RunTurnInput {
    */
   memory?: MemoryStore;
   definition: { description?: string };
-  /** When true, respond actions use 2-call streaming: Call 1 picks action+receiverId, Call 2 streams the text (ZIG-471). */
+  /**
+   * Respond actions use 2-call streaming: Call 1 picks action+receiverId,
+   * Call 2 streams the text (ZIG-471). On by default (ZIG-838); pass false
+   * (or set ENABLE_LLM_STREAMING=false) to fold the reply text back into the
+   * single decision call. The env flag is a deployment kill-switch — the
+   * streaming path once broke long replies in production, so ops keeps a way
+   * to disable it without a code change.
+   */
   streamRespondActions?: boolean;
 }
 
@@ -97,7 +104,10 @@ interface RunTurnResult {
  */
 export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
   const { stateId, statePrompt, actions, incomingEvent, ctx, eff, toolManager, promptBuilder, memory, definition } = input;
-  const streamRespondActions = input.streamRespondActions ?? (process.env.ENABLE_LLM_STREAMING === 'true');
+  // 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();
 
@@ -143,6 +153,22 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
   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 as Record<string, unknown>, tools: tools as unknown as Record<string, unknown>[] },
@@ -165,10 +191,27 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
   let lastArgs: unknown = 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: LlmResponse['usage']): void => {
+    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: { source: 'llm' | 'protocol'; cause: 'send-failed' | 'unparseable-decision' } | null = 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}`);
@@ -257,7 +300,7 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
         try { args = JSON.parse(tc.function.arguments || '{}'); } catch {}
         const decision = { action: matchingAction, tool: toolName, args };
 
-        const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory);
+        const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, null, addToolUsage);
         toolCallResults.push({ tc, matchingAction, result, args, actionDef });
       }
 
@@ -294,8 +337,20 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
 
     } else {
       // — non-tool (JSON) response path —
-      const decision = parseLLMDecision(llmResponse, actionNames, actions);
-      if (!decision) break;
+      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];
 
@@ -303,8 +358,15 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
 
       // 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.
-      runtimeLog.info('runTurn', `streaming check: enabled=${streamRespondActions} receiverId=${decision.receiverId ?? 'none'} tool=${actionDef?.tool ?? 'none'} action=${chosenAction}`);
-      if (streamRespondActions && decision.receiverId && !actionDef?.tool && chosenAction !== 'wait') {
+      // 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: LlmMessage[] = [
@@ -318,56 +380,119 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
             content: 'Write your reply now. Output ONLY the message text — no JSON wrapping, no preamble.',
           },
         ];
-        let streamedText = '';
+        let replyText = '';
         try {
           const streamResult = await eff({ kind: 'stream-text', sessionId, receiverId: decision.receiverId, messageId: streamMessageId, messages: streamMessages });
-          streamedText = streamResult.text ?? '';
-          runtimeLog.info('runTurn', `stream-text done chars=${streamedText.length}`);
+          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) {
-          runtimeLog.warn('runTurn', `stream-text failed: ${(err as Error).message}`);
+          // 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 as Error).message} — falling back to non-streaming send`);
         }
-        if (streamedText) {
-          const safeText = truncateMsg(streamedText);
+        try {
+          if (!replyText) {
+            const fallbackResponse: LlmResponse = 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 });
-          const events: EmittedEvent[] = [{ type: 'message_sent', receiverId: decision.receiverId, chatId: sessionId, message: safeText, senderId: 'system' }];
-          allEmittedEvents.push(...events);
+          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 as Error).message}`);
+          turnError = { source: 'protocol', cause: 'send-failed' };
         }
         break;
       }
 
-      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;
+      let result: EmittedEvent[] | EmittedEvent | null;
+      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 as Error).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]) 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,
-  });
+  if (!turnError) {
+    await echoOptInToolSummaryIfNeeded({
+      allEmittedEvents, eff, sessionId,
+      context: ctxObj, toolManager, incomingEvent,
+    });
+  }
 
   const toolResults: ToolResultEntry[] = [];
-  const outcome = outcomeFromActionResult(lastAction, lastActionDef, lastArgs, allEmittedEvents, toolResults);
+  let outcome: 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}`);
 
@@ -492,21 +617,29 @@ function annotateToolCallDedup(
   });
 }
 
-function parseLLMDecision(llmResponse: LlmResponse, allowedActionNames: string[], actions: Record<string, Action>): ParsedDecision | null {
+type DecisionParse =
+  | { ok: true; decision: ParsedDecision }
+  | { ok: false; error: string };
+
+function parseLLMDecision(llmResponse: LlmResponse, allowedActionNames: string[], actions: Record<string, Action>): DecisionParse {
   if (llmResponse?.tool_calls?.length) {
     const tc = llmResponse.tool_calls[0];
-    if (!tc?.function?.name) return null;
+    if (!tc?.function?.name) return { ok: false, error: 'tool call had no function name' };
     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 };
+    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) 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;
+  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'] as string)) {
+    return { ok: false, error: `missing or unknown "action" — allowed: ${allowedActionNames.join(', ')}` };
+  }
+  return { ok: true, decision: parsed as unknown as ParsedDecision };
 }
 
 function findActionForTool(toolName: string, allowedActionNames: string[], actions: Record<string, Action>): string | null {
@@ -527,17 +660,18 @@ async function executeDecision(
   sessionId: string,
   memory?: MemoryStore,
   incomingEvent: RawEvent | null = null,
+  onUsage?: (usage: LlmResponse['usage']) => void,
 ): Promise<EmittedEvent[] | EmittedEvent | null> {
   const boundTool = actionDef?.tool || null;
 
   if (boundTool) {
     decision.tool = boundTool;
-    return await executeTool(decision, eff, sessionId, memory, incomingEvent);
+    return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
   }
   if (decision.action === '_genericDiscoveryTool' && decision.tool) {
-    return await executeTool(decision, eff, sessionId, memory, incomingEvent);
+    return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
   }
-  if (decision.tool) return await executeTool(decision, eff, sessionId, memory, incomingEvent);
+  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);
   }
@@ -552,7 +686,11 @@ async function executeDecision(
       return await executeSendMessage({ ...decision, message: a.message, receiverId: a.receiverId }, eff, sessionId);
     }
   }
-  if (decision.action === 'wait') return { type: 'waited' };
+  // 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;
 }
 
@@ -562,34 +700,61 @@ function truncateMsg(msg: unknown): string {
   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;
+async function executeSendMessage(decision: ParsedDecision, eff: EffectHandler, sessionId: string): Promise<EmittedEvent[]> {
+  // 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(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' }];
+  const safeMessage = truncateMsg(decision.message);
+  await eff({ kind: 'send-message', sessionId: targetSessionId, receiverId: decision.receiverId!, text: safeMessage });
+  const events: EmittedEvent[] = [{ 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;
 }
 
-async function executeSendMessages(decision: ParsedDecision, eff: EffectHandler, sessionId: string | null): Promise<EmittedEvent[]> {
+/**
+ * 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: ParsedDecision, eff: EffectHandler, sessionId: string): Promise<EmittedEvent[] | null> {
   const events: EmittedEvent[] = [];
+  const failures: Array<{ receiverId: string; error: string }> = [];
+  let attempted = 0;
   for (const msg of decision.messages ?? []) {
-    if (!msg.receiverId || !msg.message) continue;
+    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);
-    if (targetSessionId) {
-      try { await eff({ kind: 'send-message', sessionId: targetSessionId, receiverId: msg.receiverId, text: safeMessage }); } catch { continue; }
+    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 as Error).message });
+      continue;
     }
-    events.push({ type: 'message_sent', receiverId: msg.receiverId, chatId: targetSessionId ?? undefined, message: safeMessage, senderId: 'system' });
+    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' } as unknown as EmittedEvent);
   }
+  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;
 }
 
@@ -605,6 +770,7 @@ async function executeTool(
   sessionId: string,
   memory?: MemoryStore,
   incomingEvent: RawEvent | null = null,
+  onUsage?: (usage: LlmResponse['usage']) => void,
 ): Promise<EmittedEvent[] | EmittedEvent | null> {
   const { tool, args } = decision;
   if (!tool) return null;
@@ -617,7 +783,15 @@ async function executeTool(
       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 as { agreementId?: unknown } | undefined)?.agreementId;
+        return typeof aid === 'string' && aid ? aid : undefined;
+      })(),
     }) as ToolCallResult;
+    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.

package/src/runtime/validateWorkflow.ts

@@ -1,20 +1,14 @@
-import type { Ctx, OutcomeKind, Workflow, ThinkingState } from '../types.js';
+import type { Ctx, OutcomeKind, Workflow, ThinkingState, ParkedState, MechanicalState } from '../types.js';
+import { bootstrapCtx } from './bootstrapCtx.js';
 
-const PROBE_CTX: Ctx = {
-  identity: { agentId: '', sessionId: '', laneKey: '' },
-  activeAgreementId: null,
-  activeTaskId: null,
-  pendingProposalAgreementId: null,
-  delegatedAgreementIds: [],
-  delegatedTaskIds: [],
-  toolResults: [],
-  lastOutcome: { kind: 'enter' },
-};
+/** Static probe ctx for evaluating transition `when` guards during validation. */
+export const PROBE_CTX: Ctx = bootstrapCtx({ agentId: '', sessionId: '', laneKey: '' });
 
+// 'state-timeout' is intentionally absent: it is a runtime-generated liveness
+// outcome, never something an action's `produces` may declare.
 const KNOWN_OUTCOME_KINDS = new Set<OutcomeKind>([
   'enter',
   'wait',
-  'timeout',
   'message-sent',
   'message-received',
   'task-assigned',
@@ -72,8 +66,8 @@ export function validateWorkflow(workflow: Workflow): ValidationResult {
       errors.push(`state "${name}" is not an object`);
       continue;
     }
-    if (state.kind !== 'parked' && state.kind !== 'thinking') {
-      errors.push(`state "${name}" must declare kind: 'parked' | 'thinking'`);
+    if (state.kind !== 'parked' && state.kind !== 'thinking' && state.kind !== 'mechanical') {
+      errors.push(`state "${name}" must declare kind: 'parked' | 'thinking' | 'mechanical'`);
       continue;
     }
 
@@ -85,12 +79,56 @@ export function validateWorkflow(workflow: Workflow): ValidationResult {
       if ((state as unknown as ThinkingState).actions) {
         errors.push(`state "${name}" is parked but has actions — parked states are event-driven only`);
       }
+      const tm = (state as ParkedState).timeoutMs;
+      if (tm !== undefined && (typeof tm !== 'number' || !Number.isFinite(tm) || tm <= 0)) {
+        errors.push(`state "${name}" timeoutMs must be a finite number > 0 (got ${String(tm)})`);
+      }
+      if (typeof tm === 'number' && Number.isFinite(tm) && tm > 0) {
+        const handled = state.transitions.some(t => {
+          if (!t.when) return true;
+          try { return t.when({ kind: 'state-timeout', state: name, waitedMs: tm }, PROBE_CTX); }
+          catch { return false; }
+        });
+        if (!handled) {
+          warnings.push(`parked state "${name}" declares timeoutMs=${tm} but no transition matches { kind: 'state-timeout' } — the timeout will park loudly (runtimeLog.error) instead of routing to a recovery state.`);
+        }
+      }
     }
     if (state.kind === 'thinking') {
       if (!state.prompt) errors.push(`thinking state "${name}" requires a prompt`);
       if (!state.actions || Object.keys(state.actions).length === 0) {
         errors.push(`thinking state "${name}" requires at least one action`);
       }
+      if ((state as unknown as ParkedState).timeoutMs !== undefined) {
+        errors.push(`state "${name}" is thinking but declares timeoutMs — liveness timers apply to parked states only (thinking turns are bounded by AgentHost tickTimeoutMs)`);
+      }
+    }
+    if (state.kind === 'mechanical') {
+      const mech = state as MechanicalState;
+      if (!mech.tool || typeof mech.tool !== 'string') {
+        errors.push(`mechanical state "${name}" requires a tool name`);
+      }
+      if (mech.buildArgs !== undefined && typeof mech.buildArgs !== 'function') {
+        errors.push(`mechanical state "${name}" buildArgs must be a function`);
+      }
+      if ((mech as unknown as ThinkingState).prompt) {
+        errors.push(`state "${name}" is mechanical but has a prompt — use kind: 'thinking' instead`);
+      }
+      if ((mech as unknown as ThinkingState).actions) {
+        errors.push(`state "${name}" is mechanical but has actions — use kind: 'thinking' instead`);
+      }
+      const p = mech.produces;
+      if (p === 'state-timeout') {
+        errors.push(`mechanical state "${name}" produces "state-timeout" — reserved for runtime liveness timers`);
+      } else if (typeof p === 'string') {
+        if (!KNOWN_OUTCOME_KINDS.has(p as OutcomeKind)) {
+          errors.push(
+            `mechanical state "${name}" produces unknown outcome kind "${p}" — use one of: ${[...KNOWN_OUTCOME_KINDS].join(', ')}`,
+          );
+        }
+      } else if (typeof p !== 'function') {
+        errors.push(`mechanical state "${name}" requires produces (OutcomeKind or fn)`);
+      }
     }
 
     if (!Array.isArray(state.transitions)) {
@@ -126,7 +164,9 @@ export function validateWorkflow(workflow: Workflow): ValidationResult {
           errors.push(`state "${name}" action "${actionName}" requires prompt.instruction`);
         }
         const p = action.produces;
-        if (typeof p === 'string') {
+        if (p === 'state-timeout') {
+          errors.push(`state "${name}" action "${actionName}" produces "state-timeout" — reserved for runtime liveness timers; actions cannot produce it`);
+        } else if (typeof p === 'string') {
           if (!KNOWN_OUTCOME_KINDS.has(p as OutcomeKind)) {
             errors.push(
               `state "${name}" action "${actionName}" produces unknown outcome kind "${p}" — use one of: ${[...KNOWN_OUTCOME_KINDS].join(', ')}`,

package/src/server/ConnectionPool.ts

@@ -47,6 +47,8 @@ export interface ControlOptions {
 export class ConnectionPool {
   private readonly manager: ConnectionManager;
   private readonly configs = new Map<string, AgentHostOptions>();
+  // Listeners enqueued by requestFrom — drained on outbound send-message effects.
+  private readonly responseListeners = new Map<string, Array<(text: string) => void>>();
 
   constructor({ maxActive = 50, idleTimeoutMs = 60_000 }: PoolOptions = {}) {
     this.manager = new ConnectionManager({ maxActive, idleTimeoutMs });
@@ -72,7 +74,19 @@ export class ConnectionPool {
       this.manager.register(
         agentId,
         async () => {
-          const host = new AgentHost(this.configs.get(agentId)!);
+          const cfg = this.configs.get(agentId)!;
+          const originalTap = cfg.effectTap;
+          const pool = this;
+          const host = new AgentHost({
+            ...cfg,
+            effectTap(effect, response) {
+              if (effect.kind === 'send-message') {
+                const listeners = pool.responseListeners.get(agentId);
+                if (listeners?.length) listeners.shift()!(effect.text ?? '');
+              }
+              originalTap?.(effect, response);
+            },
+          });
           await host.connectAsync();
           runtimeLog.debug(
             'ConnectionPool',
@@ -101,14 +115,51 @@ export class ConnectionPool {
     return this.manager.sleepAll();
   }
 
+  /**
+   * Wake the named agent, deliver a message, and wait for its first outbound
+   * `send-message` effect — i.e. the agent's reply. Returns the reply text.
+   *
+   * The effectTap injected in `register` drains a per-agent listener queue;
+   * this method enqueues one resolver and awaits it. Times out if the agent
+   * does not reply within `timeoutMs` (default 60 s for LLM agents).
+   */
+  async requestFrom(agentId: string, text: string, metadata: Record<string, unknown> = {}, { timeoutMs = 60_000 }: SendToOptions = {}): Promise<string> {
+    const host = await this.wake(agentId);
+    return new Promise<string>((resolve, reject) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        const ls = this.responseListeners.get(agentId);
+        if (ls) { const i = ls.indexOf(listener); if (i !== -1) ls.splice(i, 1); }
+        reject(new Error(`requestFrom timeout for "${agentId}" after ${timeoutMs}ms`));
+      }, timeoutMs);
+      const listener = (responseText: string) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(responseText);
+      };
+      const ls = this.responseListeners.get(agentId) ?? [];
+      ls.push(listener);
+      this.responseListeners.set(agentId, ls);
+      host.handleMessage(text, metadata).catch((err: unknown) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        const ls2 = this.responseListeners.get(agentId);
+        if (ls2) { const i = ls2.indexOf(listener); if (i !== -1) ls2.splice(i, 1); }
+        reject(err);
+      });
+    });
+  }
+
   /**
    * Wake the named agent and deliver one wire frame to it. Returns once the
    * host has finished processing.
    *
-   * Note: does not return the agent's response. Capturing responses
-   * synchronously required internal-buffer poking the Agent/Server split
-   * removed. For request/response semantics, run the agent under an
-   * AgentHost with an injected EffectHandler that records sends.
+   * Note: does not return the agent's response. For request/response
+   * semantics use `requestFrom`.
    */
   async sendTo(agentId: string, text: string, metadata: Record<string, unknown> = {}, { timeoutMs = 30_000 }: SendToOptions = {}): Promise<null> {
     const host = await this.wake(agentId);