@agentvault/openai-bridge 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# AgentVault OpenAI Bridge
+
+Connect a local OpenAI Codex login to encrypted AgentVault owner direct messages and rooms. This is the `openai` framework under the existing `harness` runtime. It does not use an OpenAI API key or the archived Codex channel runtime.
+
+**Release status:** initial release. The app offers installation only after registry installation and an owner-authenticated live messaging check pass. Tests alone do not establish account access, billing eligibility, or production delivery.
+
+## Prerequisites and login
+
+Node.js 20 or newer, macOS or Linux, and **the native Codex CLI 0.154.0 executable** on PATH are required. The supported model is fixed to `gpt-5.6-terra`. A JavaScript npm launcher that requires Node from a Homebrew/custom PATH cannot run inside the deliberately minimal child PATH; install the native Codex executable instead. Other CLI versions fail closed because the disabled-tool boundary must be measured again before upgrading.
+
+Install it globally (`npm install -g @agentvault/openai-bridge`). Development builds can run `node dist/index.js --help`; background service installation rejects temporary package-cache entrypoints.
+
+Choose one agent name and use it for every command:
+
+```sh
+AV_AGENT_NAME=aster agentvault-openai-bridge login
+AV_AGENT_NAME=aster agentvault-openai-bridge doctor
+AV_AGENT_NAME=aster AV_INVITE_TOKEN='<invite>' agentvault-openai-bridge run
+```
+
+`login` explicitly runs the official Codex device-auth login. It uses this agent's dedicated auth directory and does not reuse your normal Codex login or configuration. Complete the browser instructions printed by Codex. No login or provider call happens during package installation, help, version, or tests.
+
+The invite remains in a mode-0600 `pending-invite` file until the encrypted channel becomes ready after approval. A restart loads existing AgentVault credentials. Keep the same `AV_AGENT_NAME`; another name selects separate auth, device credentials and history.
+
+## Background service
+
+After explicit login and global installation:
+
+```sh
+AV_AGENT_NAME=aster AV_INVITE_TOKEN='<invite>' agentvault-openai-bridge install
+AV_AGENT_NAME=aster agentvault-openai-bridge status
+AV_AGENT_NAME=aster agentvault-openai-bridge logs
+AV_AGENT_NAME=aster agentvault-openai-bridge restart
+AV_AGENT_NAME=aster agentvault-openai-bridge uninstall
+```
+
+macOS uses a per-user launchd service; Linux uses user systemd. Linux services normally require an active user manager; configure user lingering separately if you need execution after logout. Services use the resolved stable Node and bridge paths, and the saved absolute Codex path. `uninstall` removes the service definition and retains credentials/history. `status` reports service-manager state; `doctor` checks binary compatibility and file presence, without opening credentials or claiming that the account is valid.
+
+If Codex is upgraded, install the supported version again before restarting. If authentication expires, run `uninstall`, run `login` again with the same name, then run `install` again. These commands retain the agent credentials and history. For replacement enrollment, stop the existing service with `uninstall`, obtain a fresh recovery invite from the app, then run:
+
+```sh
+AV_AGENT_NAME=aster AV_INVITE_TOKEN='<fresh-invite>' agentvault-openai-bridge replace
+```
+
+Replacement acquires the agent lock before archiving prior AgentVault credentials under the private `replacement-recovery/<uuid>/` directory and forcing enrollment. Codex login and history are retained. Existing credentials are never silently reused for this explicit command. If enrollment fails, the archive remains for deliberate operator recovery; normal restarts do not restore it automatically. After approval, stop the foreground process and install the service again. Do not copy another agent's credentials into this state directory.
+
+The shared SecureChannel currently persists new enrollment keys only after activation. A crash before approval can leave the invite consumed without recoverable local keys. Retaining `pending-invite` does not solve that gap: obtain a fresh recovery invite if the interrupted enrollment cannot resume.
+
+## Conversation and privacy boundaries
+
+Only direct messages positively attested by SecureChannel as owner 1:1 messages can dispatch a private turn. Rooms answer according to AgentVault's shared mention policy, evaluated on the typed caption, and remain silent while hushed. Recent context comes only from the addressed room. Replies are bound to the original conversation ID or room ID. Device ID, conversation kind, and conversation ID jointly select a separate persistent Codex session UUID; the bridge never resumes “last”.
+
+Each agent stores its state beneath `~/.agentvault/openai/<name-slug>/`, including isolated `home`, `codex`, `work`, `tmp`, and `sessions` directories (0700). Codex auth and local conversation transcripts persist there. Encryption protects AgentVault transport; local Codex history is plaintext and relies on the host account's filesystem protections. Do not share this directory.
+
+Codex children receive only a dedicated HOME, CODEX_HOME, TMPDIR, and a minimal PATH. The measured configuration disables shell, filesystem tools, web search, MCP/apps/plugins, delegation, and other integrations. Read-only sandboxing and approval `never` are mandatory because an unadvertised patch handler still exists. Built-in Codex system skill descriptions may appear in context, but host user skills/configuration are not inherited. Arbitrary model, provider, environment and tool configuration are intentionally unavailable.
+
+The bridge accepts only a terminal successful assistant reply after exit 0. Because the exec stream omits message phase, it additionally verifies the current turn's `final_answer` in the bounded local Codex rollout; a prior resumed turn or commentary cannot authorize delivery. Partial, failed, malformed, oversized or timed-out turns are discarded. Disconnect and shutdown invalidate pending results. One bounded queue serializes inference and awaited sending; child process groups are killed and reaped before another turn starts. Logs contain bridge-owned status codes, without prompts, replies, tokens or provider diagnostics.
+
+## Local checks
+
+```sh
+npm test
+npm run typecheck
+npm run build
+node dist/index.js --help
+npm pack --dry-run --ignore-scripts
+```
+
+Tests use disposable fixture roots, fake executables, fake encrypted channels, and injected service commands. They never run launchctl/systemctl, log into an account, contact AgentVault, or call a real provider. The build bundles the freshly built local SecureChannel artifact and checks required enrollment/sender fields.
+
+The optional real-binary gate runs only when explicitly invoked after a build:
+
+```sh
+python3 scripts/mock-provider-gate.py --codex /absolute/path/to/native/codex
+```
+
+It binds a loopback mock provider, asserts an empty tool catalog, denies hostile execution/patching, checks exact-UUID resume, rejects commentary and timeout output, and retains fixture artifacts for inspection. It never logs into an account or reaches a real provider.

package/dist/bridge.d.ts

@@ -0,0 +1,53 @@
+import type { TurnResult } from "./driver.js";
+export interface BridgeChannel {
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    off(event: string, listener: (...args: any[]) => void): unknown;
+    deviceId: string | null;
+    ownDisplayName?: string;
+    getRooms?(): Array<{
+        roomId: string;
+        members: Array<{
+            deviceId: string;
+            displayName: string;
+        }>;
+    }>;
+    getRoomHistory?(roomId: string, max: number): Array<{
+        text: string;
+        sender: string;
+    }>;
+    send(text: string, options: {
+        conversationId: string;
+    }): Promise<unknown>;
+    sendToRoom(roomId: string, text: string): Promise<unknown>;
+}
+export interface TurnDriver {
+    run(key: string, prompt: string, signal?: AbortSignal): Promise<TurnResult>;
+}
+/** Serial inference AND delivery; every queued entry owns its authenticated target. */
+export declare class OpenAIBridge {
+    private channel;
+    private driver;
+    private name;
+    private report;
+    private maxQueue;
+    private deliveryTimeoutMs;
+    private tail;
+    private pending;
+    private generation;
+    private ready;
+    private accepting;
+    private waiting;
+    private stopped;
+    private active?;
+    private hush;
+    private listeners;
+    constructor(channel: BridgeChannel, driver: TurnDriver, name: string, report?: (event: string) => void, maxQueue?: number, deliveryTimeoutMs?: number);
+    private listen;
+    private hushed;
+    private invalidate;
+    private enqueue;
+    private deliver;
+    idle(): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=bridge.d.ts.map

package/dist/cli.d.ts

@@ -0,0 +1,39 @@
+import { type Layout } from "./driver.js";
+export declare const VERSION = "0.1.0";
+export interface RunConfig {
+    name: string;
+    apiUrl: string;
+    binary: string;
+    layout: Layout;
+    inviteToken: string;
+    forceReEnroll?: boolean;
+}
+export interface CommandOptions {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    interactive?: boolean;
+}
+export interface CliDependencies {
+    env: NodeJS.ProcessEnv;
+    platform: string;
+    uid: number;
+    node: string;
+    entrypoint: string;
+    resolveBinary(): Promise<string>;
+    checkBinary(binary: string, layout: Layout): Promise<void>;
+    command(binary: string, args: string[], options?: CommandOptions): Promise<{
+        code: number;
+        stdout: string;
+    }>;
+    start(config: RunConfig): Promise<void>;
+    output(text: string): void;
+}
+export declare function agentSlug(name: string): string;
+export declare function agentStateRoot(env: NodeJS.ProcessEnv): string;
+export declare function serviceDefinition(platform: string, config: RunConfig, deps: Pick<CliDependencies, "env" | "node" | "entrypoint" | "uid">): {
+    path: string;
+    label: string;
+    contents: string;
+};
+export declare function runCli(args: string[], deps: CliDependencies): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/driver.d.ts

@@ -0,0 +1,42 @@
+export declare const SUPPORTED_CODEX_VERSION = "0.154.0";
+export declare const CODE_MODE_WARNING = "Code Mode is unavailable because code-mode host is disabled. Code mode will fail closed; enable `features.code_mode_host` and install `codex-code-mode-host`.";
+export interface Layout {
+    root: string;
+    home: string;
+    codex: string;
+    tmp: string;
+    work: string;
+    sessions: string;
+}
+export declare function createLayout(root: string): Promise<Layout>;
+export declare function atomicPrivateWrite(path: string, value: string): Promise<void>;
+export declare function childEnvironment(layout: Layout): NodeJS.ProcessEnv;
+export declare function buildInvocation(layout: Layout, sessionId?: string): {
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+};
+export declare function resolveCodex(path?: string): Promise<string>;
+export declare function checkVersion(binary: string, layout: Layout): Promise<void>;
+export interface TurnResult {
+    text: string;
+    sessionId: string;
+}
+export interface DriverOptions {
+    binary: string;
+    layout: Layout;
+    timeoutMs?: number;
+    killGraceMs?: number;
+    maxLineBytes?: number;
+    maxOutputBytes?: number;
+}
+/** One caller at a time. The bridge serializes delivery as well as inference. */
+export declare class CodexDriver {
+    private readonly options;
+    private busy;
+    private poisoned;
+    constructor(options: DriverOptions);
+    run(key: string, prompt: string, signal?: AbortSignal): Promise<TurnResult>;
+    private execute;
+}
+//# sourceMappingURL=driver.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+export { runCli } from "./cli.js";
+export { CodexDriver, buildInvocation, createLayout } from "./driver.js";
+export { OpenAIBridge } from "./bridge.js";
+export declare function main(args?: string[]): Promise<number>;
+//# sourceMappingURL=index.d.ts.map