@ziggs-ai/agent-sdk 0.2.2 → 0.3.0

package/dist/ingress/normalizeIncoming.d.ts

@@ -4,6 +4,12 @@ export interface NormalizedEvent {
         senderId?: string;
         senderType?: string;
         receiverId?: string;
+        /**
+         * Backend per-delivery id of the chat row this event came from. The one
+         * field of the event that is identical on live push and on catch-up
+         * redelivery, so it anchors the wake's idempotency keys (wakeWriteKeys).
+         */
+        messageId?: string;
         timestamp: number;
         type: 'task_result' | 'message' | 'agreement_lifecycle';
         operation?: string;
@@ -11,8 +17,6 @@ export interface NormalizedEvent {
         result?: unknown;
         text?: string;
     };
-    shouldProcess: boolean;
-    reason: string | null;
 }
 interface WireParties {
     creator?: string;
@@ -37,6 +41,7 @@ interface WireTask {
 interface WireMetadata {
     chatId?: string;
     chat_id?: string;
+    messageId?: string;
     entryType?: string;
     content_type?: string;
     contentType?: string;
@@ -61,5 +66,14 @@ interface NormalizeArgs {
     metadata?: WireMetadata;
     ownAgentId?: string | null;
 }
-export declare function normalizeIncomingEvent({ text, metadata, ownAgentId }: NormalizeArgs): NormalizedEvent;
+/**
+ * Classify + shape a wire delivery into a lane-routable event. Targeting is
+ * backend policy now (delivery law, phase 4): the inbox loop only ever delivers
+ * what is fenced to this agent, so there is no client-side "is this for me"
+ * relevance gate — this function decides SHAPE (message vs task_result vs
+ * agreement_lifecycle) and the fields the FSM / SessionResolver / wakeWriteKeys
+ * depend on, nothing more. `ownAgentId` is accepted for call-site compatibility
+ * but no longer gates anything.
+ */
+export declare function normalizeIncomingEvent({ text, metadata }: NormalizeArgs): NormalizedEvent;
 export {};

package/dist/ingress/normalizeIncoming.js

@@ -1,4 +1,3 @@
-import { OPEN_AGREEMENT_TARGET } from '@ziggs-ai/api-client';
 /** Backend wire operations that map to FSM `proposal-resolved`. */
 const PROPOSAL_RESOLVED_OPERATIONS = new Set([
     'proposal_approved',
@@ -20,11 +19,6 @@ function isTaskRelated(metadata, taskData) {
         || contentType === 'task' || contentType === 'task_update'
         || Boolean(taskData.state || taskData.proposal || taskData.parentTaskId || taskData.executorId || taskData.agentId || taskData.payerId || taskData.createdBy));
 }
-function isRelevantForAgent(ids, ownAgentId) {
-    if (!ownAgentId)
-        return true;
-    return ids.includes(ownAgentId) || ids.includes(OPEN_AGREEMENT_TARGET);
-}
 function isAgreementLifecycleNotification(metadata) {
     const entryType = metadata.entryType || 'message';
     const operation = metadata.operation;
@@ -32,7 +26,16 @@ function isAgreementLifecycleNotification(metadata) {
         typeof operation === 'string' &&
         PROPOSAL_RESOLVED_OPERATIONS.has(operation));
 }
-export function normalizeIncomingEvent({ text, metadata = {}, ownAgentId = null }) {
+/**
+ * Classify + shape a wire delivery into a lane-routable event. Targeting is
+ * backend policy now (delivery law, phase 4): the inbox loop only ever delivers
+ * what is fenced to this agent, so there is no client-side "is this for me"
+ * relevance gate — this function decides SHAPE (message vs task_result vs
+ * agreement_lifecycle) and the fields the FSM / SessionResolver / wakeWriteKeys
+ * depend on, nothing more. `ownAgentId` is accepted for call-site compatibility
+ * but no longer gates anything.
+ */
+export function normalizeIncomingEvent({ text, metadata = {} }) {
     const taskData = metadata.task || null;
     const chatId = normalizeChatId(metadata);
     const receiverId = normalizeReceiverId(metadata, taskData);
@@ -41,13 +44,10 @@ export function normalizeIncomingEvent({ text, metadata = {}, ownAgentId = null
         senderId: metadata.sender?.id,
         senderType,
         receiverId: receiverId || undefined,
+        messageId: typeof metadata.messageId === 'string' && metadata.messageId ? metadata.messageId : undefined,
         timestamp: Date.now(),
     };
     if (isAgreementLifecycleNotification(metadata)) {
-        const relevant = !ownAgentId ||
-            !receiverId ||
-            receiverId === ownAgentId ||
-            receiverId === OPEN_AGREEMENT_TARGET;
         const agreementId = typeof metadata.agreementId === 'string' ? metadata.agreementId : '';
         return {
             chatId,
@@ -58,31 +58,16 @@ export function normalizeIncomingEvent({ text, metadata = {}, ownAgentId = null
                 agreementId,
                 text,
             },
-            shouldProcess: relevant,
-            reason: relevant ? null : 'message_not_targeted_to_agent',
         };
     }
     if (isTaskRelated(metadata, taskData)) {
-        const receiverFromMeta = metadata.receiver?.id || metadata.receiverId || null;
-        const parties = taskData.agreement?.parties ?? {};
-        const candidateIds = [
-            parties.creator, parties.provider, parties.payer, parties.proposedTo,
-            taskData.agentId, taskData.executorId, taskData.payerId, taskData.proposedTo, taskData.createdBy,
-            receiverFromMeta,
-        ].filter(Boolean);
-        const relevant = isRelevantForAgent(candidateIds, ownAgentId);
         return {
             chatId,
             event: { ...base, type: 'task_result', result: taskData, text },
-            shouldProcess: relevant,
-            reason: relevant ? null : 'task_not_targeted_to_agent',
         };
     }
-    const relevant = !ownAgentId || !receiverId || receiverId === ownAgentId || receiverId === OPEN_AGREEMENT_TARGET;
     return {
         chatId,
         event: { ...base, type: 'message', text },
-        shouldProcess: relevant,
-        reason: relevant ? null : 'message_not_targeted_to_agent',
     };
 }

package/dist/runtime/AgentMachine.d.ts

@@ -1,4 +1,4 @@
-import type { Ctx, Outcome, Workflow, Identity, EffectHandler } from '../types.js';
+import type { Ctx, Outcome, Workflow, Identity, EffectHandler, WakeWriteKeys } from '../types.js';
 import { type RawEvent } from './buildOutcome.js';
 import type { runTurn as RunTurnFn } from './runTurn.js';
 import { PromptBuilder } from './PromptBuilder.js';
@@ -59,6 +59,8 @@ interface MachineOptions {
     transitionTap?: (event: TransitionEvent) => void;
     /** Runaway-loop backstop: max thinking turns without human input before parking. Default 100. */
     maxTurnsWithoutUserInput?: number;
+    /** This wake's replay-stable write keys — one stream shared by every turn of the tick. */
+    wakeKeys?: WakeWriteKeys;
 }
 interface IncomingFrame {
     event?: RawEvent;
@@ -84,6 +86,7 @@ export declare class AgentMachine {
     toolManager: ToolManager;
     promptBuilder: PromptBuilder;
     memory?: MemoryStore;
+    wakeKeys?: WakeWriteKeys;
     state: string;
     status: 'active' | 'stopped';
     ctx: Ctx;
@@ -111,7 +114,7 @@ export declare class AgentMachine {
         output: number;
     };
     get stateTimeoutUnhandled(): boolean;
-    constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput }: MachineOptions);
+    constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput, wakeKeys }: MachineOptions);
     getSnapshot(): MachineSnapshot;
     /** Parked = currently in a parked state and not executing a turn. */
     get isParked(): boolean;

package/dist/runtime/AgentMachine.js

@@ -30,6 +30,7 @@ export class AgentMachine {
     toolManager;
     promptBuilder;
     memory;
+    wakeKeys;
     state;
     status = 'active';
     ctx;
@@ -49,13 +50,14 @@ export class AgentMachine {
     get llmCalls() { return this._llmCalls; }
     get tokens() { return this._tokens; }
     get stateTimeoutUnhandled() { return this._stateTimeoutUnhandled; }
-    constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput }) {
+    constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput, wakeKeys }) {
         this.workflow = workflow;
         this.executionCore = executionCore;
         this.eff = eff;
         this.toolManager = toolManager;
         this.promptBuilder = promptBuilder;
         this.memory = memory;
+        this.wakeKeys = wakeKeys;
         this._transitionTap = transitionTap;
         this._maxTurnsWithoutUserInput = maxTurnsWithoutUserInput ?? DEFAULT_MAX_TURNS_WITHOUT_USER_INPUT;
         this.state = input.state || workflow.initial;
@@ -200,6 +202,7 @@ export class AgentMachine {
                     eff: this.eff,
                     memory: this.memory,
                     incomingEvent: this._lastIncomingEvent,
+                    wakeKeys: this.wakeKeys,
                 });
                 this.ctx.toolResults = toolResults;
                 this._llmCalls += llmCalls;
@@ -293,6 +296,7 @@ export class AgentMachine {
                 promptBuilder: this.promptBuilder,
                 memory: this.memory,
                 definition: this.workflow,
+                wakeKeys: this.wakeKeys,
             });
             this.ctx.toolResults = toolResults;
             this._llmCalls += llmCalls;
@@ -352,7 +356,9 @@ export class AgentMachine {
         if (!userId)
             return;
         try {
-            await this.eff({ kind: 'send-message', sessionId: this.ctx.identity.sessionId, receiverId: userId, text });
+            // Wake-derived messageId: a crash-replay that errors the same way parks
+            // again and re-sends this apology — same key, backend drops the dupe.
+            await this.eff({ kind: 'send-message', sessionId: this.ctx.identity.sessionId, receiverId: userId, text, messageId: this.wakeKeys?.messageKey() });
         }
         catch { /* best-effort */ }
     }

package/dist/runtime/runMechanical.d.ts

@@ -1,4 +1,4 @@
-import type { Ctx, EffectHandler, MechanicalState, Outcome, ToolResultEntry } from '../types.js';
+import type { Ctx, EffectHandler, MechanicalState, Outcome, ToolResultEntry, WakeWriteKeys } from '../types.js';
 import type { MemoryStore } from '../memory/MemoryStore.js';
 import { type RawEvent } from './buildOutcome.js';
 export interface RunMechanicalResult {
@@ -22,4 +22,6 @@ export declare function runMechanical(input: {
     eff: EffectHandler;
     memory?: MemoryStore;
     incomingEvent: RawEvent | null;
+    /** This wake's replay-stable write keys (shared across every turn of the tick — see AgentMachine). */
+    wakeKeys?: WakeWriteKeys;
 }): Promise<RunMechanicalResult>;

package/dist/runtime/runMechanical.js

@@ -5,12 +5,12 @@ import { runtimeLog } from '../shared/runtimeLog.js';
  * Used by dumb coordinators whose only job is a fixed tool call on task-assigned.
  */
 export async function runMechanical(input) {
-    const { stateId, state, ctx, eff, memory, incomingEvent } = input;
+    const { stateId, state, ctx, eff, memory, incomingEvent, wakeKeys } = input;
     const sessionId = ctx.identity.sessionId;
     const runId = crypto.randomUUID();
     const effWithTrace = (effect) => {
         if (effect.kind === 'tool-call') {
-            return eff({ ...effect, runId, stateId });
+            return eff({ ...effect, runId, stateId, wakeKeys });
         }
         return eff(effect);
     };

package/dist/runtime/runTurn.d.ts

@@ -1,4 +1,4 @@
-import type { Action, Ctx, Outcome, ToolResultEntry, EffectHandler } from '../types.js';
+import type { Action, Ctx, Outcome, ToolResultEntry, EffectHandler, WakeWriteKeys } from '../types.js';
 import type { MemoryStore } from '../memory/MemoryStore.js';
 import { type RawEvent } from './buildOutcome.js';
 import { PromptBuilder } from './PromptBuilder.js';
@@ -32,6 +32,8 @@ interface RunTurnInput {
      * to disable it without a code change.
      */
     streamRespondActions?: boolean;
+    /** This wake's replay-stable write keys (shared across every turn of the tick — see AgentMachine). */
+    wakeKeys?: WakeWriteKeys;
 }
 interface RunTurnResult {
     outcome: Outcome;

package/dist/runtime/runTurn.js

@@ -45,17 +45,28 @@ function isGenericFallbackTool(name, toolManager) {
  * call and (optionally) wrapping it in telemetry / dedup / retries.
  */
 export async function runTurn(input) {
-    const { stateId, statePrompt, actions, incomingEvent, ctx, eff, toolManager, promptBuilder, memory, definition } = input;
+    const { stateId, statePrompt, actions, incomingEvent, ctx, eff, toolManager, promptBuilder, memory, definition, wakeKeys } = input;
     // Default on (ZIG-838); ENABLE_LLM_STREAMING=false is the deployment
     // kill-switch. Any other value (unset, 'true', …) streams.
     const streamRespondActions = input.streamRespondActions ?? process.env.ENABLE_LLM_STREAMING !== 'false';
     const sessionId = ctx.identity.sessionId;
     const runId = crypto.randomUUID();
-    // Wrap eff to stamp runId + stateId onto llm-call and tool-call effects.
+    // Wrap eff to stamp runId + stateId onto llm-call and tool-call effects,
+    // and the wake's replay-stable write keys onto tool-call effects.
+    // Send-message effects without an explicit messageId get a wake-derived one
+    // here — a crash-replay of the wake re-derives the same id and the backend's
+    // (chatId, messageId) dedup drops the duplicate (ZIG-718). Undefined on
+    // keyless wakes, where the transport generates a fresh id as before.
     const effWithTrace = (effect) => {
-        if (effect.kind === 'llm-call' || effect.kind === 'tool-call') {
+        if (effect.kind === 'llm-call') {
             return eff({ ...effect, runId, stateId });
         }
+        if (effect.kind === 'tool-call') {
+            return eff({ ...effect, runId, stateId, wakeKeys });
+        }
+        if (effect.kind === 'send-message' && !effect.messageId) {
+            return eff({ ...effect, messageId: wakeKeys?.messageKey() });
+        }
         return eff(effect);
     };
     const emitThought = async (text) => {
@@ -65,7 +76,7 @@ export async function runTurn(input) {
         if (s.length === 0)
             return;
         try {
-            await eff({ kind: 'record-event', sessionId, entry: { kind: 'thought', text: s } });
+            await eff({ kind: 'record-event', sessionId, entry: { kind: 'thought', text: s }, idempotencyKey: wakeKeys?.artifactKey() });
         }
         catch (err) {
             runtimeLog.warn('runTurn', `record-event:thought failed: ${err.message}`);
@@ -295,7 +306,10 @@ export async function runTurn(input) {
             const inboundFromAgent = String(incomingEvent?.senderType || '').toUpperCase() === 'AGENT';
             runtimeLog.info('runTurn', `streaming check: enabled=${streamRespondActions} receiverId=${decision.receiverId ?? 'none'} tool=${actionDef?.tool ?? 'none'} action=${chosenAction} inboundFromAgent=${inboundFromAgent}`);
             if (streamRespondActions && !inboundFromAgent && decision.receiverId && !actionDef?.tool && chosenAction !== 'wait') {
-                const streamMessageId = crypto.randomUUID();
+                // Wake-derived when the wake has a durable identity: a crash-replay
+                // streams and persists under the SAME id, so the backend's
+                // (chatId, messageId) dedup drops the duplicate reply (ZIG-718).
+                const streamMessageId = wakeKeys?.messageKey() ?? crypto.randomUUID();
                 runtimeLog.info('runTurn', `stream-text start action=${chosenAction} receiverId=${decision.receiverId} msgId=${streamMessageId}`);
                 const streamMessages = [
                     ...messages,
@@ -362,7 +376,9 @@ export async function runTurn(input) {
             }
             let result;
             try {
-                result = await executeDecision(decision, actionDef, eff, sessionId, memory, null, addToolUsage);
+                // effWithTrace, not eff: JSON-path tool calls must carry runId/stateId
+                // and the wake's write keys exactly like tool-loop calls do.
+                result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, null, addToolUsage);
             }
             catch (err) {
                 // Only outbound sends can throw out of executeDecision — executeTool
@@ -409,8 +425,10 @@ export async function runTurn(input) {
         }
     }
     if (!turnError) {
+        // effWithTrace, not eff: the echoed summary is a user-visible send and
+        // must carry a wake-derived messageId like every other send of the turn.
         await echoOptInToolSummaryIfNeeded({
-            allEmittedEvents, eff, sessionId,
+            allEmittedEvents, eff: effWithTrace, sessionId,
             context: ctxObj, toolManager, incomingEvent,
         });
     }

package/dist/runtime/wakeWriteKeys.d.ts

@@ -0,0 +1,25 @@
+import type { WakeWriteKeys } from '../types.js';
+/**
+ * Build the per-wake key derivation. Call once per tick with the lane and the
+ * raw triggering event, then thread the instance to every write of the wake.
+ *
+ * Key shapes (all well under the backend's 128-char cap):
+ * - artifacts:        `wk_<wake-hash>_a<ordinal>` — ordinal increments per
+ *   artifact write, so a wake writing several breadcrumbs keys each one.
+ * - task transitions: `wk_<wake-hash>_t_<hash(taskId, state)>` — derived from
+ *   the transition itself, so it dedups regardless of the order in which the
+ *   replayed wake happens to re-issue its tool calls.
+ * - chat messages:    `sdk_idem_wk_<wake-hash>_m<ordinal>` — used directly as
+ *   the messageId (the backend dedups on (chatId, messageId), ZIG-718), drawn
+ *   from the same ordinal stream as artifacts so one counter keys the wake's
+ *   whole write sequence. The prefix matches the tool-layer convention for
+ *   deterministic ids (`sdk_idem_<llm-key>`).
+ * - task spawns:      `wk_<wake-hash>_s_<hash(agreement, description, …)>` —
+ *   derived from what the spawn writes, so it dedups regardless of re-issue
+ *   order while still distinguishing multiple spawns in one wake.
+ * - agreement create: `wk_<wake-hash>_ap_<hash(…)>` (propose) and
+ *   `wk_<wake-hash>_asc_<hash(…)>` (subcontract) — same content-derived scheme
+ *   as task spawns; the backend dedups on (creator, key) so a replayed
+ *   propose/subcontract resolves to the original agreement.
+ */
+export declare function createWakeWriteKeys(laneKey: string, event: unknown): WakeWriteKeys;

package/dist/runtime/wakeWriteKeys.js

@@ -0,0 +1,134 @@
+import { createHash } from 'node:crypto';
+import { getBatchEvents } from '../context/batch.js';
+/**
+ * Deterministic idempotency keys for hosted-agent writes (delivery law, item 2).
+ *
+ * A crash between acting and acking redelivers the SAME wake event; the agent
+ * re-thinks and re-writes. The backend drops duplicate artifact writes and
+ * no-ops duplicate task transitions — but only when the replayed wake derives
+ * the SAME key. So keys are a pure function of durable wake inputs (laneKey +
+ * the triggering event's delivery identity + a per-wake write ordinal). They
+ * are never LLM-supplied and never random: asking the model to invent a key
+ * makes replay-stability a matter of sampling temperature.
+ *
+ * One instance is created per wake (tick) and threaded to every write the wake
+ * performs — a second instance created for the same (laneKey, event), as a
+ * crash-replay does, reproduces the same key sequence.
+ */
+/**
+ * Durable identity of the event that triggered this wake, or null when it has
+ * none. Null means the wake is not a redelivery candidate (timer and other
+ * host-synthesized frames fire fresh each time), so its writes carry no key —
+ * a derived-anyway key could only collide across genuinely distinct wakes and
+ * silently swallow their writes, which is worse than the duplicate it prevents.
+ */
+function eventIdentity(event) {
+    if (!event || typeof event !== 'object')
+        return null;
+    const e = event;
+    if (e.type === 'batch') {
+        // EventQueue coalesces queued events into one frame. Identify the batch by
+        // its identifiable members (sorted — arrival order is not replay-stable).
+        // Members without identity are ignored rather than nulling the whole batch:
+        // an identified member can only recur via redelivery, which is exactly when
+        // matching keys are wanted.
+        const parts = getBatchEvents(event)
+            .map(eventIdentity)
+            .filter((p) => p !== null)
+            .sort();
+        return parts.length > 0 ? parts.join('|') : null;
+    }
+    // Per-delivery id stamped by the backend on chat rows — present on live
+    // pushes and on catch-up redelivery alike, and the most precise identity.
+    if (typeof e.messageId === 'string' && e.messageId)
+        return `msg:${e.messageId}`;
+    if (e.type === 'task_result') {
+        // Host-synthesized task frames (bootstrap of already-assigned tasks) carry
+        // no messageId; the task snapshot itself is the identity. Re-bootstrapping
+        // the same task in the same state IS re-processing, so the collision this
+        // produces is the dedup we want.
+        const result = (e.result ?? {});
+        const taskId = typeof result.taskId === 'string' ? result.taskId : null;
+        if (!taskId)
+            return null;
+        const state = typeof result.state === 'string' ? result.state : '';
+        const operation = typeof result._operation === 'string' ? result._operation : '';
+        return `task:${taskId}:${state}:${operation}`;
+    }
+    if (e.type === 'agreement_lifecycle') {
+        const agreementId = typeof e.agreementId === 'string' ? e.agreementId : null;
+        if (!agreementId)
+            return null;
+        return `agr:${agreementId}:${typeof e.operation === 'string' ? e.operation : ''}`;
+    }
+    // state-timeout, resource_changed, and anything else: no per-delivery id on
+    // the wire, and never redelivered by catch-up — keyless by design.
+    return null;
+}
+function sha(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+/**
+ * Build the per-wake key derivation. Call once per tick with the lane and the
+ * raw triggering event, then thread the instance to every write of the wake.
+ *
+ * Key shapes (all well under the backend's 128-char cap):
+ * - artifacts:        `wk_<wake-hash>_a<ordinal>` — ordinal increments per
+ *   artifact write, so a wake writing several breadcrumbs keys each one.
+ * - task transitions: `wk_<wake-hash>_t_<hash(taskId, state)>` — derived from
+ *   the transition itself, so it dedups regardless of the order in which the
+ *   replayed wake happens to re-issue its tool calls.
+ * - chat messages:    `sdk_idem_wk_<wake-hash>_m<ordinal>` — used directly as
+ *   the messageId (the backend dedups on (chatId, messageId), ZIG-718), drawn
+ *   from the same ordinal stream as artifacts so one counter keys the wake's
+ *   whole write sequence. The prefix matches the tool-layer convention for
+ *   deterministic ids (`sdk_idem_<llm-key>`).
+ * - task spawns:      `wk_<wake-hash>_s_<hash(agreement, description, …)>` —
+ *   derived from what the spawn writes, so it dedups regardless of re-issue
+ *   order while still distinguishing multiple spawns in one wake.
+ * - agreement create: `wk_<wake-hash>_ap_<hash(…)>` (propose) and
+ *   `wk_<wake-hash>_asc_<hash(…)>` (subcontract) — same content-derived scheme
+ *   as task spawns; the backend dedups on (creator, key) so a replayed
+ *   propose/subcontract resolves to the original agreement.
+ */
+export function createWakeWriteKeys(laneKey, event) {
+    const identity = eventIdentity(event);
+    const wakeHash = identity === null ? null : sha(`${laneKey}\n${identity}`).slice(0, 40);
+    let ordinal = 0;
+    return {
+        wakeKey: wakeHash === null ? null : `wk_${wakeHash}`,
+        artifactKey() {
+            if (wakeHash === null)
+                return undefined;
+            return `wk_${wakeHash}_a${ordinal++}`;
+        },
+        taskStateKey(taskId, state) {
+            if (wakeHash === null)
+                return undefined;
+            return `wk_${wakeHash}_t_${sha(`${taskId}\n${state}`).slice(0, 16)}`;
+        },
+        messageKey() {
+            if (wakeHash === null)
+                return undefined;
+            return `sdk_idem_wk_${wakeHash}_m${ordinal++}`;
+        },
+        taskSpawnKey(fields) {
+            if (wakeHash === null)
+                return undefined;
+            const spawnHash = sha(`${fields.agreementId}\n${fields.description}\n${fields.assigneeId ?? ''}\n${fields.parentTaskId ?? ''}`).slice(0, 16);
+            return `wk_${wakeHash}_s_${spawnHash}`;
+        },
+        agreementProposeKey(fields) {
+            if (wakeHash === null)
+                return undefined;
+            const proposeHash = sha(`${fields.proposedTo}\n${fields.providerId ?? ''}\n${fields.description}\n${fields.parentAgreementId ?? ''}`).slice(0, 16);
+            return `wk_${wakeHash}_ap_${proposeHash}`;
+        },
+        agreementSubcontractKey(fields) {
+            if (wakeHash === null)
+                return undefined;
+            const subHash = sha(`${fields.executorId}\n${fields.description}\n${fields.parentAgreementId}`).slice(0, 16);
+            return `wk_${wakeHash}_asc_${subHash}`;
+        },
+    };
+}

package/dist/server/ConnectionPool.d.ts

@@ -52,11 +52,14 @@ export declare class ConnectionPool {
      */
     sendTo(agentId: string, text: string, metadata?: Record<string, unknown>, { timeoutMs }?: SendToOptions): Promise<null>;
     /**
-     * Open a launcher (control) socket that the backend uses to push wake
-     * hints for any of the registered agents. Pool spins up the right host
-     * lazily when a hint arrives.
+     * Start the fleet lazy-start loop (delivery law, phase 4): the manager
+     * long-polls `GET /inbox/operator` with this operator key and starts the host
+     * for any owned agent whose slice has actionable content. Each started host
+     * then consumes via its own per-agent inbox loop — this is ordinary lazy
+     * process management, not a pushed signal. `wsUrl` is accepted for
+     * back-compat but unused (the poll is HTTP).
      */
-    startControl({ wsUrl, operatorKey }?: ControlOptions): void;
+    startControl({ operatorKey }?: ControlOptions): void;
     stopControl(): void;
     query(filter: QueryFilter): string[];
     list(): string[];

package/dist/server/ConnectionPool.js

@@ -137,25 +137,22 @@ export class ConnectionPool {
         return null;
     }
     /**
-     * Open a launcher (control) socket that the backend uses to push wake
-     * hints for any of the registered agents. Pool spins up the right host
-     * lazily when a hint arrives.
+     * Start the fleet lazy-start loop (delivery law, phase 4): the manager
+     * long-polls `GET /inbox/operator` with this operator key and starts the host
+     * for any owned agent whose slice has actionable content. Each started host
+     * then consumes via its own per-agent inbox loop — this is ordinary lazy
+     * process management, not a pushed signal. `wsUrl` is accepted for
+     * back-compat but unused (the poll is HTTP).
      */
-    startControl({ wsUrl, operatorKey } = {}) {
-        if (!wsUrl || !operatorKey) {
-            runtimeLog.warn('ConnectionPool', 'startControl: wsUrl and operatorKey are required — skipping');
+    startControl({ operatorKey } = {}) {
+        if (!operatorKey) {
+            runtimeLog.warn('ConnectionPool', 'startControl: operatorKey is required — skipping');
             return;
         }
-        // ConnectionManager only accepts `control` at construction; mutating its
-        // private field is the smallest way to add it later. (Cleaner fix lives
-        // in api-client: expose a `setControl` setter.)
-        this.manager['_controlOpts'] = { wsUrl, operatorKey };
-        this.manager.start();
+        this.manager.start(operatorKey);
     }
     stopControl() {
-        const m = this.manager;
-        m['_controlHandle']?.close?.();
-        m['_controlHandle'] = null;
+        void this.manager.stop();
     }
     query(filter) { return this.manager.query(filter); }
     list() { return this.manager.list(); }

package/dist/server/ZiggsEffectHandler.js

@@ -69,7 +69,7 @@ function previewToolArgs(args) {
  * Chat timeline: `Message.tsx` parses `entryType: artifact`, `content_type: operation` with
  * `operation_*:{json}` where json includes `state` and `tool`.
  */
-async function emitToolOperationArtifact(client, chatId, phase, payload) {
+async function emitToolOperationArtifact(client, chatId, phase, payload, idempotencyKey) {
     const prefix = phase === 'started' ? 'operation_started' : phase === 'completed' ? 'operation_completed' : 'operation_error';
     const text = `${prefix}:${JSON.stringify(payload)}`;
     try {
@@ -78,6 +78,7 @@ async function emitToolOperationArtifact(client, chatId, phase, payload) {
             text,
             content_type: 'operation',
             visibility: 'agent-private',
+            idempotencyKey,
         });
     }
     catch (e) {
@@ -108,7 +109,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
         state: 'started',
         tool: effect.name,
         ...(argsPreview ? { args: argsPreview } : {}),
-    });
+    }, effect.wakeKeys?.artifactKey());
     try {
         const lastUser = roster.users.find((u) => u.userId || u.id);
         // Accumulate token usage from any nested LLM call the tool makes (llmTool),
@@ -141,6 +142,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             senderType: effect.senderType ?? (lastUser ? 'USER' : undefined),
             onBehalfOfAgreementId: effect.onBehalfOfAgreementId,
             memory: effect.memory,
+            wakeKeys: effect.wakeKeys,
             reportUsage,
             turnScratch: {},
         });
@@ -148,7 +150,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             state: 'completed',
             tool: effect.name,
             result: clipForOperationArtifact(result),
-        });
+        }, effect.wakeKeys?.artifactKey());
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,
@@ -166,7 +168,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             state: 'failed',
             tool: effect.name,
             error: errMsg,
-        });
+        }, effect.wakeKeys?.artifactKey());
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,
@@ -242,13 +244,13 @@ export function createZiggsEffectHandler(deps) {
                 let usage;
                 if (deps.llm.chatMessagesStream) {
                     const streamed = await deps.llm.chatMessagesStream(messages, (chunk) => {
-                        // Live-stream display is best-effort. The transport's send rejects
-                        // empty/whitespace-only content (WebSocketClient: content.trim() === ''),
-                        // and a whitespace-only chunk (e.g. a leading newline) is truthy yet
-                        // still throws — which, uncaught, aborts the whole stream and loses the
-                        // entire reply (e.g. a composer's final synthesis). Swallow chunk-send
-                        // failures; `text` accumulates independently and the final send-message
-                        // (below, in runTurn) carries the full reply regardless.
+                        // Live-token display is best-effort and optional. Hosted agents wire
+                        // no chunkSender (delivery law, phase 4: no agent socket, no live
+                        // chunk transport), so partials are simply dropped — `text`
+                        // accumulates independently and the final send-message (below, in
+                        // runTurn) carries the full reply as one whole HTTP message. Any
+                        // chunk-send failure is swallowed so a display hiccup never aborts
+                        // the stream and loses the reply.
                         try {
                             if (chunk && chunk.trim())
                                 deps.chunkSender?.(sessionId, receiverId, chunk, messageId);
@@ -288,7 +290,9 @@ export function createZiggsEffectHandler(deps) {
                 // visible to this agent across turns, not to other chat parties.
                 try {
                     if (effect.entry.kind === 'thought' && typeof effect.entry.text === 'string') {
-                        await deps.artifactsClient.recordThought(effect.sessionId, effect.entry.text);
+                        await deps.artifactsClient.recordThought(effect.sessionId, effect.entry.text, {
+                            idempotencyKey: effect.idempotencyKey,
+                        });
                     }
                     else {
                         await deps.artifactsClient.write({
@@ -296,6 +300,7 @@ export function createZiggsEffectHandler(deps) {
                             text: JSON.stringify(effect.entry),
                             content_type: String(effect.entry.kind ?? 'event'),
                             visibility: 'agent-private',
+                            idempotencyKey: effect.idempotencyKey,
                         });
                     }
                 }