@essentialai/cogent-bridge/dist/services/peer-presence.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.

/** The four states an agent can be in with respect to its channel. */
export type PresenceState = "local" | "deferred" | "offline" | "online";
/** What a presence evaluation concluded, and what it did about it. */
export type PresenceOutcome = {
    state: "local" | "deferred" | "online";
    restored: false;
    detail: string;
} | {
    state: "online";
    restored: true;
    peerId: string;
    detail: string;
} | {
    state: "offline";
    restored: false;
    detail: string;
};
export interface PresenceDeps {
    /** True only when the ACTIVE backend really is the cloud one — not a configuration flag. */
    isCloudConfigured: () => boolean;
    /** True when something already registered in THIS process; its state is authoritative. */
    alreadyRegisteredInProcess: () => boolean;
    /**
     * Is a LIVE bridge already announcing this peer for this working directory?
     *
     * 🔴 THE SHARED-CHECKOUT CASE. There is ONE credential file per cwd, so every bridge in a
     * checkout reads the SAME peerId. Two agents legitimately share a checkout under DIFFERENT
     * peer identities (marvin-coder + marvin-mobile — which is why the ownership registry is keyed
     * on (cwd, peerId) and not cwd alone). Without this check, a second bridge restores the first
     * agent's peerId, supersession stands one of them down, and an agent silently loses its own
     * identity. Proven by controlled A/B: with the restore unguarded, wake-dedup-matrix-test
     * --topology two-peer could no longer detect its own break (STAYED_GREEN, 0 overlapping
     * resumes); with presence off it went RED with 1. The gate was telling the truth.
     */
    peerAlreadyServed: (peerId: string) => boolean;
    loadCredentials: () => Promise<{
        endpoint?: string;
        sessionId?: string;
        token?: string;
        peerId?: string;
        /** AUD-003 ownership proof, issued once when this peer was created. */
        peerSecret?: string;
    } | null>;
    /** Go cloud-live and register, restoring the channel entry. Throws on failure. */
    goOnline: (peer: {
        peerId: string;
        endpoint: string;
        sessionId: string;
        token: string;
        cwd: string;
        label: string;
        /** Replayed on register so a peer owned by an EARLIER token can be reclaimed. */
        peerSecret?: string;
    }) => Promise<void>;
    cwd: () => string;
    env?: NodeJS.ProcessEnv;
}
/**
 * Automatic presence restore. ON by default — a default-off self-heal heals nobody.
 * Opt out with COGENT_AUTO_PRESENCE=false to observe the state without acting on it.
 */
export declare function autoPresenceEnabled(env?: NodeJS.ProcessEnv): boolean;
/**
 * Determine this agent's presence and, when it is `offline` with a peer it owns,
 * bring it back `online`.
 *
 * NEVER THROWS. Runs fire-and-forget after the MCP transport connects — the
 * `initialize` handshake must never wait on I/O (scripts/startup-nonblocking-test.mjs).
 */
export declare function restorePresence(deps: PresenceDeps): Promise<PresenceOutcome>;
/** Record the evaluated presence. Called by startup after each evaluation. */
export declare function setPresence(outcome: PresenceOutcome): void;
/** The agent's own view of its channel presence. Null until first evaluated. */
export declare function getPresence(): PresenceOutcome | null;
/** Report the outcome once, at a level that matches how much it matters. */
export declare function logPresence(outcome: PresenceOutcome): void;
//# sourceMappingURL=peer-presence.d.ts.map