@ziggs-ai/agent-sdk 0.1.4 → 0.1.5

package/src/runtime/AgentMachine.ts

@@ -12,6 +12,12 @@ export interface MachineSnapshot {
   status: 'active' | 'stopped';
 }
 
+export type TransitionEvent =
+  | { kind: 'transition'; fromState: string; toState: string; outcomeKind: string; depth: number }
+  | { kind: 'no-match'; state: string; outcomeKind: string; depth: number }
+  | { kind: 'depth-guard'; state: string; depth: number }
+  | { kind: 'error-escape'; fromState: string; toState: string };
+
 interface MachineInput {
   identity: Identity;
   /** Server-provided ctx for an existing session. If omitted, a fresh ctx is built. */
@@ -31,6 +37,8 @@ interface MachineOptions {
   /** Agent-private long-term memory. Operator-provided. */
   memory?: MemoryStore;
   input: MachineInput;
+  /** Optional tap for FSM transition events — called synchronously on each transition. */
+  transitionTap?: (event: TransitionEvent) => void;
 }
 
 interface IncomingFrame {
@@ -69,17 +77,20 @@ export class AgentMachine {
   _draining = false;
   _llmCalls = 0;
   _tokens = { total: 0, input: 0, output: 0 };
+  _lastUserSenderId: string | null = null;
+  _transitionTap: ((event: TransitionEvent) => void) | undefined;
 
   get llmCalls(): number { return this._llmCalls; }
   get tokens(): { total: number; input: number; output: number } { return this._tokens; }
 
-  constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input }: MachineOptions) {
+  constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap }: MachineOptions) {
     this.workflow = workflow;
     this.executionCore = executionCore;
     this.eff = eff;
     this.toolManager = toolManager;
     this.promptBuilder = promptBuilder;
     this.memory = memory;
+    this._transitionTap = transitionTap;
     this.state = input.state || workflow.initial;
     this.ctx = input.ctx
       ? { ...input.ctx, identity: input.identity }
@@ -143,6 +154,9 @@ export class AgentMachine {
 
     const ev = frame.event;
     this._lastIncomingEvent = ev ?? null;
+    if (ev?.senderId && String(ev?.senderType ?? '').toUpperCase() === 'USER') {
+      this._lastUserSenderId = String(ev.senderId);
+    }
     runtimeLog.debug(
       'FSM',
       `_handleFrame ev.type=${ev?.type} ev.senderId=${ev?.senderId} ev.receiverId=${ev?.receiverId} myId=${this.ctx.identity?.agentId}`,
@@ -180,6 +194,7 @@ export class AgentMachine {
       `_step from=${fromState} outcome.kind=${o?.kind} senderId=${o?.senderId ?? '<none>'} myId=${this.ctx.identity?.agentId ?? '<none>'} → target=${target ?? '(stay)'} depth=${depth}`,
     );
     if (target && target !== this.state) {
+      this._transitionTap?.({ kind: 'transition', fromState, toState: target, outcomeKind: (outcome as Record<string, unknown>).kind as string, depth });
       this.state = target;
       this._notify();
     }
@@ -193,6 +208,26 @@ export class AgentMachine {
       return;
     }
 
+    // A thinking turn that yields an outcome no transition handles must not
+    // silently re-enter the same state and burn another LLM call (ZIG-303).
+    // Explicit self-loops still match (target is non-null, even if target === state).
+    if (
+      sd.kind === 'thinking' &&
+      depth > 0 &&
+      fromState === this.state &&
+      !target
+    ) {
+      if (this._escapeToInitialParked(outcome, fromState)) return;
+      runtimeLog.warn(
+        'AgentMachine',
+        `state=${fromState} outcome.kind=${(outcome as Record<string, unknown>).kind} matched no transition; parking (depth=${depth})`,
+      );
+      this._transitionTap?.({ kind: 'no-match', state: fromState, outcomeKind: (outcome as Record<string, unknown>).kind as string, depth });
+      await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+      this._notify();
+      return;
+    }
+
     // Recursion / runaway-turn guard. Without this, a thinking state whose
     // transitions don't match the turn outcome (e.g. `delegating` not
     // catching `tool-result` from an agent_network search) re-enters the
@@ -207,6 +242,8 @@ export class AgentMachine {
         'AgentMachine',
         `state=${this.state} runaway turn loop (depth=${depth}); parking`,
       );
+      this._transitionTap?.({ kind: 'depth-guard', state: this.state, depth });
+      await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
       this._notify();
       return;
     }
@@ -219,7 +256,7 @@ export class AgentMachine {
         stateId: this.state,
         statePrompt: sd.prompt,
         actions: sd.actions,
-        incomingEvent: this.ctx.lastOutcome ? this._lastIncomingEvent : null,
+        incomingEvent: this._lastIncomingEvent,
         ctx: this.ctx,
         eff: this.eff,
         toolManager: this.toolManager,
@@ -255,10 +292,39 @@ export class AgentMachine {
       if (fallback && fallback !== this.state) {
         this.state = fallback;
         this._notify();
+      } else {
+        await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
       }
     }
   }
 
+  /** Error with no author-defined escape: park at workflow.initial if it is parked. */
+  _escapeToInitialParked(outcome: Outcome, fromState: string): boolean {
+    if (outcome.kind !== 'error') return false;
+    const initial = this.workflow.initial;
+    const initialSd = this.workflow.states[initial];
+    if (!initialSd || initialSd.kind !== 'parked' || initial === fromState) {
+      return false;
+    }
+    runtimeLog.warn(
+      'AgentMachine',
+      `state=${fromState} error outcome had no transition — escaped to parked initial "${initial}"`,
+    );
+    this._transitionTap?.({ kind: 'error-escape', fromState, toState: initial });
+    this.state = initial;
+    this._notify();
+    return true;
+  }
+
+  /** Sends a short fallback to the last known human user when the machine parks unexpectedly. Best-effort — never throws. */
+  async _sendFallbackIfUserWaiting(text: string): Promise<void> {
+    const userId = this._lastUserSenderId;
+    if (!userId) return;
+    try {
+      await this.eff({ kind: 'send-message', sessionId: this.ctx.identity.sessionId, receiverId: userId, text });
+    } catch { /* best-effort */ }
+  }
+
   _evaluateTransitions(outcome: Outcome): string | null {
     const sd = this.workflow.states[this.state];
     if (!sd?.transitions?.length) {

package/src/runtime/PromptBuilder.ts

@@ -33,6 +33,8 @@ interface BuildArgs {
   chatId: string | null;
   stateId: string;
   ctx: Ctx;
+  /** When true, respond-action schemas omit the "message" field — used for 2-call streaming (ZIG-471). */
+  omitMessageFromRespond?: boolean;
 }
 
 interface HistoryFormatterI { format(history: unknown[] | null | undefined, agentId: string, options?: AnyObj): string; }
@@ -74,7 +76,7 @@ export class PromptBuilder {
   }
 
   buildFromState(args: BuildArgs): string {
-    const { statePrompt, actions, serverContext, incomingEvent, definition, stateId, ctx } = args;
+    const { statePrompt, actions, serverContext, incomingEvent, definition, stateId, ctx, omitMessageFromRespond } = args;
     const ctxObj = serverContext?.context || {};
     validateContext(ctxObj, { logger: this.logger as { warn: (msg: string) => void } | undefined });
 
@@ -91,7 +93,7 @@ ${this._renderSelfFromState(desc, statePrompt, serverContext?.tools)}
 
 ${this._renderWorld(incomingEvent, ctxObj, agentId, senderMeta, agreements, otherAgents, users, stateId, ctx)}
 
-${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj)}
+${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessageFromRespond)}
 
 </agent>`;
   }
@@ -218,11 +220,11 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj)}
 
     if (ag?.agreementId) {
       lines.push(`Agreement: ${ag.agreementId}${creatorIsYou ? ' (yours)' : ''}`);
-      lines.push(`  Creator: ${parties.creatorId ?? 'N/A'}${creatorIsYou ? ' (You)' : ''}`);
-      lines.push(`  Provider: ${parties.providerId ?? 'N/A'}${providerIsYou ? ' (You)' : ''}`);
+      lines.push(`  Creator: ${parties.creator ?? 'N/A'}${creatorIsYou ? ' (You)' : ''}`);
+      lines.push(`  Provider: ${parties.provider ?? 'N/A'}${providerIsYou ? ' (You)' : ''}`);
       const proposal = ag.proposal as AnyObj | undefined;
       if (proposal?.status) {
-        lines.push(`  Proposal: ${proposal.status} (to ${parties.proposedToId}${task.proposedToIsYou ? ' - You' : ''})`);
+        lines.push(`  Proposal: ${proposal.status} (to ${parties.proposedTo}${task.proposedToIsYou ? ' - You' : ''})`);
       }
       const money = ag.money as AnyObj | undefined;
       if (typeof money?.price === 'number' && (money.price as number) > 0) {
@@ -299,10 +301,10 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj)}
       const agId = ag?.agreementId as string | undefined;
       const parties = (ag?.parties as AnyObj) || {};
       const roles: Array<[string, string]> = [
-        ['creatorId', 'creator'],
-        ['providerId', 'provider'],
-        ['payerId', 'payer'],
-        ['proposedToId', 'proposedTo'],
+        ['creator', 'creator'],
+        ['provider', 'provider'],
+        ['payer', 'payer'],
+        ['proposedTo', 'proposedTo'],
       ];
       for (const [field, role] of roles) {
         const pid = parties[field] as string | undefined;
@@ -360,7 +362,7 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj)}
     return lines.join('\n');
   }
 
-  _renderDecisionSchemaFromActions(actions: Record<string, Action>, senderMeta: SenderMeta, ctxObj: ServerContext): string {
+  _renderDecisionSchemaFromActions(actions: Record<string, Action>, senderMeta: SenderMeta, ctxObj: ServerContext, omitMessage?: boolean): string {
     const lines: string[] = ['<decision_schema>'];
     lines.push('Return ONE JSON object. ALWAYS include "thought" as the FIRST field — briefly explain your reasoning before choosing an action.');
     lines.push('Set "action" to exactly one of the action names below.');
@@ -368,7 +370,7 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj)}
 
     const replyTo = (senderMeta.defaultReplyReceiverId as string) || '<receiverId>';
     const pendingProposals = (ctxObj.agreements || []).filter(
-      (a) => (a.proposal as Record<string, unknown> | undefined)?.status === 'pending' && (a.proposedToIsYou || (a.parties as Record<string, unknown> | undefined)?.proposedToId === 'everyone'),
+      (a) => (a.proposal as Record<string, unknown> | undefined)?.status === 'pending' && (a.proposedToIsYou || (a.parties as Record<string, unknown> | undefined)?.proposedTo === 'everyone'),
     );
 
     if (pendingProposals.length > 0) {
@@ -387,7 +389,7 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj)}
         lines.push(`Tool: ${boundTool}`);
         lines.push(`Response: {"thought": "...", "action": "${name}", "args": {...}}`);
       } else {
-        lines.push(this._buildActionSchema(name, replyTo));
+        lines.push(this._buildActionSchema(name, replyTo, omitMessage));
       }
 
       if (actionDef.prompt?.examples?.length) {
@@ -406,22 +408,22 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj)}
     return lines.join('\n');
   }
 
-  _buildActionSchema(name: string, replyTo: string): string {
+  _buildActionSchema(name: string, replyTo: string, omitMessage?: boolean): string {
     if (name === 'wait') {
       return `Response: {"thought": "...", "action": "${name}"}`;
     }
-    // Never pre-fill a system-owned id (ziggs-system, anything ending with
-    // `-system`, or the literal 'system'/'service' bucket) as the default
-    // receiverId — that just nudges the LLM to address chat replies to a
-    // non-routable destination. Fall back to an explicit placeholder so the
-    // model has to pick a real recipient from <recipients>.
+    // Never pre-fill a non-routable id (the literal 'system' or 'service'
+    // buckets) as the default receiverId. Fall back to an explicit placeholder
+    // so the model picks a real recipient from <recipients>.
     const isSystemReplyTo =
       !replyTo ||
       replyTo === 'system' ||
       replyTo === 'service' ||
-      replyTo.endsWith('-system') ||
       replyTo.startsWith('<');
     const renderedReplyTo = isSystemReplyTo ? '<receiverId from <recipients>>' : replyTo;
+    if (omitMessage) {
+      return `Response: {"thought": "...", "action": "${name}", "receiverId": "${renderedReplyTo}"}`;
+    }
     return `Response: {"thought": "...", "action": "${name}", "receiverId": "${renderedReplyTo}", "message": "..."}`;
   }
 
@@ -431,11 +433,11 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj)}
     const senderType = ev?.senderType ? String(ev.senderType).toUpperCase() : 'SYSTEM';
     const myId = this._getMyAgentId(ctxObj);
 
-    const isSystemBucket = (id: string): boolean =>
-      !id || id === 'system' || id === 'service' || id.endsWith('-system');
+    const isNonRoutableSenderType = (t: string): boolean =>
+      t === 'SYSTEM' || t === 'SERVICE';
 
     let defaultReplyReceiverId = senderId;
-    const isNonRoutable = isSystemBucket(senderId) || senderType === 'SERVICE';
+    const isNonRoutable = isNonRoutableSenderType(senderType);
     if (isNonRoutable) {
       const history = ctxObj.history || [];
       for (let i = history.length - 1; i >= 0; i--) {
@@ -443,7 +445,7 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj)}
         const sender = row.sender as Record<string, unknown> | undefined;
         const id = String(sender?.id || row.senderId || '');
         const type = String(sender?.type || row.senderType || '').toUpperCase();
-        if (id && !isSystemBucket(id) && id !== myId && type !== 'SERVICE') {
+        if (id && id !== myId && !isNonRoutableSenderType(type)) {
           defaultReplyReceiverId = id;
           break;
         }

package/src/runtime/buildOutcome.ts

@@ -83,6 +83,25 @@ export function outcomeFromEvent(
 }
 
 function singleEventToOutcome(ev: RawEvent, ownAgentId: string | null): Outcome | null {
+  if (ev.type === 'agreement_lifecycle') {
+    const operation = ev.operation as string | undefined;
+    const agreementId = (ev.agreementId as string | undefined) ?? '';
+    const action =
+      operation === 'proposal_rejected'
+        ? 'reject'
+        : operation === 'proposal_approved' || operation === 'proposal_approved_execute'
+          ? 'approve'
+          : null;
+    if (action && agreementId) {
+      return {
+        kind: 'proposal-resolved',
+        action,
+        proposal: { agreementId },
+      };
+    }
+    return null;
+  }
+
   if (ev.type === 'task_result') {
     const result = ev.result || {};
     if (
@@ -120,7 +139,7 @@ function singleEventToOutcome(ev: RawEvent, ownAgentId: string | null): Outcome
 
     // Direct assignment to me (provider) — task spawned, citing an active agreement.
     const isAssignedToMe =
-      (result.providerIsYou || parties.providerId === ownAgentId) &&
+      (result.providerIsYou || parties.provider === ownAgentId) &&
       (state === 'active' || state === 'in-progress');
     if (isAssignedToMe) {
       return { kind: 'task-assigned', task };
@@ -193,7 +212,8 @@ function singleEventToOutcome(ev: RawEvent, ownAgentId: string | null): Outcome
   if (ownAgentId && ev.senderId && ev.senderId === ownAgentId) return null;
 
   const text = typeof ev.text === 'string' ? ev.text : undefined;
-  return { kind: 'message-received', text, senderId: ev.senderId };
+  const senderType = typeof ev.senderType === 'string' ? ev.senderType : undefined;
+  return { kind: 'message-received', text, senderId: ev.senderId, senderType };
 }
 
 // Higher rank wins when collapsing batched events into one outcome.
@@ -466,7 +486,7 @@ export function applyOutcomeToCtx(ctx: Ctx, outcome: Outcome): void {
       // activeAgreementId so transitions gated on activeAgreementId fire.
       // We only do this when no agreement is currently active, so that
       // approvals of CHILD sub-agreements (e.g. coffee-agent approving the
-      // Ziggs-issued subcontract) don't overwrite the root the orchestrator
+      // Ziggs-issued subcontract) don't overwrite the root the primary agent
       // is bound to. Sub-agreement bookkeeping lives in delegatedAgreementIds
       // (recorded on task-delegated) — not here.
       if (outcome.action === 'approve' && !ctx.activeAgreementId) {
@@ -476,10 +496,20 @@ export function applyOutcomeToCtx(ctx: Ctx, outcome: Outcome): void {
       ctx.pendingProposalAgreementId = null;
       return;
     }
+    case 'subtask-finished': {
+      const t = outcome.task;
+      const taskId = t?.taskId;
+      const agId = t?.agreementId || t?.agreement?.agreementId;
+      if (taskId) ctx.delegatedTaskIds = ctx.delegatedTaskIds.filter(id => id !== taskId);
+      if (agId) ctx.delegatedAgreementIds = ctx.delegatedAgreementIds.filter(id => id !== agId);
+      return;
+    }
     case 'task-closed': {
       ctx.activeAgreementId = null;
       ctx.activeTaskId = null;
       ctx.pendingProposalAgreementId = null;
+      ctx.delegatedTaskIds = [];
+      ctx.delegatedAgreementIds = [];
       return;
     }
     default:

package/src/runtime/defaults.ts

@@ -40,6 +40,9 @@ export function thinkingDefaults(opts: { initial: string }): ThinkingDefaults {
     transitions: [
       { to: initial, when: o => o.kind === 'wait' },
       { to: initial, when: o => o.kind === 'message-sent' },
+      // Errors (empty/failed turns) fall back to the initial state instead of
+      // silently re-entering and recursing until the depth guard (ZIG-303).
+      { to: initial, when: o => o.kind === 'error' },
     ],
   };
 }

package/src/runtime/runTurn.ts

@@ -68,6 +68,8 @@ 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). */
+  streamRespondActions?: boolean;
 }
 
 interface RunTurnResult {
@@ -95,7 +97,17 @@ 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');
   const sessionId = ctx.identity.sessionId;
+  const runId = crypto.randomUUID();
+
+  // Wrap eff to stamp runId + stateId onto llm-call and tool-call effects.
+  const effWithTrace: typeof eff = (effect) => {
+    if (effect.kind === 'llm-call' || effect.kind === 'tool-call') {
+      return eff({ ...effect, runId, stateId } as typeof effect);
+    }
+    return eff(effect);
+  };
 
   const emitThought = async (text: unknown): Promise<void> => {
     if (text == null) return;
@@ -108,7 +120,7 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
     }
   };
 
-  runtimeLog.info('runTurn', `enter state=${stateId}`);
+  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
@@ -128,32 +140,15 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
         return n != null && allowedToolNames.has(n);
       })
     : [];
-  const serverContext = await eff({ kind: 'read-context', sessionId, opts: {} });
+  const serverContext = await effWithTrace({ kind: 'read-context', sessionId, opts: {} });
   const ctxObj = normalizeContextSnapshot(serverContext);
 
-  const probeDispatch = Object.entries(actions).find(([, a]) => a.tool === 'capability_probe_dispatch');
-  if (probeDispatch && incomingEvent) {
-    const [actionName, actionDef] = probeDispatch;
-    const messageText =
-      extractIncomingMessageText(incomingEvent, ctxObj as ContextSnapshot) ||
-      JSON.stringify(incomingEvent);
-    const toolResultsOut: ToolResultEntry[] = [];
-    const emitted = await executeTool(
-      { action: actionName, tool: 'capability_probe_dispatch', args: { messageText } },
-      eff,
-      sessionId,
-      memory,
-    );
-    const events = (Array.isArray(emitted) ? emitted : emitted ? [emitted] : []) as EmittedEvent[];
-    const outcome = outcomeFromActionResult(actionName, actionDef, {}, events, toolResultsOut);
-    return { outcome, toolResults: toolResultsOut, llmCalls: 0, tokens: { total: 0, input: 0, output: 0 } };
-  }
-
   const prompt = promptBuilder.buildFromState({
     statePrompt, actions,
     serverContext: { context: ctxObj as Record<string, unknown>, tools: tools as unknown as Record<string, unknown>[] },
     incomingEvent, definition,
     chatId: sessionId, stateId, ctx,
+    omitMessageFromRespond: streamRespondActions,
   });
 
   const systemContent = tools.length > 0
@@ -179,7 +174,12 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
   runtimeLog.info('runTurn', `calling LLM tools=${tools.length}`);
 
   for (let iter = 0; iter < MAX_TOOL_LOOP_ITERS; iter++) {
-    const llmResponse: LlmResponse = await eff({ kind: 'llm-call', messages, tools: tools as unknown as LlmToolSchema[] });
+    const llmResponse: LlmResponse = await effWithTrace({
+      kind: 'llm-call',
+      messages,
+      tools: tools as unknown as LlmToolSchema[],
+      sessionId,
+    });
     llmCallsTotal++;
     const usage = llmResponse?.usage;
     tokensTotal  += (usage?.total_tokens  ?? usage?.totalTokens)  || 0;
@@ -257,7 +257,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, eff, sessionId, memory);
+        const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory);
         toolCallResults.push({ tc, matchingAction, result, args, actionDef });
       }
 
@@ -286,7 +286,7 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
         if (!turnHadAgreementCreation && eventsContainAgreementCreation(events)) {
           turnHadAgreementCreation = true;
         }
-        if (eventsAreTerminal(events)) hasTerminal = true;
+        if (eventsAreTerminal(events) || actionDef?.terminatesLoop) hasTerminal = true;
       }
 
       if (hasTerminal) break;
@@ -301,6 +301,42 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
 
       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.
+      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') {
+        const streamMessageId = crypto.randomUUID();
+        runtimeLog.info('runTurn', `stream-text start action=${chosenAction} receiverId=${decision.receiverId} msgId=${streamMessageId}`);
+        const streamMessages: LlmMessage[] = [
+          ...messages,
+          {
+            role: 'assistant' as const,
+            content: JSON.stringify({ thought: decision.thought, action: decision.action, receiverId: decision.receiverId }),
+          },
+          {
+            role: 'user' as const,
+            content: 'Write your reply now. Output ONLY the message text — no JSON wrapping, no preamble.',
+          },
+        ];
+        let streamedText = '';
+        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}`);
+        } catch (err) {
+          runtimeLog.warn('runTurn', `stream-text failed: ${(err as Error).message}`);
+        }
+        if (streamedText) {
+          const safeText = truncateMsg(streamedText);
+          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);
+          lastAction = chosenAction;
+          lastActionDef = actionDef;
+        }
+        break;
+      }
+
       const result = await executeDecision(decision, actionDef, eff, sessionId, memory);
       if (result) {
         const events = (Array.isArray(result) ? result : [result]) as EmittedEvent[];
@@ -340,6 +376,25 @@ export async function runTurn(input: RunTurnInput): Promise<RunTurnResult> {
 
 // ─────────────────────────────────────────────────────────────────────────────
 
+function extractIncomingMessageText(event: RawEvent | null): string {
+  if (!event) return '';
+  const parts: string[] = [];
+  const push = (v: unknown) => {
+    if (typeof v === 'string' && v.trim()) parts.push(v.trim());
+  };
+  push(event.text);
+  push((event as Record<string, unknown>).message);
+  const agreement = (event as Record<string, unknown>).agreement as Record<string, unknown> | undefined;
+  if (agreement) {
+    const terms = agreement.terms as Record<string, unknown> | undefined;
+    push(terms?.description);
+    push(JSON.stringify(agreement));
+  }
+  const task = (event as Record<string, unknown>).task;
+  if (task) push(JSON.stringify(task));
+  return parts.join('\n');
+}
+
 function normalizeContextSnapshot(raw: ContextSnapshot | undefined | null): ContextSnapshot {
   if (!raw || typeof raw !== 'object') {
     return { history: [], agreements: [], agents: [], users: [] };
@@ -460,21 +515,38 @@ function findActionForTool(toolName: string, allowedActionNames: string[], actio
   return null;
 }
 
-async function executeDecision(decision: ParsedDecision, actionDef: Action | null, eff: EffectHandler, sessionId: string, memory?: MemoryStore): Promise<EmittedEvent[] | EmittedEvent | null> {
+async function executeDecision(
+  decision: ParsedDecision,
+  actionDef: Action | null,
+  eff: EffectHandler,
+  sessionId: string,
+  memory?: MemoryStore,
+  incomingEvent: RawEvent | null = null,
+): Promise<EmittedEvent[] | EmittedEvent | null> {
   const boundTool = actionDef?.tool || null;
 
   if (boundTool) {
     decision.tool = boundTool;
-    return await executeTool(decision, eff, sessionId, memory);
+    return await executeTool(decision, eff, sessionId, memory, incomingEvent);
   }
-  if (decision.action === '_genericDiscoveryTool' && decision.tool) return await executeTool(decision, eff, sessionId, memory);
-  if (decision.tool) return await executeTool(decision, eff, sessionId, memory);
+  if (decision.action === '_genericDiscoveryTool' && decision.tool) {
+    return await executeTool(decision, eff, sessionId, memory, incomingEvent);
+  }
+  if (decision.tool) return await executeTool(decision, eff, sessionId, memory, incomingEvent);
   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 as Record<string, unknown>;
+    if (typeof a.message === 'string' && typeof a.receiverId === 'string') {
+      return await executeSendMessage({ ...decision, message: a.message, receiverId: a.receiverId }, eff, sessionId);
+    }
+  }
   if (decision.action === 'wait') return { type: 'waited' };
   return null;
 }
@@ -522,11 +594,25 @@ async function executeSendMessages(decision: ParsedDecision, eff: EffectHandler,
  * dependencies (taskService, agreementService, agents list, etc.), and
  * wrapping the call in telemetry / operation-record entries if it wants.
  */
-async function executeTool(decision: ParsedDecision, eff: EffectHandler, sessionId: string, memory?: MemoryStore): Promise<EmittedEvent[] | EmittedEvent | null> {
+async function executeTool(
+  decision: ParsedDecision,
+  eff: EffectHandler,
+  sessionId: string,
+  memory?: MemoryStore,
+  incomingEvent: RawEvent | null = null,
+): Promise<EmittedEvent[] | EmittedEvent | null> {
   const { tool, args } = decision;
   if (!tool) return null;
   try {
-    const r = await eff({ kind: 'tool-call', sessionId, name: tool, args: args || {}, memory }) as ToolCallResult;
+    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,
+    }) as ToolCallResult;
     if (!r.ok) return { type: 'tool_error', tool, error: r.error || 'unknown', senderId: 'system' };
     // Tools may emit terminal markers (e.g. `message_sent`, `waited`) via
     // `events` — propagate so the loop can detect terminal turns.
@@ -587,38 +673,6 @@ function pickReceiverForEcho(context: ContextSnapshot, incomingEvent: RawEvent |
   return pickPrimaryUserIdFromContext(context);
 }
 
-function extractIncomingMessageText(
-  incomingEvent: RawEvent | null,
-  ctx: ContextSnapshot,
-): string {
-  const parts: string[] = [];
-  const walk = (ev: RawEvent | null | undefined): void => {
-    if (!ev) return;
-    if (ev.text) parts.push(String(ev.text));
-    if (typeof ev.message === 'string') parts.push(ev.message);
-    const result = ev.result as Record<string, unknown> | undefined;
-    if (result) {
-      if (result.description) parts.push(String(result.description));
-      const ag = result.agreement as Record<string, unknown> | undefined;
-      if (ag) {
-        const terms = ag.terms as Record<string, unknown> | undefined;
-        if (terms?.description) parts.push(String(terms.description));
-        if (ag.agreementId) parts.push(String(ag.agreementId));
-      }
-      if (result.agreementId) parts.push(String(result.agreementId));
-    }
-    if (Array.isArray(ev.events)) (ev.events as RawEvent[]).forEach(walk);
-  };
-  walk(incomingEvent);
-  const hist = ctx.history as Array<Record<string, unknown>> | undefined;
-  if (hist?.length) {
-    const last = hist[hist.length - 1];
-    const text = last?.text ?? last?.content;
-    if (text) parts.push(String(text));
-  }
-  return parts.join('\n').trim();
-}
-
 function pickPrimaryUserIdFromContext(context: ContextSnapshot): string | null {
   const users = context?.users || [];
   for (const u of users as Record<string, unknown>[]) {

package/src/runtime/validateWorkflow.ts

@@ -156,6 +156,22 @@ export function validateWorkflow(workflow: Workflow): ValidationResult {
             `thinking state "${name}" has no fallthrough for { kind: 'wait' } — agent may stall when LLM picks wait. Spread thinkingDefaults().transitions or add explicitly.`,
           );
         }
+        const hasErrorFallthrough = state.transitions.some(t => {
+          if (!t.when) return true;
+          try {
+            return t.when(
+              { kind: 'error', source: 'unknown', cause: 'probe', retryable: false },
+              PROBE_CTX,
+            );
+          } catch {
+            return false;
+          }
+        });
+        if (!hasErrorFallthrough) {
+          warnings.push(
+            `thinking state "${name}" has no fallthrough for { kind: 'error' } — empty/failed turns may silently recurse until the depth guard (ZIG-303). Add an error transition or spread thinkingDefaults().transitions.`,
+          );
+        }
       }
     }
   }