codex-channel-bgos 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrandGrowthOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# codex-channel-bgos
+
+Chat with your OpenAI Codex agents inside BGOS (Home of Agents).
+
+`codex-channel-bgos` is a small daemon that runs on your machine, pairs with your
+BGOS account, and hosts OpenAI Codex through the official
+[`@openai/codex-sdk`](https://www.npmjs.com/package/@openai/codex-sdk). Every BGOS
+chat maps to one persistent Codex thread, so your agent keeps context; tool runs
+show up live as a tool-progress card; and `/new` starts fresh.
+
+It is a sibling of `gobot-channel-bgos`, `openclaw-channel-bgos`, and
+`hermes-channel-bgos` and reuses their proven transport, dedupe, cursor, and
+outbound machinery.
+
+## Quick start (one paste)
+
+1. In the BGOS app, tap **Add an agent** and pick **Codex**. Copy the pair code.
+2. On the computer where Codex runs, paste:
+
+```bash
+npx codex-channel-bgos connect BGOS-XXXX-XX
+```
+
+That pairs and starts the daemon in one step. Your Codex agent appears in BGOS,
+ready to chat.
+
+The `codex` runtime ships with the npm package, so you do not need a separate
+install. You do need to be signed in (see Auth).
+
+## Auth
+
+The daemon prefers an existing `codex login` (your ChatGPT plan, no extra cost),
+and falls back to an OpenAI API key.
+
+- If you have run `codex login`, it is used automatically.
+- Otherwise set `OPENAI_API_KEY` (for example in `~/.env`).
+- With neither, the daemon refuses to start and tells you how to fix it.
+
+Override the choice with `CODEX_BGOS_AUTH_MODE`:
+
+| Value | Behavior |
+|---|---|
+| `auto` (default) | Prefer the codex login, else `OPENAI_API_KEY` |
+| `chatgpt` | Require the codex login |
+| `apikey` | Require `OPENAI_API_KEY` (metered billing) |
+
+The active mode is printed at startup and reported in the heartbeat.
+
+## Commands
+
+```bash
+codex-channel-bgos connect <CODE>   # pair with a BGOS code, then start
+codex-channel-bgos start            # start from the stored pairing token
+codex-channel-bgos install-service  # install launchd/systemd persistence
+codex-channel-bgos --help
+```
+
+## Keep it running
+
+```bash
+npm i -g codex-channel-bgos
+codex-channel-bgos connect BGOS-XXXX-XX   # once, to pair
+codex-channel-bgos install-service        # launchd (macOS) or systemd user unit (Linux)
+```
+
+On Linux, to keep the service alive after logout: `loginctl enable-linger "$USER"`.
+
+## What your Codex agent can do
+
+The agent talks back with plain text plus a few markers (documented for the agent
+in `AGENTS.md`, which the daemon writes into the workspace):
+
+- Files and media: put `MEDIA:/absolute/path` on its own line.
+- Inline buttons (up to 6): a `[[BGOS_BUTTONS]] ... [[/BGOS_BUTTONS]]` block.
+- Blocking questions (1 to 4): a `[[BGOS_ASK]] ... [[/BGOS_ASK]]` block.
+- Status line: `STATUS: <text>`.
+- Tool progress: automatic. Codex's shell, file, MCP, and web-search activity is
+  streamed to a live card; the agent does not self-report.
+- Inbound images are passed to Codex natively; other files are downloaded and
+  their path is given to the agent.
+
+Slash commands `/new` (reset the thread), `/retry`, and `/status` are handled by
+the daemon. Dangerous-command approval cards are not surfaced in this version (the
+SDK exposes only a fixed approval policy; the daemon runs in a workspace-write
+sandbox). See the capability canon in `hermes-channel-bgos/docs/bgos-agent-capabilities.md`.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `OPENAI_API_KEY` | (none) | API-key auth (fallback to codex login) |
+| `CODEX_BGOS_AUTH_MODE` | `auto` | `auto` / `chatgpt` / `apikey` |
+| `CODEX_BGOS_HOME` | `~/.codex-bgos` | Data dir (secrets, threads, workspace, logs) |
+| `CODEX_BGOS_MODEL` | (SDK default) | Codex model override |
+| `CODEX_BGOS_POLL_INTERVAL` | `5` | Inbound poll seconds (0 disables) |
+| `CODEX_BGOS_HEARTBEAT_INTERVAL` | `60` | Heartbeat seconds (0 disables network) |
+| `BGOS_BASE_URL` | `https://api.brandgrowthos.ai` | Backend base URL |
+
+Data lives under `~/.codex-bgos/` (kept separate from OpenAI Codex's own
+`~/.codex/`): `secrets/bgos.json` (0600), `threads.json` (chat to thread map),
+`workspace/` (Codex working dir + AGENTS.md), plus cursor/outbox/heartbeat files.
+
+## Develop
+
+```bash
+npm install
+npm test        # vitest
+npm run build   # tsc + shebang finalize
+npm run lint    # tsc --noEmit
+```
+
+## License
+
+MIT

package/dist/adapter.d.ts

@@ -0,0 +1,96 @@
+import { BgosApi } from "./bgos-api.js";
+import { BgosOutbound } from "./outbound.js";
+import { CommandsSync } from "./commands-sync.js";
+import { ToolProgressOrchestrator } from "./tool-progress.js";
+import { type CatalogAgent } from "./catalog-sync.js";
+import { type CommandSeedMode } from "./default-commands.js";
+import type { AuthResolutionOk } from "./auth-mode.js";
+import { type PluginConfig } from "./types.js";
+export interface FatalInfo {
+    code: string;
+    message: string;
+    reason: string;
+}
+export interface CodexAdapterOptions {
+    /** Agent catalog to push on connect (defaults to a single "codex" agent). */
+    agents?: CatalogAgent[];
+    /** Model override (CODEX_BGOS_MODEL). */
+    model?: string;
+    commandSeedMode?: CommandSeedMode;
+    onFatal?: (info: FatalInfo) => void;
+}
+export declare class CodexAdapter {
+    readonly api: BgosApi;
+    readonly outbound: BgosOutbound;
+    readonly commandsSync: CommandsSync;
+    readonly toolProgress: ToolProgressOrchestrator;
+    private readonly cfg;
+    private readonly ws;
+    private readonly heartbeat;
+    private readonly host;
+    private readonly assistantToRoute;
+    private readonly lastInput;
+    private readonly dispatch;
+    private catalog;
+    private commandSeedModeOverride;
+    private pairingId;
+    private pollTimer;
+    private spoolTimer;
+    private started;
+    private readonly onFatal?;
+    private identityReady;
+    private capabilitiesLoaded;
+    private identityRetryTimer;
+    private pollStarted;
+    private lastScopeRefreshAt;
+    private scopeRefreshInFlight;
+    private currentToken;
+    private fatalLatched;
+    private fatalNotified;
+    private last401LogAt;
+    private secretsWatcher;
+    private secretsStatTimer;
+    private secretsDebounce;
+    constructor(cfg: PluginConfig, auth: AuthResolutionOk, opts?: CodexAdapterOptions);
+    get authMode(): "chatgpt" | "apikey";
+    private getCommandSeedMode;
+    private getRouteForAssistant;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Fetch the served capability canon once and inject it into the Codex agent's
+     * AGENTS.md, replacing the bundled fallback the host wrote at construction.
+     * Never throws: any failure (network, 401, 404 on an old backend, malformed
+     * body) leaves the bundled copy in place so the daemon is never blocked on
+     * this. Runs once per process (start() is guarded), i.e. once at connect.
+     */
+    private loadServedCapabilities;
+    private statusLine;
+    private codexDispatch;
+    private runAndReply;
+    /**
+     * A user tapped an inline button or answered an ask question. Feed the choice
+     * back to Codex as the next turn (the thread keeps context), so the agent
+     * continues naturally. Correlate by (assistantId, chatId).
+     */
+    private handleInboundClick;
+    private refreshIdentity;
+    private scheduleIdentityRetry;
+    private refreshScopeRateLimited;
+    private reconcilePendingUnknownError;
+    private startPollLoop;
+    private stopPollLoop;
+    private onReconnect;
+    private handleWsError;
+    private enterFatalLatch;
+    private resolveSecretsDir;
+    private readSecretsFile;
+    private armSecretsWatch;
+    private startSecretsWatch;
+    private rearmSecretsWatch;
+    private stopSecretsWatch;
+    private checkSecretsForChange;
+    private recover;
+    private seedDefaultCommands;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

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