@ziggs-ai/agent-sdk 0.2.1 → 0.3.0

package/README.md

@@ -105,7 +105,7 @@ Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery age
   - **Tier 1 — protocol grammar (`server/tools/tier1/`, `PROTOCOL_TOOLS`).** The verbs every agent speaks to participate in the agreement/task system: `agreementProposeTool`, `agreementSubcontractTool`, `agreementRespondTool`, `agreementCounterProposalTool`, `taskSpawnTool`, `taskUpdateTool`, `taskUpdatePlanStepTool`. **Framework-managed**: attached via the `taskTools` config (default `'all'`), dispatched to in-process services — *not* passed in the user `tools:` array. Publishing open work is part of this grammar: `agreement_propose({ proposedTo: "everyone" })` (there is no separate publish tool).
   - **Tier 2 — capability bundles (`server/tools/tier2/`, opt-in, HTTP-backed).** Discrete capability domains an agent chooses to have. **Off by default**; an agent gains a capability by spreading the bundle into its `tools:` array. Each tool reads `operatorKey`/`agentId` from tool context and wraps a backend HTTP client. Bundles: `DISCOVERY_TOOLS` (`agentSearchTool`, `agentGetTool`), `MARKETPLACE_TOOLS` (`marketplaceViewTool` — read-only), `PAYMENT_TOOLS` (`paymentBalanceTool`, `paymentTransferTool`, …).
 - **Adapters / utils:** `OpenAIAdapter`, JSON helpers, formatters
-- **Re-exported** from `@ziggs-ai/api-client`: `WebSocketClient`, `ContextReadClient`, `ContextDiscoveryClient`, `ContextGrantsClient`, `ArtifactsClient`, `MessagesClient`, `ScopeClient`, `AgentSearchClient`, `getBackendUrl`, `getWebSocketUrl`, etc. (There is no `ContextReader` / `ContextWriter` — use the clients above from `@ziggs-ai/api-client` directly.)
+- **Re-exported** from `@ziggs-ai/api-client`: `ContextReadClient`, `ContextDiscoveryClient`, `ContextGrantsClient`, `ArtifactsClient`, `MessagesClient`, `ScopeClient`, `AgentSearchClient`, `getBackendUrl`, `getWebSocketUrl`, etc. (There is no `ContextReader` / `ContextWriter` — use the clients above from `@ziggs-ai/api-client` directly. The WebSocket client was removed — delivery is HTTP inbox long-poll; read/ack via `InboxClient` from `@ziggs-ai/api-client`.)
 
 Package export: `"."` → `dist/index.js` (see `package.json`; `npm run build` before publish or monorepo tests).
 

package/dist/AgentHost.d.ts

@@ -25,7 +25,6 @@ export interface SessionStore {
 import { ToolManager } from './tools/ToolManager.js';
 import type { ToolDefinition } from './tools/defineTool.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
-import { WebSocketClient } from '@ziggs-ai/api-client';
 /**
  * The single fleet-wide default model — the one place the fallback lives.
  * Change this (or set `LLM_MODEL`) to move the whole fleet; nothing hardcodes a
@@ -75,6 +74,15 @@ export interface AgentHostOptions {
     cognition?: CognitionKind;
     /** Max agentic turns per Claude SDK wake. Default 30. */
     claudeMaxTurns?: number;
+    /**
+     * ZIG-860: claude-sdk agents resume their transcript across wakes by default,
+     * so per-wake input grows monotonically on a long lane. When true, each wake
+     * starts a fresh Claude session — the protocol is backend-authoritative (the
+     * brain re-reads via ziggs_context_snapshot / the wake event), so the
+     * transcript is convenience memory, not source of truth. Ideal for
+     * step-driven orchestrators whose every wake already carries what it needs.
+     */
+    claudeStatelessPerWake?: boolean;
     services?: AgentServices;
     workflow?: Workflow;
     states?: Workflow['states'];
@@ -133,7 +141,6 @@ export declare class AgentHost {
     toolManager: ToolManager;
     llm?: OpenAIAdapter | LlmAdapter;
     agent: Agent | ClaudeSdkAgent;
-    wsClient: WebSocketClient;
     private eff;
     private eventQueue;
     private sessions;
@@ -145,39 +152,33 @@ export declare class AgentHost {
     private agreementService;
     private messageSender;
     private seenMessages;
-    /** Lazy inbox client for advancing the watermark on the live-push path (ZIG-832 P4). */
-    private _inbox?;
     private stateTimers;
-    private catchUpInFlight;
-    private inboxCatchUpEnabled;
+    /** The per-agent inbox long-poll loop — this agent's sole wake source. */
+    private inboxLoop;
+    private inboxLoopEnabled;
     constructor(options?: AgentHostOptions);
     private _validate;
     private _setup;
     /**
-     * Coalesce concurrent connect/reconnect bursts into one catch-up pass.
-     */
-    private _ensureCatchUp;
-    private _runInboxCatchUp;
-    /**
-     * Push notification handler — invoked when the backend sees a relevant
-     * resource change (artifact created, task state transition, agreement
-     * updated). The agent decides which session/lane to wake based on the
-     * event payload; it pulls the actual data via the primitive endpoints
-     * from inside the tick.
+     * Handler for a resource change (artifact created, task state transition,
+     * agreement updated) surfaced by the inbox loop. The agent decides which
+     * session/lane to route it to from the event payload, then pulls the actual
+     * data via the primitive endpoints from inside the tick.
      *
+     * No client-side relevance or echo guard: event targeting is backend policy
+     * now (the law never routes an agent its own writes), and the inbox loop is a
+     * single delta-read channel — there is no second channel to dedup against.
      * Lightweight: defers all work to a tick by enqueueing a synthetic event
-     * carrying just enough context for the agent to route it.
+     * carrying just enough context to route it.
      */
     handleResourceEvent(event: Record<string, unknown>): Promise<void>;
     /** Wire entry. Normalize → resolve session → enqueue on the right lane. */
     handleMessage(text: string, metadata?: Record<string, unknown>): Promise<void>;
-    /** Best-effort: advance the inbox watermark for a chat handled live (ZIG-832 P4). */
-    private _ackChatWatermark;
     private _processEvent;
     /** Arms the lane's liveness timer iff stateName is a parked state declaring timeoutMs. */
     private _armIfTimedParked;
     private _resolveOwnAgentId;
-    connectAsync(timeout?: number): Promise<this>;
+    connectAsync(_timeout?: number): Promise<this>;
     private _bootstrapAssignedActiveTasks;
     /** ZIG-802: replay task-assigned for an existing active task (demo recovery). */
     wakeTaskAssignment(taskId: string): Promise<void>;

package/dist/AgentHost.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { Agent } from './agent/Agent.js';
 import { ClaudeSdkAgent } from './agent/ClaudeSdkAgent.js';
 import { applyBrainToHostOptions, isClaudeCognition, } from './brain/index.js';
@@ -13,10 +14,10 @@ import { ToolManager } from './tools/ToolManager.js';
 import { PROTOCOL_TOOLS } from './server/tools/tier1/protocolTools.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
-import { WebSocketClient, ArtifactsClient, ContextReadClient, TelemetryClient, InboxClient, } from '@ziggs-ai/api-client';
+import { ArtifactsClient, ContextReadClient, TelemetryClient, sendChatMessage, } from '@ziggs-ai/api-client';
 import { TaskService } from './server/tasks/TaskService.js';
 import { AgreementService } from './server/agreements/AgreementService.js';
-import { runInboxCatchUp } from './server/InboxCatchUp.js';
+import { runInboxLoop } from './server/inboxLoop.js';
 import { SeenMessages } from './server/SeenMessages.js';
 import { runtimeLog } from './shared/runtimeLog.js';
 /**
@@ -100,7 +101,6 @@ export class AgentHost {
     // drives query() directly and needs no LLM adapter.
     llm;
     agent;
-    wsClient;
     eff;
     eventQueue;
     sessions = new Map();
@@ -112,11 +112,10 @@ export class AgentHost {
     agreementService;
     messageSender;
     seenMessages = new SeenMessages();
-    /** Lazy inbox client for advancing the watermark on the live-push path (ZIG-832 P4). */
-    _inbox;
     stateTimers;
-    catchUpInFlight = null;
-    inboxCatchUpEnabled;
+    /** The per-agent inbox long-poll loop — this agent's sole wake source. */
+    inboxLoop = null;
+    inboxLoopEnabled;
     constructor(options = {}) {
         const resolved = applyBrainToHostOptions(options);
         this.options = {
@@ -144,8 +143,9 @@ export class AgentHost {
             brain: resolved.brain,
             cognition: resolved.cognition ?? 'fsm',
             claudeMaxTurns: resolved.claudeMaxTurns,
+            claudeStatelessPerWake: resolved.claudeStatelessPerWake,
         };
-        this.inboxCatchUpEnabled = options.inboxCatchUp !== false;
+        this.inboxLoopEnabled = options.inboxCatchUp !== false;
         this.sessionResolver = options.sessionResolver || DEFAULT_SESSION_RESOLVER;
         this.tickTimeoutMs = options.tickTimeoutMs ?? 120_000;
         this.memory = options.memory ?? new InMemoryStore();
@@ -177,19 +177,24 @@ export class AgentHost {
         const services = createBackendServices(this.options);
         this.toolManager = services.toolManager;
         this.llm = services.llm;
-        this.wsClient = new WebSocketClient({
-            wsUrl: this.options.wsUrl,
+        // Outbound send is HTTP (delivery law, phase 4): the agent no longer holds a
+        // socket. `POST /chats/:id/messages` persists the whole message — the same
+        // row the WS path persisted. Live-token streaming had no HTTP path, so
+        // `chunkSender` is intentionally dropped: partials degrade, the full reply
+        // is never lost (runTurn always follows a stream with a whole send-message).
+        const creds = {
             operatorKey: this.options.operatorKey,
             agentId: this.options.agentId,
-            label: this.options.name || 'agent',
-        });
-        const messageSender = (message, receiverId, sessionId, messageId) => {
-            this.wsClient.send(sessionId, receiverId, message, messageId ? { messageId } : undefined);
-            return Promise.resolve(undefined);
-        };
-        const chunkSender = (sessionId, receiverId, text, messageId) => {
-            this.wsClient.send(sessionId, receiverId, text, { partial: true, messageId });
         };
+        const messageSender = (message, receiverId, sessionId, messageId) => sendChatMessage({
+            chatId: sessionId,
+            receiverId,
+            text: message,
+            // messageId is the backend's (chatId, messageId) dedup key. Callers
+            // pass a wake-derived id for replay-stability; fall back to a fresh id
+            // only when absent (matches the old WS path letting the server assign).
+            messageId: messageId ?? `sdk_${randomUUID()}`,
+        }, creds);
         this.taskService = services.taskService;
         this.agreementService = services.agreementService;
         this.messageSender = messageSender;
@@ -225,7 +230,6 @@ export class AgentHost {
             taskService: services.taskService,
             agreementService: services.agreementService,
             messageSender,
-            chunkSender,
             toolManager: services.toolManager,
             operatorKey: this.options.operatorKey,
             agentId: this.options.agentId,
@@ -247,6 +251,7 @@ export class AgentHost {
                 // eff({ kind: 'tool-call' }) → the shared executor, which sources those
                 // services from the effect handler's deps like the FSM path (ZIG-775).
                 maxTurns: this.options.claudeMaxTurns,
+                statelessPerWake: this.options.claudeStatelessPerWake,
             })
             : new Agent({
                 workflow,
@@ -255,54 +260,18 @@ export class AgentHost {
             });
         this.eventQueue = new EventQueue((event, laneKey) => this._processEvent(event, laneKey));
         this.stateTimers = new StateTimers((ev, laneKey) => { void this.eventQueue.enqueue(ev, laneKey); });
-        this.wsClient.setMessageHandler((text, metadata) => this.handleMessage(text, metadata));
-        this.wsClient.setResourceEventHandler((event) => this.handleResourceEvent(event));
-        if (this.inboxCatchUpEnabled) {
-            this.wsClient.onConnect(() => {
-                void this._ensureCatchUp();
-            });
-        }
-    }
-    /**
-     * Coalesce concurrent connect/reconnect bursts into one catch-up pass.
-     */
-    _ensureCatchUp() {
-        if (!this.catchUpInFlight) {
-            this.catchUpInFlight = this._runInboxCatchUp().finally(() => {
-                this.catchUpInFlight = null;
-            });
-        }
-        return this.catchUpInFlight;
-    }
-    async _runInboxCatchUp() {
-        const label = this.options.name || 'agent';
-        try {
-            await runInboxCatchUp({
-                creds: {
-                    operatorKey: this.options.operatorKey,
-                    agentId: this.options.agentId,
-                },
-                ownAgentId: this.options.agentId,
-                baseUrl: this.options.wsUrl ? undefined : undefined,
-                seen: this.seenMessages,
-                label,
-                onMessage: (text, metadata) => this.handleMessage(text, metadata),
-                onResourceEvent: (event) => this.handleResourceEvent(event),
-            });
-        }
-        catch (err) {
-            runtimeLog.warn(label, `inbox catch-up failed: ${err?.message ?? err}`);
-        }
     }
     /**
-     * Push notification handler — invoked when the backend sees a relevant
-     * resource change (artifact created, task state transition, agreement
-     * updated). The agent decides which session/lane to wake based on the
-     * event payload; it pulls the actual data via the primitive endpoints
-     * from inside the tick.
+     * Handler for a resource change (artifact created, task state transition,
+     * agreement updated) surfaced by the inbox loop. The agent decides which
+     * session/lane to route it to from the event payload, then pulls the actual
+     * data via the primitive endpoints from inside the tick.
      *
+     * No client-side relevance or echo guard: event targeting is backend policy
+     * now (the law never routes an agent its own writes), and the inbox loop is a
+     * single delta-read channel — there is no second channel to dedup against.
      * Lightweight: defers all work to a tick by enqueueing a synthetic event
-     * carrying just enough context for the agent to route it.
+     * carrying just enough context to route it.
      */
     async handleResourceEvent(event) {
         if (!event || typeof event !== 'object')
@@ -310,29 +279,6 @@ export class AgentHost {
         const ownAgentId = this.options.agentId;
         if (!ownAgentId)
             return;
-        // The agent's own writes aren't news to it (same rule the backend inbox
-        // applies to counts). The backend already skips agent actors on emit;
-        // this guards the same invariant host-side so a self-caused event can
-        // never re-wake the brain — that echo was a token-burning wake loop for
-        // LLM cognitions (one wake's tool calls seeded the next wake, forever).
-        if (event.actorId != null && String(event.actorId) === ownAgentId) {
-            runtimeLog.debug('AgentHost', `skip self-caused resource event kind=${event.kind ?? 'unknown'} resourceId=${event.resourceId ?? 'null'}`);
-            return;
-        }
-        // A `message` resource event is the second channel for news the message
-        // push already delivered — the backend emits BOTH a `chat:message` frame
-        // and a `resource_changed {kind:'message', resourceId: messageId}` for
-        // every send. The resource frame exists for offline recovery (queue +
-        // launcher wake); when we already processed that messageId live via
-        // handleMessage, waking again just re-runs the brain over handled news
-        // (every inbound chat message cost a second wake). Unseen ids still wake:
-        // that's the recovery path working.
-        if (event.kind === 'message' &&
-            typeof event.resourceId === 'string' &&
-            this.seenMessages.has(event.resourceId)) {
-            runtimeLog.debug('AgentHost', `skip resource event for already-handled message ${event.resourceId}`);
-            return;
-        }
         // Map the event to a candidate session key using the configured resolver
         // on a synthetic normalized-event shape. Default resolver buckets by
         // chatId; agents using a different sessionResolver (agreementId, taskId,
@@ -341,8 +287,6 @@ export class AgentHost {
         const fakeNormalized = {
             chatId: event.chatId,
             event: { type: 'message', timestamp: Date.now(), text: '' },
-            shouldProcess: true,
-            reason: null,
         };
         const sessionId = this.sessionResolver(fakeNormalized, ownAgentId);
         if (!sessionId)
@@ -375,12 +319,10 @@ export class AgentHost {
                 enrichedText = String(terms.description);
             }
         }
+        // Classification + shape only. Targeting is backend policy now — the inbox
+        // loop delivers only what is fenced to this agent, so there is no
+        // client-side "is this for me" gate to apply.
         const normalized = normalizeIncomingEvent({ text: enrichedText, metadata, ownAgentId });
-        if (!normalized.shouldProcess) {
-            const receiverId = metadata.receiver?.id ?? metadata.receiverId;
-            runtimeLog.warn('AgentHost', `skip reason=${normalized.reason || 'not_relevant'} ownAgentId=${ownAgentId} receiverId=${receiverId ?? 'null'} chatId=${normalized.chatId ?? 'null'}`);
-            return;
-        }
         const sessionId = this.sessionResolver(normalized, ownAgentId);
         if (!sessionId) {
             runtimeLog.warn('AgentHost', `session resolver returned null ownAgentId=${ownAgentId} chatId=${normalized.chatId ?? 'null'}`);
@@ -390,38 +332,10 @@ export class AgentHost {
         if (!this.sessions.has(laneKey)) {
             this.sessions.set(laneKey, { sessionId, ownAgentId });
         }
-        const enqueued = this.eventQueue.enqueue(normalized.event, laneKey);
-        // ZIG-832 P4: advance this chat's inbox watermark for a message handled on
-        // the LIVE push path. Without it, only catch-up acks — so on a re-host the
-        // server watermark still sits before this message and catch-up re-delivers
-        // it, re-running a finished pipeline (the cross-wake token burn). Mirrors
-        // catch-up's ack-on-delivery; newer messages carry a later ts and still
-        // deliver, so a genuinely new turn in the same chat is not lost. Best-effort:
-        // never block or fail the wake.
-        const msgTs = (metadata.createdAt ?? metadata.timestamp ?? metadata.sentTimestamp);
-        if (normalized.chatId && typeof msgTs === 'string' && msgTs) {
-            void this._ackChatWatermark(normalized.chatId, msgTs);
-        }
-        else if (normalized.chatId) {
-            // ZIG-860: this ack silently not firing is exactly how the re-delivery
-            // bug hid — a live message with no usable timestamp must be loud.
-            runtimeLog.warn('AgentHost', `live-ack skipped: no timestamp on message chatId=${normalized.chatId} messageId=${messageId ?? 'null'}`);
-        }
-        return enqueued;
-    }
-    /** Best-effort: advance the inbox watermark for a chat handled live (ZIG-832 P4). */
-    async _ackChatWatermark(chatId, upTo) {
-        try {
-            if (!this._inbox) {
-                this._inbox = new InboxClient(this.options.operatorKey, this.options.agentId);
-            }
-            await this._inbox.ack([{ kind: 'chat', id: chatId, upTo }]);
-        }
-        catch (e) {
-            // warn, not debug (ZIG-860): a failing live-ack means catch-up will
-            // re-deliver this chat's backlog after the next host eviction.
-            runtimeLog.warn('AgentHost', `live-ack chat ${chatId} failed: ${e?.message ?? e}`);
-        }
+        // The inbox loop owns ack (act-before-ack, delivery law); the host only
+        // routes the event onto its lane. No live-path watermark ack — there is no
+        // separate live/push channel to reconcile against anymore.
+        return this.eventQueue.enqueue(normalized.event, laneKey);
     }
     async _processEvent(event, laneKey) {
         const session = this.sessions.get(laneKey);
@@ -540,16 +454,26 @@ export class AgentHost {
         const agent = metadata.agent;
         return this.options.agentId || self?.id || agent?.id || metadata.ziggsAgentId || null;
     }
-    async connectAsync(timeout) {
-        await this.wsClient.connectAsync(timeout);
-        if (this.inboxCatchUpEnabled) {
-            await this._ensureCatchUp();
-            // Backend flushPendingMessages can emit after auth; re-poll once so inbox
-            // ack catches stragglers and we don't leave newMessages > 0 (ZIG-462).
-            await new Promise((r) => setTimeout(r, 750));
-            this.catchUpInFlight = null;
-            await this._ensureCatchUp();
+    async connectAsync(_timeout) {
+        // Bootstrap active assigned tasks once (HTTP pull → lane), then start the
+        // per-agent inbox long-poll loop — the agent's sole wake source. There is
+        // no socket to connect and no reconnect: a crash is just the loop's next
+        // iteration (the cursor is server-side). `_timeout` is accepted for
+        // backward-compatible call sites but no longer gates a handshake.
+        if (this.inboxLoopEnabled) {
             await this._bootstrapAssignedActiveTasks();
+            const label = this.options.name || 'agent';
+            this.inboxLoop = runInboxLoop({
+                creds: {
+                    operatorKey: this.options.operatorKey,
+                    agentId: this.options.agentId,
+                },
+                ownAgentId: this.options.agentId,
+                seen: this.seenMessages,
+                label,
+                onMessage: (text, metadata) => this.handleMessage(text, metadata),
+                onResourceEvent: (event) => this.handleResourceEvent(event),
+            });
         }
         return this;
     }
@@ -630,11 +554,11 @@ export class AgentHost {
             chatId: full.originChatId,
         }, laneKey);
     }
-    disconnect() { this.stateTimers.clearAll(); this.wsClient.disconnect(); }
+    disconnect() { this.stateTimers.clearAll(); void this.inboxLoop?.stop(); this.inboxLoop = null; }
     /** Waits for all in-flight ticks to complete. Call before process.exit() on SIGTERM. */
     drain(timeoutMs = 30_000) { return this.eventQueue.waitForIdle(timeoutMs); }
     registerTool(tool) { return this.toolManager.register(tool); }
-    isConnected() { return this.wsClient.isConnected(); }
+    isConnected() { return this.inboxLoop?.running ?? false; }
 }
 /**
  * createAgent(config)            → AgentHost

package/dist/adapters/McpAdapter.js

@@ -1,6 +1,7 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { ConnectionsClient } from '@ziggs-ai/api-client';
 import { AgentHost } from '../AgentHost.js';
 import { thinkingDefaults } from '../runtime/defaults.js';
 /**
@@ -368,21 +369,21 @@ export async function createMcpAgent(options) {
             if (!transportConfig.serverUrl)
                 return null;
             const operatorKey = transportConfig.operatorKey || process.env.ZIGGS_OPERATOR_KEY;
-            const res = await fetch(`${backendBase}/connections/mcp/requests`, {
-                method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    authorization: `Bearer ${operatorKey}`,
-                    'x-agent-id': agentId,
-                    'x-on-behalf-of-user': userId,
-                },
-                body: JSON.stringify({
+            if (!operatorKey)
+                return null;
+            try {
+                const body = await new ConnectionsClient(operatorKey, agentId, backendBase).requestMcpConnection({
                     serverUrl: transportConfig.serverUrl,
                     tools: tools.map(t => t.name),
-                }),
-            });
-            const body = (await res.json().catch(() => null));
-            return body?.request?.requestId ?? null;
+                    onBehalfOfUserId: userId,
+                });
+                return (body?.request?.requestId) ?? null;
+            }
+            catch {
+                // Best-effort: the backend dedups pending requests and the caller falls
+                // back to a plain Connections-page link when there's no requestId.
+                return null;
+            }
         };
         const caller = async (name, args, context) => {
             const userId = typeof context.senderId === 'string' ? context.senderId : undefined;

package/dist/agent/Agent.js

@@ -1,4 +1,5 @@
 import { AgentMachine } from '../runtime/AgentMachine.js';
+import { createWakeWriteKeys } from '../runtime/wakeWriteKeys.js';
 import { runTurn } from '../runtime/runTurn.js';
 import { PromptBuilder } from '../runtime/PromptBuilder.js';
 /**
@@ -43,6 +44,9 @@ export class Agent {
             memory,
             input: { identity, ctx, state },
             transitionTap,
+            // One key stream per wake, shared by every state this tick runs through —
+            // per-state streams would restart the ordinal and collide across states.
+            wakeKeys: createWakeWriteKeys(identity.laneKey, event),
         });
         // `send` awaits the recursive _step until the machine settles at a
         // parked state (or stops). When it returns, we have the final state.

package/dist/agent/ClaudeSdkAgent.d.ts

@@ -13,6 +13,10 @@ export interface ClaudeSdkAgentOptions {
     operatorKey: string;
     agentId: string;
     maxTurns?: number;
+    /** ZIG-860: when true, never resume the prior Claude session — each wake is a
+     *  fresh transcript. Keeps per-wake input flat on step-driven orchestrators
+     *  whose wakes already carry their state. */
+    statelessPerWake?: boolean;
     /** Injectable for tests. Defaults to @anthropic-ai/claude-agent-sdk query(). */
     queryFn?: typeof query;
 }
@@ -32,6 +36,7 @@ export declare class ClaudeSdkAgent {
     private operatorKey;
     private agentId;
     private maxTurns;
+    private statelessPerWake;
     private queryFn;
     constructor(opts: ClaudeSdkAgentOptions);
     tick({ event, ctx, state, identity, eff }: TickInput): Promise<TickOutput>;

package/dist/agent/ClaudeSdkAgent.js

@@ -1,6 +1,7 @@
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { outcomeFromEvent } from '../runtime/buildOutcome.js';
 import { bootstrapCtx } from '../runtime/bootstrapCtx.js';
+import { createWakeWriteKeys } from '../runtime/wakeWriteKeys.js';
 import { CLAUDE_SDK_PROTOCOL } from './claudeSdkProtocol.js';
 import { buildZiggsSdkMcpServer } from './toolManagerToSdkMcp.js';
 import { claudeQueryOptions, buildClaudeEventPrompt, summarizeContext, extractAssistantText, } from './claudeCognition.js';
@@ -24,9 +25,9 @@ const MAX_TASK_INPUT_TOKENS = Number(process.env.CLAUDE_SDK_MAX_INPUT_TOKENS ??
 /**
  * Per-lane wake-rate circuit breaker. The per-wake caps above bound one wake;
  * nothing bounded the NUMBER of wakes — the agent-private artifact echo drove
- * one wake per wake, forever. The echo is fixed at the source (backend skips
- * agent actors; host drops self-caused events), so this is a backstop for any
- * future echo path: a lane waking faster than real traffic plausibly drives it
+ * one wake per wake, forever. The echo is fixed at the source (backend
+ * targeting never routes an agent its own writes), so this is a backstop for
+ * any future echo path: a lane waking faster than real traffic plausibly drives it
  * skips the LLM (and logs loudly) instead of draining the fleet key. */
 const WAKE_WINDOW_MS = 10 * 60_000;
 const MAX_WAKES_PER_WINDOW = Number(process.env.CLAUDE_SDK_MAX_WAKES_PER_WINDOW ?? 40);
@@ -141,6 +142,7 @@ export class ClaudeSdkAgent {
     operatorKey;
     agentId;
     maxTurns;
+    statelessPerWake;
     queryFn;
     constructor(opts) {
         if (!opts.workflow?.states)
@@ -158,6 +160,7 @@ export class ClaudeSdkAgent {
         this.operatorKey = opts.operatorKey;
         this.agentId = opts.agentId;
         this.maxTurns = opts.maxTurns ?? DEFAULT_MAX_TURNS;
+        this.statelessPerWake = opts.statelessPerWake ?? false;
         this.queryFn = opts.queryFn ?? query;
     }
     async tick({ event, ctx, state, identity, eff }) {
@@ -214,6 +217,10 @@ export class ClaudeSdkAgent {
         ].filter(Boolean).join('\n');
         const systemPrompt = `${CLAUDE_SDK_PROTOCOL}\n\n${roleBlock}`;
         const runId = crypto.randomUUID();
+        // Replay-stable write keys for this wake (runId is random and can't serve):
+        // a crash-replay of the same event derives the same keys, so the backend
+        // drops the duplicate artifacts / no-ops the repeated task transitions.
+        const wakeKeys = createWakeWriteKeys(identity.laneKey, rawEvent);
         const toolContext = {
             operatorKey: this.operatorKey,
             agentId: this.agentId,
@@ -228,6 +235,7 @@ export class ClaudeSdkAgent {
             // not just task_result events — see resolveOnBehalfAgreementId.
             onBehalfOfAgreementId: resolveOnBehalfAgreementId(rawEvent, contextSnap, this.agentId, identity.sessionId),
             runId,
+            wakeKeys,
         };
         const availableTools = await this.toolManager.getAvailableTools();
         const mcpServer = buildZiggsSdkMcpServer(availableTools, () => toolContext, {
@@ -248,7 +256,10 @@ export class ClaudeSdkAgent {
                 if (line)
                     runtimeLog.warn('ClaudeSdkAgent', `stderr session=${identity.sessionId}: ${line}`);
             },
-            resume: nextCtx.claudeSessionId,
+            // ZIG-860: stateless-per-wake never resumes — each wake is a fresh
+            // transcript, so per-wake input stays flat instead of replaying the
+            // whole lane history every turn.
+            resume: this.statelessPerWake ? undefined : nextCtx.claudeSessionId,
         });
         let metrics = { llmCalls: 0, tokens: { total: 0, input: 0, output: 0, cacheRead: 0, cacheCreation: 0 } };
         let sessionId = nextCtx.claudeSessionId;
@@ -274,7 +285,10 @@ export class ClaudeSdkAgent {
                 if (message.type === 'assistant') {
                     const text = extractAssistantText(message).trim();
                     if (text) {
-                        void eff({ kind: 'record-event', sessionId: identity.sessionId, entry: { kind: 'thought', text } })
+                        // Ordinal drawn synchronously so the fire-and-forget below can't
+                        // reorder key assignment against other writes of this wake.
+                        const idempotencyKey = wakeKeys.artifactKey();
+                        void eff({ kind: 'record-event', sessionId: identity.sessionId, entry: { kind: 'thought', text }, idempotencyKey })
                             .catch((err) => runtimeLog.warn('ClaudeSdkAgent', `record thought failed session=${identity.sessionId}: ${err.message}`));
                     }
                 }
@@ -298,7 +312,12 @@ export class ClaudeSdkAgent {
             runtimeLog.warn('ClaudeSdkAgent', `query failed session=${identity.sessionId}: ${err.message}`);
             throw err;
         }
-        if (sessionId)
+        // Stateless-per-wake keeps no session id — clear any carried over from the
+        // prior ctx so the next wake starts fresh too (ZIG-860). Otherwise remember
+        // this wake's session for resume.
+        if (this.statelessPerWake)
+            nextCtx.claudeSessionId = undefined;
+        else if (sessionId)
             nextCtx.claudeSessionId = sessionId;
         // ZIG-816: bound resumed-transcript growth. `metrics.tokens.input` is the
         // wake's billable input off the result message (dominated by the resumed

package/dist/agent/claudeCognition.d.ts

@@ -63,5 +63,12 @@ export declare function summarizeContext(snap: Record<string, unknown> | null |
  * Turn a Ziggs wake event + context digest into the user prompt that starts a
  * Claude-brain turn. The agent's standing instructions come from its system
  * prompt (protocol + role); this is just "here's what woke you, go handle it."
+ *
+ * ZIG-880: EventQueue coalesces events that arrive while the lane is busy into
+ * a `{type:'batch', events:[...]}` frame. The FSM path unwraps those
+ * (PromptBuilder), but this path used to render just "Event type: batch" —
+ * every payload inside (including task results) was invisible to the model,
+ * stalling delegation pipelines whose notifications share one chat lane.
+ * Render each batched event in order instead.
  */
 export declare function buildClaudeEventPrompt(event: RawEvent | undefined, contextSummary: string): string;