@agentproto/adapter-codex 0.1.0-alpha.0

package/CODEX.md

@@ -0,0 +1,87 @@
+---
+name: codex
+id: codex
+description: OpenAI's Codex coding agent wrapped as an ACP server by Zed's @zed-industries/codex-acp. Spawned via `npx -y @zed-industries/codex-acp` and driven over stdio JSON-RPC. The wrapper bundles its own Codex runtime — no separate @openai/codex install required.
+version: 0.1.0
+bin: npx
+bin_args: ["-y", "@zed-industries/codex-acp"]
+install:
+  - method: npm
+    package: "@zed-industries/codex-acp"
+    global: true
+version_check:
+  cmd: npm view @zed-industries/codex-acp version
+  parse: "(\\d+\\.\\d+\\.\\d+)"
+  range: ">=0.14.0"
+  timeout_ms: 15000
+auth:
+  ref: ./SECRETS.md
+  state:
+    env: [OPENAI_API_KEY, CODEX_API_KEY]
+sandbox: ./SANDBOX.md
+protocol: acp
+acp: ./codex-acp.ACP.md
+session:
+  mode: persistent
+  idle_timeout_ms: 1800000
+  context_carryover: true
+models:
+  default: gpt-5-codex
+  allowed:
+    - gpt-5-codex
+    - gpt-5
+    - gpt-5-mini
+    - gpt-5-pro
+  env:
+    openai: OPENAI_API_KEY
+    codex: CODEX_API_KEY
+capabilities:
+  streaming: true
+  tool_calls: true
+  sub_agents: false
+  file_io: true
+  multimodal: true
+  resumable: true
+  bidirectional: true
+tags: ["codex", "openai", "acp", "agent-runtime", "coding"]
+---
+
+# Codex adapter
+
+`@agentproto/adapter-codex` wraps OpenAI's Codex coding agent as an
+AIP-45 agent CLI by spawning **`@zed-industries/codex-acp`** — a
+Rust-based ACP wrapper published by Zed Industries that bundles its
+own Codex runtime.
+
+## Why the Zed wrapper
+
+OpenAI's `@openai/codex` CLI does not expose an ACP mode. The Zed
+wrapper provides a stable stdio JSON-RPC bridge with full ACP session
+lifecycle support (newSession / loadSession / resumeSession), slash
+commands, ACP `AvailableCommands` updates, and read-only / auto /
+full-access session modes.
+
+## Install
+
+```bash
+# npm (global) — recommended for fast spawn
+npm install -g @zed-industries/codex-acp
+
+# or rely on the npx form (no manual install)
+npx -y @zed-industries/codex-acp
+```
+
+The wrapper ships platform-specific native binaries via npm optional
+dependencies — no separate `@openai/codex` install is required.
+
+## Auth
+
+Codex authenticates one of three ways:
+
+| Mechanism      | How                                                       |
+|----------------|-----------------------------------------------------------|
+| ChatGPT login  | Use the existing paid ChatGPT subscription via OAuth      |
+| API key        | `CODEX_API_KEY=sk-…`                                      |
+| Fallback       | `OPENAI_API_KEY=sk-…`                                     |
+
+For headless / sandboxed spawns, prefer `OPENAI_API_KEY`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentproto contributors
+
+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/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { AgentCliHandle, AgentCliRuntime } from '@agentproto/driver-agent-cli';
+export { AgentCliHandle, AgentCliRuntime } from '@agentproto/driver-agent-cli';
+
+/**
+ * @agentproto/adapter-codex — AIP-45 adapter for OpenAI Codex via the
+ * Zed-published ACP wrapper @zed-industries/codex-acp.
+ *
+ * The wrapper bundles its own Codex runtime (Rust binary delivered via
+ * npm optional deps) so a single `npx -y @zed-industries/codex-acp`
+ * invocation is enough — no separate @openai/codex install needed.
+ *
+ *   import { codex, codexRuntime } from "@agentproto/adapter-codex"
+ *   const session = await codexRuntime().start({
+ *     env: { OPENAI_API_KEY: "sk-..." },
+ *   })
+ *   for await (const evt of session.send({ role: "user", content: "..." })) {
+ *     console.log(evt)
+ *   }
+ *   await session.close()
+ */
+
+declare const codex: AgentCliHandle;
+declare function codexRuntime(): AgentCliRuntime;
+
+export { codex, codexRuntime };

package/dist/index.mjs

@@ -0,0 +1,100 @@
+import { defineAgentCli, createAgentCliRuntime } from '@agentproto/driver-agent-cli';
+
+/**
+ * @agentproto/adapter-codex v0.1.0-alpha
+ * AIP-45 adapter for OpenAI Codex via @zed-industries/codex-acp.
+ */
+
+var codex = defineAgentCli({
+  name: "codex",
+  id: "codex",
+  description: "OpenAI's Codex coding agent wrapped as an ACP server by Zed's @zed-industries/codex-acp. Spawned via `npx -y @zed-industries/codex-acp` and driven over stdio JSON-RPC. The wrapper bundles its own Codex runtime \u2014 no separate @openai/codex install required.",
+  version: "0.1.0",
+  bin: "npx",
+  bin_args: ["-y", "@zed-industries/codex-acp"],
+  install: [
+    {
+      method: "npm",
+      package: "@zed-industries/codex-acp",
+      global: true
+    }
+  ],
+  version_check: {
+    cmd: "npm view @zed-industries/codex-acp version",
+    parse: "(\\d+\\.\\d+\\.\\d+)",
+    range: ">=0.14.0",
+    timeout_ms: 15e3
+  },
+  auth: {
+    ref: "./SECRETS.md",
+    state: { env: ["OPENAI_API_KEY", "CODEX_API_KEY"] }
+  },
+  sandbox: "./SANDBOX.md",
+  protocol: "acp",
+  acp: "./codex-acp.ACP.md",
+  session: {
+    mode: "persistent",
+    idle_timeout_ms: 18e5,
+    context_carryover: true
+  },
+  models: {
+    default: "gpt-5-codex",
+    allowed: ["gpt-5-codex", "gpt-5", "gpt-5-mini", "gpt-5-pro"],
+    env: { openai: "OPENAI_API_KEY", codex: "CODEX_API_KEY" }
+  },
+  capabilities: {
+    streaming: true,
+    tool_calls: true,
+    sub_agents: false,
+    file_io: true,
+    // The Zed wrapper forwards ACP image content blocks to Codex which
+    // runs them through the underlying GPT-5 vision pipeline.
+    multimodal: true,
+    // codex-acp implements full ACP session lifecycle (newSession /
+    // loadSession / resumeSession). Pair with the `native-resume`
+    // continuation strategy for cold-start reattach.
+    resumable: true,
+    bidirectional: true
+  },
+  modes: [
+    {
+      id: "default",
+      description: "Auto mode (default) \u2014 Codex executes file edits and shell commands with per-tool prompts."
+    },
+    {
+      id: "read-only",
+      description: "Read-only mode \u2014 Codex inspects but does not edit or run commands.",
+      bin_args_append: ["--mode", "read-only"]
+    },
+    {
+      id: "full-access",
+      description: "Full-access mode \u2014 auto-approve all file/shell operations. Use only in trusted sandboxes.",
+      bin_args_append: ["--mode", "full-access"]
+    }
+  ],
+  options: [
+    {
+      id: "model",
+      type: "enum",
+      enum: ["gpt-5-codex", "gpt-5", "gpt-5-mini", "gpt-5-pro"],
+      description: "Override the default model for this operator binding.",
+      bin_args_template: ["--model", "{value}"]
+    }
+  ],
+  continuation: {
+    default: "native-resume",
+    supported: ["native-resume", "pinned-session", "transcript", "none"],
+    pinned_session: {
+      idle_timeout_ms: 18e5,
+      key_scope: ["conversation", "operator"]
+    }
+  },
+  tags: ["codex", "openai", "acp", "agent-runtime", "coding"]
+});
+function codexRuntime() {
+  return createAgentCliRuntime(codex);
+}
+
+export { codex, codexRuntime };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * @agentproto/adapter-codex — AIP-45 adapter for OpenAI Codex via the\n * Zed-published ACP wrapper @zed-industries/codex-acp.\n *\n * The wrapper bundles its own Codex runtime (Rust binary delivered via\n * npm optional deps) so a single `npx -y @zed-industries/codex-acp`\n * invocation is enough — no separate @openai/codex install needed.\n *\n *   import { codex, codexRuntime } from \"@agentproto/adapter-codex\"\n *   const session = await codexRuntime().start({\n *     env: { OPENAI_API_KEY: \"sk-...\" },\n *   })\n *   for await (const evt of session.send({ role: \"user\", content: \"...\" })) {\n *     console.log(evt)\n *   }\n *   await session.close()\n */\n\nimport {\n  createAgentCliRuntime,\n  defineAgentCli,\n  type AgentCliHandle,\n  type AgentCliRuntime,\n} from \"@agentproto/driver-agent-cli\"\n\nexport const codex: AgentCliHandle = defineAgentCli({\n  name: \"codex\",\n  id: \"codex\",\n  description:\n    \"OpenAI's Codex coding agent wrapped as an ACP server by Zed's @zed-industries/codex-acp. Spawned via `npx -y @zed-industries/codex-acp` and driven over stdio JSON-RPC. The wrapper bundles its own Codex runtime — no separate @openai/codex install required.\",\n  version: \"0.1.0\",\n  bin: \"npx\",\n  bin_args: [\"-y\", \"@zed-industries/codex-acp\"],\n  install: [\n    {\n      method: \"npm\",\n      package: \"@zed-industries/codex-acp\",\n      global: true,\n    },\n  ],\n  version_check: {\n    cmd: \"npm view @zed-industries/codex-acp version\",\n    parse: \"(\\\\d+\\\\.\\\\d+\\\\.\\\\d+)\",\n    range: \">=0.14.0\",\n    timeout_ms: 15_000,\n  },\n  auth: {\n    ref: \"./SECRETS.md\",\n    state: { env: [\"OPENAI_API_KEY\", \"CODEX_API_KEY\"] },\n  },\n  sandbox: \"./SANDBOX.md\",\n  protocol: \"acp\",\n  acp: \"./codex-acp.ACP.md\",\n  session: {\n    mode: \"persistent\",\n    idle_timeout_ms: 1_800_000,\n    context_carryover: true,\n  },\n  models: {\n    default: \"gpt-5-codex\",\n    allowed: [\"gpt-5-codex\", \"gpt-5\", \"gpt-5-mini\", \"gpt-5-pro\"],\n    env: { openai: \"OPENAI_API_KEY\", codex: \"CODEX_API_KEY\" },\n  },\n  capabilities: {\n    streaming: true,\n    tool_calls: true,\n    sub_agents: false,\n    file_io: true,\n    // The Zed wrapper forwards ACP image content blocks to Codex which\n    // runs them through the underlying GPT-5 vision pipeline.\n    multimodal: true,\n    // codex-acp implements full ACP session lifecycle (newSession /\n    // loadSession / resumeSession). Pair with the `native-resume`\n    // continuation strategy for cold-start reattach.\n    resumable: true,\n    bidirectional: true,\n  },\n  modes: [\n    {\n      id: \"default\",\n      description:\n        \"Auto mode (default) — Codex executes file edits and shell commands with per-tool prompts.\",\n    },\n    {\n      id: \"read-only\",\n      description:\n        \"Read-only mode — Codex inspects but does not edit or run commands.\",\n      bin_args_append: [\"--mode\", \"read-only\"],\n    },\n    {\n      id: \"full-access\",\n      description:\n        \"Full-access mode — auto-approve all file/shell operations. Use only in trusted sandboxes.\",\n      bin_args_append: [\"--mode\", \"full-access\"],\n    },\n  ],\n  options: [\n    {\n      id: \"model\",\n      type: \"enum\",\n      enum: [\"gpt-5-codex\", \"gpt-5\", \"gpt-5-mini\", \"gpt-5-pro\"],\n      description: \"Override the default model for this operator binding.\",\n      bin_args_template: [\"--model\", \"{value}\"],\n    },\n  ],\n  continuation: {\n    default: \"native-resume\",\n    supported: [\"native-resume\", \"pinned-session\", \"transcript\", \"none\"],\n    pinned_session: {\n      idle_timeout_ms: 1_800_000,\n      key_scope: [\"conversation\", \"operator\"],\n    },\n  },\n  tags: [\"codex\", \"openai\", \"acp\", \"agent-runtime\", \"coding\"],\n})\n\nexport function codexRuntime(): AgentCliRuntime {\n  return createAgentCliRuntime(codex)\n}\n\nexport type { AgentCliHandle, AgentCliRuntime }\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@agentproto/adapter-codex",
+  "version": "0.1.0-alpha.0",
+  "description": "@agentproto/adapter-codex — AIP-45 AGENT-CLI adapter for OpenAI's Codex CLI via @zed-industries/codex-acp. Spawns the ACP wrapper over stdio JSON-RPC.",
+  "keywords": [
+    "agentproto",
+    "aip-45",
+    "codex",
+    "openai",
+    "acp",
+    "agent-cli",
+    "adapter"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-45",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "adapters/codex"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./CODEX.md": "./CODEX.md",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "CODEX.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentproto/driver-agent-cli": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}