@filepad/a2a-codex-bridge

Local A2A v1 bridge that lets Filepad delegate work to OpenAI Codex.

This is not MCP. MCP lets Codex call Filepad tools. This bridge lets FilepadAI send an A2A task to a local Codex runtime and receive a task result back.

Install

npm install -g @filepad/a2a-codex-bridge

Or run directly:

npx -y @filepad/a2a-codex-bridge@latest serve --code fp_bridge_... --base-url https://api.filepad.ai

Local development

pnpm -C packages/a2a-codex-bridge build
pnpm -C packages/a2a-codex-bridge test
pnpm -C packages/a2a-codex-bridge exec filepad-a2a-codex-bridge serve --port 4218 --cwd /path/to/repo

The bridge exposes:

• GET /.well-known/agent-card.json
• GET /health
• POST /a2a

The Agent Card advertises A2A v1 through supportedInterfaces[]:

{
  "supportedInterfaces": [
    {
      "url": "http://127.0.0.1:4218/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0.0"
    }
  ]
}

Commands

filepad-a2a-codex-bridge serve \
  --code fp_bridge_... \
  --base-url https://api.filepad.ai \
  --host 127.0.0.1 \
  --port 4218 \
  --public-url http://127.0.0.1:4218 \
  --cwd /path/to/repo \
  --codex-command codex \
  --timeout-ms 600000

--public-url is the URL Filepad should put in the Agent Card and call for /a2a. For pure local development this can be http://127.0.0.1:4218. For cloud Filepad to reach a local bridge, place the bridge behind a deliberate tunnel or relay and use that public URL.

A2A methods

Implemented now:

• SendMessage
• GetTask
• ListTasks
• CancelTask

SubscribeToTask intentionally returns a JSON-RPC method error until streaming is implemented. The Agent Card advertises streaming: false.

Codex execution

The first implementation uses the official Codex CLI shape:

codex exec "<delegated task text>"

The code is structured around a CodexExecutor interface so a future release can add @openai/codex-sdk execution without changing the A2A server surface.