@hua-labs/tap 0.1.1 → 0.2.1

package/README.md

@@ -1,223 +1,194 @@
-# tap
+# @hua-labs/tap
 
-[![npm version](https://img.shields.io/npm/v/@hua-labs/tap.svg)](https://www.npmjs.com/package/@hua-labs/tap)
-[![license](https://img.shields.io/npm/l/@hua-labs/tap.svg)](LICENSE)
+Zero-dependency CLI for cross-model AI agent communication setup.
 
-> Your AI sessions can already work in parallel. tap gives them a shared protocol.
->
-> Sessions end. Systems grow.
+One command to connect Claude, Codex, and Gemini agents through a shared file-based communication layer.
 
-**A local-first, cross-model orchestration protocol for AI coding agents.**
-
-Run multiple AI agents (Claude, Codex, Gemini) on the same codebase — in parallel.
-
----
-
-## What you can do with tap
-
-- Run multiple AI agents in parallel on one repo
-- Split work into independent tasks with isolated worktrees
-- Communicate between Claude, Codex, and Gemini sessions
-- Review code across models (Codex reviews Claude's code, and vice versa)
-- Keep all communication and history in git
-- Continue work across sessions and machines — nothing is lost
-
----
-
-## Why tap?
-
-Because using one AI at a time is slow.
-
-You already have Claude Code, Codex, Gemini CLI. They're powerful alone. But they can't see each other. tap connects them — through files, not proxies.
-
-- **No server.** Messages are markdown files in a git repo.
-- **No vendor lock-in.** Works with any model that can read/write files.
-- **No lost context.** Everything persists in git — messages, reviews, findings, retros.
-- **No TOS violations.** Only official interfaces — MCP, App Server WebSocket, fs.watch.
-
----
+## Quick Start
 
-## Install
+> `bun` is required to run the managed tap MCP server. When installed from npm, `@hua-labs/tap` now ships its own bundled MCP server entry.
 
 ```bash
+# 1. Initialize comms directory and state
 npx @hua-labs/tap init
-```
 
-One command. Sets up comms directory, config, and MCP server entry. Works on Windows, macOS, and Linux.
+# 2. Add runtimes
+npx @hua-labs/tap add claude
+npx @hua-labs/tap add codex
+npx @hua-labs/tap add gemini
 
----
-
-## How It Works
-
-```
-tap (protocol)  -->  bridge (delivery)  -->  agent (execution)
-git (memory)    <--  human (governance)  <--  tower (decision)
+# 3. Check status
+npx @hua-labs/tap status
 ```
 
-No central server. The file system is the message bus — git is the transport and history.
+Your agents can now communicate through the shared comms directory.
 
-Messages are plain markdown files: `inbox/YYYYMMDD-{from}-{to}-{subject}.md`
+## Commands
 
-**Delivery modes:**
-- **Claude**: MCP channel push — real-time
-- **Codex**: App Server WebSocket bridge — real-time
-- **Gemini**: File-watch notification — experimental
+### `init`
 
-**Cross-device?** Point both machines at the same git repo. Done.
+Initialize the comms directory and `.tap-comms/` state.
 
----
-
-## Quick Start
-
-### 1. Two agents talking
+By default, the comms directory is created inside the current repo at `./tap-comms`.
 
 ```bash
-# Terminal 1 — Agent A
 npx @hua-labs/tap init
-claude --dangerously-load-development-channels server:tap-comms
-# Inside Claude: tap_set_name("agent-a")
-# Inside Claude: tap_reply(to: "agent-b", subject: "hello", content: "can you see this?")
-
-# Terminal 2 — Agent B
-cd same-repo
-claude
-# Inside Claude: tap_set_name("agent-b")
-# Inside Claude: tap_list_unread()
+npx @hua-labs/tap init --comms-dir /path/to/comms
+npx @hua-labs/tap init --permissions safe    # default: deny destructive ops
+npx @hua-labs/tap init --permissions full    # no restrictions (use with caution)
+npx @hua-labs/tap init --force               # re-initialize
 ```
 
-That's it. Two Claude sessions, talking through files. You should see messages appear in the other session instantly.
+### `add <runtime>`
 
-### 2. Parallel work with worktrees
+Add a runtime. Probes config, plans patches, applies, and verifies.
 
 ```bash
-# Set up isolated workspaces
-npx @hua-labs/tap init-worktree --path ../wt-1 --branch feat/auth
-npx @hua-labs/tap init-worktree --path ../wt-2 --branch feat/dashboard
-
-# Each agent works in its own worktree — no git conflicts
+npx @hua-labs/tap add claude
+npx @hua-labs/tap add codex
+npx @hua-labs/tap add gemini
+npx @hua-labs/tap add claude --force   # re-install
 ```
 
-### 3. Add Codex to the team
+### `remove <runtime>`
 
-```bash
-# Register and start bridge
-npx @hua-labs/tap add codex --name reviewer --port 4501
-npx @hua-labs/tap bridge start codex-reviewer --agent-name reviewer
+Remove a runtime and rollback config changes.
 
-# You can now send a message from Claude and see it appear in Codex in real time.
+```bash
+npx @hua-labs/tap remove claude
+npx @hua-labs/tap remove codex
 ```
 
----
-
-## CLI Commands
+### `status`
 
-| Command | Description |
-|---------|-------------|
-| `tap init` | Initialize tap in a project |
-| `tap init-worktree` | Bootstrap a git worktree with deps, permissions, MCP config |
-| `tap add <runtime>` | Register a runtime (codex, gemini) |
-| `tap remove <runtime>` | Remove a registered runtime |
-| `tap bridge start` | Start real-time bridge for a runtime |
-| `tap bridge stop` | Stop a running bridge |
-| `tap bridge status` | Show bridge health and heartbeat |
-| `tap status` | Show registered runtimes and instances |
-| `tap dashboard` | Unified ops view — agents, bridges, PRs |
-| `tap serve` | Start MCP server for development |
+Show installed runtimes and their status.
 
-All commands support `--json` for automation.
+```bash
+npx @hua-labs/tap status
+```
 
----
+Output shows three status levels:
 
-## Advanced Features
+- **installed** — config written but not verified
+- **configured** — config written and verified
+- **active** — runtime is running and connected
 
-### Multi-Instance Bridge
+### `serve`
 
-Run multiple agents on the same runtime:
+Start the tap-comms MCP server (stdio). Convenience command for running the MCP server locally.
 
 ```bash
-npx @hua-labs/tap add codex --name reviewer --port 4501
-npx @hua-labs/tap add codex --name builder --port 4502
+npx @hua-labs/tap serve
+npx @hua-labs/tap serve --comms-dir /path/to/comms
 ```
 
-Each instance gets its own PID, state directory, and heartbeat.
+Requires `bun`. Uses the bundled MCP server entry from `@hua-labs/tap`, with a repo-local fallback for monorepo checkouts.
+
+## Supported Runtimes
+
+| Runtime | Config                  | Bridge                 | Mode               |
+| ------- | ----------------------- | ---------------------- | ------------------ |
+| Claude  | `.mcp.json`             | native-push (fs.watch) | No daemon needed   |
+| Codex   | `~/.codex/config.toml`  | WebSocket bridge       | Daemon per session |
+| Gemini  | `.gemini/settings.json` | polling                | No daemon needed   |
 
-### Headless Reviewer
+## `--json` Flag
 
-Run Codex as a background review daemon — no TUI:
+All commands support `--json` for machine-readable output. Returns a single JSON object to stdout with no human log noise.
 
 ```bash
-npx @hua-labs/tap bridge start codex --headless --role reviewer --agent-name my-reviewer
+npx @hua-labs/tap status --json
 ```
 
-Auto-polls inbox for review requests. Terminates based on configurable conditions (round cap, quality threshold, repetition detection).
+```json
+{
+  "ok": true,
+  "command": "status",
+  "code": "TAP_STATUS_OK",
+  "message": "2 runtime(s) installed",
+  "warnings": [],
+  "data": {
+    "version": "0.2.0",
+    "commsDir": "/path/to/comms",
+    "runtimes": {
+      "claude": { "status": "active", "bridgeMode": "native-push" },
+      "codex": { "status": "configured", "bridgeMode": "app-server" }
+    }
+  }
+}
+```
 
-### Ops Dashboard
+Error codes use `TAP_*` prefix: `TAP_ADD_OK`, `TAP_NO_OP`, `TAP_PATCH_FAILED`, etc.
 
-```bash
-npx @hua-labs/tap dashboard
-```
+Exit codes: `0` = ok, `1` = error.
 
-Agents, bridges, and PR status in one screen. `--watch` for live updates.
+## Permissions
 
-### Config System
+`tap init` auto-configures runtime permissions.
 
-Two-layer config for portability:
+### Safe mode (default)
 
-- `tap-config.json` — shared, git-tracked
-- `tap-config.local.json` — machine-specific, gitignored
+**Claude**: Adds deny rules to `.claude/settings.local.json` blocking destructive operations (force push, hard reset, rm -rf, etc.).
 
-Automatic runtime resolution: `.node-version` + fnm probing + tsx fallback.
+**Codex**: Sets `workspace-write` sandbox, `full` network access, trusted project paths, and writable roots in `~/.codex/config.toml`.
 
-### Generational Knowledge Transfer
+### Full mode
 
-Agents are stateless — sessions end, context is lost. tap solves this with files:
+```bash
+npx @hua-labs/tap init --permissions full
+```
 
-- **Retros** — what worked, what didn't
-- **Handoffs** — context for the next session
-- **Findings** — discoveries that become backlog items
-- **Letters** — agent-to-agent or agent-to-human messages
+**Claude**: Removes tap-managed deny rules. User-added rules preserved.
 
-Used across multiple sessions ("generations") where each session builds on previous findings and handoffs.
+**Codex**: Sets `danger-full-access` sandbox. Use on trusted local machines only.
 
----
+## How It Works
 
-## Results
+Agents communicate through a shared directory (`comms/`) using markdown files:
 
-Used in production multi-session workflows:
+```
+comms/
+├── inbox/          # Agent-to-agent messages
+├── reviews/        # Code review results
+├── findings/       # Out-of-scope discoveries
+├── handoff/        # Session handoff documents
+├── retros/         # Retrospectives
+└── archive/        # Archived messages
+```
 
-| Metric | Value |
-|--------|-------|
-| Generations | 11 |
-| Agents | 50+ |
-| Models | Claude + Codex + Gemini |
-| PRs merged | 55+ |
-| Platforms | Windows + macOS + Linux |
+Each runtime has an adapter that:
 
----
+1. **Probes** — finds config files, checks runtime installation
+2. **Plans** — determines what patches to apply
+3. **Applies** — backs up and patches config files
+4. **Verifies** — confirms the runtime can read the config
 
-## Docs
+The adapter contract (`RuntimeAdapter`) is the extension point for adding new runtimes.
 
-| Document | Description |
-|----------|-------------|
-| [ARCHITECTURE.md](ARCHITECTURE.md) | Design decisions, data model, delivery modes |
-| [CHANGELOG.md](CHANGELOG.md) | Version history |
-| [Protocol Rules](docs/) | Rules for agent coordination |
-| [Cross-Platform Strategy](docs/cross-platform-strategy.md) | Windows, macOS, Linux support |
-| [Codex Bridge Deep Dive](docs/codex-app-server-bridge.md) | WebSocket injection details |
-| [Multi-Device Hub](docs/MULTI-DEVICE-HUB.md) | Cross-device via git sync |
+## Changelog (0.2.0)
 
----
+### Bridge
 
-## Contributing
+- **Auth gateway** — Managed bridge now includes an auth proxy with timing-safe token validation (M99)
+- **`--no-auth` flag** — Skip auth gateway for localhost-only setups; app-server listens directly on public port (M102)
+- **TUI connect URL** — `bridge start` and `bridge status` output shows where to connect Codex TUI (M102)
+- **Identity routing** — Bridge matches inbox messages by both `agentId` and `agentName`; self echo-back filtered by both (M101)
+- **Display labels** — Bridge prompts, `tap_who`, and notifications use `name [id]` format (M101)
 
-Built by [HUA Labs](https://github.com/HUA-Labs). Issues and PRs welcome.
+### CLI
 
-The best way to contribute? Use tap, run a generation, and submit your retro as a PR.
+- **`tap doctor`** — Diagnose comms, bridge, message, and MCP issues (M95)
+- **`tap doctor --fix`** — Auto-fix common issues with post-fix revalidation (M100)
+- **Error codes** — 24 CLI error codes with consistent `TAP_*` prefix (M91)
+- **Boot streamline** — Faster CLI startup with agent-name persistence (M92)
 
----
+### Infrastructure
 
-*Built by Claude (Anthropic) + Codex (OpenAI) + Gemini (Google) + Devin (human).*
+- **Auto-poll fallback** — Bridge falls back to polling when fs.watch is unavailable (M93)
+- **Watcher dedup** — Root-cause fix for duplicate message dispatch (M90)
+- **tap-plugin test infra** — In-memory test harness for MCP channel tests (M94)
+- **Blind test CI** — Cross-model communication verification framework (M98)
 
-*"Sessions end. Systems grow."*
+## License
 
-**MIT License** — HUA Labs
+MIT

package/dist/bridges/codex-app-server-auth-gateway.d.mts

@@ -0,0 +1,8 @@
+interface GatewayOptions {
+    listenUrl: string;
+    upstreamUrl: string;
+    token: string;
+}
+declare function buildGatewayOptions(argv: string[]): GatewayOptions;
+
+export { buildGatewayOptions };

package/dist/bridges/codex-app-server-auth-gateway.mjs

@@ -0,0 +1,183 @@
+// src/bridges/codex-app-server-auth-gateway.ts
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import { pathToFileURL } from "url";
+import { timingSafeEqual } from "crypto";
+import { WebSocket, WebSocketServer } from "ws";
+var AUTH_QUERY_PARAM = "tap_token";
+var CLOSE_UNAUTHORIZED = 4401;
+var CLOSE_UPSTREAM_ERROR = 1013;
+function normalizeUrl(value) {
+  return value.replace(/\/$/, "");
+}
+function closeSocket(socket, code, reason) {
+  if (socket.readyState === WebSocket.CLOSING || socket.readyState === WebSocket.CLOSED) {
+    return;
+  }
+  try {
+    socket.close(code, reason);
+  } catch {
+  }
+}
+function readFlagValue(argv, index, flag) {
+  const current = argv[index] ?? "";
+  const eqIndex = current.indexOf("=");
+  if (eqIndex >= 0) {
+    return current.slice(eqIndex + 1);
+  }
+  const next = argv[index + 1];
+  if (!next || next.startsWith("--")) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return next;
+}
+function buildGatewayOptions(argv) {
+  let listenUrl = process.env.TAP_GATEWAY_LISTEN_URL?.trim() || "";
+  let upstreamUrl = process.env.TAP_GATEWAY_UPSTREAM_URL?.trim() || "";
+  let tokenFile = process.env.TAP_GATEWAY_TOKEN_FILE?.trim() || "";
+  let token = process.env.TAP_GATEWAY_TOKEN?.trim() || "";
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index] ?? "";
+    const consumesNext = !flag.includes("=");
+    if (flag.startsWith("--listen-url")) {
+      listenUrl = readFlagValue(argv, index, "--listen-url").trim();
+      if (consumesNext) index += 1;
+      continue;
+    }
+    if (flag.startsWith("--upstream-url")) {
+      upstreamUrl = readFlagValue(argv, index, "--upstream-url").trim();
+      if (consumesNext) index += 1;
+      continue;
+    }
+    if (flag.startsWith("--token")) {
+      token = readFlagValue(argv, index, "--token").trim();
+      if (consumesNext) index += 1;
+      continue;
+    }
+    if (flag.startsWith("--token-file")) {
+      tokenFile = readFlagValue(argv, index, "--token-file").trim();
+      if (consumesNext) index += 1;
+      continue;
+    }
+  }
+  if (tokenFile) {
+    token = readFileSync(tokenFile, "utf8").trim();
+  }
+  if (!listenUrl) {
+    throw new Error("Missing gateway listen URL");
+  }
+  if (!upstreamUrl) {
+    throw new Error("Missing gateway upstream URL");
+  }
+  if (!token) {
+    throw new Error("Missing gateway auth token");
+  }
+  const listen = new URL(listenUrl);
+  const upstream = new URL(upstreamUrl);
+  if (!/^wss?:$/.test(listen.protocol)) {
+    throw new Error(`Unsupported gateway listen protocol: ${listen.protocol}`);
+  }
+  if (!/^wss?:$/.test(upstream.protocol)) {
+    throw new Error(
+      `Unsupported gateway upstream protocol: ${upstream.protocol}`
+    );
+  }
+  return {
+    listenUrl: normalizeUrl(listen.toString()),
+    upstreamUrl: normalizeUrl(upstream.toString()),
+    token
+  };
+}
+function tokensMatch(presentedToken, expectedToken) {
+  if (!presentedToken) {
+    return false;
+  }
+  const presented = Buffer.from(presentedToken, "utf8");
+  const expected = Buffer.from(expectedToken, "utf8");
+  if (presented.length !== expected.length) {
+    return false;
+  }
+  return timingSafeEqual(presented, expected);
+}
+async function main() {
+  const options = buildGatewayOptions(process.argv.slice(2));
+  const listen = new URL(options.listenUrl);
+  const host = listen.hostname === "localhost" ? "127.0.0.1" : listen.hostname;
+  const port = Number.parseInt(listen.port, 10);
+  if (!Number.isFinite(port) || port <= 0) {
+    throw new Error(`Gateway listen URL must include a valid port: ${options.listenUrl}`);
+  }
+  const server = new WebSocketServer({
+    host,
+    port,
+    path: listen.pathname === "/" ? void 0 : listen.pathname,
+    perMessageDeflate: false
+  });
+  server.on("connection", (client, request) => {
+    const requestUrl = new URL(request.url ?? "/", options.listenUrl);
+    const presentedToken = requestUrl.searchParams.get(AUTH_QUERY_PARAM);
+    if (!tokensMatch(presentedToken, options.token)) {
+      closeSocket(client, CLOSE_UNAUTHORIZED, "Unauthorized");
+      return;
+    }
+    const upstream = new WebSocket(options.upstreamUrl, {
+      perMessageDeflate: false
+    });
+    upstream.on("message", (data, isBinary) => {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(data, { binary: isBinary });
+      }
+    });
+    client.on("message", (data, isBinary) => {
+      if (upstream.readyState === WebSocket.OPEN) {
+        upstream.send(data, { binary: isBinary });
+      }
+    });
+    upstream.on("close", (code, reasonBuffer) => {
+      const reason = reasonBuffer.toString() || "Upstream closed";
+      closeSocket(client, code || 1e3, reason);
+    });
+    client.on("close", (code, reasonBuffer) => {
+      const reason = reasonBuffer.toString() || "Client closed";
+      closeSocket(upstream, code || 1e3, reason);
+    });
+    upstream.on("error", (error) => {
+      console.error(`[auth-gateway] upstream error: ${String(error)}`);
+      closeSocket(client, CLOSE_UPSTREAM_ERROR, "Upstream unavailable");
+      closeSocket(upstream, CLOSE_UPSTREAM_ERROR, "Upstream unavailable");
+    });
+    client.on("error", (error) => {
+      console.error(`[auth-gateway] client error: ${String(error)}`);
+      closeSocket(upstream, 1011, "Client error");
+    });
+  });
+  server.on("listening", () => {
+    console.log(
+      `[auth-gateway] listening ${options.listenUrl} -> ${options.upstreamUrl}`
+    );
+  });
+  const shutdown = () => {
+    server.close(() => {
+      process.exit(0);
+    });
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+function isDirectExecution() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  return import.meta.url === pathToFileURL(resolve(entry)).href;
+}
+if (isDirectExecution()) {
+  main().catch((error) => {
+    console.error(
+      error instanceof Error ? error.stack ?? error.message : String(error)
+    );
+    process.exit(1);
+  });
+}
+export {
+  buildGatewayOptions
+};
+//# sourceMappingURL=codex-app-server-auth-gateway.mjs.map

package/dist/bridges/codex-app-server-auth-gateway.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/bridges/codex-app-server-auth-gateway.ts"],"sourcesContent":["import type { IncomingMessage } from \"node:http\";\nimport { readFileSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport { timingSafeEqual } from \"node:crypto\";\nimport { WebSocket, WebSocketServer, type RawData } from \"ws\";\n\nconst AUTH_QUERY_PARAM = \"tap_token\";\nconst CLOSE_UNAUTHORIZED = 4401;\nconst CLOSE_UPSTREAM_ERROR = 1013;\n\ninterface GatewayOptions {\n  listenUrl: string;\n  upstreamUrl: string;\n  token: string;\n}\n\nfunction normalizeUrl(value: string): string {\n  return value.replace(/\\/$/, \"\");\n}\n\nfunction closeSocket(\n  socket: Pick<WebSocket, \"readyState\" | \"close\">,\n  code: number,\n  reason: string,\n): void {\n  if (\n    socket.readyState === WebSocket.CLOSING ||\n    socket.readyState === WebSocket.CLOSED\n  ) {\n    return;\n  }\n\n  try {\n    socket.close(code, reason);\n  } catch {\n    // Best-effort cleanup only.\n  }\n}\n\nfunction readFlagValue(argv: string[], index: number, flag: string): string {\n  const current = argv[index] ?? \"\";\n  const eqIndex = current.indexOf(\"=\");\n  if (eqIndex >= 0) {\n    return current.slice(eqIndex + 1);\n  }\n\n  const next = argv[index + 1];\n  if (!next || next.startsWith(\"--\")) {\n    throw new Error(`Missing value for ${flag}`);\n  }\n  return next;\n}\n\nexport function buildGatewayOptions(argv: string[]): GatewayOptions {\n  let listenUrl = process.env.TAP_GATEWAY_LISTEN_URL?.trim() || \"\";\n  let upstreamUrl = process.env.TAP_GATEWAY_UPSTREAM_URL?.trim() || \"\";\n  let tokenFile = process.env.TAP_GATEWAY_TOKEN_FILE?.trim() || \"\";\n  let token = process.env.TAP_GATEWAY_TOKEN?.trim() || \"\";\n\n  for (let index = 0; index < argv.length; index += 1) {\n    const flag = argv[index] ?? \"\";\n    const consumesNext = !flag.includes(\"=\");\n\n    if (flag.startsWith(\"--listen-url\")) {\n      listenUrl = readFlagValue(argv, index, \"--listen-url\").trim();\n      if (consumesNext) index += 1;\n      continue;\n    }\n\n    if (flag.startsWith(\"--upstream-url\")) {\n      upstreamUrl = readFlagValue(argv, index, \"--upstream-url\").trim();\n      if (consumesNext) index += 1;\n      continue;\n    }\n\n    if (flag.startsWith(\"--token\")) {\n      token = readFlagValue(argv, index, \"--token\").trim();\n      if (consumesNext) index += 1;\n      continue;\n    }\n\n    if (flag.startsWith(\"--token-file\")) {\n      tokenFile = readFlagValue(argv, index, \"--token-file\").trim();\n      if (consumesNext) index += 1;\n      continue;\n    }\n  }\n\n  if (tokenFile) {\n    token = readFileSync(tokenFile, \"utf8\").trim();\n  }\n\n  if (!listenUrl) {\n    throw new Error(\"Missing gateway listen URL\");\n  }\n  if (!upstreamUrl) {\n    throw new Error(\"Missing gateway upstream URL\");\n  }\n  if (!token) {\n    throw new Error(\"Missing gateway auth token\");\n  }\n\n  const listen = new URL(listenUrl);\n  const upstream = new URL(upstreamUrl);\n  if (!/^wss?:$/.test(listen.protocol)) {\n    throw new Error(`Unsupported gateway listen protocol: ${listen.protocol}`);\n  }\n  if (!/^wss?:$/.test(upstream.protocol)) {\n    throw new Error(\n      `Unsupported gateway upstream protocol: ${upstream.protocol}`,\n    );\n  }\n\n  return {\n    listenUrl: normalizeUrl(listen.toString()),\n    upstreamUrl: normalizeUrl(upstream.toString()),\n    token,\n  };\n}\n\nfunction tokensMatch(presentedToken: string | null, expectedToken: string): boolean {\n  if (!presentedToken) {\n    return false;\n  }\n\n  const presented = Buffer.from(presentedToken, \"utf8\");\n  const expected = Buffer.from(expectedToken, \"utf8\");\n  if (presented.length !== expected.length) {\n    return false;\n  }\n\n  return timingSafeEqual(presented, expected);\n}\n\nasync function main(): Promise<void> {\n  const options = buildGatewayOptions(process.argv.slice(2));\n  const listen = new URL(options.listenUrl);\n  const host = listen.hostname === \"localhost\" ? \"127.0.0.1\" : listen.hostname;\n  const port = Number.parseInt(listen.port, 10);\n  if (!Number.isFinite(port) || port <= 0) {\n    throw new Error(`Gateway listen URL must include a valid port: ${options.listenUrl}`);\n  }\n\n  const server = new WebSocketServer({\n    host,\n    port,\n    path: listen.pathname === \"/\" ? undefined : listen.pathname,\n    perMessageDeflate: false,\n  });\n\n  server.on(\"connection\", (client: WebSocket, request: IncomingMessage) => {\n    const requestUrl = new URL(request.url ?? \"/\", options.listenUrl);\n    const presentedToken = requestUrl.searchParams.get(AUTH_QUERY_PARAM);\n    if (!tokensMatch(presentedToken, options.token)) {\n      closeSocket(client, CLOSE_UNAUTHORIZED, \"Unauthorized\");\n      return;\n    }\n\n    const upstream = new WebSocket(options.upstreamUrl, {\n      perMessageDeflate: false,\n    });\n\n    upstream.on(\"message\", (data: RawData, isBinary: boolean) => {\n      if (client.readyState === WebSocket.OPEN) {\n        client.send(data, { binary: isBinary });\n      }\n    });\n\n    client.on(\"message\", (data: RawData, isBinary: boolean) => {\n      if (upstream.readyState === WebSocket.OPEN) {\n        upstream.send(data, { binary: isBinary });\n      }\n    });\n\n    upstream.on(\"close\", (code: number, reasonBuffer: Buffer) => {\n      const reason = reasonBuffer.toString() || \"Upstream closed\";\n      closeSocket(client, code || 1000, reason);\n    });\n\n    client.on(\"close\", (code: number, reasonBuffer: Buffer) => {\n      const reason = reasonBuffer.toString() || \"Client closed\";\n      closeSocket(upstream, code || 1000, reason);\n    });\n\n    upstream.on(\"error\", (error: Error) => {\n      console.error(`[auth-gateway] upstream error: ${String(error)}`);\n      closeSocket(client, CLOSE_UPSTREAM_ERROR, \"Upstream unavailable\");\n      closeSocket(upstream, CLOSE_UPSTREAM_ERROR, \"Upstream unavailable\");\n    });\n\n    client.on(\"error\", (error: Error) => {\n      console.error(`[auth-gateway] client error: ${String(error)}`);\n      closeSocket(upstream, 1011, \"Client error\");\n    });\n  });\n\n  server.on(\"listening\", () => {\n    console.log(\n      `[auth-gateway] listening ${options.listenUrl} -> ${options.upstreamUrl}`,\n    );\n  });\n\n  const shutdown = () => {\n    server.close(() => {\n      process.exit(0);\n    });\n  };\n\n  process.on(\"SIGINT\", shutdown);\n  process.on(\"SIGTERM\", shutdown);\n}\n\nfunction isDirectExecution(): boolean {\n  const entry = process.argv[1];\n  if (!entry) return false;\n  return import.meta.url === pathToFileURL(resolve(entry)).href;\n}\n\nif (isDirectExecution()) {\n  main().catch((error) => {\n    console.error(\n      error instanceof Error ? (error.stack ?? error.message) : String(error),\n    );\n    process.exit(1);\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/bridges/codex-app-server-bridge.d.mts

@@ -0,0 +1,55 @@
+type BusyMode = "wait" | "steer";
+interface Options {
+    repoRoot: string;
+    commsDir: string;
+    agentId: string;
+    agentName: string;
+    stateDir: string;
+    pollSeconds: number;
+    reconnectSeconds: number;
+    messageLookbackMinutes: number;
+    processExistingMessages: boolean;
+    dryRun: boolean;
+    runOnce: boolean;
+    waitAfterDispatchSeconds: number;
+    appServerUrl: string;
+    connectAppServerUrl: string;
+    gatewayTokenFile: string | null;
+    busyMode: BusyMode;
+    threadId: string | null;
+    ephemeral: boolean;
+}
+interface Candidate {
+    markerId: string;
+    filePath: string;
+    fileName: string;
+    sender: string;
+    recipient: string;
+    subject: string;
+    body: string;
+    mtimeMs: number;
+}
+interface HeadlessWarmupClient {
+    activeTurnId: string | null;
+    lastTurnStatus: string | null;
+    startTurn(inputText: string): Promise<string | null>;
+    refreshCurrentThreadState(): Promise<void>;
+}
+interface HeartbeatStoreRecord {
+    id?: string;
+    agent?: string;
+}
+type HeartbeatStore = Record<string, HeartbeatStoreRecord>;
+declare const HEADLESS_WARMUP_PROMPT: string;
+declare function resolveAgentId(preferredAgentName?: string | null): string;
+declare function recipientMatchesAgent(recipient: string, agentId: string, agentName: string): boolean;
+declare function isOwnMessageSender(sender: string, agentId: string, agentName: string): boolean;
+declare function resolveAddressLabel(address: string, heartbeats: HeartbeatStore): string;
+declare function resolveCurrentAgentName(agentId: string, fallbackAgentName: string, heartbeats: HeartbeatStore): string;
+declare function buildUserInput(candidate: Candidate, agentName: string, heartbeats: HeartbeatStore): string;
+declare function waitForTurnCompletion(client: Pick<HeadlessWarmupClient, "activeTurnId" | "lastTurnStatus" | "refreshCurrentThreadState">, turnId: string, timeoutMs: number): Promise<string | null>;
+declare function maybeBootstrapHeadlessTurn(options: Options, cutoff: Date, client: HeadlessWarmupClient): Promise<boolean>;
+declare function buildOptions(argv: string[]): Options;
+declare function main(): Promise<void>;
+
+export { HEADLESS_WARMUP_PROMPT, type HeadlessWarmupClient, buildOptions, buildUserInput, isOwnMessageSender, main, maybeBootstrapHeadlessTurn, recipientMatchesAgent, resolveAddressLabel, resolveAgentId, resolveCurrentAgentName, waitForTurnCompletion };