@essentialai/cogent-bridge/dist/backend/storage-backend.d.ts

Cogent Bridge — cross-agent comms for Claude Code, OpenAI Codex and Slack. Codex users: install with `curl -fsSL https://cogent.tools/install.sh | sh`, then start with `cogent-codex` for real-time peer wake.

import { PeerInfo, MessageRecord, CliExecResult } from "../types.js";
import { HealthCheckResult } from "../services/health-check.js";
/**
 * Result of deregistering a peer. `removed` = the peer existed and was removed.
 * `mailboxDeprovisioned` = the relay confirmed (via the DELETE response header) that this
 * peer's Team mailbox was reaped (Cogent Mail F3), so the bridge should clear its now-dead
 * local mail creds. Always false on the local/free path (no mailboxes there).
 */
export interface DeregisterResult {
    removed: boolean;
    mailboxDeprovisioned: boolean;
}
/**
 * Abstract storage backend interface.
 *
 * Mirrors the exact signatures of the free functions in peer-registry.ts,
 * cc-cli.ts, and health-check.ts. Implementations can delegate to local
 * file-based state (FileBackend) or to a remote HTTP server (future).
 */
export interface StorageBackend {
    registerPeer(peerId: string, sessionId: string, cwd: string, label: string, 
    /** cogent-bridge client version sent by the registering process (3.1.6+). */
    clientVersion?: string, 
    /** Observer peers receive frames but never auto-respond, added in 3.2 (Phase 17 OBS-01). */
    mode?: "observer" | "agent", 
    /** Cloud/relay session id, kept distinct from the local sessionId (3.5.9, local-only). */
    channelSessionId?: string, 
    /** Advertised capabilities, e.g. ["auto-resume"] (3.5.9, local-only rail). */
    capabilities?: string[], 
    /** Durable workspace id — on the wire in cloud mode (Slice 5 / Story 8.6). */
    workspaceId?: string, 
    /** Durable thread/conversation id — on the wire in cloud mode (Slice 5 / Story 8.6). */
    threadId?: string, 
    /**
     * AUD-003 ownership proof, replayed from local credentials when this agent's token changed
     * since the peer was created (a re-join). Cloud-only, and only sent when the relay advertises
     * `peer-ownership` — the register schema is .strict().
     */
    peerSecret?: string): Promise<PeerInfo>;
    /**
     * @param peerSecret AUD-003 ownership proof. Needed when this agent re-joined and holds a
     *   token DIFFERENT from the one that registered the peer — without it the relay now refuses
     *   the delete, because evict-then-register is how a channel member could take over another
     *   agent's identity. Local mode ignores it (no tokens there).
     */
    deregisterPeer(peerId: string, peerSecret?: string): Promise<DeregisterResult>;
    getPeer(peerId: string): Promise<PeerInfo | undefined>;
    listPeers(): Promise<PeerInfo[]>;
    updateLastSeen(peerId: string): Promise<void>;
    recordMessage(record: Omit<MessageRecord, "id" | "timestamp">): Promise<MessageRecord>;
    /**
     * Retrieve message history.
     *
     * @param includeRelayEchoes When true, includes auto-relay echo records
     * (FE->BE response mirrors). Defaults to false in implementations -- the
     * common case is a "clean" history with one record per directed exchange.
     * Added in 3.1.11 (260511-o3p).
     * @param metadataOnly When true, records are returned with body fields
     * (message, response) omitted — only id, fromPeerId, toPeerId, timestamp,
     * durationMs, isRelayEcho, success kept. Added in 3.2 (HIST-02).
     * @param dedupInferredEchoes When true, suppress untagged auto-relay echoes
     * via content-and-direction heuristic. Cloud-backend-only; FileBackend
     * ignores the flag. Added in 3.2.1 (FIX-INFERRED-ECHO).
     */
    getHistory(peerId?: string, limit?: number, includeRelayEchoes?: boolean, metadataOnly?: boolean, dedupInferredEchoes?: boolean): Promise<MessageRecord[]>;
    validateSession(sessionId: string, cwd: string): Promise<boolean>;
    execClaude(sessionId: string, message: string, cwd: string, timeoutMs?: number): Promise<CliExecResult>;
    /**
     * Update an existing message record's response field. Optional -- only
     * HttpBackend implements this. Pass `null` to mark a timed-out send so
     * the record's response is not mistaken for the recipient's actual reply
     * (v3.2.1, FIX-TIMEOUT-UX).
     *
     * `pending` (260527-mkz): when true, marks the record as a successful
     * async delivery whose reply will arrive later via the inject-only path.
     * Forwarded to the relay (servers that don't yet know the field ignore it).
     */
    updateMessageResponse?(messageId: string, response: string | null, durationMs: number, pending?: boolean): Promise<void>;
    checkHealth(): Promise<HealthCheckResult>;
    /**
     * Lazy lookup of the upstream relay's `version` field, memoized for 60s
     * by the implementing backend. Returns null in local mode or on fetch
     * failure. Optional — only HttpBackend implements this; FileBackend omits.
     * Added in 3.2 (VER-02). Consumers must use optional chaining.
     */
    getRelayVersion?(): Promise<string | null>;
}
//# sourceMappingURL=storage-backend.d.ts.map