@ziggs-ai/agent-sdk 0.1.10 → 0.1.12

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

@@ -1,5 +1,6 @@
 import type { AgreementService } from '../../agreements/AgreementService.js';
 import type { TaskService } from '../../tasks/TaskService.js';
+import type { ContextReadClient } from '@ziggs-ai/api-client';
 import {
   applyFleetCounterPricing,
   applyFleetPricingForProtocol,
@@ -15,6 +16,7 @@ function normalizeState(state: string): string {
 interface Services {
   agreementService: AgreementService;
   taskService: TaskService;
+  contextReadClient: ContextReadClient;
 }
 
 interface ProtocolPayload {
@@ -22,6 +24,7 @@ interface ProtocolPayload {
   agreementId?: string;
   description?: string;
   proposedTo?: string;
+  providerId?: string;
   executorId?: string;
   action?: 'approve' | 'reject';
   price?: number;
@@ -32,6 +35,7 @@ interface ProtocolPayload {
   parentAgreementId?: string;
   parentTaskId?: string;
   taskId?: string;
+  stepId?: string;
   assigneeId?: string;
   status?: string;
   result?: unknown;
@@ -43,6 +47,39 @@ interface ProtocolPayload {
   [key: string]: unknown;
 }
 
+// ZIG-793: the `plan` tool-schema is underspecified (`plan: {type:'object'}`,
+// `planReviewTiming: 'string'`), so the LLM emits steps missing stepId/order and an
+// out-of-enum planReviewTiming, which the backend DTO rejects. Normalize in-place here
+// so every op (propose / subcontract / counter / task-spawn) sends a valid plan.
+function normalizePlanInPlace(payload: ProtocolPayload): void {
+  const plan = payload.plan as { steps?: unknown } | undefined;
+  if (plan && Array.isArray(plan.steps)) {
+    plan.steps = plan.steps.map((s, i) => {
+      const step =
+        s && typeof s === 'object'
+          ? (s as Record<string, unknown>)
+          : { description: String(s) };
+      return {
+        ...step,
+        stepId:
+          typeof step.stepId === 'string' && step.stepId ? step.stepId : `step-${i + 1}`,
+        order: typeof step.order === 'number' ? step.order : i,
+        description:
+          typeof step.description === 'string'
+            ? step.description
+            : String(step.description ?? ''),
+      };
+    });
+  }
+  if (
+    payload.planReviewTiming !== undefined &&
+    payload.planReviewTiming !== 'with_proposal' &&
+    payload.planReviewTiming !== 'before_execution'
+  ) {
+    payload.planReviewTiming = 'with_proposal';
+  }
+}
+
 export async function dispatchProtocolOp(
   services: Services,
   payload: ProtocolPayload,
@@ -51,6 +88,7 @@ export async function dispatchProtocolOp(
   actingAgentId: string | null = null,
 ): Promise<unknown> {
   if (!payload?.operation) return null;
+  normalizePlanInPlace(payload);
   const { operation } = payload;
   const { agreementService, taskService } = services;
   const actorId = actingAgentId?.trim() || null;
@@ -88,21 +126,100 @@ export async function dispatchProtocolOp(
     case 'agreement-revoke':
       if (!payload.agreementId) return null;
       return agreementService.revoke(payload.agreementId);
-    case 'task-spawn':
+    case 'agreement-fulfill':
+      if (!payload.agreementId) return null;
+      return agreementService.fulfill(payload.agreementId);
+    case 'task-spawn': {
       if (!payload.agreementId || !payload.description) return null;
-      return taskService.spawnUnderAgreement(payload.agreementId, {
+      let spawnAgreementId = payload.agreementId;
+      const ags = await agreementsInChat(services, chatId);
+      // b2 (ZIG-832): if the assignee is not a party on the cited agreement,
+      // redirect the spawn to the ACTIVE sub-agreement (same root) where the
+      // assignee IS the provider — the orchestrator often cites the top-level
+      // hire, which the backend rejects with "assignee not a party".
+      // ZIG-858: also redirect when the cited agreement is no longer active —
+      // a count-bound sub fulfills after its quota (default 1), and the LLM
+      // keeps citing that now-terminal sub for the next spawn even when a
+      // fresh active sub for the same executor exists.
+      if (payload.assigneeId) {
+        const cited = ags.find((a) => a.agreementId === payload.agreementId);
+        if (cited && (!agIsParty(cited, payload.assigneeId) || !agIsActiveStatus(cited))) {
+          const root = cited.rootAgreementId || payload.agreementId;
+          const sub = ags.find(
+            (a) => agIsActiveStatus(a) && agIsProvider(a, payload.assigneeId as string) &&
+              (a.rootAgreementId === root || a.parentAgreementId === payload.agreementId ||
+                a.parentAgreementId === root),
+          );
+          if (sub?.agreementId) spawnAgreementId = sub.agreementId;
+        }
+      }
+      // Safety guard (ZIG-832, B): a spawn against an agreement that is not active,
+      // or whose assignee is not a party on it, hard-400s at the backend AND makes
+      // the worker invent a "connection needed" message. That happens when the
+      // orchestrator spawns before its sub-agreement is subcontracted/approved.
+      // Skip GRACEFULLY instead — the sub-agreement's activation event will wake
+      // the orchestrator to spawn correctly on a later turn, no 400, no cascade.
+      const target = ags.find((a) => a.agreementId === spawnAgreementId);
+      // ZIG-858: a TERMINAL target is not the same as a not-yet-active one — no
+      // activation event will ever arrive, so the "wait for a later turn" skip
+      // below would stall the run. Tell the caller the actionable next step:
+      // subcontract a fresh sub for this executor, then spawn under it.
+      if (target && TERMINAL_STATUS.has(String(target.status))) {
+        return {
+          ok: false,
+          skipped: 'spawn-target-terminal',
+          reason: `agreement ${spawnAgreementId} is ${target.status} (terminal — its quota or term is exhausted). Subcontract a new sub-agreement to ${payload.assigneeId ?? 'the executor'}, then spawn this task under that new agreement.`,
+          agreementId: spawnAgreementId,
+        };
+      }
+      const notReady =
+        (target && !agIsActiveStatus(target)) ||
+        (!!payload.assigneeId && target && !agIsParty(target, payload.assigneeId));
+      if (notReady) {
+        return {
+          ok: false,
+          skipped: 'spawn-target-not-ready',
+          reason: target && !agIsActiveStatus(target)
+            ? `agreement ${spawnAgreementId} is ${target?.status ?? 'unknown'} (not active yet)`
+            : `assignee is not a party on ${spawnAgreementId} yet — subcontract to it first`,
+          agreementId: spawnAgreementId,
+        };
+      }
+      return taskService.spawnUnderAgreement(spawnAgreementId, {
         description: payload.description,
         parentTaskId: payload.parentTaskId,
         plan: payload.plan,
         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`');
+      // ZIG-793: a plan-step tick is cosmetic progress. Worker subtasks usually
+      // have NO plan (only the orchestrator's job task does), and the LLM may tick
+      // a stepId that isn't in the plan — the backend 400s on both. That must never
+      // hard-fail the tool → fail the task → wake-loop. Make it best-effort.
+      try {
+        return await taskService.updatePlanStep(
+          payload.taskId,
+          payload.stepId,
+          payload.status,
+          payload.result,
+        );
+      } catch {
+        return { ok: false, skipped: 'plan-step-not-updatable', stepId: payload.stepId };
+      }
     default:
-      return null;
+      throw new Error(`Unknown protocol operation: ${operation}`);
   }
 }
 
@@ -115,11 +232,64 @@ async function proposeAgreement(
 ): Promise<unknown> {
   if (!payload.description) throw new Error('agreement-propose requires `description`');
   if (!payload.proposedTo) throw new Error('agreement-propose requires `proposedTo` (userId or agentId). To spawn a task under an existing agreement, use `task_spawn` instead.');
+  const isBroadcast = payload.proposedTo === 'everyone' || payload.proposedTo === 'org';
+  if (!isBroadcast && !payload.providerId) {
+    throw new Error(
+      'agreement-propose requires `providerId` — name who does the work: your own id (you are offering to work) or the proposedTo id (you are commissioning the recipient).',
+    );
+  }
+  if (isBroadcast && payload.providerId) {
+    throw new Error(
+      'agreement-propose forbids `providerId` on a broadcast — the claiming agent fills the open side.',
+    );
+  }
   const priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
   const { operation: _op, ...fields } = priced;
   return services.agreementService.propose({ ...fields, chatId } as Parameters<typeof services.agreementService.propose>[0]);
 }
 
+// ── ZIG-832: deterministic sub-agreement resolution ─────────────────────────
+// The orchestrator delegates one task per worker, but the LLM inconsistently
+// (a) re-subcontracts the same worker (duplicate sub-agreements) and (b)
+// task_spawns a worker under the TOP-LEVEL hire — where the worker is not a
+// party — instead of under that worker's sub-agreement, which the backend
+// rejects with 400 "assignee is not a party". Both are made deterministic here
+// using the chat's existing agreements.
+const TERMINAL_STATUS = new Set(['fulfilled', 'cancelled', 'refunded', 'rejected']);
+type AgLike = Record<string, unknown> & {
+  agreementId?: string; status?: string; rootAgreementId?: string;
+  parentAgreementId?: string; parties?: Record<string, unknown>;
+};
+async function agreementsInChat(services: Services, chatId: string | null): Promise<AgLike[]> {
+  if (!chatId) return [];
+  try {
+    const snap = await services.contextReadClient.snapshot(chatId, { maxMessages: 1 });
+    const ags = snap.agreements;
+    return Array.isArray(ags) ? (ags as AgLike[]) : [];
+  } catch {
+    return [];
+  }
+}
+function agIsProvider(a: AgLike, agentId: string): boolean {
+  const p = a.parties ?? {};
+  return p['provider'] === agentId || p['providerAgent'] === agentId || a['providerId'] === agentId;
+}
+function agIsParty(a: AgLike, agentId: string): boolean {
+  const p = a.parties ?? {};
+  return ['provider', 'providerAgent', 'payer', 'proposedTo', 'creator', 'creatorAgent']
+    .some((k) => p[k] === agentId);
+}
+function agActive(a: AgLike): boolean {
+  return !a.status || !TERMINAL_STATUS.has(String(a.status));
+}
+// Spawnable = actually ACTIVE. A freshly-subcontracted sub is `draft` until its
+// counterparty auto-approves; spawning under a draft (or citing an agreement the
+// assignee isn't a party on) 400s and cascades into a bogus worker "connection
+// needed" message. We treat only 'active' as spawnable (ZIG-832).
+function agIsActiveStatus(a: AgLike): boolean {
+  return String(a.status ?? '') === 'active';
+}
+
 async function subcontractAgreement(
   services: Services,
   payload: ProtocolPayload,
@@ -128,8 +298,56 @@ async function subcontractAgreement(
   actingAgentId: string | null,
 ): Promise<unknown> {
   if (!payload.description || !payload.executorId) return null;
+  // b1 (ZIG-832): idempotent subcontract — if a non-terminal sub-agreement for
+  // this executor already exists under the same parent, reuse it instead of
+  // creating a duplicate (which bloats the chain and blocks the fulfill cascade).
+  if (chatId) {
+    const parent = payload.parentAgreementId;
+    const existing = (await agreementsInChat(services, chatId)).find(
+      (a) => agActive(a) && agIsProvider(a, payload.executorId as string) &&
+        (!parent || a.parentAgreementId === parent || a.rootAgreementId === parent),
+    );
+    if (existing?.agreementId) return existing;
+  }
   const priced = applyFleetPricingForProtocol('agreement-subcontract', payload, actingAgentId);
   const { operation: _op, ...fields } = priced;
+  // ZIG-832: a subcontract must carry a working close condition, or it hangs
+  // 'active' forever — and because the backend only auto-fulfills a parent hire
+  // once every child sub-agreement is terminal (the fulfill cascade), one
+  // never-closing child leaves the whole engagement open. Deciding lifecycle is
+  // left to the model, which under load (context bloat, competing wakes) emits
+  // incomplete terms — e.g. time-bound with no expiresAt and no maxExecutions —
+  // that never reach fulfillment. Make the common single-delegated-task case
+  // deterministic: if the caller gave neither a real quota nor a real deadline,
+  // treat it as one count-bound execution so completing that task closes the
+  // sub — which then cascades the parent closed. A genuinely durable subcontract
+  // still opts out by setting maxExecutions>1 or a time-bound expiresAt.
+  const f = fields as { lifecycle?: string; maxExecutions?: number | string; expiresAt?: string };
+  // ZIG-858: repair incomplete terms instead of clobbering them. The model
+  // often emits a real quota or deadline but gets the envelope wrong — a
+  // numeric-string maxExecutions, or a quota/deadline with the lifecycle field
+  // missing or mismatched. The old check treated all of those as "no close
+  // condition" and forced count-bound/1, silently discarding the stated intent
+  // (e.g. maxExecutions=2 → 1, so the sub fulfills one task early and the next
+  // spawn under it fails).
+  if (typeof f.maxExecutions === 'string' && f.maxExecutions.trim() !== '' && Number.isFinite(Number(f.maxExecutions))) {
+    f.maxExecutions = Number(f.maxExecutions);
+  }
+  const hasQuota = typeof f.maxExecutions === 'number' && f.maxExecutions > 0;
+  const hasDeadline = typeof f.expiresAt === 'string' && f.expiresAt.length > 0;
+  if (f.lifecycle === 'count-bound' && hasQuota) {
+    // coherent as stated
+  } else if (f.lifecycle === 'time-bound' && hasDeadline) {
+    // coherent as stated
+  } else if (hasQuota) {
+    f.lifecycle = 'count-bound'; // quota given, lifecycle missing/mismatched — keep the quota
+  } else if (hasDeadline) {
+    f.lifecycle = 'time-bound'; // deadline given, lifecycle missing/mismatched — keep the deadline
+  } else {
+    // no usable close condition at all — the deterministic single-task default
+    f.lifecycle = 'count-bound';
+    f.maxExecutions = 1;
+  }
   return services.agreementService.delegate({ ...fields, chatId } as Parameters<typeof services.agreementService.delegate>[0]);
 }
 

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

@@ -2,10 +2,12 @@ import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
 import { dispatchProtocolOp } from './protocolRunner.js';
 import type { AgreementService } from '../../agreements/AgreementService.js';
 import type { TaskService } from '../../tasks/TaskService.js';
+import type { ContextReadClient } from '@ziggs-ai/api-client';
 
 interface ToolContext extends Record<string, unknown> {
   taskService: TaskService;
   agreementService: AgreementService;
+  contextReadClient: ContextReadClient;
   chatId?: string | null;
   agents?: unknown[];
   /** Acting agent (ZIG-368 default pricing). */
@@ -17,8 +19,13 @@ function handlerFor(operation: string) {
     const c = ctx as ToolContext;
     if (!c.taskService) throw new Error('taskService missing from tool context (expected when running under Agent)');
     if (!c.agreementService) throw new Error('agreementService missing from tool context (expected when running under Agent)');
+    if (!c.contextReadClient) throw new Error('contextReadClient missing from tool context (expected when running under Agent)');
     const result = await dispatchProtocolOp(
-      { taskService: c.taskService, agreementService: c.agreementService },
+      {
+        taskService: c.taskService,
+        agreementService: c.agreementService,
+        contextReadClient: c.contextReadClient,
+      },
       { operation, ...args },
       c.chatId ?? null,
       c.agents ?? [],
@@ -31,9 +38,9 @@ function handlerFor(operation: string) {
 
 export const agreementProposeTool: ToolDefinition = defineTool(
   'agreement_propose',
-  { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service when omitted.' }, parentAgreementId: 'string', parentTaskId: 'string', payerId: 'string', providerId: 'string', price: 'number', lifecycle: 'string', expiresAt: 'string', maxExecutions: 'number', agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' },
+  { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service when omitted.' }, parentAgreementId: 'string', parentTaskId: 'string', providerId: { type: 'string', description: 'Who does the work — required on direct proposals, forbidden on broadcasts (the claiming agent fills the open side). Pass your own id when YOU are offering to do the work, or the proposedTo id when you are commissioning the RECIPIENT. Naming any other third party requires that party to have a matching published offer. The payer is always derived as the non-providing side.' }, price: 'number', lifecycle: 'string', expiresAt: 'string', maxExecutions: 'number', agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' },
   handlerFor('agreement-propose'),
-  { description: 'Propose a contract to a user, agent, or as an open broadcast. For a broadcast set proposedTo="everyone" (fully public — any agent may claim) or proposedTo="org" (scoped to your org — only members of your org see and claim it). engagementKind defaults to service.', isAgreementCreation: true },
+  { description: 'Propose a contract to a user, agent, or as an open broadcast. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay"). Required on direct proposals; omit it only for a broadcast — proposedTo="everyone" (fully public — any agent may claim) or proposedTo="org" (scoped to your org). engagementKind defaults to service.', isAgreementCreation: true },
 );
 
 export const agreementSubcontractTool: ToolDefinition = defineTool(
@@ -78,6 +85,13 @@ export const agreementRevokeTool: ToolDefinition = defineTool(
   { description: 'Revoke a pending proposal you created so it can no longer be approved. Use when the user has clearly moved on to a different request before responding to the previous proposal card.' },
 );
 
+export const agreementFulfillTool: ToolDefinition = defineTool(
+  'agreement_fulfill',
+  { agreementId: { type: 'string', required: true } },
+  handlerFor('agreement-fulfill'),
+  { description: 'Mark an agreement you provide as fulfilled (complete) once its work is delivered — closes the engagement so it no longer reads as in-progress. Use on your hire after the final deliverable is done and delivered to the human.' },
+);
+
 export const taskUpdatePlanStepTool: ToolDefinition = defineTool(
   'task_update_plan_step',
   { taskId: { type: 'string', required: true }, stepId: { type: 'string', required: true }, status: { type: 'string', required: true }, result: 'string' },
@@ -87,7 +101,7 @@ export const taskUpdatePlanStepTool: ToolDefinition = defineTool(
 
 export const taskSpawnTool: ToolDefinition = defineTool(
   'task_spawn',
-  { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', assigneeId: { type: 'string', description: 'Explicitly hand this task to one specific agent (e.g. a worker your orchestrator selected via agent search) instead of leaving it unassigned. Must be a party on the agreement (payer, provider, creator, or creator agent).' }, plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' },
+  { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', assigneeId: { type: 'string', description: 'Explicitly hand this task to one specific agent (e.g. a worker your orchestrator selected via agent search) instead of leaving it unassigned. Must be a party on the agreement (payer, provider, creator, or creator agent).' }, inputArtifactIds: { type: 'array', items: { type: 'string' }, description: 'ZIG-734: prior-step output artifact handles for structured input links.' }, plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' },
   handlerFor('task-spawn'),
   { description: 'Spawn a new task under an existing approved agreement. Use when the contract is already in place. Pass assigneeId to delegate the task to a specific agent rather than leaving it open.' },
 );
@@ -95,5 +109,6 @@ export const taskSpawnTool: ToolDefinition = defineTool(
 export const PROTOCOL_TOOLS: ToolDefinition[] = [
   agreementProposeTool, agreementSubcontractTool,
   agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool, agreementRevokeTool,
+  agreementFulfillTool,
   taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool,
 ];

package/src/types.ts

@@ -26,6 +26,10 @@ export interface TaskRef {
   state?: string;
   description?: string;
   parentTaskId?: string;
+  executorId?: string;
+  assigneeId?: string | null;
+  /** Work product set by task_update (safeJsonStringify'd string on the wire). */
+  result?: unknown;
   proposal?: { status?: 'pending' | 'approved' | 'rejected' | 'cancelled' };
   proposedToIsYou?: boolean;
   providerIsYou?: boolean;
@@ -43,7 +47,7 @@ export interface ProposalRef {
 export type OutcomeKind =
   | 'enter'
   | 'wait'
-  | 'timeout'
+  | 'state-timeout'
   | 'message-sent'
   | 'message-received'
   | 'task-assigned'
@@ -59,7 +63,7 @@ export type OutcomeKind =
 export type Outcome =
   | { kind: 'enter' }
   | { kind: 'wait' }
-  | { kind: 'timeout' }
+  | { kind: 'state-timeout'; state: string; waitedMs: number }
   | { kind: 'message-sent'; text?: string; receiverId?: string }
   | { kind: 'message-received'; text?: string; senderId?: string; senderType?: string }
   | { kind: 'task-assigned'; task: TaskRef }
@@ -67,7 +71,20 @@ export type Outcome =
   | { kind: 'task-closed'; status: 'completed' | 'failed'; result?: unknown }
   | { kind: 'subtask-finished'; status: 'completed' | 'failed'; task: TaskRef; result?: unknown }
   | { kind: 'proposal-made'; proposal: ProposalRef }
-  | { kind: 'proposal-resolved'; action: 'approve' | 'reject'; proposal: ProposalRef }
+  | {
+      kind: 'proposal-resolved';
+      action: 'approve' | 'reject';
+      proposal: ProposalRef;
+      /**
+       * True when THIS agent made the proposal being resolved. Computed in
+       * AgentMachine._handleFrame by matching proposal.agreementId against
+       * ctx.pendingProposalAgreementId BEFORE applyOutcomeToCtx clears it —
+       * wire frames carry no trustworthy proposer field (agreement_lifecycle
+       * drops `parties` at ingress, and parties.creator is a principal id,
+       * not an agentId). Drives the injected agreement-kickoff default.
+       */
+      proposedByMe: boolean;
+    }
   | { kind: 'tool-result'; tool: string; result: unknown }
   | {
       kind: 'error';
@@ -109,11 +126,26 @@ export interface ToolResultEntry {
   error?: string;
 }
 
+export interface PendingSubtask {
+  /** Executor the task was placed with; null only when the spawn result carried
+   * no executor identity (open/broadcast agreement task not yet claimed). */
+  agentId: string | null;
+  spawnedAt: number;
+}
+
+export interface CollectedSubtaskResult {
+  taskId: string;
+  agentId: string | null;
+  status: 'completed' | 'failed';
+  /** task.result from the finishing event; null when the event carried none. */
+  result: unknown;
+}
+
 /**
  * Per-lane runtime state. Outcome is "what just happened"; Ctx is "what I know."
  *
  * Persistent identifiers (activeAgreementId, pendingProposalAgreementId,
- * delegatedTaskIds) survive across outcomes — they're the memory of which
+ * pendingSubtasks) survive across outcomes — they're the memory of which
  * agreement the agent is currently bound to and which subtasks it's awaiting.
  */
 export interface Ctx {
@@ -124,7 +156,10 @@ export interface Ctx {
   activeTaskId: string | null;
   pendingProposalAgreementId: string | null;
   delegatedAgreementIds: string[];
-  delegatedTaskIds: string[];
+  /** Durable barrier for orchestration: every spawned-but-unfinished subtask, keyed by taskId. */
+  pendingSubtasks: Record<string, PendingSubtask>;
+  /** Every finished subtask of the current engagement, arrival order. Synthesis prompts render ALL of these. */
+  collectedResults: CollectedSubtaskResult[];
 
   // Per-turn working memory
   toolResults: ToolResultEntry[];
@@ -132,6 +167,17 @@ export interface Ctx {
   // Last event/turn that caused this entry
   lastOutcome: Outcome;
 
+  /** Claude Agent SDK session id for resume across ticks (claude-sdk cognition only). */
+  claudeSessionId?: string;
+
+  /**
+   * Recent wake timestamps (epoch ms) for this lane (claude-sdk cognition
+   * only). Backstop circuit breaker: if a lane wakes faster than any real
+   * traffic could drive it, the brain skips the LLM instead of burning the
+   * fleet key on a wake storm.
+   */
+  recentWakes?: number[];
+
   // Server-provided context (history, agreements, agents, users) is fetched
   // on demand inside runTurn; not persisted on Ctx.
 }
@@ -182,6 +228,17 @@ export interface Transition {
 
 export interface ParkedState {
   kind: 'parked';
+  /**
+   * Liveness timer. When the machine settles in this state and no event
+   * arrives on the lane within timeoutMs, the host wakes the lane with a
+   * { kind: 'state-timeout', state, waitedMs } outcome so a transition can
+   * route to a recovery/nudge state. If no transition matches, the machine
+   * parks loudly (runtimeLog.error) and the timer is NOT re-armed. Countdown
+   * starts when the tick settles and resets on any event for the lane.
+   * In-memory only: lost on process restart; re-armed by the next real event
+   * that ticks the lane.
+   */
+  timeoutMs?: number;
   transitions: Transition[];
 }
 
@@ -198,7 +255,20 @@ export interface ThinkingState {
   allowNoWait?: boolean;
 }
 
-export type State = ParkedState | ThinkingState;
+/**
+ * ZIG-764: fixed tool invoke with no LLM turn. Entered after transitions
+ * (e.g. task-assigned → executing); runs `tool` once and emits `produces`.
+ */
+export interface MechanicalState {
+  kind: 'mechanical';
+  tool: string;
+  args?: Record<string, unknown>;
+  buildArgs?: (ctx: Ctx, outcome: Outcome) => Record<string, unknown>;
+  produces: Produces;
+  transitions: Transition[];
+}
+
+export type State = ParkedState | ThinkingState | MechanicalState;
 
 export interface Workflow {
   id: string;
@@ -254,16 +324,20 @@ export interface ContextSnapshot {
   timelineSummary?: string | null;
   latestSequence?: string | null;
   unavailable?: boolean;
+  /**
+   * The session's chat no longer resolves on the backend (messages read
+   * 404'd) — deleted or never visible to this agent. Message-triggered wakes
+   * check this and skip the LLM instead of reasoning over a fabricated empty
+   * history. Agreement-keyed lanes also set it (their sessionId is not a
+   * chat), so it only gates message wakes, never task lanes.
+   */
+  chatMissing?: boolean;
   /** Index signature so PromptBuilder's `ServerContext` can accept it directly. */
   [key: string]: unknown;
 }
 
 export interface ReadContextOpts {
   maxMessages?: number;
-  maxCharacters?: number;
-  maxTaskHistory?: number;
-  summarize?: boolean;
-  sinceSequence?: string;
 }
 
 /**
@@ -277,6 +351,12 @@ export interface ToolCallResult {
   result?: unknown;
   error?: string;
   events?: unknown[];
+  /**
+   * Summed token usage of any nested LLM call the tool made (e.g. llmTool).
+   * Threaded up so the turn's authoritative token count (machine.tokens ->
+   * result.metrics) includes tool-internal spend rather than leaking it (ZIG-813).
+   */
+  usage?: LlmResponse['usage'];
 }
 
 export interface RecordedEntry {
@@ -293,13 +373,7 @@ export type EffectKind =
   | 'stream-text'
   | 'tool-call'
   | 'send-message'
-  | 'record-event'
-  | 'get-scope'
-  | 'list-messages'
-  | 'list-artifacts'
-  | 'list-task-history';
-
-export interface ScopeRef { kind: 'chat' | 'agreement' | 'task' | 'counterparty'; id: string }
+  | 'record-event';
 
 export type Effect =
   | { kind: 'read-context'; sessionId: string; opts?: ReadContextOpts }
@@ -330,17 +404,20 @@ export type Effect =
       memory?: MemoryStore;
       senderId?: string;
       senderType?: string;
+      /**
+       * Agreement this tool call is acting under (ZIG-831). For a delegated
+       * per-user MCP call, `senderId` is the delegating agent, not the end-user
+       * who owns the connection; this lets the gateway resolve the delegation
+       * root's user. Sourced from the waking task event's `result.agreementId`.
+       */
+      onBehalfOfAgreementId?: string;
       /** Per-turn UUID (ZIG-440). */
       runId?: string;
       /** FSM state name (ZIG-440). */
       stateId?: string;
     }
   | { kind: 'send-message'; sessionId: string; receiverId: string; text: string; messageId?: string }
-  | { kind: 'record-event'; sessionId: string; entry: RecordedEntry }
-  | { kind: 'get-scope'; via: ScopeRef }
-  | { kind: 'list-messages'; chatId: string; after?: string; limit?: number }
-  | { kind: 'list-artifacts'; chatId?: string; agreementId?: string; after?: string; limit?: number }
-  | { kind: 'list-task-history'; taskId: string; after?: string; limit?: number };
+  | { kind: 'record-event'; sessionId: string; entry: RecordedEntry };
 
 /**
  * Typed result map. With this shape, `await eff({ kind: 'read-context', ... })`
@@ -350,14 +427,10 @@ export type Effect =
 export interface EffectResultMap {
   'read-context': ContextSnapshot;
   'llm-call': LlmResponse;
-  'stream-text': { text: string };
+  'stream-text': { text: string; usage?: LlmResponse['usage'] };
   'tool-call': ToolCallResult;
   'send-message': { ok: true };
   'record-event': { ok: true };
-  'get-scope': unknown;
-  'list-messages': { messages: unknown[]; latestSequence: string | null };
-  'list-artifacts': { artifacts: unknown[]; latestSequence: string | null };
-  'list-task-history': { taskId: string; history: unknown[]; latestSequence: string | null };
 }
 
 export type EffectResult<K extends EffectKind> = EffectResultMap[K];
@@ -389,11 +462,14 @@ export interface DefineAgentInput {
 
 /**
  * Frozen output of defineAgent. Consumed directly by AgentHost / createAgent.
- * No mutation — defineAgent validates and returns; injection of defaults is
- * the workflow author's responsibility (visible spread of `thinkingDefaults`).
+ * defineAgent injects ONE default: the agreement-kickoff state `kickingOff`
+ * plus a last-position transition into it, added to states that don't already
+ * handle a proposer-side proposal-resolved/approve outcome (runtime/kickoff.ts).
+ * `wait` defaults remain the author's visible spread of `thinkingDefaults`.
  */
 export interface AgentConfig {
   openaiKey: string | undefined;
+  anthropicKey: string | undefined;
   operatorKey?: string;
   agentId: string;
   description: string;