@ziggs-ai/agent-sdk 0.2.1 → 0.3.0

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,
                         });
                     }
                 }

package/dist/server/inboxLoop.d.ts

@@ -0,0 +1,50 @@
+import { type Creds } from '@ziggs-ai/api-client';
+import { SeenMessages } from './SeenMessages.js';
+/**
+ * Per-agent inbox long-poll loop (delivery law, phase 4). This is the ONLY way
+ * a hosted agent consumes: `GET /inbox?wait=` → grant-fenced reads of the delta
+ * → deliver into the host's lane/tick machinery → `POST /inbox/ack`. No socket,
+ * no push, no separate catch-up channel — a crash-replay is just the next
+ * iteration (the cursor is server-side), and writes carry idempotency keys so
+ * re-processing a redelivered window is wasteful, never harmful. Act-before-ack
+ * is the one ordering rule.
+ */
+export interface InboxLoopDeps {
+    creds: Creds;
+    ownAgentId: string;
+    baseUrl?: string;
+    seen: SeenMessages;
+    onMessage: (text: string, metadata: Record<string, unknown>) => Promise<void>;
+    onResourceEvent: (event: Record<string, unknown>) => Promise<void>;
+    label?: string;
+}
+export interface InboxPassResult {
+    scopes: number;
+    messagesDelivered: number;
+    resourceEvents: number;
+    acked: number;
+    truncated: boolean;
+}
+/**
+ * One long-poll pass: hold up to `waitSeconds` for new inbox content, then read
+ * the deltas, deliver them into the host, and ack. Returns what it delivered.
+ * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
+ * read (`waitSeconds: 0`) at bootstrap.
+ */
+export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number): Promise<InboxPassResult>;
+export interface InboxLoopHandle {
+    /** Stop the loop after the current pass; resolves when it has fully exited. */
+    stop(): Promise<void>;
+    /** True while the loop is running. */
+    readonly running: boolean;
+}
+/**
+ * Run {@link pollInboxOnce} forever (until stopped). Each iteration long-polls
+ * for `waitSeconds`; a passing envelope returns instantly, an empty one holds.
+ * Errors retry with exponential backoff + jitter and never exit the loop —
+ * there is nothing to resynchronize (the cursor is server-side), so recovery is
+ * just the next iteration.
+ */
+export declare function runInboxLoop(deps: InboxLoopDeps, opts?: {
+    waitSeconds?: number;
+}): InboxLoopHandle;

package/dist/server/{InboxCatchUp.js → inboxLoop.js}

@@ -1,4 +1,4 @@
-import { ContextReadClient, GrantsClient, InboxClient, getChatsForAgreement, getAgreementStatus, } from '@ziggs-ai/api-client';
+import { ContextReadClient, GrantsClient, InboxClient, getChatsForAgreement, } from '@ziggs-ai/api-client';
 import { runtimeLog } from '../shared/runtimeLog.js';
 const READ_PAGE = 100;
 function log(label, msg) {
@@ -7,19 +7,6 @@ function log(label, msg) {
 function warn(label, msg) {
     runtimeLog.warn(label, msg);
 }
-const TERMINAL_AGREEMENT_STATUSES = new Set(['fulfilled', 'cancelled', 'refunded']);
-/** ZIG-832 P4: is this agreement finished (so its backlog must not be re-run)? */
-async function isTerminalAgreement(agreementId, creds) {
-    try {
-        const res = (await getAgreementStatus(agreementId, creds));
-        const status = res?.status ?? res?.agreement?.status;
-        return status != null && TERMINAL_AGREEMENT_STATUSES.has(status);
-    }
-    catch {
-        // On lookup failure, don't skip — fall through to normal delivery.
-        return false;
-    }
-}
 /** Map Mongo message row → wire metadata for normalizeIncomingEvent. */
 function rowToMetadata(row, chatId) {
     const senderRaw = row.sender;
@@ -47,7 +34,7 @@ function rowToMetadata(row, chatId) {
         text: row.text,
     };
 }
-async function chatIdsForScope(scope, creds, baseUrl, grants) {
+async function chatIdsForScope(scope, creds, grants) {
     const { kind, id } = scope.scope;
     switch (kind) {
         case 'chat':
@@ -57,8 +44,8 @@ async function chatIdsForScope(scope, creds, baseUrl, grants) {
             return [...new Set(links.map((l) => l.chatId).filter(Boolean))];
         }
         case 'org': {
-            // All pages of live chat grants — an org-scope catch-up must not miss
-            // chats hidden behind pagination (GET /grants defaults to one page).
+            // All pages of live chat grants — an org-scope read must not miss chats
+            // hidden behind pagination (GET /grants defaults to one page).
             const items = await grants.listAllGrants({
                 scopeKind: 'chat',
                 health: 'active',
@@ -71,7 +58,7 @@ async function chatIdsForScope(scope, creds, baseUrl, grants) {
 }
 async function deliverMessagesForScope(deps, scope, chatIds, reader, countCap) {
     let delivered = 0;
-    const label = deps.label ?? 'InboxCatchUp';
+    const label = deps.label ?? 'inboxLoop';
     const expected = scope.newMessages;
     let remaining = expected >= countCap ? Number.POSITIVE_INFINITY : expected;
     for (const chatId of chatIds) {
@@ -113,49 +100,31 @@ async function deliverMessagesForScope(deps, scope, chatIds, reader, countCap) {
     return delivered;
 }
 /**
- * Pull-based recovery after reconnect (ZIG-434 / ZIG-446 / ZIG-454).
- * Inbox → read message deltas → deliver → ack. Push remains a hint;
- * this path survives backend restarts that drop in-memory pending queues.
+ * One long-poll pass: hold up to `waitSeconds` for new inbox content, then read
+ * the deltas, deliver them into the host, and ack. Returns what it delivered.
+ * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
+ * read (`waitSeconds: 0`) at bootstrap.
  */
-export async function runInboxCatchUp(deps) {
-    const label = deps.label ?? 'InboxCatchUp';
+export async function pollInboxOnce(deps, waitSeconds = 0) {
+    const label = deps.label ?? 'inboxLoop';
     const inbox = new InboxClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
     const reader = new ContextReadClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
     const grants = new GrantsClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
-    const envelope = await inbox.getInbox();
+    const envelope = await inbox.getInbox(waitSeconds > 0 ? { waitSeconds } : {});
     const countCap = envelope.countCap;
     let messagesDelivered = 0;
     let resourceEvents = 0;
     const toAck = [];
     if (envelope.truncatedScopes > 0) {
-        // Informational only — does NOT block acking the scopes actually
-        // returned below. truncatedScopes just means the caller's total reach
-        // exceeded the server's per-call scope cap (backend/src/inbox/inbox.service.ts,
-        // INBOX_MAX_SCOPES); each entry in envelope.scopes is still an
-        // independently accurate, safe-to-ack unit of news for that scope. Never
-        // acking here meant a busy long-lived agent (reach > cap) would never ack
-        // anything and re-deliver its entire backlog on every reconnect forever.
+        // Informational only — does NOT block acking the scopes returned below.
+        // truncatedScopes just means the caller's total reach exceeded the server's
+        // per-call scope cap; each returned scope is still an independently accurate,
+        // safe-to-ack unit of news. Never acking here would make a busy agent
+        // (reach > cap) re-deliver its whole backlog every pass forever.
         warn(label, `inbox truncatedScopes=${envelope.truncatedScopes} (reach exceeds per-call cap — examined scopes are still acked normally)`);
     }
     for (const scope of envelope.scopes) {
-        // ZIG-832 P4: a re-host runs catch-up from the server watermark and would
-        // re-deliver an already-finished agreement's backlog, re-running a completed
-        // pipeline and burning tokens. If this is an agreement scope that has reached
-        // a terminal status, ack it (so it drops out of future catch-ups) and skip
-        // re-delivery. Only agreement scopes — chat scopes may carry genuinely new
-        // conversation, so those are never skipped on status. (The deeper fix, acking
-        // the watermark on the live-push path so nothing re-delivers, is tracked
-        // separately.)
-        if (scope.scope.kind === 'agreement' &&
-            (scope.newMessages > 0 || scope.newArtifacts > 0) &&
-            (await isTerminalAgreement(scope.scope.id, deps.creds))) {
-            if (scope.latestAt) {
-                toAck.push({ kind: scope.scope.kind, id: scope.scope.id, upTo: scope.latestAt });
-            }
-            log(label, `scope agreement:${scope.scope.id} terminal — acked, not re-delivered`);
-            continue;
-        }
-        const chatIds = await chatIdsForScope(scope, deps.creds, deps.baseUrl, grants);
+        const chatIds = await chatIdsForScope(scope, deps.creds, grants);
         if (!chatIds.length && (scope.newMessages > 0 || scope.newArtifacts > 0)) {
             warn(label, `no chat ids for scope ${scope.scope.kind}:${scope.scope.id} (${scope.newMessages} msgs)`);
         }
@@ -201,9 +170,6 @@ export async function runInboxCatchUp(deps) {
         acked = toAck.length;
         log(label, `acked ${acked} scope(s)`);
     }
-    if (messagesDelivered > 0 || resourceEvents > 0) {
-        log(label, `catch-up complete: ${messagesDelivered} message(s), ${resourceEvents} resource hint(s)`);
-    }
     return {
         scopes: envelope.scopes.length,
         messagesDelivered,
@@ -212,3 +178,48 @@ export async function runInboxCatchUp(deps) {
         truncated: envelope.truncatedScopes > 0,
     };
 }
+const DEFAULT_WAIT_SECONDS = 25;
+const ERROR_BACKOFF_BASE_MS = 1_000;
+const ERROR_BACKOFF_MAX_MS = 30_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Run {@link pollInboxOnce} forever (until stopped). Each iteration long-polls
+ * for `waitSeconds`; a passing envelope returns instantly, an empty one holds.
+ * Errors retry with exponential backoff + jitter and never exit the loop —
+ * there is nothing to resynchronize (the cursor is server-side), so recovery is
+ * just the next iteration.
+ */
+export function runInboxLoop(deps, opts = {}) {
+    const label = deps.label ?? 'inboxLoop';
+    const waitSeconds = opts.waitSeconds ?? DEFAULT_WAIT_SECONDS;
+    let running = true;
+    let consecutiveErrors = 0;
+    const done = (async () => {
+        while (running) {
+            try {
+                await pollInboxOnce(deps, waitSeconds);
+                consecutiveErrors = 0;
+            }
+            catch (err) {
+                if (!running)
+                    break;
+                consecutiveErrors++;
+                const backoff = Math.min(ERROR_BACKOFF_MAX_MS, ERROR_BACKOFF_BASE_MS * 2 ** (consecutiveErrors - 1));
+                const jitter = backoff * (0.5 + (consecutiveErrors % 7) / 14); // deterministic-ish, no Math.random
+                warn(label, `inbox loop pass failed (#${consecutiveErrors}): ${err?.message ?? err} — retrying in ~${Math.round(jitter)}ms`);
+                await sleep(jitter);
+            }
+        }
+    })();
+    return {
+        get running() {
+            return running;
+        },
+        async stop() {
+            running = false;
+            await done.catch(() => { });
+        },
+    };
+}

package/dist/server/runLauncher.js

@@ -53,7 +53,7 @@ async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port
         pool.startControl({ wsUrl, operatorKey: controlKey });
     }
     else {
-        runtimeLog.warn(label, 'No operatorKey provided — skipping control socket');
+        runtimeLog.warn(label, 'No operatorKey provided — skipping fleet inbox poll (no agents will be lazily started)');
     }
     let primary = null;
     if (resolvedPrimaryConfig) {

package/dist/server/tasks/TaskService.d.ts

@@ -15,8 +15,9 @@ export declare class TaskService {
         requireMidWorkPlanAck?: boolean;
         assigneeId?: string;
         inputArtifactIds?: string[];
+        idempotencyKey?: string;
     }): Promise<Task>;
-    updateState(taskId: string, state: TaskState, result?: unknown): Promise<Task>;
+    updateState(taskId: string, state: TaskState, result?: unknown, idempotencyKey?: string): Promise<Task>;
     updatePlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<Task>;
     cancel(taskId: string): Promise<Task>;
     report(taskId: string, message?: string): Promise<Task>;

package/dist/server/tasks/TaskService.js

@@ -57,9 +57,12 @@ export class TaskService {
             throw error;
         }
     }
-    async updateState(taskId, state, result) {
+    async updateState(taskId, state, result, idempotencyKey) {
         try {
-            const data = result !== undefined ? { result: safeJsonStringify(result) } : {};
+            const data = {
+                ...(result !== undefined ? { result: safeJsonStringify(result) } : {}),
+                ...(idempotencyKey ? { idempotencyKey } : {}),
+            };
             const updated = await updateTaskState(taskId, state, data, this.creds);
             runtimeLog.info('TaskService', `Task state: ${taskId} → ${state}`);
             return updated;

package/dist/server/tools/index.d.ts

@@ -19,6 +19,10 @@ export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreeme
 export { dispatchProtocolOp } from './tier1/protocolRunner.js';
 export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discoveryTools.js';
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
-export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, paymentListGrantsTool, } from './tier2/paymentTools.js';
-export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, } from './tier2/connectionTools.js';
-export { CONTEXT_TOOLS, contextDiscoverTool, contextDelegateTool, } from './tier2/contextTools.js';
+export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, } from './tier2/paymentTools.js';
+export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, } from './tier2/connectionTools.js';
+export { CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
+export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';
+export { LINK_TOOLS, requestLinkTool, createLinkInviteTool, claimLinkInviteTool, listLinksTool, revokeLinkTool, } from './tier2/linkTools.js';
+export { ARTIFACT_TOOLS, recordArtifactTool } from './tier2/artifactTools.js';
+export { CHAT_TOOLS, openConversationTool } from './tier2/chatTools.js';

package/dist/server/tools/index.js

@@ -21,6 +21,16 @@ export { dispatchProtocolOp } from './tier1/protocolRunner.js';
 // ── Tier 2: capability bundles ──────────────────────────────────────────────
 export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discoveryTools.js';
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
-export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, paymentListGrantsTool, } from './tier2/paymentTools.js';
-export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, } from './tier2/connectionTools.js';
-export { CONTEXT_TOOLS, contextDiscoverTool, contextDelegateTool, } from './tier2/contextTools.js';
+export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, } from './tier2/paymentTools.js';
+export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, } from './tier2/connectionTools.js';
+export { CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
+// ZIG-893: one grant lister across every rail (retires context_discover +
+// payment_list_grants). Always-available on the hosted agent — see CLAUDE_SDK_TOOLS.
+export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';
+// ZIG-898: links (agreements with engagementKind 'link') — cross-org reach.
+export { LINK_TOOLS, requestLinkTool, createLinkInviteTool, claimLinkInviteTool, listLinksTool, revokeLinkTool, } from './tier2/linkTools.js';
+// ZIG-899: deliberate artifact recording (the model decides "record this").
+export { ARTIFACT_TOOLS, recordArtifactTool } from './tier2/artifactTools.js';
+// ZIG-900 decision: open_conversation only — chat listing stays a context-rail
+// read (list_grants scopeKind=chat), no duplicate lister (ZIG-626 rule).
+export { CHAT_TOOLS, openConversationTool } from './tier2/chatTools.js';

package/dist/server/tools/tier1/protocolRunner.d.ts

@@ -1,5 +1,6 @@
 import type { AgreementService } from '../../agreements/AgreementService.js';
 import type { TaskService } from '../../tasks/TaskService.js';
+import type { WakeWriteKeys } from '../../../types.js';
 import type { ContextReadClient } from '@ziggs-ai/api-client';
 interface Services {
     agreementService: AgreementService;
@@ -35,5 +36,5 @@ interface ProtocolPayload {
     })[];
     [key: string]: unknown;
 }
-export declare function dispatchProtocolOp(services: Services, payload: ProtocolPayload, chatId: string | null, agents?: unknown[], actingAgentId?: string | null): Promise<unknown>;
+export declare function dispatchProtocolOp(services: Services, payload: ProtocolPayload, chatId: string | null, agents?: unknown[], actingAgentId?: string | null, wakeKeys?: WakeWriteKeys | null): Promise<unknown>;
 export {};