@ziggs-ai/agent-sdk 0.2.2 → 0.3.0

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/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 {};

package/dist/server/tools/tier1/protocolRunner.js

@@ -34,7 +34,7 @@ function normalizePlanInPlace(payload) {
         payload.planReviewTiming = 'with_proposal';
     }
 }
-export async function dispatchProtocolOp(services, payload, chatId, agents = [], actingAgentId = null) {
+export async function dispatchProtocolOp(services, payload, chatId, agents = [], actingAgentId = null, wakeKeys = null) {
     if (!payload?.operation)
         return null;
     normalizePlanInPlace(payload);
@@ -43,9 +43,9 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
     const actorId = actingAgentId?.trim() || null;
     switch (operation) {
         case 'agreement-propose':
-            return proposeAgreement(services, payload, chatId, agents, actorId);
+            return proposeAgreement(services, payload, chatId, agents, actorId, wakeKeys);
         case 'agreement-subcontract':
-            return subcontractAgreement(services, payload, chatId, agents, actorId);
+            return subcontractAgreement(services, payload, chatId, agents, actorId, wakeKeys);
         case 'agreement-respond':
             if (!payload.agreementId || !payload.action)
                 return null;
@@ -146,12 +146,27 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
                 inputArtifactIds: Array.isArray(payload.inputArtifactIds)
                     ? payload.inputArtifactIds
                     : undefined,
+                // Wake-derived idempotency key (delivery law): a crash-replay re-issuing
+                // this spawn resolves to the already-created task server-side instead of
+                // creating a duplicate. Keyed on what is actually written (the resolved
+                // agreement, not the LLM-cited one), so multiple spawns in one wake stay
+                // distinct.
+                idempotencyKey: wakeKeys?.taskSpawnKey({
+                    agreementId: spawnAgreementId,
+                    description: payload.description,
+                    assigneeId: payload.assigneeId,
+                    parentTaskId: payload.parentTaskId,
+                }),
             });
         }
-        case 'task-update':
+        case 'task-update': {
             if (!payload.taskId || !payload.status)
                 return null;
-            return taskService.updateState(payload.taskId, normalizeState(payload.status), payload.result);
+            const state = normalizeState(payload.status);
+            // Wake-derived idempotency key: a crash-replay re-issuing this transition
+            // no-ops server-side instead of erroring on the already-terminal task.
+            return taskService.updateState(payload.taskId, state, payload.result, wakeKeys?.taskStateKey(payload.taskId, state));
+        }
         case 'task-update-plan-step':
             if (!payload.taskId)
                 throw new Error('task-update-plan-step requires `taskId`');
@@ -173,7 +188,7 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
             throw new Error(`Unknown protocol operation: ${operation}`);
     }
 }
-async function proposeAgreement(services, payload, chatId, _agents, actingAgentId) {
+async function proposeAgreement(services, payload, chatId, _agents, actingAgentId, wakeKeys = null) {
     if (!payload.description)
         throw new Error('agreement-propose requires `description`');
     if (!payload.proposedTo)
@@ -187,7 +202,17 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
     }
     const priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
     const { operation: _op, ...fields } = priced;
-    return services.agreementService.propose({ ...fields, chatId });
+    // Wake-derived idempotency key (delivery law): a crash-replay re-issuing this
+    // propose resolves to the already-created agreement server-side instead of
+    // minting a duplicate proposal. Keyed on what the proposal writes, so
+    // multiple proposals in one wake stay distinct.
+    const idempotencyKey = wakeKeys?.agreementProposeKey({
+        proposedTo: payload.proposedTo,
+        providerId: payload.providerId,
+        description: payload.description,
+        parentAgreementId: payload.parentAgreementId,
+    });
+    return services.agreementService.propose({ ...fields, chatId, idempotencyKey });
 }
 // ── ZIG-832: deterministic sub-agreement resolution ─────────────────────────
 // The orchestrator delegates one task per worker, but the LLM inconsistently
@@ -228,7 +253,7 @@ function agActive(a) {
 function agIsActiveStatus(a) {
     return String(a.status ?? '') === 'active';
 }
-async function subcontractAgreement(services, payload, chatId, _agents, actingAgentId) {
+async function subcontractAgreement(services, payload, chatId, _agents, actingAgentId, wakeKeys = null) {
     if (!payload.description || !payload.executorId)
         return null;
     // b1 (ZIG-832): idempotent subcontract — if a non-terminal sub-agreement for
@@ -284,5 +309,14 @@ async function subcontractAgreement(services, payload, chatId, _agents, actingAg
         f.lifecycle = 'count-bound';
         f.maxExecutions = 1;
     }
-    return services.agreementService.delegate({ ...fields, chatId });
+    // Wake-derived idempotency key (delivery law): a crash-replay that slips past
+    // the b1 reuse check above (e.g. no chatId, or the sub not yet visible in the
+    // snapshot) resolves to the already-created sub-agreement server-side instead
+    // of minting a duplicate.
+    const idempotencyKey = wakeKeys?.agreementSubcontractKey({
+        executorId: payload.executorId,
+        description: payload.description,
+        parentAgreementId: payload.parentAgreementId ?? '',
+    });
+    return services.agreementService.delegate({ ...fields, chatId, idempotencyKey });
 }

package/dist/server/tools/tier1/protocolTools.js

@@ -13,7 +13,7 @@ function handlerFor(operation) {
             taskService: c.taskService,
             agreementService: c.agreementService,
             contextReadClient: c.contextReadClient,
-        }, { operation, ...args }, c.chatId ?? null, c.agents ?? [], typeof c.agentId === 'string' ? c.agentId : null);
+        }, { operation, ...args }, c.chatId ?? null, c.agents ?? [], typeof c.agentId === 'string' ? c.agentId : null, c.wakeKeys ?? null);
         if (result == null)
             throw new Error(`Operation ${operation} returned no result`);
         return result;

package/dist/types.d.ts

@@ -346,6 +346,43 @@ export interface RecordedEntry {
     text?: string;
     [k: string]: unknown;
 }
+/**
+ * Deterministic idempotency keys for one wake's writes (delivery law, item 2).
+ * Created once per tick from (laneKey, triggering event) — see
+ * `createWakeWriteKeys` — and threaded to every artifact / task-state write the
+ * wake performs, so a crash-replay of the same wake reproduces the same keys
+ * and the backend drops the duplicates. Never LLM-supplied, never random.
+ */
+export interface WakeWriteKeys {
+    /** Stable id of this wake, or null when its trigger has no durable delivery identity (timer/synthetic frames) — null means writes go keyless, as before. */
+    readonly wakeKey: string | null;
+    /** Key for the next artifact write of this wake. Draws a per-wake ordinal — call exactly once per write, at the call site. */
+    artifactKey(): string | undefined;
+    /** Key for a task state transition. Derived from (taskId, state), so it is stable regardless of tool-call order within the wake. */
+    taskStateKey(taskId: string, state: string): string | undefined;
+    /** Default messageId for the next chat-message send of this wake — the backend dedups on (chatId, messageId). Draws the same per-wake ordinal as artifactKey — call exactly once per send, at the call site. */
+    messageKey(): string | undefined;
+    /** Key for a task spawn. Derived from what the spawn writes (agreement, description, assignee, parent), so it is stable regardless of tool-call order within the wake. */
+    taskSpawnKey(fields: {
+        agreementId: string;
+        description: string;
+        assigneeId?: string;
+        parentTaskId?: string;
+    }): string | undefined;
+    /** Key for an agreement proposal (`agreement_propose`). Derived from what the proposal writes (proposedTo, provider, description, parent), so a crash-replay dedups the row instead of minting a duplicate proposal — and multiple proposals in one wake stay distinct. */
+    agreementProposeKey(fields: {
+        proposedTo: string;
+        providerId?: string;
+        description: string;
+        parentAgreementId?: string;
+    }): string | undefined;
+    /** Key for a sub-agreement (`agreement_subcontract`). Derived from what the subcontract writes (executor, description, parent), so a replay dedups the row. */
+    agreementSubcontractKey(fields: {
+        executorId: string;
+        description: string;
+        parentAgreementId: string;
+    }): string | undefined;
+}
 import type { MemoryStore } from './memory/MemoryStore.js';
 export type EffectKind = 'read-context' | 'llm-call' | 'stream-text' | 'tool-call' | 'send-message' | 'record-event';
 export type Effect = {
@@ -388,6 +425,8 @@ export type Effect = {
     runId?: string;
     /** FSM state name (ZIG-440). */
     stateId?: string;
+    /** Replay-stable write keys for this wake — write-capable tools derive their idempotency key from here, never from the LLM. */
+    wakeKeys?: WakeWriteKeys;
 } | {
     kind: 'send-message';
     sessionId: string;
@@ -398,6 +437,7 @@ export type Effect = {
     kind: 'record-event';
     sessionId: string;
     entry: RecordedEntry;
+    idempotencyKey?: string;
 };
 /**
  * Typed result map. With this shape, `await eff({ kind: 'read-context', ... })`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.204",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.1.30",
+    "@ziggs-ai/api-client": "^0.2.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",

package/dist/server/InboxCatchUp.d.ts

@@ -1,24 +0,0 @@
-import { type Creds } from '@ziggs-ai/api-client';
-import { SeenMessages } from './SeenMessages.js';
-export interface InboxCatchUpDeps {
-    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 InboxCatchUpResult {
-    scopes: number;
-    messagesDelivered: number;
-    resourceEvents: number;
-    acked: number;
-    truncated: boolean;
-}
-/**
- * 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.
- */
-export declare function runInboxCatchUp(deps: InboxCatchUpDeps): Promise<InboxCatchUpResult>;