@ziggs-ai/agent-sdk 0.1.12 → 0.2.1

package/dist/runtime/validateWorkflow.d.ts

@@ -0,0 +1,17 @@
+import type { Ctx, Workflow } from '../types.js';
+/** Static probe ctx for evaluating transition `when` guards during validation. */
+export declare const PROBE_CTX: Ctx;
+export declare class WorkflowValidationError extends Error {
+    readonly issues: string[];
+    constructor(issues: string[]);
+}
+export interface ValidationResult {
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Synchronous structural validation. Errors throw; warnings are returned for
+ * the caller to log. defineAgent runs this on construction, so misconfigured
+ * workflows fail loudly at load instead of mysteriously misbehaving at runtime.
+ */
+export declare function validateWorkflow(workflow: Workflow): ValidationResult;

package/dist/runtime/validateWorkflow.js

@@ -0,0 +1,209 @@
+import { bootstrapCtx } from './bootstrapCtx.js';
+/** Static probe ctx for evaluating transition `when` guards during validation. */
+export const PROBE_CTX = bootstrapCtx({ agentId: '', sessionId: '', laneKey: '' });
+// 'state-timeout' is intentionally absent: it is a runtime-generated liveness
+// outcome, never something an action's `produces` may declare.
+const KNOWN_OUTCOME_KINDS = new Set([
+    'enter',
+    'wait',
+    'message-sent',
+    'message-received',
+    'task-assigned',
+    'task-delegated',
+    'task-closed',
+    'subtask-finished',
+    'proposal-made',
+    'proposal-resolved',
+    'tool-result',
+    'error',
+    'extension',
+]);
+export class WorkflowValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Workflow validation failed:\n  - ${issues.join('\n  - ')}`);
+        this.name = 'WorkflowValidationError';
+        this.issues = issues;
+    }
+}
+/**
+ * Synchronous structural validation. Errors throw; warnings are returned for
+ * the caller to log. defineAgent runs this on construction, so misconfigured
+ * workflows fail loudly at load instead of mysteriously misbehaving at runtime.
+ */
+export function validateWorkflow(workflow) {
+    const errors = [];
+    const warnings = [];
+    if (!workflow || typeof workflow !== 'object') {
+        throw new WorkflowValidationError(['workflow must be an object']);
+    }
+    if (!workflow.id)
+        errors.push('workflow.id is required');
+    if (!workflow.initial)
+        errors.push('workflow.initial is required');
+    if (!workflow.states || typeof workflow.states !== 'object') {
+        errors.push('workflow.states is required');
+    }
+    if (errors.length)
+        throw new WorkflowValidationError(errors);
+    const stateNames = new Set(Object.keys(workflow.states));
+    if (!stateNames.has(workflow.initial)) {
+        errors.push(`workflow.initial "${workflow.initial}" is not a defined state`);
+    }
+    for (const [name, state] of Object.entries(workflow.states)) {
+        if (!state || typeof state !== 'object') {
+            errors.push(`state "${name}" is not an object`);
+            continue;
+        }
+        if (state.kind !== 'parked' && state.kind !== 'thinking' && state.kind !== 'mechanical') {
+            errors.push(`state "${name}" must declare kind: 'parked' | 'thinking' | 'mechanical'`);
+            continue;
+        }
+        // Shape rejects mixing
+        if (state.kind === 'parked') {
+            if (state.prompt) {
+                errors.push(`state "${name}" is parked but has a prompt — parked states are event-driven only`);
+            }
+            if (state.actions) {
+                errors.push(`state "${name}" is parked but has actions — parked states are event-driven only`);
+            }
+            const tm = state.timeoutMs;
+            if (tm !== undefined && (typeof tm !== 'number' || !Number.isFinite(tm) || tm <= 0)) {
+                errors.push(`state "${name}" timeoutMs must be a finite number > 0 (got ${String(tm)})`);
+            }
+            if (typeof tm === 'number' && Number.isFinite(tm) && tm > 0) {
+                const handled = state.transitions.some(t => {
+                    if (!t.when)
+                        return true;
+                    try {
+                        return t.when({ kind: 'state-timeout', state: name, waitedMs: tm }, PROBE_CTX);
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                if (!handled) {
+                    warnings.push(`parked state "${name}" declares timeoutMs=${tm} but no transition matches { kind: 'state-timeout' } — the timeout will park loudly (runtimeLog.error) instead of routing to a recovery state.`);
+                }
+            }
+        }
+        if (state.kind === 'thinking') {
+            if (!state.prompt)
+                errors.push(`thinking state "${name}" requires a prompt`);
+            if (!state.actions || Object.keys(state.actions).length === 0) {
+                errors.push(`thinking state "${name}" requires at least one action`);
+            }
+            if (state.timeoutMs !== undefined) {
+                errors.push(`state "${name}" is thinking but declares timeoutMs — liveness timers apply to parked states only (thinking turns are bounded by AgentHost tickTimeoutMs)`);
+            }
+        }
+        if (state.kind === 'mechanical') {
+            const mech = state;
+            if (!mech.tool || typeof mech.tool !== 'string') {
+                errors.push(`mechanical state "${name}" requires a tool name`);
+            }
+            if (mech.buildArgs !== undefined && typeof mech.buildArgs !== 'function') {
+                errors.push(`mechanical state "${name}" buildArgs must be a function`);
+            }
+            if (mech.prompt) {
+                errors.push(`state "${name}" is mechanical but has a prompt — use kind: 'thinking' instead`);
+            }
+            if (mech.actions) {
+                errors.push(`state "${name}" is mechanical but has actions — use kind: 'thinking' instead`);
+            }
+            const p = mech.produces;
+            if (p === 'state-timeout') {
+                errors.push(`mechanical state "${name}" produces "state-timeout" — reserved for runtime liveness timers`);
+            }
+            else if (typeof p === 'string') {
+                if (!KNOWN_OUTCOME_KINDS.has(p)) {
+                    errors.push(`mechanical state "${name}" produces unknown outcome kind "${p}" — use one of: ${[...KNOWN_OUTCOME_KINDS].join(', ')}`);
+                }
+            }
+            else if (typeof p !== 'function') {
+                errors.push(`mechanical state "${name}" requires produces (OutcomeKind or fn)`);
+            }
+        }
+        if (!Array.isArray(state.transitions)) {
+            errors.push(`state "${name}" requires a transitions array`);
+            continue;
+        }
+        for (let i = 0; i < state.transitions.length; i++) {
+            const t = state.transitions[i];
+            if (!t || typeof t !== 'object') {
+                errors.push(`state "${name}" transition[${i}] is not an object`);
+                continue;
+            }
+            if (typeof t.to !== 'string') {
+                errors.push(`state "${name}" transition[${i}] is missing string "to"`);
+                continue;
+            }
+            if (!stateNames.has(t.to)) {
+                errors.push(`state "${name}" transition[${i}] points to unknown state "${t.to}"`);
+            }
+            if (t.when !== undefined && typeof t.when !== 'function') {
+                errors.push(`state "${name}" transition[${i}].when must be a function or omitted`);
+            }
+        }
+        if (state.kind === 'thinking') {
+            for (const [actionName, action] of Object.entries(state.actions)) {
+                if (!action || typeof action !== 'object') {
+                    errors.push(`state "${name}" action "${actionName}" is not an object`);
+                    continue;
+                }
+                if (!action.prompt || !action.prompt.instruction) {
+                    errors.push(`state "${name}" action "${actionName}" requires prompt.instruction`);
+                }
+                const p = action.produces;
+                if (p === 'state-timeout') {
+                    errors.push(`state "${name}" action "${actionName}" produces "state-timeout" — reserved for runtime liveness timers; actions cannot produce it`);
+                }
+                else if (typeof p === 'string') {
+                    if (!KNOWN_OUTCOME_KINDS.has(p)) {
+                        errors.push(`state "${name}" action "${actionName}" produces unknown outcome kind "${p}" — use one of: ${[...KNOWN_OUTCOME_KINDS].join(', ')}`);
+                    }
+                }
+                else if (typeof p !== 'function') {
+                    errors.push(`state "${name}" action "${actionName}" requires produces (OutcomeKind or fn)`);
+                }
+            }
+            // Soft check: thinking state should have a wait action and a fallthrough.
+            // Authors can opt out via allowNoWait when intentionally building a
+            // looping or always-progressing state.
+            if (!state.allowNoWait) {
+                if (!state.actions?.wait) {
+                    warnings.push(`thinking state "${name}" has no "wait" action — did you forget to spread thinkingDefaults({ initial: '${workflow.initial}' })? Set allowNoWait: true to silence.`);
+                }
+                const hasWaitFallthrough = state.transitions.some(t => {
+                    if (!t.when)
+                        return true;
+                    try {
+                        return t.when({ kind: 'wait' }, PROBE_CTX);
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                if (!hasWaitFallthrough) {
+                    warnings.push(`thinking state "${name}" has no fallthrough for { kind: 'wait' } — agent may stall when LLM picks wait. Spread thinkingDefaults().transitions or add explicitly.`);
+                }
+                const hasErrorFallthrough = state.transitions.some(t => {
+                    if (!t.when)
+                        return true;
+                    try {
+                        return t.when({ kind: 'error', source: 'unknown', cause: 'probe', retryable: false }, PROBE_CTX);
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                if (!hasErrorFallthrough) {
+                    warnings.push(`thinking state "${name}" has no fallthrough for { kind: 'error' } — empty/failed turns may silently recurse until the depth guard. Add an error transition or spread thinkingDefaults().transitions.`);
+                }
+            }
+        }
+    }
+    if (errors.length)
+        throw new WorkflowValidationError(errors);
+    return { errors, warnings };
+}

package/dist/server/ConnectionPool.d.ts

@@ -0,0 +1,68 @@
+import { AgentHost, type AgentHostOptions } from '../AgentHost.js';
+interface ConnectionManagerMeta {
+    domain?: string;
+    expertise?: string[];
+    tags?: string[];
+    [key: string]: unknown;
+}
+interface QueryFilter {
+    domain?: string;
+    expertise?: string[];
+    tags?: string[];
+}
+export interface PoolOptions {
+    maxActive?: number;
+    idleTimeoutMs?: number;
+}
+export interface SendToOptions {
+    timeoutMs?: number;
+}
+export interface ControlOptions {
+    wsUrl?: string;
+    operatorKey?: string;
+}
+export declare class ConnectionPool {
+    private readonly manager;
+    private readonly configs;
+    private readonly responseListeners;
+    constructor({ maxActive, idleTimeoutMs }?: PoolOptions);
+    /**
+     * Register N agent configs. Each will be lazily woken (a fresh
+     * `AgentHost` constructed + connected) the first time it's referenced.
+     */
+    register(configs: AgentHostOptions[], metaArr?: ConnectionManagerMeta[]): void;
+    wake(agentId: string): Promise<AgentHost>;
+    sleep(agentId: string): Promise<void>;
+    disconnectAll(): Promise<void>;
+    /**
+     * Wake the named agent, deliver a message, and wait for its first outbound
+     * `send-message` effect — i.e. the agent's reply. Returns the reply text.
+     *
+     * The effectTap injected in `register` drains a per-agent listener queue;
+     * this method enqueues one resolver and awaits it. Times out if the agent
+     * does not reply within `timeoutMs` (default 60 s for LLM agents).
+     */
+    requestFrom(agentId: string, text: string, metadata?: Record<string, unknown>, { timeoutMs }?: SendToOptions): Promise<string>;
+    /**
+     * Wake the named agent and deliver one wire frame to it. Returns once the
+     * host has finished processing.
+     *
+     * Note: does not return the agent's response. For request/response
+     * semantics use `requestFrom`.
+     */
+    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.
+     */
+    startControl({ wsUrl, operatorKey }?: ControlOptions): void;
+    stopControl(): void;
+    query(filter: QueryFilter): string[];
+    list(): string[];
+    listActive(): string[];
+    get size(): number;
+    get maxActive(): number;
+    getMeta(id: string): ConnectionManagerMeta | undefined;
+}
+export {};

package/dist/server/ConnectionPool.js

@@ -0,0 +1,166 @@
+/**
+ * ConnectionPool — multi-agent fleet manager.
+ *
+ * Holds N `AgentHostOptions` configs but only constructs/wakes an
+ * `AgentHost` (one WS connection) when needed. Idle hosts are slept after
+ * `idleTimeoutMs`. At most `maxActive` hosts are connected at a time; LRU
+ * eviction drops the oldest if the cap is reached. With `startControl`, a
+ * separate "launcher" socket receives backend-driven wake hints so the pool
+ * spins up the right host on demand.
+ *
+ * This is how a single Node process serves a fleet of agents without
+ * holding 1000 open sockets — typical config: 1000+ registered, ~50 live.
+ */
+import { ConnectionManager } from '@ziggs-ai/api-client';
+import { AgentHost } from '../AgentHost.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+export class ConnectionPool {
+    manager;
+    configs = new Map();
+    // Listeners enqueued by requestFrom — drained on outbound send-message effects.
+    responseListeners = new Map();
+    constructor({ maxActive = 50, idleTimeoutMs = 60_000 } = {}) {
+        this.manager = new ConnectionManager({ maxActive, idleTimeoutMs });
+    }
+    /**
+     * Register N agent configs. Each will be lazily woken (a fresh
+     * `AgentHost` constructed + connected) the first time it's referenced.
+     */
+    register(configs, metaArr = []) {
+        const metaByAgentId = new Map();
+        for (const m of metaArr) {
+            const id = m['agentId'];
+            if (id)
+                metaByAgentId.set(id, m);
+        }
+        for (const config of configs) {
+            const agentId = config.agentId ?? config.workflow?.id;
+            if (!agentId) {
+                runtimeLog.warn('ConnectionPool', 'skipping config with no resolvable agentId');
+                continue;
+            }
+            this.configs.set(agentId, config);
+            this.manager.register(agentId, async () => {
+                const cfg = this.configs.get(agentId);
+                const originalTap = cfg.effectTap;
+                const pool = this;
+                const host = new AgentHost({
+                    ...cfg,
+                    effectTap(effect, response) {
+                        if (effect.kind === 'send-message') {
+                            const listeners = pool.responseListeners.get(agentId);
+                            if (listeners?.length)
+                                listeners.shift()(effect.text ?? '');
+                        }
+                        originalTap?.(effect, response);
+                    },
+                });
+                await host.connectAsync();
+                runtimeLog.debug('ConnectionPool', `woke "${agentId}" (active: ${this.manager.listActive().length}/${this.maxActive})`);
+                return host;
+            }, async (host) => {
+                host.disconnect();
+                runtimeLog.debug('ConnectionPool', `slept "${agentId}"`);
+            }, metaByAgentId.get(agentId));
+        }
+    }
+    async wake(agentId) {
+        return await this.manager.wake(agentId);
+    }
+    async sleep(agentId) {
+        return this.manager.sleep(agentId);
+    }
+    async disconnectAll() {
+        return this.manager.sleepAll();
+    }
+    /**
+     * Wake the named agent, deliver a message, and wait for its first outbound
+     * `send-message` effect — i.e. the agent's reply. Returns the reply text.
+     *
+     * The effectTap injected in `register` drains a per-agent listener queue;
+     * this method enqueues one resolver and awaits it. Times out if the agent
+     * does not reply within `timeoutMs` (default 60 s for LLM agents).
+     */
+    async requestFrom(agentId, text, metadata = {}, { timeoutMs = 60_000 } = {}) {
+        const host = await this.wake(agentId);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                const ls = this.responseListeners.get(agentId);
+                if (ls) {
+                    const i = ls.indexOf(listener);
+                    if (i !== -1)
+                        ls.splice(i, 1);
+                }
+                reject(new Error(`requestFrom timeout for "${agentId}" after ${timeoutMs}ms`));
+            }, timeoutMs);
+            const listener = (responseText) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(responseText);
+            };
+            const ls = this.responseListeners.get(agentId) ?? [];
+            ls.push(listener);
+            this.responseListeners.set(agentId, ls);
+            host.handleMessage(text, metadata).catch((err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                const ls2 = this.responseListeners.get(agentId);
+                if (ls2) {
+                    const i = ls2.indexOf(listener);
+                    if (i !== -1)
+                        ls2.splice(i, 1);
+                }
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Wake the named agent and deliver one wire frame to it. Returns once the
+     * host has finished processing.
+     *
+     * Note: does not return the agent's response. For request/response
+     * semantics use `requestFrom`.
+     */
+    async sendTo(agentId, text, metadata = {}, { timeoutMs = 30_000 } = {}) {
+        const host = await this.wake(agentId);
+        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`sendTo timeout for "${agentId}" after ${timeoutMs}ms`)), timeoutMs));
+        await Promise.race([host.handleMessage(text, metadata), timeoutPromise]);
+        this.manager.touch(agentId);
+        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.
+     */
+    startControl({ wsUrl, operatorKey } = {}) {
+        if (!wsUrl || !operatorKey) {
+            runtimeLog.warn('ConnectionPool', 'startControl: wsUrl and operatorKey are 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();
+    }
+    stopControl() {
+        const m = this.manager;
+        m['_controlHandle']?.close?.();
+        m['_controlHandle'] = null;
+    }
+    query(filter) { return this.manager.query(filter); }
+    list() { return this.manager.list(); }
+    listActive() { return this.manager.listActive(); }
+    get size() { return this.manager.size; }
+    get maxActive() { return this.manager.maxActive; }
+    getMeta(id) { return this.manager.getMeta(id); }
+}

package/dist/server/EventQueue.d.ts

@@ -0,0 +1,33 @@
+export type ProcessEventFn = (event: unknown, laneKey: string) => Promise<void>;
+export interface EventQueueOptions {
+    maxQueueLengthPerLane?: number;
+}
+/**
+ * Serializes events per lane and coalesces multiple queued events into one
+ * batch dispatch. The runtime sees at most one in-flight processEvent call
+ * per laneKey at a time; multiple events arriving while busy are merged
+ * into a single { type: 'batch', events: [...] } frame on the next pass.
+ */
+export declare class EventQueue {
+    private _processEvent;
+    private _maxQueueLengthPerLane;
+    private _state;
+    private _metrics;
+    constructor(processEventFn: ProcessEventFn, options?: EventQueueOptions);
+    enqueue(event: unknown, laneKey: string): Promise<void>;
+    private _processIfNeeded;
+    private _processLoop;
+    private _trimQueueIfNeeded;
+    get isIdle(): boolean;
+    /** Resolves when all lanes finish processing, or after timeoutMs. Best-effort — never throws. */
+    waitForIdle(timeoutMs?: number): Promise<void>;
+    getMetrics(): {
+        lanes: number;
+        queuedEvents: number;
+        enqueued: number;
+        dropped: number;
+        processedBatches: number;
+        processedEvents: number;
+        errors: number;
+    };
+}

package/dist/server/EventQueue.js

@@ -0,0 +1,98 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+/**
+ * Serializes events per lane and coalesces multiple queued events into one
+ * batch dispatch. The runtime sees at most one in-flight processEvent call
+ * per laneKey at a time; multiple events arriving while busy are merged
+ * into a single { type: 'batch', events: [...] } frame on the next pass.
+ */
+export class EventQueue {
+    _processEvent;
+    _maxQueueLengthPerLane;
+    _state = new Map();
+    _metrics = {
+        enqueued: 0, dropped: 0, processedBatches: 0, processedEvents: 0, errors: 0,
+    };
+    constructor(processEventFn, options = {}) {
+        this._processEvent = processEventFn;
+        this._maxQueueLengthPerLane = Number.isFinite(options.maxQueueLengthPerLane)
+            ? Math.max(1, options.maxQueueLengthPerLane)
+            : 100;
+    }
+    enqueue(event, laneKey) {
+        if (!laneKey) {
+            runtimeLog.warn('EventQueue', 'enqueue called without laneKey, skipping');
+            return Promise.resolve();
+        }
+        let state = this._state.get(laneKey);
+        if (!state) {
+            state = { events: [], processing: false };
+            this._state.set(laneKey, state);
+        }
+        return new Promise((resolve) => {
+            this._metrics.enqueued += 1;
+            state.events.push({ event, resolve });
+            this._trimQueueIfNeeded(state, laneKey);
+            this._processIfNeeded(laneKey);
+        });
+    }
+    _processIfNeeded(laneKey) {
+        const state = this._state.get(laneKey);
+        if (!state || state.processing || state.events.length === 0)
+            return;
+        state.processing = true;
+        this._processLoop(laneKey);
+    }
+    async _processLoop(laneKey) {
+        const state = this._state.get(laneKey);
+        if (!state)
+            return;
+        while (state.events.length > 0) {
+            const batch = state.events.splice(0, state.events.length);
+            const events = batch.map(e => e.event);
+            const resolvers = batch.map(e => e.resolve);
+            const coalesced = events.length === 1
+                ? events[0]
+                : { type: 'batch', events };
+            try {
+                await this._processEvent(coalesced, laneKey);
+            }
+            catch (error) {
+                this._metrics.errors += 1;
+                runtimeLog.error('EventQueue', `processEvent error for laneKey=${laneKey}: ${error?.message || error}`);
+            }
+            this._metrics.processedBatches += 1;
+            this._metrics.processedEvents += events.length;
+            for (const r of resolvers)
+                r();
+        }
+        state.processing = false;
+    }
+    _trimQueueIfNeeded(state, laneKey) {
+        while (state.events.length > this._maxQueueLengthPerLane) {
+            const dropped = state.events.shift();
+            this._metrics.dropped += 1;
+            dropped?.resolve();
+            runtimeLog.warn('EventQueue', `dropped oldest event laneKey=${laneKey} max=${this._maxQueueLengthPerLane}`);
+        }
+    }
+    get isIdle() {
+        return [...this._state.values()].every(s => !s.processing && s.events.length === 0);
+    }
+    /** Resolves when all lanes finish processing, or after timeoutMs. Best-effort — never throws. */
+    async waitForIdle(timeoutMs = 30_000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (this.isIdle)
+                return;
+            await new Promise(r => setTimeout(r, 50));
+        }
+        runtimeLog.warn('EventQueue', `waitForIdle timed out after ${timeoutMs}ms`);
+    }
+    getMetrics() {
+        return {
+            ...this._metrics,
+            lanes: this._state.size,
+            queuedEvents: [...this._state.values()].reduce((sum, lane) => sum + lane.events.length, 0),
+        };
+    }
+}

package/dist/server/InboxCatchUp.d.ts

@@ -0,0 +1,24 @@
+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>;