@ziggs-ai/agent-sdk 0.1.10 → 0.1.12

package/src/runtime/AgentMachine.ts

@@ -2,7 +2,9 @@ import type { Ctx, Outcome, Workflow, Identity, EffectHandler } from '../types.j
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { applyOutcomeToCtx, outcomeFromEvent, type RawEvent } from './buildOutcome.js';
 import type { runTurn as RunTurnFn } from './runTurn.js';
+import { runMechanical } from './runMechanical.js';
 import { PromptBuilder } from './PromptBuilder.js';
+import { bootstrapCtx } from './bootstrapCtx.js';
 import type { MemoryStore } from '../memory/MemoryStore.js';
 import type { ToolManager } from '../tools/ToolManager.js';
 
@@ -16,7 +18,19 @@ 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 };
+  | { kind: 'turn-budget-guard'; state: string; turns: number }
+  | { kind: 'error-escape'; fromState: string; toState: string }
+  | { kind: 'timeout-unhandled'; state: string; waitedMs: number };
+
+/**
+ * Max thinking turns a session may run without any human (USER) input before it
+ * is treated as a runaway loop and parked (ZIG-768). The depth-guard only bounds
+ * re-entries within a single event chain; this bounds turns ACROSS events, which
+ * is how a supervising session ran 436 turns in a day. The counter resets on
+ * every USER frame, so human-driven conversations are never affected — only
+ * autonomous agent↔agent loops accumulate toward it.
+ */
+const DEFAULT_MAX_TURNS_WITHOUT_USER_INPUT = 100;
 
 interface MachineInput {
   identity: Identity;
@@ -39,6 +53,8 @@ interface MachineOptions {
   input: MachineInput;
   /** Optional tap for FSM transition events — called synchronously on each transition. */
   transitionTap?: (event: TransitionEvent) => void;
+  /** Runaway-loop backstop: max thinking turns without human input before parking. Default 100. */
+  maxTurnsWithoutUserInput?: number;
 }
 
 interface IncomingFrame {
@@ -78,12 +94,17 @@ export class AgentMachine {
   _llmCalls = 0;
   _tokens = { total: 0, input: 0, output: 0 };
   _lastUserSenderId: string | null = null;
+  _stateTimeoutUnhandled = false;
   _transitionTap: ((event: TransitionEvent) => void) | undefined;
+  /** Thinking turns run since the last human (USER) frame. Reset on USER input. */
+  _turnsSinceUserInput = 0;
+  _maxTurnsWithoutUserInput: number;
 
   get llmCalls(): number { return this._llmCalls; }
   get tokens(): { total: number; input: number; output: number } { return this._tokens; }
+  get stateTimeoutUnhandled(): boolean { return this._stateTimeoutUnhandled; }
 
-  constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap }: MachineOptions) {
+  constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput }: MachineOptions) {
     this.workflow = workflow;
     this.executionCore = executionCore;
     this.eff = eff;
@@ -91,19 +112,9 @@ export class AgentMachine {
     this.promptBuilder = promptBuilder;
     this.memory = memory;
     this._transitionTap = transitionTap;
+    this._maxTurnsWithoutUserInput = maxTurnsWithoutUserInput ?? DEFAULT_MAX_TURNS_WITHOUT_USER_INPUT;
     this.state = input.state || workflow.initial;
-    this.ctx = input.ctx
-      ? { ...input.ctx, identity: input.identity }
-      : {
-          identity: input.identity,
-          activeAgreementId: null,
-          activeTaskId: null,
-          pendingProposalAgreementId: null,
-          delegatedAgreementIds: [],
-          delegatedTaskIds: [],
-          toolResults: [],
-          lastOutcome: { kind: 'enter' },
-        };
+    this.ctx = bootstrapCtx(input.identity, input.ctx);
   }
 
   getSnapshot(): MachineSnapshot {
@@ -156,6 +167,8 @@ export class AgentMachine {
     this._lastIncomingEvent = ev ?? null;
     if (ev?.senderId && String(ev?.senderType ?? '').toUpperCase() === 'USER') {
       this._lastUserSenderId = String(ev.senderId);
+      // Human input is real progress — reset the runaway-loop budget (ZIG-768).
+      this._turnsSinceUserInput = 0;
     }
     runtimeLog.debug(
       'FSM',
@@ -172,13 +185,18 @@ export class AgentMachine {
     // message, which triggers another resource_changed, and so on.
     if (ev && outcome.kind === 'enter') return;
 
-    if (
-      outcome.kind === 'subtask-finished' &&
-      ev?.type === 'task_result' &&
-      ev?.result?.taskId &&
-      this.ctx.delegatedTaskIds.includes(ev.result.taskId)
-    ) {
-      // Already correctly classified — no override needed.
+    // Proposer detection must read pendingProposalAgreementId BEFORE
+    // applyOutcomeToCtx clears it on resolution (buildOutcome.ts). Wire frames
+    // carry no trustworthy proposer field — agreement_lifecycle drops `parties`
+    // in normalizeIncomingEvent, and parties.creator is a principal id, not an
+    // agentId (backend ZIG-272) — so the SDK's own "I made this proposal"
+    // memory is the signal. Side effect we rely on: the first resolution clears
+    // the pending id, so duplicate approval frames compute proposedByMe=false
+    // and can never double-kickoff.
+    if (outcome.kind === 'proposal-resolved') {
+      outcome.proposedByMe =
+        this.ctx.pendingProposalAgreementId !== null &&
+        outcome.proposal.agreementId === this.ctx.pendingProposalAgreementId;
     }
 
     applyOutcomeToCtx(this.ctx, outcome);
@@ -199,6 +217,24 @@ export class AgentMachine {
       this._notify();
     }
 
+    // A state-timeout only enters at depth 0 (host-armed frame via _handleFrame;
+    // turns cannot produce it — validateWorkflow rejects produces:'state-timeout').
+    // No matching transition = the author declared timeoutMs but no route: park
+    // loudly and tell the host not to re-arm (re-arming would error every
+    // timeoutMs forever). Next real event still recovers the lane. A matched
+    // transition (target !== null) — including an explicit self-loop — is
+    // "handled" and re-arms as a heartbeat.
+    if (outcome.kind === 'state-timeout' && depth === 0 && !target) {
+      this._stateTimeoutUnhandled = true;
+      runtimeLog.error(
+        'AgentMachine',
+        `state=${this.state} timed out after ${outcome.waitedMs}ms but no transition matches { kind: 'state-timeout' } — parking without a timer. Add a state-timeout transition to "${this.state}" or remove timeoutMs.`,
+      );
+      this._transitionTap?.({ kind: 'timeout-unhandled', state: this.state, waitedMs: outcome.waitedMs });
+      this._notify();
+      return;
+    }
+
     const sd = this.workflow.states[this.state];
     if (!sd) return;
     if (sd.kind === 'parked') {
@@ -208,6 +244,70 @@ export class AgentMachine {
       return;
     }
 
+    if (sd.kind === 'mechanical') {
+      if (depth >= 12) {
+        runtimeLog.warn(
+          'AgentMachine',
+          `state=${this.state} runaway mechanical 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;
+      }
+      if (this._turnsSinceUserInput >= this._maxTurnsWithoutUserInput) {
+        runtimeLog.warn(
+          'AgentMachine',
+          `state=${this.state} runaway loop: ${this._turnsSinceUserInput} turns without user input (cap ${this._maxTurnsWithoutUserInput}); parking`,
+        );
+        this._transitionTap?.({ kind: 'turn-budget-guard', state: this.state, turns: this._turnsSinceUserInput });
+        await this._sendFallbackIfUserWaiting('I got stuck in a loop and paused. Please send another message to continue.');
+        this._notify();
+        return;
+      }
+      runtimeLog.debug('FSM', `_step mechanical state=${this.state} — run tool`);
+      this._running = true;
+      try {
+        const { outcome: turnOutcome, toolResults, llmCalls, tokens } = await runMechanical({
+          stateId: this.state,
+          state: sd,
+          ctx: this.ctx,
+          eff: this.eff,
+          memory: this.memory,
+          incomingEvent: this._lastIncomingEvent,
+        });
+        this.ctx.toolResults = toolResults;
+        this._llmCalls += llmCalls;
+        this._turnsSinceUserInput += 1;
+        this._tokens.total += tokens.total;
+        this._tokens.input += tokens.input;
+        this._tokens.output += tokens.output;
+        applyOutcomeToCtx(this.ctx, turnOutcome);
+        this._running = false;
+        this._notify();
+        await this._step(turnOutcome, depth + 1);
+      } catch (error: unknown) {
+        runtimeLog.error('AgentMachine', `mechanical state=${this.state} error: ${(error as Error)?.message || error}`);
+        const errOutcome: Outcome = {
+          kind: 'error',
+          source: 'unknown',
+          cause: (error as Error)?.message || String(error),
+          retryable: false,
+        };
+        applyOutcomeToCtx(this.ctx, errOutcome);
+        this._running = false;
+        this._notify();
+        const fallback = this._evaluateTransitions(errOutcome);
+        if (fallback && fallback !== this.state) {
+          this.state = fallback;
+          this._notify();
+        } else {
+          await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+        }
+      }
+      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).
@@ -217,7 +317,7 @@ export class AgentMachine {
       fromState === this.state &&
       !target
     ) {
-      if (this._escapeToInitialParked(outcome, fromState)) return;
+      if (await this._escapeToInitialParked(outcome, fromState)) return;
       runtimeLog.warn(
         'AgentMachine',
         `state=${fromState} outcome.kind=${(outcome as Record<string, unknown>).kind} matched no transition; parking (depth=${depth})`,
@@ -247,6 +347,22 @@ export class AgentMachine {
       this._notify();
       return;
     }
+    // Cross-event runaway guard (ZIG-768). The depth-guard above only bounds
+    // one event chain; a supervising session that keeps waking on agent/system
+    // messages re-enters at depth 0 each time and never trips it. Bound the
+    // total thinking turns since the last human input instead — a runaway
+    // agent↔agent loop climbs toward the cap while a human conversation resets
+    // it on every user message.
+    if (this._turnsSinceUserInput >= this._maxTurnsWithoutUserInput) {
+      runtimeLog.warn(
+        'AgentMachine',
+        `state=${this.state} runaway loop: ${this._turnsSinceUserInput} turns without user input (cap ${this._maxTurnsWithoutUserInput}); parking`,
+      );
+      this._transitionTap?.({ kind: 'turn-budget-guard', state: this.state, turns: this._turnsSinceUserInput });
+      await this._sendFallbackIfUserWaiting('I got stuck in a loop and paused. Please send another message to continue.');
+      this._notify();
+      return;
+    }
     runtimeLog.debug('FSM', `_step thinking state=${this.state} — run turn`);
 
     // Thinking: run a turn, produce an outcome, re-step.
@@ -267,6 +383,7 @@ export class AgentMachine {
 
       this.ctx.toolResults = toolResults;
       this._llmCalls += llmCalls;
+      this._turnsSinceUserInput += 1;
       this._tokens.total += tokens.total;
       this._tokens.input += tokens.input;
       this._tokens.output += tokens.output;
@@ -299,7 +416,7 @@ export class AgentMachine {
   }
 
   /** Error with no author-defined escape: park at workflow.initial if it is parked. */
-  _escapeToInitialParked(outcome: Outcome, fromState: string): boolean {
+  async _escapeToInitialParked(outcome: Outcome, fromState: string): Promise<boolean> {
     if (outcome.kind !== 'error') return false;
     const initial = this.workflow.initial;
     const initialSd = this.workflow.states[initial];
@@ -312,6 +429,9 @@ export class AgentMachine {
     );
     this._transitionTap?.({ kind: 'error-escape', fromState, toState: initial });
     this.state = initial;
+    // The turn failed and no workflow transition handled it — a waiting human
+    // got nothing, so apologize before parking (same text as the other parks).
+    await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
     this._notify();
     return true;
   }

package/src/runtime/PromptBuilder.ts

@@ -1,4 +1,4 @@
-import type { Action, Ctx, PromptDef } from '../types.js';
+import type { Action, CollectedSubtaskResult, Ctx, PromptDef } from '../types.js';
 import { HistoryFormatter, AgreementFormatter } from '../formatters/index.js';
 import { validateContext } from '../cognition/validateContext.js';
 import type { RawEvent } from './buildOutcome.js';
@@ -46,11 +46,21 @@ export interface PromptBuilderOptions {
   description?: string;
   specialization?: string | null;
   maxHistoryEntries?: number;
+  /**
+   * Token budget for the <history> block. History is included newest-first up
+   * to this many (estimated) tokens, so a few large turns can't blow the prompt
+   * up to tens of thousands of input tokens (ZIG-769). maxHistoryEntries still
+   * applies as a secondary hard ceiling.
+   */
+  maxHistoryTokens?: number;
   historyFormatter?: HistoryFormatterI;
   agreementFormatter?: AgreementFormatterI;
   logger?: LoggerI | null | { warn: (msg: string) => void };
 }
 
+/** Rough chars-per-token ratio for budgeting (English/JSON averages ~4). */
+const CHARS_PER_TOKEN = 4;
+
 /**
  * Builds the XML prompt for a thinking-state turn:
  *   <agent><self/><world/><decision_schema/></agent>
@@ -63,6 +73,7 @@ export class PromptBuilder {
   description: string;
   specialization: string | null;
   maxHistoryEntries: number;
+  maxHistoryTokens: number;
   historyFormatter: HistoryFormatterI;
   agreementFormatter: AgreementFormatterI;
   logger: LoggerI | null;
@@ -71,11 +82,17 @@ export class PromptBuilder {
     this.description = options.description || 'A capable agent ready to assist';
     this.specialization = options.specialization ?? null;
     this.maxHistoryEntries = options.maxHistoryEntries ?? 50;
+    this.maxHistoryTokens = options.maxHistoryTokens ?? 8000;
     this.historyFormatter = options.historyFormatter || new HistoryFormatter();
     this.agreementFormatter = (options.agreementFormatter || new AgreementFormatter()) as AgreementFormatterI;
     this.logger = options.logger as LoggerI | null || null;
   }
 
+  // Section order is deliberate and cache-stable (ZIG-769): <self> (identity,
+  // state, tools) is stable per agent+state and comes first, so OpenAI automatic
+  // prompt caching can reuse it as a prefix across a conversation's turns. All
+  // volatile content (the incoming event, history, and currentTime) lives later
+  // in <world>, so it never invalidates that cacheable prefix.
   buildFromState(args: BuildArgs): string {
     const { statePrompt, actions, serverContext, incomingEvent, definition, stateId, ctx, omitMessageFromRespond } = args;
     const ctxObj = serverContext?.context || {};
@@ -151,6 +168,11 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
     lines.push('');
     lines.push(this._renderAgreements(agreements));
 
+    if (ctx?.collectedResults?.length) {
+      lines.push('');
+      lines.push(this._renderSubtaskResults(ctx.collectedResults));
+    }
+
     if (users.length > 0 || otherAgents.length > 0) {
       lines.push('');
       lines.push(this._renderRecipients(users, otherAgents, agreements, agentId));
@@ -171,10 +193,24 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
     if (ctx.activeTaskId) out.activeTaskId = ctx.activeTaskId;
     if (ctx.pendingProposalAgreementId) out.pendingProposalAgreementId = ctx.pendingProposalAgreementId;
     if (ctx.delegatedAgreementIds?.length) out.delegatedAgreementIds = ctx.delegatedAgreementIds;
+    if (Object.keys(ctx.pendingSubtasks ?? {}).length) out.pendingSubtasks = ctx.pendingSubtasks;
     if (ctx.lastOutcome) out.lastOutcomeKind = ctx.lastOutcome.kind;
     return `<machine_context>\n${JSON.stringify(out, null, 2)}\n</machine_context>`;
   }
 
+  _renderSubtaskResults(results: CollectedSubtaskResult[]): string {
+    const lines: string[] = ['<subtask_results>'];
+    lines.push(`All ${results.length} finished subtask(s) for the current engagement, oldest first. Synthesize from ALL of them — not just the most recent event.`);
+    for (const r of results) {
+      const payload = r.result == null ? null : typeof r.result === 'string' ? r.result : JSON.stringify(r.result);
+      const display = payload && payload.length > 2000 ? payload.slice(0, 2000) + `… [truncated of ${payload.length} chars]` : payload;
+      lines.push(`- taskId=${r.taskId} agent=${r.agentId ?? 'unknown'} status=${r.status}`);
+      lines.push(`  result: ${display ?? '(none)'}`);
+    }
+    lines.push('</subtask_results>');
+    return lines.join('\n');
+  }
+
   _renderEvent(event: RawEvent | AnyObj | null, senderMeta: SenderMeta): string {
     if (!event) return '<event type="none">No incoming event.</event>';
 
@@ -251,16 +287,36 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
   }
 
   _renderHistory(history: AnyObj[] | undefined, agentId: string | null): string {
-    let entries = history || [];
-    let truncNote = '';
-    if (entries.length > this.maxHistoryEntries) {
-      truncNote = `[Showing last ${this.maxHistoryEntries} of ${entries.length} entries]\n\n`;
-      entries = entries.slice(-this.maxHistoryEntries);
+    const all = history || [];
+    const charBudget = this.maxHistoryTokens * CHARS_PER_TOKEN;
+
+    // Include entries newest-first, bounded by BOTH a token budget and the
+    // entry-count ceiling. The newest entry is always kept even if it alone
+    // exceeds the budget, so the most recent turn is never dropped.
+    let startIdx = all.length;
+    let usedChars = 0;
+    for (let i = all.length - 1; i >= 0; i--) {
+      if (all.length - i > this.maxHistoryEntries) break;
+      const size = this._estimateEntryChars(all[i]);
+      if (startIdx < all.length && usedChars + size > charBudget) break;
+      usedChars += size;
+      startIdx = i;
     }
+
+    const entries = all.slice(startIdx);
+    const dropped = all.length - entries.length;
+    const truncNote = dropped > 0
+      ? `[Showing last ${entries.length} of ${all.length} entries — older turns dropped to fit the context budget]\n\n`
+      : '';
     const formatted = this.historyFormatter.format(entries, agentId ?? '', {});
     return `<history>\n${truncNote}${formatted}\n</history>`;
   }
 
+  /** Rough character size of one history entry, used for the token budget. */
+  _estimateEntryChars(entry: AnyObj): number {
+    try { return JSON.stringify(entry)?.length ?? 0; } catch { return 0; }
+  }
+
   _renderAgreements(agreements: AnyObj[]): string {
     const formatted = this.agreementFormatter.format(agreements || []);
     return `<agreements>\n${formatted}\n</agreements>`;

package/src/runtime/bootstrapCtx.ts

@@ -0,0 +1,39 @@
+import type { Ctx, Identity } from '../types.js';
+
+/**
+ * The one place a per-lane `Ctx` is constructed.
+ *
+ * Both cognitions bootstrap the same Ctx: the FSM (`AgentMachine` constructor)
+ * and the Claude Agent SDK brain (`ClaudeSdkAgent.tick`). Before this, each
+ * carried its own copy of the fresh-Ctx literal and the restore-path defaulting,
+ * and they had already drifted (the "default them ONCE here" comment in
+ * AgentMachine no longer held). Keep it here so the shape lives in a single spot.
+ *
+ * - No `existing` → a fresh Ctx for a brand-new session.
+ * - `existing` present → restore it, re-stamping `identity` and defaulting the
+ *   fields that sessions persisted before they existed may lack. Sessions live
+ *   up to SESSION_TTL_SECONDS (24h) in DynamoDB, so an old row can come back
+ *   without `pendingSubtasks` / `collectedResults`; default them here, nowhere
+ *   else.
+ */
+export function bootstrapCtx(identity: Identity, existing?: Ctx | null): Ctx {
+  if (existing) {
+    return {
+      ...existing,
+      identity,
+      pendingSubtasks: existing.pendingSubtasks ?? {},
+      collectedResults: existing.collectedResults ?? [],
+    };
+  }
+  return {
+    identity,
+    activeAgreementId: null,
+    activeTaskId: null,
+    pendingProposalAgreementId: null,
+    delegatedAgreementIds: [],
+    pendingSubtasks: {},
+    collectedResults: [],
+    toolResults: [],
+    lastOutcome: { kind: 'enter' },
+  };
+}

package/src/runtime/buildOutcome.ts

@@ -97,6 +97,7 @@ function singleEventToOutcome(ev: RawEvent, ownAgentId: string | null): Outcome
         kind: 'proposal-resolved',
         action,
         proposal: { agreementId },
+        proposedByMe: false, // real value stamped in AgentMachine._handleFrame from ctx (needs pendingProposalAgreementId, unavailable here)
       };
     }
     return null;
@@ -124,7 +125,7 @@ function singleEventToOutcome(ev: RawEvent, ownAgentId: string | null): Outcome
         const proposal: ProposalRef = agId
           ? { agreementId: agId, agreement: result as unknown as AgreementRef }
           : { agreementId: '' };
-        return { kind: 'proposal-resolved', action: proposalAction as 'approve' | 'reject', proposal };
+        return { kind: 'proposal-resolved', action: proposalAction as 'approve' | 'reject', proposal, proposedByMe: false }; // real value stamped in AgentMachine._handleFrame from ctx
       }
       // Other lifecycle ops (countered, expired) treated as enter — no FSM action needed here.
       return null;
@@ -194,6 +195,7 @@ function singleEventToOutcome(ev: RawEvent, ownAgentId: string | null): Outcome
         kind: 'proposal-resolved',
         action: reason === 'proposal_approved' ? 'approve' : 'reject',
         proposal,
+        proposedByMe: false, // real value stamped in AgentMachine._handleFrame from ctx
       };
     }
     if (resource.kind === 'task-state' && reason === 'subtask_completed') {
@@ -204,6 +206,11 @@ function singleEventToOutcome(ev: RawEvent, ownAgentId: string | null): Outcome
     return null;
   }
 
+  if (ev.type === 'state-timeout') {
+    // Synthetic frame from AgentHost's StateTimers — host-constructed, fields always present.
+    return { kind: 'state-timeout', state: ev.state as string, waitedMs: ev.waitedMs as number };
+  }
+
   // Only real inbound chat messages should drive the FSM. Backend bookkeeping
   // (presence/heartbeat, raw `batch` outer frames, etc.) are NOT chat traffic.
   if (ev.type !== 'message') return null;
@@ -223,6 +230,10 @@ function outcomeRank(o: Outcome): number {
     case 'proposal-resolved': return 90;
     case 'subtask-finished': return 80;
     case 'message-received': return 10;
+    // Any real event coalesced into the same batch supersedes the timer —
+    // waking to "nothing happened" is moot when something did. Must stay below
+    // message-received (10).
+    case 'state-timeout': return 1;
     default: return 50;
   }
 }
@@ -390,9 +401,13 @@ function buildOutcomeOfKind(
   switch (kind) {
     case 'enter':
     case 'wait':
-    case 'timeout':
       return { kind };
 
+    case 'state-timeout':
+      // Runtime-generated only (validateWorkflow rejects produces:'state-timeout').
+      // Break-fast backstop if an action somehow declares it.
+      throw new Error(`action produced reserved outcome kind "state-timeout" — runtime-generated only`);
+
     case 'message-sent':
       return { kind, text: primary?.message, receiverId: primary?.receiverId };
 
@@ -431,7 +446,7 @@ function buildOutcomeOfKind(
       const proposal: ProposalRef = ag
         ? { agreementId: ag.agreementId, agreement: ag }
         : { agreementId: result?.agreementId || '' };
-      return { kind, action: action_, proposal };
+      return { kind, action: action_, proposal, proposedByMe: false }; // turn path = our own agreement_respond ran — we are the responder, by definition not the proposer
     }
     case 'tool-result':
       return { kind, tool, result };
@@ -471,7 +486,12 @@ export function applyOutcomeToCtx(ctx: Ctx, outcome: Outcome): void {
       const t = outcome.task || ({} as TaskRef);
       const tid = t.taskId;
       const agId = t.agreementId || t.agreement?.agreementId;
-      if (tid && !ctx.delegatedTaskIds.includes(tid)) ctx.delegatedTaskIds.push(tid);
+      if (tid && !(tid in ctx.pendingSubtasks)) {
+        ctx.pendingSubtasks[tid] = {
+          agentId: t.assigneeId ?? t.executorId ?? t.agreement?.parties?.provider ?? null,
+          spawnedAt: Date.now(),
+        };
+      }
       if (agId && !ctx.delegatedAgreementIds.includes(agId)) ctx.delegatedAgreementIds.push(agId);
       return;
     }
@@ -500,7 +520,31 @@ export function applyOutcomeToCtx(ctx: Ctx, outcome: Outcome): void {
       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 (taskId) {
+        const pending = ctx.pendingSubtasks[taskId];
+        delete ctx.pendingSubtasks[taskId];
+        const payload = t?.result ?? null;
+        const existing = ctx.collectedResults.find(r => r.taskId === taskId);
+        if (!existing) {
+          ctx.collectedResults.push({
+            taskId,
+            agentId: pending?.agentId ?? t?.assigneeId ?? t?.executorId ?? t?.agreement?.parties?.provider ?? null,
+            status: outcome.status,
+            result: payload,
+          });
+        } else if (existing.result == null && payload != null) {
+          // A bare resource_changed(subtask_completed) skeleton ({taskId, state})
+          // can arrive BEFORE the full task_result for the same completion.
+          // Upgrade the placeholder in place instead of dropping the real payload.
+          // The skeleton often lacks executor identity, so also fill agentId
+          // from the fuller frame when the placeholder recorded none.
+          existing.status = outcome.status;
+          existing.result = payload;
+          if (existing.agentId == null) {
+            existing.agentId = t?.assigneeId ?? t?.executorId ?? t?.agreement?.parties?.provider ?? null;
+          }
+        }
+      }
       if (agId) ctx.delegatedAgreementIds = ctx.delegatedAgreementIds.filter(id => id !== agId);
       return;
     }
@@ -508,7 +552,8 @@ export function applyOutcomeToCtx(ctx: Ctx, outcome: Outcome): void {
       ctx.activeAgreementId = null;
       ctx.activeTaskId = null;
       ctx.pendingProposalAgreementId = null;
-      ctx.delegatedTaskIds = [];
+      ctx.pendingSubtasks = {};
+      ctx.collectedResults = [];
       ctx.delegatedAgreementIds = [];
       return;
     }

package/src/runtime/defaults.ts

@@ -1,4 +1,4 @@
-import type { Action, Transition, ThinkingState } from '../types.js';
+import type { Action, Ctx, MechanicalState, Outcome, Produces, Transition, ThinkingState } from '../types.js';
 
 /**
  * Defaults that workflow authors spread into thinking states explicitly.
@@ -73,3 +73,14 @@ export function defineThinkingState(
     transitions: [...state.transitions, ...dflt.transitions],
   };
 }
+
+/** ZIG-764: mechanical state — one tool call, zero LLM turns. */
+export function defineMechanicalState(state: {
+  tool: string;
+  args?: Record<string, unknown>;
+  buildArgs?: (ctx: Ctx, outcome: Outcome) => Record<string, unknown>;
+  produces: Produces;
+  transitions: Transition[];
+}): MechanicalState {
+  return { kind: 'mechanical', ...state };
+}

package/src/runtime/deriveRespondsToProposals.ts

@@ -0,0 +1,35 @@
+import type { State, ThinkingState, Workflow } from '../types.js';
+
+/**
+ * ZIG-826: true when the workflow exposes `agreement_respond` on a thinking
+ * action — the agent can approve/reject inbound proposals directed at it.
+ * Kickoff-only states (proposer-side approval → task_spawn) do not count.
+ */
+export function deriveRespondsToProposals(workflow: Workflow): boolean {
+  if (!workflow?.states) return false;
+  for (const state of Object.values(workflow.states)) {
+    if (state.kind !== 'thinking') continue;
+    const actions = (state as ThinkingState).actions;
+    if (!actions) continue;
+    for (const action of Object.values(actions)) {
+      if (action?.tool === 'agreement_respond') return true;
+    }
+  }
+  return false;
+}
+
+/** Scan custom states (pre-defineAgent) for agreement_respond actions. */
+export function statesRespondToProposals(
+  states: Record<string, State> | undefined,
+): boolean {
+  if (!states) return false;
+  for (const state of Object.values(states)) {
+    if (state.kind !== 'thinking') continue;
+    const actions = (state as ThinkingState).actions;
+    if (!actions) continue;
+    for (const action of Object.values(actions)) {
+      if (action?.tool === 'agreement_respond') return true;
+    }
+  }
+  return false;
+}