@ziggs-ai/agent-sdk 0.2.2 → 0.4.0

package/dist/server/staleBacklogGate.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Launcher startup backlog policy (ZIG-910).
+ *
+ * "Work waits" has no statute of limitations on the backend — the inbox never
+ * expires anything. But when a fleet comes up after a dark period, replaying
+ * every weeks-old actionable slice means a mass of LLM turns on stale work at
+ * real token cost. The consumer chooses what to pick up: this gate keeps the
+ * operator-poll lazy start from resurrecting agents whose newest actionable
+ * item is older than a cutoff. Skips are never silent — one loud aggregated
+ * summary line announces what was left down and how to opt back in.
+ *
+ * Env:
+ *   FLEET_REPLAY_MAX_AGE  cutoff, e.g. "3d" | "12h" | "30m" | bare number =
+ *                         days (default "3d")
+ *   FLEET_REPLAY_STALE=1  replay everything (disable the gate)
+ *
+ * Scope is the launcher only. The backend inbox is untouched, explicit
+ * `pool.startAgent()` / preStart are untouched, and an agent with ANY fresh item
+ * starts normally (its own inbox loop then drains the stale backlog too).
+ */
+import type { InboxEnvelope, InboxOperatorAgentEntry } from '@ziggs-ai/api-client';
+export declare const DEFAULT_REPLAY_MAX_AGE_MS: number;
+export interface ReplayPolicy {
+    /** Skip slices whose newest actionable item is older than this. */
+    maxAgeMs: number;
+    /** FLEET_REPLAY_STALE=1 — replay everything, gate disabled. */
+    replayAll: boolean;
+}
+/**
+ * "3d" | "12h" | "30m" | "45s"; a bare number means days (the knob's natural
+ * granularity). Returns null on garbage so the caller can warn and fall back.
+ */
+export declare function parseReplayMaxAge(raw: string): number | null;
+export declare function resolveReplayPolicy(env?: NodeJS.ProcessEnv): ReplayPolicy;
+/**
+ * Newest actionable timestamp across an agent's slice: scope activity,
+ * proposals, and connection/MCP requests. Null when nothing carries a
+ * timestamp (e.g. a joined-but-idle chat) — age unprovable, treated as fresh.
+ */
+export declare function newestActionableAt(inbox: InboxEnvelope): number | null;
+export declare function formatAge(ms: number): string;
+export interface StaleBacklogGateOptions extends ReplayPolicy {
+    label?: string;
+    now?: () => number;
+    log?: (line: string) => void;
+}
+/**
+ * Build the `shouldLazyStart` gate for the operator poll. Skipped agents
+ * resurface in every envelope (reading never acks), so announcements are
+ * per-agent-once: each poll pass that skips agents not yet announced emits one
+ * aggregated warn line covering them.
+ */
+export declare function createStaleBacklogGate({ maxAgeMs, replayAll, label, now, log, }: StaleBacklogGateOptions): (entry: InboxOperatorAgentEntry) => boolean;

package/dist/server/staleBacklogGate.js

@@ -0,0 +1,120 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+export const DEFAULT_REPLAY_MAX_AGE_MS = 3 * 24 * 60 * 60 * 1000;
+/**
+ * "3d" | "12h" | "30m" | "45s"; a bare number means days (the knob's natural
+ * granularity). Returns null on garbage so the caller can warn and fall back.
+ */
+export function parseReplayMaxAge(raw) {
+    const m = /^\s*(\d+(?:\.\d+)?)\s*([dhms]?)\s*$/i.exec(raw);
+    if (!m)
+        return null;
+    const value = Number(m[1]);
+    if (!Number.isFinite(value) || value <= 0)
+        return null;
+    const unitMs = { d: 86_400_000, h: 3_600_000, m: 60_000, s: 1_000 }[(m[2] || 'd').toLowerCase()];
+    return value * unitMs;
+}
+export function resolveReplayPolicy(env = process.env) {
+    const replayAll = env.FLEET_REPLAY_STALE === '1' || env.FLEET_REPLAY_STALE === 'true';
+    const raw = env.FLEET_REPLAY_MAX_AGE?.trim();
+    let maxAgeMs = DEFAULT_REPLAY_MAX_AGE_MS;
+    if (raw) {
+        const parsed = parseReplayMaxAge(raw);
+        if (parsed == null) {
+            runtimeLog.warn('staleBacklogGate', `FLEET_REPLAY_MAX_AGE="${raw}" is not a duration (use e.g. "3d", "12h", "30m") — using default ${formatAge(DEFAULT_REPLAY_MAX_AGE_MS)}`);
+        }
+        else {
+            maxAgeMs = parsed;
+        }
+    }
+    return { maxAgeMs, replayAll };
+}
+/**
+ * Newest actionable timestamp across an agent's slice: scope activity,
+ * proposals, and connection/MCP requests. Null when nothing carries a
+ * timestamp (e.g. a joined-but-idle chat) — age unprovable, treated as fresh.
+ */
+export function newestActionableAt(inbox) {
+    let newest = null;
+    const consider = (iso) => {
+        if (!iso)
+            return;
+        const t = Date.parse(iso);
+        if (!Number.isNaN(t) && (newest == null || t > newest))
+            newest = t;
+    };
+    for (const scope of inbox.scopes ?? [])
+        consider(scope.latestAt);
+    for (const p of inbox.proposalsAwaitingMe ?? [])
+        consider(p.proposedAt);
+    for (const r of inbox.connectionRequestsAwaitingMe ?? [])
+        consider(r.requestedAt);
+    for (const r of inbox.mcpServerRequestsAwaitingMe ?? [])
+        consider(r.requestedAt);
+    return newest;
+}
+/** Unread items in a slice, for the summary line. Counts are backend-capped. */
+function countItems(inbox) {
+    let items = 0;
+    for (const scope of inbox.scopes ?? []) {
+        items += (scope.newMessages ?? 0) + (scope.newArtifacts ?? 0);
+    }
+    items += (inbox.proposalsAwaitingMe ?? []).length;
+    items += (inbox.connectionRequestsAwaitingMe ?? []).length;
+    items += (inbox.mcpServerRequestsAwaitingMe ?? []).length;
+    return items;
+}
+export function formatAge(ms) {
+    if (ms >= 86_400_000)
+        return `${trimNum(ms / 86_400_000)}d`;
+    if (ms >= 3_600_000)
+        return `${trimNum(ms / 3_600_000)}h`;
+    if (ms >= 60_000)
+        return `${trimNum(ms / 60_000)}m`;
+    return `${trimNum(ms / 1_000)}s`;
+}
+function trimNum(n) {
+    return Number(n.toFixed(1)).toString();
+}
+/**
+ * Build the `shouldLazyStart` gate for the operator poll. Skipped agents
+ * resurface in every envelope (reading never acks), so announcements are
+ * per-agent-once: each poll pass that skips agents not yet announced emits one
+ * aggregated warn line covering them.
+ */
+export function createStaleBacklogGate({ maxAgeMs, replayAll, label = 'launcher', now = Date.now, log, }) {
+    const emit = log ?? ((line) => runtimeLog.warn(label, line));
+    const announced = new Set();
+    let pendingAgents = [];
+    let pendingItems = 0;
+    let flushScheduled = false;
+    // One envelope's entries are gated synchronously; a microtask-deferred
+    // flush turns a whole boot flood into a single summary line.
+    const flush = () => {
+        flushScheduled = false;
+        if (pendingAgents.length === 0)
+            return;
+        const preview = pendingAgents.slice(0, 5).join(', ');
+        const more = pendingAgents.length > 5 ? `, +${pendingAgents.length - 5} more` : '';
+        emit(`startup backlog policy: skipped ${pendingItems} stale item(s) across ${pendingAgents.length} agent(s) older than ${formatAge(maxAgeMs)} (${preview}${more}) — set FLEET_REPLAY_STALE=1 to replay them`);
+        pendingAgents = [];
+        pendingItems = 0;
+    };
+    return (entry) => {
+        if (replayAll)
+            return true;
+        const newest = newestActionableAt(entry.inbox);
+        if (newest == null || now() - newest <= maxAgeMs)
+            return true;
+        if (!announced.has(entry.agentId)) {
+            announced.add(entry.agentId);
+            pendingAgents.push(entry.agentId);
+            pendingItems += countItems(entry.inbox);
+            if (!flushScheduled) {
+                flushScheduled = true;
+                queueMicrotask(flush);
+            }
+        }
+        return false;
+    };
+}

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/server/tools/tier2/contextTools.js

@@ -129,7 +129,7 @@ export const contextDiscoverGrantableTool = defineTool('context_discover_grantab
     const items = await new ContextDiscoveryClient(operatorKey, agentId).discoverGrantable();
     return { count: items.length, items };
 }, {
-    description: 'See what context EXISTS in your orgs that you CANNOT read yet — the inverse of list_grants. Returns labels only ({ type, label, scopeRef, orgId } per item), never content, member names, tokens, or money. Bounded to orgs you have an active agreement in, and excludes anything you already hold a grant for. Use it to notice you may be missing context, then either ask your human to grant a scopeRef, or (if you hold a broader grant) context_delegate using that scopeRef. Pair with list_grants (what you hold) and context_expand_reach (what a held grant covers).',
+    description: 'See what context EXISTS in your orgs that you CANNOT read yet — the inverse of list_grants. Covers chats, agreements, and connections (type is one of "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only ({ type, label, scopeRef, orgId } per item), never content, member names, tokens, or money. Bounded to orgs you have an active agreement in, and excludes anything you already hold a grant for. Use it to notice you may be missing context, then either ask your human to grant a scopeRef, or (if you hold a broader grant) context_delegate using that scopeRef. Pair with list_grants (what you hold) and context_expand_reach (what a held grant covers).',
 });
 export const CONTEXT_TOOLS = [
     contextReadTool,

package/dist/shared/operatorKeyClaims.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Client-side peek at an operator key's JWT payload (signature NOT verified —
+ * identity hint only, the backend remains the authority). Used by the fleet
+ * launcher to warn when the key is agent-bound (ZIG-911): a bound key
+ * collapses the operator multiplex to its one agent and 403s every other
+ * per-agent loop, so a large fleet quietly watches a single agent.
+ */
+export interface OperatorKeyClaims {
+    type?: string;
+    keyId?: string;
+    ownerId?: string;
+    boundAgentId?: string | null;
+    exp?: number;
+}
+export declare function decodeOperatorKeyClaims(token: string): OperatorKeyClaims | null;
+/**
+ * The ZIG-911 startup check: warn (never refuse — a one-agent launcher on a
+ * bound key is legitimate) when the fleet's control key is bound to a single
+ * agent while more than one agent is registered. Returns the warning line, or
+ * null when the setup is coherent.
+ */
+export declare function boundKeyFleetWarning(operatorKey: string, registeredAgents: number): string | null;

package/dist/shared/operatorKeyClaims.js

@@ -0,0 +1,35 @@
+export function decodeOperatorKeyClaims(token) {
+    const parts = token.trim().split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const json = Buffer.from(parts[1], 'base64url').toString('utf8');
+        const payload = JSON.parse(json);
+        return {
+            type: payload.type,
+            keyId: payload.keyId,
+            ownerId: payload.ownerId,
+            boundAgentId: payload.boundAgentId ?? null,
+            exp: payload.exp,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The ZIG-911 startup check: warn (never refuse — a one-agent launcher on a
+ * bound key is legitimate) when the fleet's control key is bound to a single
+ * agent while more than one agent is registered. Returns the warning line, or
+ * null when the setup is coherent.
+ */
+export function boundKeyFleetWarning(operatorKey, registeredAgents) {
+    if (registeredAgents <= 1)
+        return null;
+    const bound = decodeOperatorKeyClaims(operatorKey)?.boundAgentId;
+    if (!bound)
+        return null;
+    return (`fleet key is bound to agent "${bound}": the operator multiplex covers 1 of ${registeredAgents} registered agents, ` +
+        `and per-agent inbox loops for the rest will 403 ("cannot impersonate"). ` +
+        `Use an unbound owner key with agents:impersonate to run a fleet.`);
+}

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.4.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.3.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>;