npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@amond-ai/harness-codex-bridge

v0.2.0

Published

The per-turn host that runs inside the sandbox image — hosts @openai/codex-sdk and serves the Worker over a WebSocket

Readme

@amond-ai/harness-codex-bridge

The per-turn host that runs inside the sandbox image: it hosts @openai/codex-sdk and serves the orchestrator over a WebSocket, appending each transcript frame to a sequence-numbered journal on disk before it sends it.

Every turn event is journaled, the text and reasoning deltas included. That is the one place this bridge differs from @amond-ai/harness-claude-code-bridge, which sends its deltas live-only: there the same text arrives again on a raw frame carrying the whole SDK message, so a delta is a duplicate. Codex emits no raw frames, so here the deltas are the transcript and a reconnect has to get them back.

Two things fall outside that, and both are the runtime's rather than this host's. An append the filesystem refuses costs that one entry on disk rather than the turn: the frame is in the in-memory log before the append is queued, so a resume against this process still replays it and only a reader that arrives after a restart misses it. And a control frame the runtime answers a socket with directly, such as a start refused because a turn is already running, never goes through the journal at all.

This package ships one artifact — dist/bridge.mjs, a Node bundle. It is not a library: the orchestrator never imports it, it execs it. The transport underneath is @amond-ai/harness-bridge-runtime and the wire schema is @amond-ai/harness-protocol's ./codex entry point.

Baking it into an image

The bundle leaves three dependencies external, so they resolve from the image's own node_modules and the SDK the turn runs on is the one the image pins:

  • @openai/codex-sdk
  • ws
  • zod
RUN npm install --global @amond-ai/harness-codex-bridge@<version> \
 && cp "$(npm root -g)/@amond-ai/harness-codex-bridge/dist/bridge.mjs" /opt/turn-host/codex-bridge.mjs
# Pin all three. Unpinned, a rebuild pairs this bundle with whatever npm calls latest.
# The versions this bundle is built against are the repository root's `sandbox-image`
# catalog (`@openai/codex-sdk`, `ws`) and its `zod` entry. `@openai/codex-sdk` depends on
# `@openai/codex`, the CLI it spawns, so pinning the SDK pins the CLI with it — there is no
# second pin to keep in step the way the Claude bridge has.
RUN npm install --prefix /opt/turn-host \
      @openai/codex-sdk@<version> ws@<version> zod@<version>

# The image build's smoke test: loads the bundle and the real SDK, prints both versions, exits 0.
RUN node /opt/turn-host/codex-bridge.mjs --version

--version is what fails the build — rather than a turn, mid-run in a sandbox — when the bundle cannot resolve its runtime dependencies.

How a turn reaches it

The host takes --workdir and --bridge-state-dir, binds the port it is told to, prints bridge-ready with that port, and gates the socket on the per-turn token. From there the orchestrator sends start, consumes frames for one bounded round, and reconnects with resume { lastSeenEventId } — the journal replays every frame after that sequence, so a dropped socket loses no transcript.

A turn ending does not end the process: stop and destroy are the ordinary way it exits, so the same host serves the next turn. stop answers with the thread id, which is also announced mid-turn on bridge-thread — a process that dies still leaves the client a thread to resume, and a later start picks it up with resumeThreadId.

What the turn runs as

Three settings are fixed rather than taken from start, and the wire schema is written around them:

  • approvalPolicy: 'never'. Load-bearing, not a default. codexTurnHostFinishSchema has no deferredToolUse because of this: a turn under this policy cannot park on a decision, so there is no deferral for an ending to name. A bridge that wants approvals needs the schema changed first.
  • sandboxMode: 'danger-full-access'. The sandbox is the isolation boundary, not the CLI. A start whose permissionMode names something narrower is refused rather than run with more access than it asked for.
  • skipGitRepoCheck: true. The workdir is whatever the orchestrator prepared.

start.tools and start.builtinToolFiltering are refused for the same reason: this host has no way to honour either, and a turn that silently ran without the tools it asked for is worse than one that did not run.

Credentials

Whatever the process's environment holds is forwarded to the CLI child, and that is the only route in — it is what the consumer's env: () => Record<string, string> thunk populated when the sandbox exec'd this bridge. CODEX_API_KEY is passed straight to the SDK as its apiKey, the credential the CLI's own configuration authenticates with; it selects no provider by itself. OPENAI_BASE_URL or start.headers are the separate provider-selection path: either one stands up a named agent_bridge_openai model provider pointed at that base URL (default https://api.openai.com/v1 when only start.headers is given, since headers can only attach to a configured provider), reading its credential from the same CODEX_API_KEY variable and, when start.headers is present, carrying it as that provider's per-request headers. With none of the three set, the CLI falls back to its own configuration. Upstream's keyring-and-auth.json subscription path is deliberately not ported — see UPSTREAM.md.

Stopping a turn

abort and interrupt pull the same lever, because the Codex SDK has only one: the AbortSignal its stream runs on. What differs is the ending. An abort is a teardown the client asked for and gets no finish; an interrupt is remembered, and the turn is reported as a finish { stopped: 'interrupted', interruptedBy: … } carrying what it produced before the stop. There is no grace period and no escalation — unlike the Claude bridge, whose query.interrupt() winds the CLI down and yields a typed result, here the abort is the escalation.

A turn that fails mid-run reports it the same way: error { phase, interruptedBy? }, with phase naming which part of the turn was running and interruptedBy set only when the failure landed during the wind-down of an interrupt. journalPath rides both finish and error flat, per codexTurnHostFinishSchema / codexTurnHostErrorSchema in @amond-ai/harness-protocol's ./codex entry point.

Upstream

A fork of Vercel's @ai-sdk/harness-codex bridge (Apache-2.0).

License

Apache-2.0 — see LICENSE.