@ziggs-ai/agent-sdk 0.2.2 → 0.4.0

package/dist/index.d.ts

@@ -34,11 +34,14 @@ export { KICKOFF_STATE, injectKickoffDefault, buildKickoffState } from './runtim
 export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
 export { deriveRespondsToProposals, statesRespondToProposals, } from './runtime/deriveRespondsToProposals.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
-export type { Outcome, OutcomeKind, Ctx, Identity, HistoryEntry, ToolResultEntry, Workflow, State, ParkedState, ThinkingState, MechanicalState, Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn, AgreementRef, TaskRef, ProposalRef, AgentConfig, DefineAgentInput, ServicesConfig, Effect, EffectKind, EffectResult, EffectResultMap, EffectHandler, LlmMessage, LlmToolCall, LlmToolSchema, LlmResponse, ContextSnapshot, ReadContextOpts, ToolCallResult, RecordedEntry, } from './types.js';
+export { createWakeWriteKeys } from './runtime/wakeWriteKeys.js';
+export type { Outcome, OutcomeKind, Ctx, Identity, HistoryEntry, ToolResultEntry, Workflow, State, ParkedState, ThinkingState, MechanicalState, Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn, AgreementRef, TaskRef, ProposalRef, AgentConfig, DefineAgentInput, ServicesConfig, Effect, EffectKind, EffectResult, EffectResultMap, EffectHandler, LlmMessage, LlmToolCall, LlmToolSchema, LlmResponse, ContextSnapshot, ReadContextOpts, ToolCallResult, RecordedEntry, WakeWriteKeys, } from './types.js';
 export { default } from './AgentHost.js';
 export { validateContext, ContextWarning } from './cognition/validateContext.js';
 export { runLauncher } from './server/runLauncher.js';
 export { ConnectionPool } from './server/ConnectionPool.js';
+export { createStaleBacklogGate, resolveReplayPolicy, newestActionableAt, parseReplayMaxAge, } from './server/staleBacklogGate.js';
+export { decodeOperatorKeyClaims, boundKeyFleetWarning } from './shared/operatorKeyClaims.js';
 export { createHealthServer } from './server/createHealthServer.js';
 export { TaskService } from './server/tasks/TaskService.js';
 export { AgreementService } from './server/agreements/AgreementService.js';
@@ -61,9 +64,7 @@ export { classifyIncomingEvent } from './context/classifyEnvelope.js';
 export { buildContextUpdates, CONTEXT_RESET } from './context/applyEffects.js';
 export { getBatchEvents, isTaskResultRelevantToAgent } from './context/batch.js';
 export { classifyWorkflowEvent, findTaskResult, unwrapBatchEvent, findIncomingTaskResult } from './context/routingLabels.js';
-export { WebSocketClient, MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl, getWebSocketUrl, } from '@ziggs-ai/api-client';
-export { runInboxCatchUp } from './server/InboxCatchUp.js';
-export type { InboxCatchUpDeps, InboxCatchUpResult } from './server/InboxCatchUp.js';
+export { MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl, getWebSocketUrl, } from '@ziggs-ai/api-client';
 export { SeenMessages } from './server/SeenMessages.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 export type { RuntimeLogLevel } from './shared/runtimeLog.js';

package/dist/index.js

@@ -28,11 +28,14 @@ export { KICKOFF_STATE, injectKickoffDefault, buildKickoffState } from './runtim
 export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
 export { deriveRespondsToProposals, statesRespondToProposals, } from './runtime/deriveRespondsToProposals.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
+export { createWakeWriteKeys } from './runtime/wakeWriteKeys.js';
 export { default } from './AgentHost.js';
 // ── Supporting modules ──────────────────────────────────────────────────────
 export { validateContext, ContextWarning } from './cognition/validateContext.js';
 export { runLauncher } from './server/runLauncher.js';
 export { ConnectionPool } from './server/ConnectionPool.js';
+export { createStaleBacklogGate, resolveReplayPolicy, newestActionableAt, parseReplayMaxAge, } from './server/staleBacklogGate.js';
+export { decodeOperatorKeyClaims, boundKeyFleetWarning } from './shared/operatorKeyClaims.js';
 export { createHealthServer } from './server/createHealthServer.js';
 export { TaskService } from './server/tasks/TaskService.js';
 export { AgreementService } from './server/agreements/AgreementService.js';
@@ -66,7 +69,6 @@ export { classifyIncomingEvent } from './context/classifyEnvelope.js';
 export { buildContextUpdates, CONTEXT_RESET } from './context/applyEffects.js';
 export { getBatchEvents, isTaskResultRelevantToAgent } from './context/batch.js';
 export { classifyWorkflowEvent, findTaskResult, unwrapBatchEvent, findIncomingTaskResult } from './context/routingLabels.js';
-export { WebSocketClient, MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl, getWebSocketUrl, } from '@ziggs-ai/api-client';
-export { runInboxCatchUp } from './server/InboxCatchUp.js';
+export { MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl, getWebSocketUrl, } from '@ziggs-ai/api-client';
 export { SeenMessages } from './server/SeenMessages.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';

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;
@@ -36,11 +40,10 @@ interface WireTask {
 }
 interface WireMetadata {
     chatId?: string;
-    chat_id?: string;
+    messageId?: string;
     entryType?: string;
     content_type?: string;
     contentType?: string;
-    receiverId?: string;
     operation?: string;
     agreementId?: string;
     sender?: {
@@ -50,10 +53,13 @@ interface WireMetadata {
     receiver?: {
         id?: string;
     };
-    to?: {
-        id?: string;
-    };
     task?: WireTask;
+    service?: {
+        task?: WireTask;
+        operation?: string;
+        agreement?: unknown;
+        agreementId?: string;
+    };
     [key: string]: unknown;
 }
 interface NormalizeArgs {
@@ -61,5 +67,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',
@@ -6,10 +5,10 @@ const PROPOSAL_RESOLVED_OPERATIONS = new Set([
     'proposal_approved_execute',
 ]);
 function normalizeChatId(metadata) {
-    return metadata.chatId || metadata.chat_id || null;
+    return metadata.chatId || null;
 }
 function normalizeReceiverId(metadata, taskData) {
-    return metadata.receiver?.id || metadata.receiverId || metadata.to?.id || taskData?.executorId || taskData?.proposedTo || null;
+    return metadata.receiver?.id || taskData?.executorId || taskData?.proposedTo || null;
 }
 function isTaskRelated(metadata, taskData) {
     if (!taskData?.taskId)
@@ -20,20 +19,26 @@ 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;
+    const operation = metadata.service?.operation ?? metadata.operation;
     return (entryType === 'notification' &&
         typeof operation === 'string' &&
         PROPOSAL_RESOLVED_OPERATIONS.has(operation));
 }
-export function normalizeIncomingEvent({ text, metadata = {}, ownAgentId = null }) {
-    const taskData = metadata.task || 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 = {} }) {
+    // ZIG-936: classifier data lives under `service` on the inbox-pull wire;
+    // fall back to top-level for hand-built (direct-injection) metadata.
+    const taskData = (metadata.service?.task ?? metadata.task) || null;
     const chatId = normalizeChatId(metadata);
     const receiverId = normalizeReceiverId(metadata, taskData);
     const senderType = metadata.sender?.type ? String(metadata.sender.type).toUpperCase() : undefined;
@@ -41,48 +46,32 @@ 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 : '';
+        const operation = metadata.service?.operation ?? metadata.operation;
+        const rawAgreementId = metadata.service?.agreementId ?? metadata.agreementId;
+        const agreementId = typeof rawAgreementId === 'string' ? rawAgreementId : '';
         return {
             chatId,
             event: {
                 ...base,
                 type: 'agreement_lifecycle',
-                operation: metadata.operation,
+                operation,
                 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/PromptBuilder.js

@@ -421,8 +421,8 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
             for (let i = history.length - 1; i >= 0; i--) {
                 const row = history[i];
                 const sender = row.sender;
-                const id = String(sender?.id || row.senderId || '');
-                const type = String(sender?.type || row.senderType || '').toUpperCase();
+                const id = String(sender?.id || '');
+                const type = String(sender?.type || '').toUpperCase();
                 if (id && id !== myId && !isNonRoutableSenderType(type)) {
                     defaultReplyReceiverId = id;
                     break;

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,
         });
     }
@@ -791,8 +809,8 @@ function pickPrimaryUserIdFromContext(context) {
     for (let i = hist.length - 1; i >= 0; i--) {
         const row = hist[i];
         const sender = row?.sender;
-        const type = String(sender?.type || row?.senderType || '').toUpperCase();
-        const id = (sender?.id ?? row?.senderId);
+        const type = String(sender?.type || '').toUpperCase();
+        const id = sender?.id;
         if (type === 'USER' && id)
             return id;
     }

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}`;
+        },
+    };
+}