codex-channel-bgos 0.2.0

package/dist/heartbeat.d.ts

@@ -0,0 +1,75 @@
+export interface HeartbeatLastError {
+    code: string;
+    message: string;
+    at: string;
+}
+/** Wire shape POSTed to the backend heartbeat endpoint. */
+export interface HeartbeatDto {
+    daemonVersion?: string;
+    uptimeS?: number;
+    wsConnected?: boolean;
+    lastError?: HeartbeatLastError | null;
+    /** Active Codex auth mode ("chatgpt" | "apikey"), D7 surfacing. */
+    authMode?: string;
+}
+/** Local heartbeat file shape (contract C1). */
+export interface HeartbeatFileState {
+    ts: string;
+    pid: number;
+    version: string;
+    wsConnected: boolean;
+    wsConnectedSince: string | null;
+    lastInboundAt: string | null;
+    lastOutboundAt: string | null;
+    lastError: HeartbeatLastError | null;
+    pairingId: number | null;
+    authMode: string | null;
+}
+export interface HeartbeatDeps {
+    version: string;
+    /** Best-effort POST to the backend heartbeat endpoint. */
+    postHeartbeat: (body: HeartbeatDto) => Promise<void>;
+    /** Active Codex auth mode, surfaced in the payload + local file (D7). */
+    authMode?: string;
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+export declare class HeartbeatController {
+    private readonly deps;
+    private wsConnected;
+    private wsConnectedSince;
+    private lastInboundAt;
+    private lastOutboundAt;
+    private lastError;
+    private pairingId;
+    private readonly startedAtMs;
+    private readonly now;
+    private fileTimer;
+    private netTimer;
+    private netEnabled;
+    private started;
+    constructor(deps: HeartbeatDeps);
+    start(): void;
+    stop(): void;
+    private armNetworkTimer;
+    private clearNetworkTimer;
+    /** Enable/disable the NETWORK sink (fatal latch disables it; recovery
+     *  re-enables). The local file keeps writing regardless. */
+    setNetEnabled(enabled: boolean): void;
+    setWsConnected(connected: boolean, since: string | null): void;
+    setPairingId(id: number | null): void;
+    recordInbound(): void;
+    recordOutbound(): void;
+    /**
+     * Record (or clear) the last error. A change of error CODE (including to
+     * null) is an "error transition": it writes the file AND posts a network
+     * heartbeat immediately.
+     */
+    setLastError(err: HeartbeatLastError | null): void;
+    /** Current error code (used by callers to decide whether to clear). */
+    getLastErrorCode(): string | null;
+    snapshotFile(): HeartbeatFileState;
+    private writeFile;
+    private postNetwork;
+}
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACtC,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACrC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,aAAa,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAiBD,qBAAa,mBAAmB;IAelB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAdjC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,SAAS,CAAuB;IAExC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,OAAO,CAAS;gBAEK,IAAI,EAAE,aAAa;IAKhD,KAAK,IAAI,IAAI;IAUb,IAAI,IAAI,IAAI;IASZ,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,iBAAiB;IAOzB;gEAC4D;IAC5D,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAYrC,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAS9D,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIrC,aAAa,IAAI,IAAI;IAIrB,cAAc,IAAI,IAAI;IAItB;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,GAAG,IAAI;IAWlD,uEAAuE;IACvE,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAIjC,YAAY,IAAI,kBAAkB;IAelC,OAAO,CAAC,SAAS;YAcH,WAAW;CAuB1B"}

package/dist/heartbeat.js

@@ -0,0 +1,186 @@
+/**
+ * Daemon liveness + error telemetry for the BGOS channel (contract C1).
+ *
+ * Two sinks:
+ *   1. Network: POST /api/v1/integrations/heartbeat every
+ *      CODEX_BGOS_HEARTBEAT_INTERVAL seconds (default 60, 0 disables) PLUS
+ *      once on start and on every error transition. Backend touches
+ *      last_seen_at + records daemon_version / last_error_*.
+ *   2. Local file: `$CODEX_BGOS_HOME/bgos_heartbeat.json` written every 30s and on
+ *      state change, atomic tmp+rename mode 0600. Read by the fork watchdog.
+ *
+ * During a fatal latch (revoked / rotated token) the network sink is disabled
+ * but the local file keeps writing so the watchdog can see the lastError.
+ */
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const FILE_INTERVAL_MS = 30_000;
+function heartbeatPath() {
+    const root = process.env.CODEX_BGOS_HOME ?? join(homedir(), ".codex-bgos");
+    return join(root, "bgos_heartbeat.json");
+}
+function resolveNetworkIntervalMs() {
+    const raw = process.env.CODEX_BGOS_HEARTBEAT_INTERVAL;
+    if (raw === undefined || raw === "")
+        return 60_000;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return 60_000;
+    return n * 1000;
+}
+export class HeartbeatController {
+    deps;
+    wsConnected = false;
+    wsConnectedSince = null;
+    lastInboundAt = null;
+    lastOutboundAt = null;
+    lastError = null;
+    pairingId = null;
+    startedAtMs;
+    now;
+    fileTimer = null;
+    netTimer = null;
+    netEnabled = true;
+    started = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? (() => Date.now());
+        this.startedAtMs = this.now();
+    }
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.writeFile();
+        void this.postNetwork();
+        this.fileTimer = setInterval(() => this.writeFile(), FILE_INTERVAL_MS);
+        this.fileTimer.unref?.();
+        this.armNetworkTimer();
+    }
+    stop() {
+        this.started = false;
+        if (this.fileTimer !== null) {
+            clearInterval(this.fileTimer);
+            this.fileTimer = null;
+        }
+        this.clearNetworkTimer();
+    }
+    armNetworkTimer() {
+        this.clearNetworkTimer();
+        const intervalMs = resolveNetworkIntervalMs();
+        if (intervalMs <= 0)
+            return; // 0 disables periodic network heartbeat
+        this.netTimer = setInterval(() => void this.postNetwork(), intervalMs);
+        this.netTimer.unref?.();
+    }
+    clearNetworkTimer() {
+        if (this.netTimer !== null) {
+            clearInterval(this.netTimer);
+            this.netTimer = null;
+        }
+    }
+    /** Enable/disable the NETWORK sink (fatal latch disables it; recovery
+     *  re-enables). The local file keeps writing regardless. */
+    setNetEnabled(enabled) {
+        if (this.netEnabled === enabled)
+            return;
+        this.netEnabled = enabled;
+        if (!this.started)
+            return;
+        if (enabled) {
+            this.armNetworkTimer();
+            void this.postNetwork();
+        }
+        else {
+            this.clearNetworkTimer();
+        }
+    }
+    setWsConnected(connected, since) {
+        if (this.wsConnected === connected && this.wsConnectedSince === since) {
+            return;
+        }
+        this.wsConnected = connected;
+        this.wsConnectedSince = since;
+        this.writeFile(); // state change
+    }
+    setPairingId(id) {
+        this.pairingId = id;
+    }
+    recordInbound() {
+        this.lastInboundAt = new Date(this.now()).toISOString();
+    }
+    recordOutbound() {
+        this.lastOutboundAt = new Date(this.now()).toISOString();
+    }
+    /**
+     * Record (or clear) the last error. A change of error CODE (including to
+     * null) is an "error transition": it writes the file AND posts a network
+     * heartbeat immediately.
+     */
+    setLastError(err) {
+        const prevCode = this.lastError?.code ?? null;
+        const nextCode = err?.code ?? null;
+        const transition = prevCode !== nextCode;
+        this.lastError = err;
+        if (transition) {
+            this.writeFile();
+            void this.postNetwork();
+        }
+    }
+    /** Current error code (used by callers to decide whether to clear). */
+    getLastErrorCode() {
+        return this.lastError?.code ?? null;
+    }
+    snapshotFile() {
+        return {
+            ts: new Date(this.now()).toISOString(),
+            pid: process.pid,
+            version: this.deps.version,
+            wsConnected: this.wsConnected,
+            wsConnectedSince: this.wsConnectedSince,
+            lastInboundAt: this.lastInboundAt,
+            lastOutboundAt: this.lastOutboundAt,
+            lastError: this.lastError,
+            pairingId: this.pairingId,
+            authMode: this.deps.authMode ?? null,
+        };
+    }
+    writeFile() {
+        try {
+            const target = heartbeatPath();
+            mkdirSync(dirname(target), { recursive: true });
+            const tmp = `${target}.${process.pid}.tmp`;
+            writeFileSync(tmp, JSON.stringify(this.snapshotFile(), null, 2), {
+                mode: 0o600,
+            });
+            renameSync(tmp, target);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    async postNetwork() {
+        if (!this.netEnabled)
+            return;
+        if (resolveNetworkIntervalMs() <= 0) {
+            // interval 0 disables periodic posts; still allow start()'s single
+            // post? No: 0 means "disabled", so skip entirely.
+            return;
+        }
+        const uptimeS = Math.max(0, Math.floor((this.now() - this.startedAtMs) / 1000));
+        try {
+            await this.deps.postHeartbeat({
+                daemonVersion: this.deps.version,
+                uptimeS,
+                wsConnected: this.wsConnected,
+                lastError: this.lastError,
+                authMode: this.deps.authMode,
+            });
+        }
+        catch {
+            /* best-effort: a heartbeat failure must never break the daemon */
+        }
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/heartbeat.js.map

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

package/dist/inbound-handler.d.ts

@@ -0,0 +1,167 @@
+import type { BgosOutbound } from "./outbound.js";
+import type { ToolProgressOrchestrator } from "./tool-progress.js";
+import type { ApprovalMeta, InboundMessagePayload, MessageOption } from "./types.js";
+/**
+ * Reply handle the fork's `processMessageForAgent` calls into.
+ *
+ * Mirrors the Telegram side (which the fork builds in
+ * `src/adapters/bgos/reply-handle.ts`) so a single agent handler can
+ * speak to either origin without branching internally. Methods are
+ * Promise-returning so the fork can await delivery confirmation when it
+ * cares.
+ */
+export interface ReplyHandle {
+    origin: "bgos";
+    sendText: (text: string) => Promise<{
+        id: number;
+    }>;
+    sendButtons: (text: string, options: MessageOption[]) => Promise<{
+        id: number;
+    }>;
+    sendApprovalRequest: (text: string, meta: ApprovalMeta) => Promise<{
+        id: number;
+    }>;
+    sendAskUserInput: (prompt: string, options?: MessageOption[], modal?: boolean) => Promise<{
+        id: number;
+    }>;
+    sendFile: (filePath: string, caption?: string) => Promise<{
+        id: number;
+    }>;
+    sendImage: (filePath: string, caption?: string) => Promise<{
+        id: number;
+    }>;
+    sendVideo: (filePath: string, caption?: string) => Promise<{
+        id: number;
+    }>;
+    sendTyping: () => Promise<void>;
+    /** Publish a local file path to BGOS as a `files[]` entry; useful when
+     *  the agent emits structured tool output rather than a `MEDIA:` line.
+     *  The `filePath` is validated against the `CODEX_BGOS_MEDIA_ROOT` allowlist
+     *  (see media-guard.ts) before any bytes are read - paths outside the
+     *  root, traversal, escaping symlinks, and sensitive locations throw. */
+    uploadFile: (filePath: string, opts?: {
+        fileName?: string;
+        mimeType?: string;
+    }) => Promise<{
+        fileName: string;
+        fileMimeType: string;
+        size: number;
+    }>;
+    /**
+     * Record that a tool just started executing in the current agent turn.
+     * The plugin emits a live `tool_progress` card in BGOS - POSTing on the
+     * first call per turn, PATCHing on subsequent calls (debounced).
+     *
+     * Codex fork wiring: call this from `callClaudeStreaming`'s `onToolStart`
+     * hook on the BGOS dispatch path:
+     *
+     *   onToolStart: (toolName) => replyHandle.sendToolStart(toolName)
+     *
+     * No-op when the adapter wasn't constructed with a tool-progress
+     * orchestrator (old host code) - safe to call unconditionally.
+     * `args` is optional, ≤120 chars (truncated by the plugin).
+     */
+    sendToolStart: (toolName: string, args?: string) => Promise<void>;
+    /**
+     * End-of-turn signal - transitions the active tool_progress card from
+     * state="running" to "done" so the frontend auto-collapses it. The
+     * fork should call this AFTER the agent's text reply has been sent
+     * via `sendText` (or even if the turn ends without a reply). Idempotent
+     * - safe to call multiple times. No-op when no card exists for this
+     * chat (turn used no tools).
+     */
+    finalizeTurn: () => Promise<void>;
+}
+/**
+ * Args the fork's dispatch function receives. Kept deliberately flat
+ * and dependency-free so the fork can adapt them onto whatever shape
+ * Codex's internal pipeline expects.
+ */
+export interface DispatchArgs {
+    origin: "bgos";
+    agentRoute: string;
+    assistantId: number;
+    chatId: number;
+    /** The BGOS message id of this inbound. Surfaced so the fork can correlate
+     *  / log; the reply anchoring (reply_to_id) is handled automatically by
+     *  the ReplyHandle for a2a side-threads. */
+    messageId: number;
+    userId: string;
+    text: string;
+    /** Local file paths the user attached (already downloaded). Empty
+     *  when the user only sent text. */
+    attachments: Array<{
+        localPath: string;
+        fileName: string;
+        mimeType: string;
+        kind: "photo" | "video" | "document" | "voice";
+    }>;
+    /** Append to the agent's existing system prompt (hints injection
+     *  happens here so every dispatch carries them). */
+    systemPrompt: string;
+    /** Reply handle scoped to BGOS - the agent only talks back via this. */
+    replyHandle: ReplyHandle;
+    /** Slash-command metadata if `messageType==='slash_command'`. */
+    command?: {
+        name: string;
+        args: string;
+    };
+    messageType: InboundMessagePayload["messageType"];
+    /** Present when this inbound is a peer agent's a2a side-thread message.
+     *  The reply is auto-routed back to the peer (via `/send-message` with
+     *  `reply_to_id`) so the peer's `wait_for_reply` resolves - the agent
+     *  does NOT need to do anything special. Surfaced for awareness / future
+     *  use (e.g. tailoring the reply to `turnState`). */
+    peerConversationId?: number;
+    /** Turn state on the peer side-thread (`expecting_reply` | `more_coming`
+     *  | `final`) when `peerConversationId` is set. */
+    turnState?: string;
+}
+export type DispatchFn = (args: DispatchArgs) => Promise<void>;
+export interface InboundHandlerDeps {
+    outbound: BgosOutbound;
+    /** Map an assistant id to the bound agent route. Adapter-provided. */
+    getRouteForAssistant(assistantId: number): string | null;
+    /** The fork-supplied dispatch function. May be `null` until the fork
+     *  calls `setDispatch(fn)` - early WS messages then no-op safely. */
+    getDispatch(): DispatchFn | null;
+    /** Optional system-prompt prefix (e.g. agent persona). The handler
+     *  appends `BGOS_AGENT_HINTS` to whatever this returns. */
+    getSystemPrompt?(agentRoute: string): string;
+    /** Tool-progress card orchestrator - adapter-provided. The factory
+     *  wires `replyHandle.sendToolStart` + `replyHandle.finalizeTurn`
+     *  through this. Optional for back-compat; older host code that
+     *  doesn't call these methods continues to work, just without cards. */
+    toolProgress?: ToolProgressOrchestrator;
+    /** Called (best-effort) when a message is about to dispatch, driving the
+     *  heartbeat `lastInboundAt` timestamp. Optional. */
+    onInbound?(): void;
+    /** Rate-limited, single-flight scope refresh invoked when an inbound
+     *  arrives for an assistant_id NOT in the route map. The adapter refreshes
+     *  identity (whoami) so a newly-exposed agent heals without a restart. The
+     *  handler retries the route lookup ONCE after this resolves. Optional. */
+    onUnknownAssistant?(assistantId: number): Promise<void>;
+}
+/**
+ * Build a BGOS-scoped ReplyHandle. Extracted so both the inbound dispatch
+ * path AND the adapter's `makeReplyHandle` factory (contract C6, for the
+ * fork's HITL button-click resume) produce an identical surface.
+ *
+ * `replyVia` / `replyToId` are set by the inbound path for a2a peer replies;
+ * `makeReplyHandle` leaves them undefined (a plain reply into a chat).
+ */
+export declare function buildReplyHandle(deps: {
+    outbound: BgosOutbound;
+    toolProgress?: ToolProgressOrchestrator;
+}, target: {
+    assistantId: number;
+    chatId: number;
+    replyVia?: "send-message";
+    replyToId?: number;
+}): ReplyHandle;
+/**
+ * Build the inbound-event handler. Returns an async function the
+ * adapter wires onto `BgosWs`'s `inbound_message` event.
+ */
+export declare function createInboundHandler(deps: InboundHandlerDeps): (event: InboundMessagePayload) => Promise<void>;
+//# sourceMappingURL=inbound-handler.d.ts.map

package/dist/inbound-handler.d.ts.map

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