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:
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:
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:
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. This explicit command never reuses existing credentials silently. 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. Rooms use recent messages from the addressed room; a 1:1 that starts a new Codex session is seeded with that 1:1's recent messages only. A chat opened from a browser the agent has not mapped yet may start without earlier messages until the agent learns which person it belongs to. 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.
When a reply fails
When a turn fails, the bridge records it first and then tells the chat. It does not drop a failed turn without a trace.
- In a 1:1, the owner sees one plain sentence that names the cause when the bridge can tell what it is. For example: "Aster couldn't answer this message: its OpenAI sign-in expired. Sign in again on the agent's computer." This bridge can also tell when OpenAI can't be reached and when the Codex CLI needs attention. The shared list also covers billing problems, rate limits and retired models, but this bridge does not detect those yet. When the cause is unclear, the sentence simply says the agent couldn't answer this message.
- In a room, the sentence does not name the cause, because other people and agents can read it. The room just sees that the agent couldn't answer this message.
- In both cases, the exact cause appears privately to the owner in the app under Health, Recent problems.
These failure notices are left out of the context the bridge sends to Codex on later turns.
The bridge log (agentvault-openai-bridge logs) writes one line per event:
| Log line | What it means |
|---|---|
turn_failed code=<code> exit=<n or none> | Codex did not produce a verified reply. The code is the cause the bridge assigned, and exit is the Codex exit status, or none when there is no exit status to report. A notice follows. |
reply_failed code=<code> | Codex answered, but the reply could not be delivered to the chat. |
notice_failed code=<code> | The turn failed, and the failure notice could not be delivered either. The failure is still recorded under Health. |
turn_cancelled reason=shutdown notice=<sent, failed, timeout or none> | The bridge was stopped or restarted (for example during an update) while it owed this message an answer. Nothing replays the message, so the chat gets the plain sentence "Aster couldn't answer this message." It never names a cause. notice says whether that sentence was sent. late=true marks a message that arrived while the bridge was stopping. notice=none delivered=true means the answer was already being sent and it arrived, so nothing more is posted. The bridge waits at most 10 seconds for it, so a stuck send cannot hold up the restart. Nothing is recorded under Health, because the model did not fail. |
turn_cancelled reason=<reason> | The turn was cut short on purpose, so no reply or notice is posted. Reasons: auth_failed (the agent's credentials were refused, which is how a revoked device shows up, followed by channel_state), channel_state (the encrypted channel dropped or reconnected), delivery_timeout (sending took too long), hushed (the room was hushed), device_changed (the agent's device ID changed), and unknown. |
turn_recovered code=session_resume_failed | The saved Codex session for this chat was gone, so the bridge started a fresh one and its reply passed the final-answer check. Delivery is then logged as usual. See below. |
dm_dropped reason=unmapped_conversation | A 1:1 message arrived that the agent cannot yet match to a conversation. That message got no answer and no notice yet. |
Self-restart of a saved session. Each chat keeps its own saved Codex session in the sessions directory. If that saved session can no longer be found, the bridge runs one fresh session, seeded with the recent messages of that same chat. It replaces the saved session only after the fresh reply passes the same final-answer check as any other reply. The first session it replaced is kept in a .prev file next to it, and that file is never overwritten, so a later restart cannot erase the original. If the fresh session also fails, nothing is replaced and the turn is reported as turn_failed.
The log holds only these codes and exit numbers. It never holds message text or provider error text.
Local checks
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:
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.