# codex-app-server-bridge

`codex-app-server-bridge` lets stock `codex-acp` use an already-running Codex
App Server. It adapts the child-process transport expected by `codex-acp`
(newline-delimited messages on stdio) to the App Server WebSocket transport
(one text frame per message).

The bridge is deliberately only a transport adapter. It does not discover,
start, stop, restart, supervise, or reconnect to a Codex App Server, and it
never falls back to a private server.

## Prerequisites

- Node.js 24 or newer. Release packaging compiles the TypeScript source to ESM
  JavaScript; the installed executable runs only that build output.
- A separately managed Codex App Server listening on an accepted loopback URL.
- Stock `codex-acp`. Version 1.6.2 was used for the 0.1.0 validation.

The 0.1.0 release was validated with Node.js 24.19.0, `codex-acp` 1.6.2, and
Codex CLI 0.149.0.

## Invocation and environment

The executable accepts exactly one command:

```sh
codex-app-server-bridge app-server
```

Configure `codex-acp` with both of these environment variables:

```sh
CODEX_PATH=/absolute/path/to/codex-app-server-bridge
CODEX_APP_SERVER_URL=ws://127.0.0.1:4500
```

`CODEX_PATH` tells `codex-acp` which executable to invoke with `app-server`.
`CODEX_APP_SERVER_URL` is required by the bridge and must be a root-path URL in
exactly one of these forms, with an explicit port from 1 through 65535:

```text
ws://127.0.0.1:<port>
ws://[::1]:<port>
```

`localhost`, non-loopback addresses, credentials, TLS, paths, query strings,
and fragments are rejected before a socket is opened. If the configured shared
server is absent, the bridge exits nonzero within the five-second startup
deadline. It does not start another server.

Each bridge process creates at most one WebSocket connection and never
reconnects. Blank input records are ignored. Other records and server text
frames are relayed in order without parsing their JSON-RPC content. Binary
frames are rejected. Normal relay is silent on stderr, and failure diagnostics
never include JSON-RPC payloads.

Stdin EOF, `SIGINT`, and `SIGTERM` close only the bridge connection and exit
successfully. They do not stop or otherwise manage the shared App Server.

## Authentication scope

Authentication belongs to the shared App Server, not to the bridge. Requests
such as `account/logout` are forwarded unchanged. Logging out through any
connected client therefore logs out the shared server and affects every client
using that server.

## Install from an immutable Git revision

The canonical repository is
`https://git.bodicsek.host/bodicsek/codex-app-server-bridge.git`. Git access and
any required trust or authentication configuration are host prerequisites;
keep credentials out of package URLs and command output. Preflight the exact
release tag before installation:

```sh
git ls-remote --exit-code \
  https://git.bodicsek.host/bodicsek/codex-app-server-bridge.git \
  refs/tags/v0.1.1
```

Install only an immutable release tag or full 40-character commit. Do not use
`#main` for a reproducible installation. The repository contains the compiled
runtime, so lifecycle scripts are disabled and no TypeScript toolchain is
needed on the consumer machine:

```sh
npm run verify:git-package -- \
  'git+https://git.bodicsek.host/bodicsek/codex-app-server-bridge.git#v0.1.1'
npm install --global \
  --ignore-scripts \
  --cache /private/tmp/codex-app-server-bridge-npm-cache \
  'git+https://git.bodicsek.host/bodicsek/codex-app-server-bridge.git#v0.1.1'
command -v codex-app-server-bridge
npm list --global --depth=0 codex-app-server-bridge
codex-app-server-bridge --unsupported
```

For a commit pin, replace `v0.1.1` in both commands with the full commit
reported by `git ls-remote`; abbreviated commits and branches are rejected by
the verifier. The verifier uses a temporary global prefix and never contacts a
Codex App Server. The end-user install intentionally omits `--prefix` so the
executable is placed on the normal global PATH used to launch Emacs.

Installing `v0.1.1` upgrades the existing `0.1.0` local-tarball installation
in place. The package name, executable, and `CODEX_PATH` value do not change.
Existing bridge processes continue using the version with which they started;
new agent-shell launches discover the replacement PATH executable.

To roll back, reinstall the verified `0.1.0` tarball or a previously verified
immutable Git revision:

```sh
npm install --global \
  --ignore-scripts \
  --cache /private/tmp/codex-app-server-bridge-npm-cache \
  /Users/dnabracz/Work/packages/codex-app-server-bridge-0.1.0.tgz
npm install --global \
  --ignore-scripts \
  --cache /private/tmp/codex-app-server-bridge-npm-cache \
  'git+https://git.bodicsek.host/bodicsek/codex-app-server-bridge.git#v0.1.1'
```

Remove the globally installed package without changing Emacs configuration:

```sh
npm uninstall --global codex-app-server-bridge
```

## Build and verify a local npm package

No registry publication is used. The package remains private. Maintainers use
the explicit `pack:verified` workflow, which compiles, tests, checks committed
runtime freshness, and invokes `npm pack --ignore-scripts`. A raw `npm pack`
does not run those release gates.

```sh
mkdir -p /Users/dnabracz/Work/packages
npm run pack:verified -- \
  --pack-destination /Users/dnabracz/Work/packages \
  --cache /private/tmp/codex-app-server-bridge-npm-cache
npm run verify:package -- \
  /Users/dnabracz/Work/packages/codex-app-server-bridge-0.1.1.tgz
```

The artifact contains only package metadata, `README.md`, `LICENSE`, the
launcher under `bin/`, and the two compiled runtime files under `dist/`.
TypeScript source, tests, credentials, caches, and local artifacts are
excluded. The verifier installs the tarball in a temporary prefix and exercises
the installed launcher without connecting to the shared App Server.

## Development

```sh
npm ci
npm run typecheck
npm run compile
npm test
npm run verify:runtime
```

Tests use only `node:test` and a loopback WebSocket peer built from Node core
APIs. They do not require Codex, credentials, or external network access. When
source changes, commit the matching `dist/cli.js` and `dist/config.js` output;
`npm run verify:runtime` fails when those files are stale.