@ziggs-ai/agent-sdk 0.1.10 → 0.1.11

package/src/runtime/runTurn.ts

@@ -169,6 +169,14 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
   // 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}`);
@@ -294,8 +302,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 +323,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 +345,107 @@ 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 ?? '';
+          runtimeLog.info('runTurn', `stream-text done chars=${replyText.length}`);
         } 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);
+      } 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 +570,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 {
@@ -552,7 +638,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 +652,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;
 }
 

package/src/runtime/validateWorkflow.ts

@@ -1,20 +1,22 @@
-import type { Ctx, OutcomeKind, Workflow, ThinkingState } from '../types.js';
+import type { Ctx, OutcomeKind, Workflow, ThinkingState, ParkedState } from '../types.js';
 
-const PROBE_CTX: Ctx = {
+export const PROBE_CTX: Ctx = {
   identity: { agentId: '', sessionId: '', laneKey: '' },
   activeAgreementId: null,
   activeTaskId: null,
   pendingProposalAgreementId: null,
   delegatedAgreementIds: [],
-  delegatedTaskIds: [],
+  pendingSubtasks: {},
+  collectedResults: [],
   toolResults: [],
   lastOutcome: { kind: 'enter' },
 };
 
+// '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',
@@ -85,12 +87,29 @@ 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 (!Array.isArray(state.transitions)) {
@@ -126,7 +145,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);

package/src/server/StateTimers.ts

@@ -0,0 +1,85 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+export interface StateTimeoutEvent {
+  type: 'state-timeout';
+  state: string;
+  waitedMs: number;
+  epoch: number;
+}
+
+interface ArmedTimer {
+  epoch: number;
+  state: string;
+  timeoutMs: number;
+  armedAt: number;
+  handle: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Per-lane liveness timers for parked states declaring timeoutMs. Owned by
+ * AgentHost. A firing timer enqueues a state-timeout frame on the SAME lane
+ * (caller-provided enqueue → EventQueue), so it serializes behind any real
+ * event and can never race one. Epochs make stale frames identifiable: a
+ * queued timeout frame whose epoch is not the lane's currently-armed epoch was
+ * superseded (a tick ran after it fired) and must be dropped.
+ *
+ * In-memory only: process restart loses all timers; each lane re-arms on its
+ * next real event (sessionStore persists { ctx, state } but not timers).
+ */
+export class StateTimers {
+  private _timers = new Map<string, ArmedTimer>();
+  private _epoch = 0;
+  private _enqueue: (event: StateTimeoutEvent, laneKey: string) => void;
+
+  constructor(enqueue: (event: StateTimeoutEvent, laneKey: string) => void) {
+    this._enqueue = enqueue;
+  }
+
+  /** Re-arm is idempotent: any previously armed timer for the lane is cancelled first. */
+  arm(laneKey: string, state: string, timeoutMs: number): void {
+    this.clear(laneKey);
+    const epoch = ++this._epoch;
+    const handle = setTimeout(() => {
+      runtimeLog.debug('StateTimers', `fired laneKey=${laneKey} state=${state} waitedMs=${timeoutMs} epoch=${epoch}`);
+      this._enqueue({ type: 'state-timeout', state, waitedMs: timeoutMs, epoch }, laneKey);
+    }, timeoutMs);
+    (handle as unknown as { unref?: () => void }).unref?.();
+    this._timers.set(laneKey, { epoch, state, timeoutMs, armedAt: Date.now(), handle });
+  }
+
+  clear(laneKey: string): void {
+    const t = this._timers.get(laneKey);
+    if (!t) return;
+    clearTimeout(t.handle);
+    this._timers.delete(laneKey);
+  }
+
+  clearAll(): void {
+    for (const key of [...this._timers.keys()]) this.clear(key);
+  }
+
+  /**
+   * Drop stale state-timeout events from an incoming frame (single event or an
+   * EventQueue-coalesced { type: 'batch', events } frame). Returns null when
+   * nothing survives (pure stale-timeout frame — the lane's live timer, if any,
+   * must be left untouched by the caller in that case).
+   */
+  stripStale(event: unknown, laneKey: string): unknown | null {
+    const pending = this._timers.get(laneKey);
+    const fresh = (ev: unknown): boolean => {
+      const e = ev as { type?: string; epoch?: number };
+      if (e?.type !== 'state-timeout') return true;
+      const ok = pending !== undefined && e.epoch === pending.epoch;
+      if (!ok) runtimeLog.debug('StateTimers', `dropping stale state-timeout laneKey=${laneKey} epoch=${e.epoch} armed=${pending?.epoch ?? 'none'}`);
+      return ok;
+    };
+    const b = event as { type?: string; events?: unknown[] };
+    if (b?.type === 'batch' && Array.isArray(b.events)) {
+      const kept = b.events.filter(fresh);
+      if (kept.length === 0) return null;
+      if (kept.length === b.events.length) return event;
+      return kept.length === 1 ? kept[0] : { type: 'batch', events: kept };
+    }
+    return fresh(event) ? event : null;
+  }
+}

package/src/server/ZiggsEffectHandler.ts

@@ -280,7 +280,16 @@ export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
         let text = '';
         if (deps.llm.chatMessagesStream) {
           text = await deps.llm.chatMessagesStream(messages as LlmMessage[], (chunk) => {
-            deps.chunkSender?.(sessionId, receiverId, chunk, messageId);
+            // Live-stream display is best-effort. The transport's send rejects
+            // empty/whitespace-only content (WebSocketClient: content.trim() === ''),
+            // and a whitespace-only chunk (e.g. a leading newline) is truthy yet
+            // still throws — which, uncaught, aborts the whole stream and loses the
+            // entire reply (e.g. a composer's final synthesis). Swallow chunk-send
+            // failures; `text` accumulates independently and the final send-message
+            // (below, in runTurn) carries the full reply regardless.
+            try {
+              if (chunk && chunk.trim()) deps.chunkSender?.(sessionId, receiverId, chunk, messageId);
+            } catch { /* ignore — streaming display only */ }
           });
         } else {
           const r = await deps.llm.chatMessages(messages as LlmMessage[]);

package/src/server/tasks/TaskService.ts

@@ -1,6 +1,6 @@
 import {
   createTask, getTask, getActiveTasksForAgent, getActiveTasksForChat, getSubtasks,
-  updateTaskState, cancelTask,
+  updateTaskState, updateTaskPlanStep, cancelTask,
   reportTask, setTaskSatisfaction, countTasks,
   type Creds, type Task, type TaskState,
 } from '@ziggs-ai/api-client';
@@ -50,7 +50,7 @@ export class TaskService {
     return getSubtasks(parentTaskId, this.creds);
   }
 
-  async spawnUnderAgreement(agreementId: string, taskData: { description: string; parentTaskId?: string; plan?: unknown; planReviewTiming?: string; requireMidWorkPlanAck?: boolean; assigneeId?: string }): Promise<Task> {
+  async spawnUnderAgreement(agreementId: string, taskData: { description: string; parentTaskId?: string; plan?: unknown; planReviewTiming?: string; requireMidWorkPlanAck?: boolean; assigneeId?: string; inputArtifactIds?: string[] }): Promise<Task> {
     if (!agreementId) throw new Error('TaskService.spawnUnderAgreement: agreementId is required');
     try {
       const result = await createTask({ ...taskData, agreementId } as Parameters<typeof createTask>[0], this.creds);
@@ -74,6 +74,17 @@ export class TaskService {
     }
   }
 
+  async updatePlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<Task> {
+    try {
+      const updated = await updateTaskPlanStep(taskId, stepId, status, result, this.creds);
+      runtimeLog.info('TaskService', `Task plan step: ${taskId}/${stepId} → ${status}`);
+      return updated;
+    } catch (error) {
+      runtimeLog.error('TaskService', `Task plan step update failed: ${(error as Error).message}`);
+      throw error;
+    }
+  }
+
   async cancel(taskId: string): Promise<Task> {
     try {
       const updated = await cancelTask(taskId, this.creds);

package/src/server/tools/tier1/protocolRunner.ts

@@ -32,6 +32,7 @@ interface ProtocolPayload {
   parentAgreementId?: string;
   parentTaskId?: string;
   taskId?: string;
+  stepId?: string;
   assigneeId?: string;
   status?: string;
   result?: unknown;
@@ -97,12 +98,20 @@ export async function dispatchProtocolOp(
         planReviewTiming: payload.planReviewTiming,
         requireMidWorkPlanAck: payload.requireMidWorkPlanAck,
         assigneeId: payload.assigneeId,
+        inputArtifactIds: Array.isArray(payload.inputArtifactIds)
+          ? (payload.inputArtifactIds as string[])
+          : undefined,
       });
     case 'task-update':
       if (!payload.taskId || !payload.status) return null;
       return taskService.updateState(payload.taskId, normalizeState(payload.status) as Parameters<typeof taskService.updateState>[1], payload.result);
+    case 'task-update-plan-step':
+      if (!payload.taskId) throw new Error('task-update-plan-step requires `taskId`');
+      if (!payload.stepId) throw new Error('task-update-plan-step requires `stepId`');
+      if (!payload.status) throw new Error('task-update-plan-step requires `status`');
+      return taskService.updatePlanStep(payload.taskId, payload.stepId, payload.status, payload.result);
     default:
-      return null;
+      throw new Error(`Unknown protocol operation: ${operation}`);
   }
 }