@ziggs-ai/agent-sdk 0.1.9 → 0.1.11

package/src/agent/Agent.ts

@@ -40,6 +40,8 @@ export interface TickOutput {
   state: string;
   /** Whether the machine settled at a parked state. */
   parked: boolean;
+  /** True when a state-timeout outcome matched no transition this tick — the host must NOT re-arm. */
+  stateTimeoutUnhandled: boolean;
   /** Accumulated LLM call count and token usage for this tick. */
   metrics: { llmCalls: number; tokens: { total: number; input: number; output: number } };
 }
@@ -95,6 +97,7 @@ export class Agent {
       ctx: machine.ctx,
       state: machine.state,
       parked: machine.isParked,
+      stateTimeoutUnhandled: machine.stateTimeoutUnhandled,
       metrics: { llmCalls: machine.llmCalls, tokens: machine.tokens },
     };
   }

package/src/defineAgent.ts

@@ -1,12 +1,16 @@
 import type { AgentConfig, DefineAgentInput, Workflow } from './types.js';
 import { validateWorkflow } from './runtime/validateWorkflow.js';
+import { injectKickoffDefault } from './runtime/kickoff.js';
 import { runtimeLog } from './shared/runtimeLog.js';
 
 /**
  * Validates the workflow synchronously, resolves merged tools and model, and
- * returns a frozen AgentConfig. Does NOT mutate the input — `wait` action and
- * `activeWait` transitions are the workflow author's responsibility (visible
- * spread of `thinkingDefaults`).
+ * returns a frozen AgentConfig. Never mutates the input. `wait` defaults remain
+ * the author's visible spread of `thinkingDefaults`. ONE default is injected (as
+ * new objects): the agreement-kickoff state `kickingOff` plus a last-position
+ * transition into it, appended to every state that does not already handle a
+ * proposer-side proposal-resolved/approve outcome (runtime/kickoff.ts). The
+ * state name 'kickingOff' is reserved; defining it throws.
  *
  * Validation throws WorkflowValidationError on hard problems and logs warnings
  * on soft ones (e.g. missing wait fallthrough).
@@ -17,12 +21,14 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
   if (!input?.states) throw new Error('[defineAgent] states is required');
   if (!input?.initial) throw new Error('[defineAgent] initial state is required');
 
-  const workflow: Workflow = {
+  // Agreement-kickoff default (see runtime/kickoff.ts): injected BEFORE
+  // validation so the injected state/transitions are validated too.
+  const workflow: Workflow = injectKickoffDefault({
     id: input.agentId,
     description: input.description,
     initial: input.initial,
     states: input.states,
-  };
+  });
 
   const { warnings } = validateWorkflow(workflow);
   for (const w of warnings) runtimeLog.warn('defineAgent', w);
@@ -34,6 +40,7 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
 
   const model =
     input.services?.llm?.model ||
+    process.env.LLM_MODEL ||
     process.env.OPENAI_MODEL ||
     'gpt-5.4';
 
@@ -46,6 +53,7 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
 
   const config: AgentConfig = {
     openaiKey: process.env.OPENAI_API_KEY,
+    anthropicKey: process.env.ANTHROPIC_API_KEY,
     ...(operatorKey ? { operatorKey } : {}),
     agentId,
     description,

package/src/index.ts

@@ -9,7 +9,7 @@
  */
 
 export { defineAgent } from './defineAgent.js';
-export { createMcpAgent } from './adapters/McpAdapter.js';
+export { createMcpAgent, resolveZiggsGatewayTarget, wrapGatewayFetch, ZiggsGatewayError } from './adapters/McpAdapter.js';
 export type { CreateMcpAgentOptions, McpAgentHandle, McpTransportConfig } from './adapters/McpAdapter.js';
 export { AgentHost, createAgent, createAgentPool } from './AgentHost.js';
 export { Agent } from './agent/Agent.js';
@@ -18,6 +18,8 @@ export type { SessionResolver, AgentHostOptions } from './AgentHost.js';
 export { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
 export type { ZiggsEffectDeps } from './server/ZiggsEffectHandler.js';
 export { EventQueue } from './server/EventQueue.js';
+export { StateTimers } from './server/StateTimers.js';
+export type { StateTimeoutEvent } from './server/StateTimers.js';
 export { OutboxBuffer } from './server/OutboxBuffer.js';
 export { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
 
@@ -26,6 +28,7 @@ export { AgentMachine, type TransitionEvent } from './runtime/AgentMachine.js';
 export { runTurn } from './runtime/runTurn.js';
 export { PromptBuilder } from './runtime/PromptBuilder.js';
 export { thinkingDefaults, defineThinkingState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
+export { KICKOFF_STATE, injectKickoffDefault, buildKickoffState } from './runtime/kickoff.js';
 export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
 

package/src/pricing/fleetTierByAgentId.gen.ts

@@ -17,6 +17,13 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "shopper-agent": "D",
   "hire-agent": "B",
   "ziggs-docs-agent": "B",
+  "relay-coordinator": "D",
+  "relay-intake-worker": "D",
+  "relay-work-worker": "D",
+  "relay-deliver-worker": "D",
+  "retry-coordinator": "D",
+  "retry-fail-worker": "D",
+  "retry-ok-worker": "D",
   "weather-forecaster": "A",
   "climate-data-analyst": "A",
   "air-quality-monitor": "A",
@@ -25,6 +32,8 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "uv-index-advisor": "A",
   "pollen-tracker": "A",
   "marine-weather-reporter": "A",
+  "us-alerts-monitor": "A",
+  "daylight-tracker": "A",
   "stock-market-analyst": "A",
   "crypto-tracker": "A",
   "forex-monitor": "A",
@@ -40,12 +49,16 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "world-news-briefer": "A",
   "business-news-analyst": "A",
   "reddit-trend-spotter": "A",
+  "tech-news-digest": "A",
+  "news-searcher": "A",
+  "subreddit-pulse": "A",
   "science-news-reporter": "A",
   "sports-score-tracker": "A",
   "breaking-news-alert": "A",
   "wikipedia-researcher": "A",
   "book-finder": "A",
   "dictionary-thesaurus": "A",
+  "wikidata-explorer": "A",
   "trivia-master": "A",
   "poetry-curator": "A",
   "quote-finder": "A",
@@ -75,6 +88,8 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "distance-calculator": "A",
   "place-finder": "A",
   "ip-geolocator": "A",
+  "postal-code-resolver": "A",
+  "brewery-finder": "A",
   "astronomy-photo-curator": "A",
   "mars-rover-explorer": "A",
   "neo-tracker": "A",
@@ -83,9 +98,16 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "exoplanet-explorer": "A",
   "drug-interaction-checker": "A",
   "solar-system-explorer": "A",
+  "species-lookup": "A",
+  "census-analyst": "A",
+  "river-monitor": "A",
+  "fbi-wanted-monitor": "A",
   "github-repo-analyst": "A",
   "github-issue-tracker": "A",
   "github-pr-reviewer": "A",
+  "package-inspector": "A",
+  "service-status-checker": "A",
+  "password-safety-checker": "A",
   "ip-analyst": "A",
   "qr-code-generator": "A",
   "http-debugger": "A",
@@ -117,6 +139,9 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "uuid-generator": "A",
   "hash-calculator": "A",
   "base64-encoder": "A",
+  "card-dealer": "A",
+  "world-clock": "A",
+  "link-unfurler": "A",
   "code-reviewer": "B",
   "bug-finder": "B",
   "refactoring-advisor": "B",
@@ -141,6 +166,30 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "stack-trace-analyzer": "B",
   "commit-message-writer": "B",
   "schema-designer": "B",
+  "name-brainstormer": "B",
+  "term-explainer": "B",
+  "pros-cons-lister": "B",
+  "decision-matrix-builder": "B",
+  "checklist-generator": "B",
+  "config-converter": "B",
+  "csv-to-table": "B",
+  "markup-converter": "B",
+  "case-converter": "B",
+  "color-converter": "B",
+  "timestamp-humanizer": "B",
+  "text-summarizer": "B",
+  "notes-cleaner": "B",
+  "audience-rewriter": "B",
+  "text-reformatter": "B",
+  "json-fixer": "B",
+  "sql-explainer": "B",
+  "regex-writer": "B",
+  "cron-explainer": "B",
+  "curl-converter": "B",
+  "changelog-writer": "B",
+  "stacktrace-explainer": "B",
+  "diff-explainer": "B",
+  "scaffold-generator": "B",
   "copywriter": "B",
   "technical-writer": "B",
   "blog-post-drafter": "B",
@@ -270,6 +319,9 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "feature-prioritizer": "C",
   "threat-model-committee": "C",
   "negotiation-simulator": "C",
+  "trip-desk": "C",
+  "tech-radar-brief": "C",
+  "market-open-brief": "C",
   "aristotle": "B",
   "plato": "B",
   "confucius": "B",
@@ -720,4 +772,4 @@ export const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier> = {
   "death-studies-scholar": "B"
 } as Record<string, FleetPricingTier>;
 
-export const FLEET_TIER_MAP_SIZE = 713;
+export const FLEET_TIER_MAP_SIZE = 765;

package/src/runtime/AgentMachine.ts

@@ -16,7 +16,8 @@ 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: 'error-escape'; fromState: string; toState: string }
+  | { kind: 'timeout-unhandled'; state: string; waitedMs: number };
 
 interface MachineInput {
   identity: Identity;
@@ -78,10 +79,12 @@ export class AgentMachine {
   _llmCalls = 0;
   _tokens = { total: 0, input: 0, output: 0 };
   _lastUserSenderId: string | null = null;
+  _stateTimeoutUnhandled = false;
   _transitionTap: ((event: TransitionEvent) => void) | undefined;
 
   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) {
     this.workflow = workflow;
@@ -93,14 +96,23 @@ export class AgentMachine {
     this._transitionTap = transitionTap;
     this.state = input.state || workflow.initial;
     this.ctx = input.ctx
-      ? { ...input.ctx, identity: input.identity }
+      ? {
+          ...input.ctx,
+          identity: input.identity,
+          // Sessions persisted before pendingSubtasks/collectedResults existed
+          // (DynamoDB rows live up to SESSION_TTL_SECONDS = 24h) restore without
+          // these fields. Default them ONCE here — nowhere else.
+          pendingSubtasks: input.ctx.pendingSubtasks ?? {},
+          collectedResults: input.ctx.collectedResults ?? [],
+        }
       : {
           identity: input.identity,
           activeAgreementId: null,
           activeTaskId: null,
           pendingProposalAgreementId: null,
           delegatedAgreementIds: [],
-          delegatedTaskIds: [],
+          pendingSubtasks: {},
+          collectedResults: [],
           toolResults: [],
           lastOutcome: { kind: 'enter' },
         };
@@ -172,13 +184,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 +216,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') {
@@ -217,7 +252,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})`,
@@ -299,7 +334,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 +347,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';
@@ -151,6 +151,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 +176,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>';
 

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/kickoff.ts

@@ -0,0 +1,117 @@
+import type { Outcome, State, ThinkingState, Transition, Workflow } from '../types.js';
+import { thinkingDefaults } from './defaults.js';
+import { PROBE_CTX } from './validateWorkflow.js';
+
+/** Reserved state name for the injected agreement-kickoff default. */
+export const KICKOFF_STATE = 'kickingOff';
+
+// Synthetic outcome used to ask "does this state already handle a proposer-side
+// approval?" — the same probe pattern validateWorkflow uses for the wait/error
+// fallthrough checks.
+const PROBE_APPROVE: Outcome = {
+  kind: 'proposal-resolved',
+  action: 'approve',
+  proposal: { agreementId: '__kickoff_probe__' },
+  proposedByMe: true,
+};
+
+const KICKOFF_TRANSITION: Transition = {
+  to: KICKOFF_STATE,
+  when: (o, ctx) =>
+    o.kind === 'proposal-resolved' &&
+    o.action === 'approve' &&
+    o.proposedByMe === true &&
+    // "first task" guard — both branches cover one exact scenario: a task under
+    // THIS agreement already exists because a racing task_result frame was
+    // applied to ctx before this approval frame.
+    // (1) we already delegated under it:
+    !ctx.delegatedAgreementIds.includes(o.proposal.agreementId) &&
+    // (2) we already hold an assigned task bound to it (task-assigned sets
+    // activeTaskId + activeAgreementId together in applyOutcomeToCtx):
+    !(ctx.activeTaskId !== null && ctx.activeAgreementId === o.proposal.agreementId),
+};
+
+// A state "handles" proposer-approval if some transition would fire for it.
+// An unconditional (when-less) transition counts: it catches every outcome,
+// so the kickoff transition — appended LAST — would be unreachable dead code
+// there anyway. Consequence to know: a state whose only route for a
+// proposal-resolved/approve is an unconditional fallthrough to an UNRELATED
+// state will NOT auto-kickoff (the approval follows the fallthrough instead).
+// Authors who want guaranteed kickoff in such a state must add an explicit
+// `when: o => o.kind === 'proposal-resolved' && o.action === 'approve'`
+// transition (which this probe then respects) — or route approval into a
+// thinking state that spawns the task itself.
+function stateHandlesProposerApproval(state: State): boolean {
+  return state.transitions.some(t => {
+    if (!t.when) return true;
+    try { return !!t.when(PROBE_APPROVE, PROBE_CTX); }
+    catch { return false; }
+  });
+}
+
+export function buildKickoffState(initial: string): ThinkingState {
+  const dflt = thinkingDefaults({ initial });
+  return {
+    kind: 'thinking',
+    prompt: {
+      role: 'The counterparty just approved an agreement you proposed. The platform never auto-starts work — as the proposer, you spawn the first task now.',
+      goal: 'Spawn exactly one task under the just-approved agreement so work begins.',
+      constraints:
+        'The approved agreement id is in <event> and as activeAgreementId in <machine_context>; the agreement row is in <agreements>. Call task_spawn with that agreementId and a description of the concrete work the agreement covers. Include ALL specifics the counterparty provided in <history> (addresses, quantities, times, item names, deliverables) — the executor has no other way to get them. Plain natural language, no step numbering. Do not re-negotiate — the agreement is active. Do not send a chat message instead of spawning. If <agreements> or <history> show a task already running under this agreement, choose wait.',
+    },
+    actions: {
+      ...dflt.actions,
+      spawnFirstTask: {
+        prompt: {
+          when: 'Always — this state exists only to spawn the first task under the agreement whose proposal was just approved. Pick wait only if a task already exists under it.',
+          instruction: 'Spawn the first task under the approved agreement so work starts.',
+          format: '{"agreementId": "<the agreement whose proposal was just approved>", "description": "<concrete work + all counterparty specifics from history>"}',
+        },
+        tool: 'task_spawn',
+        // Function form so a failed task_spawn surfaces as an error outcome
+        // (→ dflt error transition + machine warn log) instead of a fake
+        // task-delegated with an empty task.
+        produces: (result) => {
+          const r = result as { taskId?: string; task?: { taskId?: string } } | undefined;
+          return r?.taskId || r?.task?.taskId ? 'task-delegated' : 'error';
+        },
+        terminatesLoop: true,
+      },
+    },
+    transitions: [
+      { to: initial, when: o => o.kind === 'task-delegated' },
+      ...dflt.transitions, // wait / message-sent / error → initial
+    ],
+  };
+}
+
+/**
+ * Agreement-kickoff default. For every state whose transitions do not already
+ * match a proposer-side approval (probe above), append a transition to the
+ * injected `kickingOff` state. Appended LAST so any user transition on the same
+ * outcome always wins (first match wins in AgentMachine._evaluateTransitions).
+ * Returns a NEW workflow — input states are not mutated. After kickoff the
+ * machine returns to `initial`; when this agent is itself the provider the
+ * backend then assigns the spawned task back to it as a normal task-assigned
+ * event, which the author's existing work loop handles.
+ */
+export function injectKickoffDefault(workflow: Workflow): Workflow {
+  if (workflow.states[KICKOFF_STATE]) {
+    throw new Error(
+      `[defineAgent] state name "${KICKOFF_STATE}" is reserved for the injected agreement-kickoff default — rename the state`,
+    );
+  }
+  const states: Record<string, State> = {};
+  let injected = false;
+  for (const [name, state] of Object.entries(workflow.states)) {
+    if (stateHandlesProposerApproval(state)) {
+      states[name] = state;
+      continue;
+    }
+    states[name] = { ...state, transitions: [...state.transitions, KICKOFF_TRANSITION] } as State;
+    injected = true;
+  }
+  if (!injected) return workflow; // every state handles approval — nothing to add, no dead state
+  states[KICKOFF_STATE] = buildKickoffState(workflow.initial);
+  return { ...workflow, states };
+}