@relaymessenger/cli 0.3.0

package/dist/receive.js

@@ -0,0 +1,353 @@
+/**
+ * Receive loop: long-poll GET /v1/events → durable queue → engine turn →
+ * one finalized POST /v1/messages per turn.
+ *
+ * Reliability contract:
+ *  - Durable-before-ack: inbound events are appended to state.json's
+ *    pending_events queue in the SAME atomic write that advances the cursor,
+ *    so an acked event is always durable and a crash replays, never drops.
+ *  - Dedupe: delivery is at-least-once; event_id is checked against a
+ *    persisted seen-set before enqueueing.
+ *  - Debounce: rapid messages in one conversation coalesce for ~800 ms into a
+ *    single engine turn.
+ *  - Supervisor: poll/turn failures restart with exponential backoff + jitter.
+ */
+import { createHash } from "node:crypto";
+export function turnIdempotencyKey(conversationId, eventIds) {
+    const digest = createHash("sha256")
+        .update(JSON.stringify([conversationId, eventIds]))
+        .digest("hex");
+    return `relay-turn-${digest.slice(0, 40)}`;
+}
+export function promptTextFromMessages(messages) {
+    const chunks = [];
+    for (const message of messages) {
+        const text = message.parts
+            .filter((part) => part.type === "text" && typeof part.text === "string")
+            .map((part) => part.text)
+            .join("\n")
+            .trim();
+        chunks.push(text.length > 0 ? text : message.fallback_text);
+    }
+    return chunks.filter((chunk) => chunk && chunk.length > 0).join("\n\n");
+}
+export class ReceiveLoop {
+    client;
+    state;
+    engine;
+    broker;
+    ownerUserId;
+    debounceMs;
+    cwd;
+    log;
+    setTimeoutImpl;
+    debounceTimers = new Map();
+    /** Serializes turns per conversation. */
+    turnChains = new Map();
+    stopped = false;
+    constructor(client, state, engine, broker, options) {
+        this.client = client;
+        this.state = state;
+        this.engine = engine;
+        this.broker = broker;
+        this.ownerUserId = options.ownerUserId;
+        this.debounceMs = options.debounceMs ?? 800;
+        this.cwd = options.cwd ?? process.cwd();
+        this.log = options.log ?? (() => { });
+        this.setTimeoutImpl = options.setTimeoutImpl ?? setTimeout;
+    }
+    /**
+     * One poll cycle: fetch, dedupe, durably enqueue + ack, schedule flushes.
+     * Exposed for tests; `run()` supervises it forever.
+     */
+    async pollOnce(timeoutS = 25) {
+        const page = await this.client.getEvents(this.state.current.cursor, timeoutS);
+        const touched = new Set();
+        let accepted = 0;
+        for (const event of page.events ?? []) {
+            if (!event.event_id || this.state.hasSeen(event.event_id))
+                continue;
+            this.state.markSeen(event.event_id);
+            const routed = this.routeEvent(event);
+            if (routed) {
+                touched.add(routed);
+                accepted += 1;
+            }
+        }
+        // Durable-before-ack: queue mutation and cursor advance are one atomic write.
+        if (typeof page.next_cursor === "number") {
+            this.state.current.cursor = page.next_cursor;
+        }
+        this.state.persist();
+        for (const conversationId of touched)
+            this.scheduleFlush(conversationId);
+        return accepted;
+    }
+    /** Returns the conversation id when the event was enqueued for the engine. */
+    routeEvent(event) {
+        if (event.event_type !== "message.received")
+            return undefined;
+        const message = event.data?.message;
+        if (!message || message.sender?.kind !== "user")
+            return undefined;
+        // Owner gate before any content is interpreted: non-owner senders can
+        // neither prompt the engine nor answer a permission card.
+        if (message.sender.id !== this.ownerUserId) {
+            this.log(`ignoring message from non-owner sender ${message.sender.id}`);
+            return undefined;
+        }
+        // First owner message pins the default notify/MCP conversation.
+        this.state.current.owner_conversation_id ??= message.conversation_id;
+        if (this.broker.consumeReply(message))
+            return undefined;
+        const queue = (this.state.current.pending_events[message.conversation_id] ??= []);
+        queue.push(event);
+        return message.conversation_id;
+    }
+    scheduleFlush(conversationId) {
+        if (this.stopped)
+            return;
+        const existing = this.debounceTimers.get(conversationId);
+        if (existing)
+            clearTimeout(existing);
+        const timer = this.setTimeoutImpl(() => {
+            this.debounceTimers.delete(conversationId);
+            this.chainTurn(conversationId);
+        }, this.debounceMs);
+        timer.unref?.();
+        this.debounceTimers.set(conversationId, timer);
+    }
+    chainTurn(conversationId) {
+        const previous = this.turnChains.get(conversationId) ?? Promise.resolve();
+        const next = previous
+            .then(() => this.runTurn(conversationId))
+            .catch((error) => {
+            this.log(`turn failed for ${conversationId}: ${error}`);
+        });
+        this.turnChains.set(conversationId, next);
+        void next.finally(() => {
+            if (this.turnChains.get(conversationId) === next)
+                this.turnChains.delete(conversationId);
+        });
+    }
+    /** Waits for in-flight turns (tests + graceful shutdown). */
+    async settle() {
+        await Promise.allSettled([...this.turnChains.values()]);
+    }
+    /** Removes THIS turn's consumed events (and its attempt marker) durably. */
+    clearBatch(conversationId, events, turnKey) {
+        const queue = this.state.current.pending_events[conversationId] ?? [];
+        const remaining = queue.filter((event) => !events.some((consumed) => consumed.event_id === event.event_id));
+        if (remaining.length === 0) {
+            delete this.state.current.pending_events[conversationId];
+        }
+        else {
+            this.state.current.pending_events[conversationId] = remaining;
+            // New messages arrived mid-turn; run again.
+            this.scheduleFlush(conversationId);
+        }
+        const attempted = (this.state.current.attempted_turns ??= {})[conversationId];
+        if (attempted && (!turnKey || attempted.turn_key === turnKey)) {
+            delete this.state.current.attempted_turns[conversationId];
+        }
+        if (turnKey)
+            delete (this.state.current.pending_replies ??= {})[turnKey];
+        this.state.persist();
+    }
+    async postNotice(conversationId, text, key) {
+        try {
+            await this.client.postMessage({ conversation_id: conversationId, parts: [{ type: "text", text }] }, key);
+        }
+        catch (error) {
+            this.log(`notice post failed for ${conversationId}: ${error}`);
+        }
+    }
+    pendingReplyForConversation(conversationId) {
+        return Object.entries(this.state.current.pending_replies ?? {}).find(([, reply]) => reply.conversation_id === conversationId);
+    }
+    /** Idempotently deliver an engine-completed reply without rerunning tools. */
+    async deliverPendingReply(turnKey, reply) {
+        let lastError;
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                await this.client.postMessage({ conversation_id: reply.conversation_id, parts: [{ type: "text", text: reply.text }] }, turnKey);
+                return true;
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < 2) {
+                    await new Promise((resolve) => this.setTimeoutImpl(resolve, 1_000 * (attempt + 1)));
+                }
+            }
+        }
+        this.log(`final reply post failed for ${reply.conversation_id}: ${lastError}`);
+        return false;
+    }
+    async runTurn(conversationId) {
+        // Delivery is its own durable phase. Finish an older reply before looking
+        // at newer queued prompts, otherwise appending a message after an unknown
+        // POST outcome could cause the older tool turn to execute again.
+        const queuedReply = this.pendingReplyForConversation(conversationId);
+        if (queuedReply) {
+            const [turnKey, reply] = queuedReply;
+            const queuedEvents = this.state.current.pending_events[conversationId] ?? [];
+            const consumed = queuedEvents.filter((event) => reply.event_ids.includes(event.event_id));
+            if (await this.deliverPendingReply(turnKey, reply)) {
+                this.clearBatch(conversationId, consumed, turnKey);
+            }
+            else {
+                this.scheduleFlush(conversationId);
+            }
+            return;
+        }
+        // Recover the exact prefix a previous invocation durably claimed before
+        // it disappeared. Later events may already be queued; they must survive
+        // and run separately, while the attempted prefix is never re-executed.
+        const attempted = (this.state.current.attempted_turns ??= {})[conversationId];
+        if (attempted) {
+            const queue = this.state.current.pending_events[conversationId] ?? [];
+            const prefix = queue.slice(0, attempted.event_ids.length);
+            if (prefix.length !== attempted.event_ids.length ||
+                prefix.some((event, index) => event.event_id !== attempted.event_ids[index])) {
+                throw new Error(`attempt ledger mismatch for ${conversationId}; refusing to execute queued events`);
+            }
+            this.log(`turn ${attempted.turn_key} was interrupted — dropping its ${prefix.length}-event prefix, not re-executing`);
+            this.clearBatch(conversationId, prefix, attempted.turn_key);
+            await this.postNotice(conversationId, "The bridge restarted while working on your last message, so it was not retried " +
+                "automatically (its tools may have partially run). Send it again to retry.", `${attempted.turn_key}-crashed`);
+            return;
+        }
+        // Snapshot: routeEvent keeps appending to the live queue while the turn
+        // runs, and the post-turn filter must only remove what THIS turn consumed.
+        const events = [...(this.state.current.pending_events[conversationId] ?? [])];
+        if (events.length === 0)
+            return;
+        const messages = events
+            .map((event) => event.data?.message)
+            .filter((message) => message !== undefined);
+        const promptText = promptTextFromMessages(messages);
+        if (promptText.length === 0) {
+            // Nothing promptable; drop the batch durably.
+            delete this.state.current.pending_events[conversationId];
+            this.state.persist();
+            return;
+        }
+        // Crash semantics: engine/tool side effects are at-most-once per batch.
+        // The exact event-id batch is persisted BEFORE the engine starts. A later
+        // message cannot change or overwrite which prefix was already attempted.
+        const eventIds = events.map((event) => event.event_id);
+        const turnKey = turnIdempotencyKey(conversationId, eventIds);
+        (this.state.current.attempted_turns ??= {})[conversationId] = {
+            turn_key: turnKey,
+            event_ids: eventIds,
+            started_at: new Date().toISOString(),
+        };
+        this.state.persist();
+        const typing = this.startTyping(conversationId);
+        try {
+            let result;
+            try {
+                result = await this.engine.startTurn({ conversationId, cwd: this.cwd }, promptText, {
+                    onToolEvent: (event) => typing.setLabel(event.title ?? "Working…"),
+                    onPermissionAsk: (ask) => this.broker.ask(conversationId, ask, this.engine.engine),
+                });
+            }
+            catch (error) {
+                // A failed engine turn is not silently retried (its side effects may
+                // have partially run) and must not strand the queue: tell the owner
+                // and clear the batch so the conversation stays usable.
+                this.log(`engine turn failed for ${conversationId}: ${error}`);
+                this.clearBatch(conversationId, events, turnKey);
+                await this.postNotice(conversationId, `The ${this.engine.engine} turn failed: ${String(error instanceof Error ? error.message : error).slice(0, 300)}\n` +
+                    "Send your message again to retry.", `${turnKey}-failed`);
+                return;
+            }
+            const text = result.text.trim().length > 0
+                ? result.text.trim()
+                : `(turn finished: ${result.stopReason})`;
+            // Persist the completed output BEFORE delivery. Any crash from here on
+            // can retry this idempotent POST without rerunning the engine or tools.
+            const pendingReply = {
+                conversation_id: conversationId,
+                event_ids: events.map((event) => event.event_id),
+                text,
+                created_at: new Date().toISOString(),
+            };
+            (this.state.current.pending_replies ??= {})[turnKey] = pendingReply;
+            this.state.persist();
+            if (await this.deliverPendingReply(turnKey, pendingReply)) {
+                this.clearBatch(conversationId, events, turnKey);
+            }
+            else {
+                // Keep the queue, attempt marker and completed reply. The scheduled
+                // retry enters the delivery-only path above.
+                this.scheduleFlush(conversationId);
+            }
+        }
+        finally {
+            await typing.stop();
+        }
+    }
+    startTyping(conversationId) {
+        let label;
+        let active = true;
+        const push = () => {
+            if (!active)
+                return;
+            this.client.setTyping(conversationId, true, label).catch(() => { });
+        };
+        push();
+        const interval = setInterval(push, 20_000);
+        interval.unref?.();
+        return {
+            setLabel: (next) => {
+                label = next.slice(0, 80);
+                push();
+            },
+            stop: async () => {
+                active = false;
+                clearInterval(interval);
+                await this.client.setTyping(conversationId, false).catch(() => { });
+            },
+        };
+    }
+    stop() {
+        this.stopped = true;
+        for (const timer of this.debounceTimers.values())
+            clearTimeout(timer);
+        this.debounceTimers.clear();
+    }
+    /** Supervisor: restart the poll loop on failure with capped backoff + jitter. */
+    async run() {
+        let failures = 0;
+        // Replay anything a previous process left behind.
+        this.broker.sweep();
+        for (const conversationId of Object.keys(this.state.current.pending_events)) {
+            this.scheduleFlush(conversationId);
+        }
+        while (!this.stopped) {
+            try {
+                this.broker.sweep();
+                await this.pollOnce();
+                failures = 0;
+            }
+            catch (error) {
+                if (error?.status === 409) {
+                    // Another consumer (webhook or second long-poll) owns this token.
+                    this.log(`fatal: ${error.message}`);
+                    throw error;
+                }
+                if (error?.status === 401) {
+                    this.log("fatal: agent token rejected (401) — run `relaymessenger pair` again.");
+                    throw error;
+                }
+                failures += 1;
+                const base = Math.min(500 * 2 ** Math.min(failures, 6), 30_000);
+                const jitter = base * (0.7 + Math.random() * 0.6);
+                this.log(`poll failed (attempt ${failures}), retrying in ${Math.round(jitter)}ms: ${error}`);
+                await new Promise((resolve) => this.setTimeoutImpl(resolve, jitter));
+            }
+        }
+    }
+}
+//# sourceMappingURL=receive.js.map

package/dist/receive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receive.js","sourceRoot":"","sources":["../src/receive.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Durable local state for the relaymessenger bridge.
+ *
+ * Everything lives under ~/.relaymessenger (override with RELAYMESSENGER_HOME):
+ *   config.json    — active agent token, API origin, owner_user_id (chmod 600)
+ *   accounts/<origin-agent-hash>/state.json — receive cursor, dedupe set,
+ *                    pending events. EXCLUSIVELY
+ *                    owned (written) by the `start` loop process; other
+ *                    entrypoints (codex hook, notify, mcp) may only read it
+ *                    via readStateSnapshot().
+ *   accounts/<hash>/approvals/<request_id>.json — pending approval (create-once
+ *                    by whoever arms it, resolution written by the loop,
+ *                    consumed+unlinked by the waiter). No read-modify-write
+ *                    of shared snapshots across processes.
+ *   accounts/<hash>/sessions.json — conversation_id → engine session binding
+ *
+ * Writes are atomic: content is fsync'd to a tmp file, then renamed into
+ * place, so a crash can never leave a half-written file. Cursor + pending
+ * queue share one file, so the durable-before-ack invariant holds with a
+ * single atomic write.
+ */
+import { renameSync } from "node:fs";
+export declare function relaymessengerHome(): string;
+export interface RelayConfig {
+    api_origin: string;
+    agent_token: string;
+    /**
+     * The Relay user id allowed to drive this bridge. Pinned at pair time from
+     * GET /v1/agents/me; overridable with RELAY_OWNER_USER_ID. Everything the
+     * bridge does — prompts, approvals, notify targets — is gated on it.
+     */
+    owner_user_id?: string;
+    agent?: {
+        id?: string;
+        handle?: string;
+        display_name?: string;
+    };
+    paired_at?: string;
+}
+/** Stable, non-secret identity label used inside account-scoped ledgers. */
+export declare function relayIdentityForConfig(config: Pick<RelayConfig, "agent_token" | "agent">): string;
+/**
+ * Durable bridge state is scoped to one authenticated Relay identity. The
+ * agent id is preferred; a token fingerprint is the fail-safe fallback for
+ * legacy servers that do not expose it. Raw tokens/origins never enter paths.
+ */
+export declare function runtimeHomeForConfig(config: Pick<RelayConfig, "api_origin" | "agent_token" | "agent">, baseHome?: string): string;
+export declare function activeRuntimeHome(baseHome?: string): string;
+/** Resolve the pinned owner, failing closed when it is missing. */
+export declare function resolveOwnerUserId(config: RelayConfig | undefined): string;
+export interface PendingApproval {
+    request_id: string;
+    conversation_id: string;
+    engine?: string;
+    tool_name?: string;
+    created_at: string;
+    /** ISO time after which the approval is denied. */
+    deadline_at: string;
+    /** Relay message id of the card, for reply_to matching. */
+    relay_message_id?: string;
+    options: Array<{
+        option_id: string;
+        label: string;
+        kind?: string;
+    }>;
+    source: "acp" | "hook";
+    resolution?: {
+        option_id?: string;
+        behavior: "allow" | "deny" | "cancelled";
+        decided_at: string;
+    };
+}
+export interface RelayEvent {
+    event_id: string;
+    event_type: string;
+    agent_id?: string;
+    created_at?: string;
+    data?: {
+        message?: RelayMessage;
+        [key: string]: unknown;
+    };
+}
+export interface RelayMessage {
+    id: string;
+    conversation_id: string;
+    sequence: number;
+    sender: {
+        kind: "user" | "agent";
+        id: string;
+    };
+    parts: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    fallback_text: string;
+    reply_to?: {
+        message_id?: string;
+        part_index?: number;
+    } | null;
+    created_at?: string;
+}
+export interface BridgeState {
+    cursor: number;
+    seen_event_ids: string[];
+    pending_events: Record<string, RelayEvent[]>;
+    /**
+     * conversation_id → turn idempotency key persisted immediately BEFORE the
+     * engine turn starts and cleared on success. A marker found at startup means
+     * a previous process crashed mid-turn: that batch is dropped with a notice
+     * instead of re-executed, so engine/tool side effects (deploys, deletions,
+     * sends) run at most once per owner message.
+     */
+    attempted_turns?: Record<string, {
+        turn_key: string;
+        event_ids: string[];
+        started_at: string;
+    }>;
+    /**
+     * Engine-completed replies waiting for idempotent Relay delivery. The full
+     * reply is persisted before the POST, so a restart can redeliver it without
+     * executing the engine or its tools again.
+     */
+    pending_replies?: Record<string, {
+        conversation_id: string;
+        event_ids: string[];
+        text: string;
+        created_at: string;
+    }>;
+    /**
+     * The owner's conversation with this agent, persisted by the loop when the
+     * first owner message arrives. Default target for notify/MCP sends. Never
+     * derived from the most recent writer.
+     */
+    owner_conversation_id?: string;
+}
+export interface SessionBinding {
+    engine: string;
+    session_id: string;
+    cwd: string;
+    created_at: string;
+}
+export interface BlockInvalidStateOperations {
+    writeBlock?: typeof atomicWriteJson;
+    quarantine?: typeof renameSync;
+    /** Test-only crash boundary after the fail-closed marker is durable. */
+    afterBlockPersisted?: () => void;
+}
+export declare function blockInvalidState(home: string, path: string, reason: string, operations?: BlockInvalidStateOperations): never;
+export declare function atomicWriteJson(path: string, value: unknown, mode: number): void;
+export declare class ConfigStore {
+    private readonly home;
+    constructor(home?: string);
+    get path(): string;
+    load(): RelayConfig | undefined;
+    save(config: RelayConfig): void;
+}
+/**
+ * Read-only view of state.json for non-loop processes (hook, notify, mcp).
+ * Those processes MUST NOT construct a StateStore: only the `start` loop
+ * writes state.json.
+ */
+export declare function readStateSnapshot(home?: string): BridgeState;
+export declare class StateStore {
+    private readonly home;
+    private state;
+    constructor(home?: string);
+    get path(): string;
+    get current(): BridgeState;
+    markSeen(eventId: string): void;
+    hasSeen(eventId: string): boolean;
+    persist(): void;
+}
+/**
+ * Per-request approval files in the active account runtime directory.
+ * Create-once by whoever arms the approval (loop or codex hook), resolution
+ * written by the loop when the tap arrives, consumed + unlinked by the waiter.
+ * Each file has a single writer at a time, so there is no read-modify-write
+ * of a shared snapshot across processes.
+ */
+export declare class ApprovalStore {
+    private readonly home;
+    constructor(home?: string);
+    get dir(): string;
+    private pathFor;
+    /** Create-once: throws if the request id already exists. */
+    create(approval: PendingApproval): void;
+    get(requestId: string): PendingApproval | undefined;
+    /** Full rewrite of one approval file (single-writer per file by protocol). */
+    put(approval: PendingApproval): void;
+    /** The waiter consumes the decision by removing the file. */
+    consume(requestId: string): void;
+    list(): PendingApproval[];
+    /**
+     * Age out abandoned files. An unconsumed resolution belongs to a waiter in
+     * another process, so nothing is removed before deadline + grace — only
+     * files whose waiter has clearly given up (crashed hook, dead loop).
+     */
+    sweep(now?: number, graceMs?: number): string[];
+}
+export interface McpOutboundSend {
+    send_id: string;
+    api_origin: string;
+    account_identity: string;
+    conversation_id: string;
+    payload_hash: string;
+    idempotency_key: string;
+    created_at: string;
+    confirmed_at?: string;
+}
+/**
+ * Create-once ledger for Codex MCP logical sends. Each caller-provided send_id
+ * is permanently bound to one account, origin, conversation, and exact body.
+ * An ambiguous POST can therefore be repeated after a process restart with
+ * the same server idempotency key, while changed content fails closed.
+ */
+export declare class McpSendLedger {
+    private readonly home;
+    private readonly apiOrigin;
+    private readonly accountIdentity;
+    constructor(home: string, apiOrigin: string, accountIdentity: string);
+    get dir(): string;
+    private pathFor;
+    register(sendId: string, conversationId: string, text: string): McpOutboundSend;
+    confirm(send: McpOutboundSend): void;
+}
+export declare class SessionStore {
+    private readonly home;
+    private sessions;
+    constructor(home?: string);
+    get path(): string;
+    get(conversationId: string): SessionBinding | undefined;
+    set(conversationId: string, binding: SessionBinding): void;
+    delete(conversationId: string): void;
+    all(): Record<string, SessionBinding>;
+}
+export interface CodexNotifyPolicy {
+    allowed_project_roots: string[];
+}
+/** Local, non-secret project opt-ins shared across Relay re-pairs. */
+export declare class CodexNotifyPolicyStore {
+    private readonly home;
+    constructor(home?: string);
+    get path(): string;
+    load(): CodexNotifyPolicy;
+    allowProject(projectRoot: string): string;
+    matchProject(cwd: string | undefined): string | undefined;
+}
+/** One live `relaymessenger start` process per origin+agent runtime namespace. */
+export declare class RuntimeLock {
+    private readonly runtimeHome;
+    private readonly nonce;
+    private held;
+    constructor(runtimeHome: string);
+    get dir(): string;
+    private ownerPath;
+    acquire(): void;
+    release(): void;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}