qantara 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Gamil (ahmed.gamil.codes@gmail.com)
+
+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/README.md

@@ -0,0 +1,272 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ahmeedgamil/qantara/main/assets/qantara_logo.png" alt="Qantara" width="300">
+  <br>
+  <em>An arched bridge between your coding agents.</em>
+</p>
+
+<p align="center">
+  <!-- After `npm publish`, replace this static badge with the dynamic one:
+       <a href="https://www.npmjs.com/package/qantara"><img alt="npm" src="https://img.shields.io/npm/v/qantara"></a> -->
+  <img alt="version 0.1.0" src="https://img.shields.io/badge/version-0.1.0-blue">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
+  <img alt="Node.js >= 18" src="https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white">
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white">
+  <img alt="MCP server" src="https://img.shields.io/badge/MCP-server-8A2BE2">
+  <img alt="Bridges Claude, Codex, Gemini" src="https://img.shields.io/badge/bridges-Claude%20%C2%B7%20Codex%20%C2%B7%20Gemini-FF6B35">
+</p>
+
+---
+
+An MCP server that lets coding agents **delegate tasks to each other**. Claude Code can
+hand a task to Codex or Gemini, Codex can hand a task to Claude, and the design extends
+to any other agent (Aider, …) by adding a small adapter.
+
+It works by shelling out to each tool's **headless CLI** (`claude -p`, `codex exec`,
+`gemini -p`), so it **reuses your existing CLI logins** — no extra API keys, no separate
+per-token billing.
+
+```
+Claude Code ──(MCP tool: ask_codex)──► qantara ──► codex exec --json ──► Codex
+Codex       ──(MCP tool: ask_claude)─► qantara ──► claude -p --json ──► Claude Code
+Gemini      ──(MCP tool: ask_codex)──► qantara ──► ...
+```
+
+## Setup (one command)
+
+```powershell
+npm i -g qantara     # or run from a clone: npm install && npm run build
+qantara setup        # detects claude/codex/gemini, registers the bridge in each
+```
+
+`setup` detects which agent CLIs are installed, registers qantara into each host
+(exposing the *other* agents as tools), pre-approves the tools so nothing prompts,
+and forwards your proxy env to Codex if you have one. It backs up every file it
+touches (`*.qantara.bak`), is idempotent, and `qantara setup --dry-run` shows the
+plan without writing. Restart your hosts afterwards — MCP servers load at session
+start. The sections below describe what it writes, for manual setup or auditing.
+
+## The control model
+
+There is no central controller — control follows whoever you talk to:
+
+```
+You (the human)
+ └── Host agent — whichever one you opened (Claude Code OR Codex)
+      └── qantara (dumb pipe, controls nothing)
+           └── Delegated agent (contractor: gets a brief, works, reports, exits)
+                └── can delegate again, down to a depth limit
+```
+
+- **You** own all policy: which agents exist, what they may do, every limit. Policy is
+  written in config files *before* anything runs; there is no API for an agent to change
+  it at runtime.
+- **The host agent** is the brain for the session: it decides when to delegate, writes the
+  brief, and judges the result. The roles are symmetric — open Claude Code and Claude
+  commands Codex; open Codex and Codex commands Claude.
+- **The bridge makes no decisions** about the work. It translates one MCP tool call into
+  one CLI invocation and enforces mechanical guards (depth, timeout, output cap). All
+  intelligence and all safety policy live in the agents and in your config.
+- **The delegated agent** is autonomous *within* its task, but its powers (sandbox,
+  permission mode) were fixed by your config before it started — not by the caller.
+
+Delegation is a *letter, not a phone call*: the delegated agent gets only the task text,
+none of the caller's conversation. Write briefs accordingly (file paths, constraints,
+acceptance criteria). By default the bridge tells delegated agents to **reply with
+questions instead of guessing** when a task is ambiguous; answer them with a
+`continue_session: true` follow-up call.
+
+## Prerequisites
+
+- Node.js 18+
+- The agent CLIs you want to bridge, installed and logged in:
+  - `npm i -g @anthropic-ai/claude-code` (`claude`)
+  - `npm i -g @openai/codex` (`codex`)
+  - `npm i -g @google/gemini-cli` (`gemini`) — log in by running `gemini` once
+    interactively (Google account), or set `GEMINI_API_KEY`
+
+## Build
+
+```powershell
+npm install
+npm run build
+```
+
+## Manual registration (what `setup` writes)
+
+### Into Claude Code (gives Claude `ask_codex` / `ask_gemini`)
+
+```powershell
+claude mcp add -s user qantara -e BRIDGE_EXPOSE=codex,gemini -- node "<path-to>/qantara/dist/server.js"
+```
+
+To skip the per-session permission prompt, allowlist the server in
+`~/.claude/settings.json` (one entry covers all its tools):
+
+```json
+{
+  "permissions": {
+    "allow": ["mcp__qantara"]
+  }
+}
+```
+
+### Into Codex (gives Codex `ask_claude` / `ask_gemini`)
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.qantara]
+command = "node"
+args = ['<path-to>/qantara/dist/server.js']
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 600
+# Required for headless `codex exec`: without this, Codex auto-cancels the
+# MCP tool call ("user cancelled MCP tool call") because there is no human
+# to approve it. Also removes the prompt in interactive Codex.
+# Available since Codex 0.122.0.
+default_tools_approval_mode = "approve"
+
+[mcp_servers.qantara.env]
+BRIDGE_EXPOSE = "claude"
+# Codex spawns MCP servers with a stripped environment (a fixed whitelist of
+# core OS vars). If your `claude` login needs a proxy (HTTP_PROXY/HTTPS_PROXY),
+# you MUST re-declare it here or the spawned claude gets
+# "API Error: 403 Request not allowed".
+# HTTP_PROXY = "http://user:pass@host:port"
+# HTTPS_PROXY = "http://user:pass@host:port"
+# NO_PROXY = "localhost,127.0.0.1,::1"
+```
+
+> The general rule: **the caller's side pre-approves the tool call** (Claude's
+> `permissions.allow`, Codex's `default_tools_approval_mode`); **the delegated agent never
+> prompts** — its behavior is governed by the `BRIDGE_*` policy below. If you expose both
+> agents in one host (`BRIDGE_EXPOSE = "all"`), allowlist both `ask_*` tool names.
+
+## Tools
+
+### `ask_<agent>` — delegate a task
+
+| Param              | Type                                            | Notes                                            |
+| ------------------ | ----------------------------------------------- | ------------------------------------------------ |
+| `task`             | string (required)                               | The work to delegate. Include all context — the agent sees nothing else. |
+| `cwd`              | string                                          | Working directory for the agent (set it to your project to work on the same files). |
+| `continue_session` | boolean                                         | Resume the last session with this agent (sequential shorthand). |
+| `session_id`       | string                                          | Resume an exact session (id from a result's footer). Takes precedence over `continue_session`; use with parallel sessions. |
+| `background`       | boolean                                         | Don't block: returns a job id immediately. Poll with `check_job`. For long tasks. |
+| `model`            | string                                          | Override the model (e.g. `gpt-5.5`, `opus`).     |
+| `reasoning`        | `low` \| `medium` \| `high`                     | Maps to Codex `model_reasoning_effort` / Claude `--effort`. |
+| `thinking`         | `off` \| `think` \| `think_hard` \| `ultrathink` | **Claude only** — extended thinking.             |
+
+Blocking calls time out after `BRIDGE_TIMEOUT_MS` (10 min default). For anything that
+might run longer, use `background: true` — background jobs get `BRIDGE_JOB_TIMEOUT_MS`
+(1 h default) and the caller keeps working while they run.
+
+### `check_job` / `cancel_job` — manage background jobs
+
+- `check_job` with a `job_id`: status, and the agent's full result once finished.
+- `check_job` without arguments: list all jobs of the session.
+- `cancel_job`: kill a running job.
+
+Jobs live in the bridge process's memory: they last for your host session and are gone
+after a restart. There is no push notification (MCP is request/response) — the caller
+polls between its own steps.
+
+## Working on the same project
+
+Pass your project path as `cwd` and both agents edit the same real files. Within one
+delegation there is no write conflict — the caller is paused (or, for background jobs,
+should avoid editing the same areas). Two habits make this reliable:
+
+1. **Re-read changed files after a delegation returns.** The caller's in-context copy is
+   stale the moment the child edits the file.
+2. **One writer per area at a time.** There is no locking and no git isolation — the
+   working tree and the git index are shared. (Worktree isolation is on the roadmap.)
+
+## Configuration (environment variables)
+
+Set these in the host's MCP registration (see above). They are read once at startup —
+**callers cannot change policy at runtime.**
+
+| Variable                  | Default           | Purpose                                              |
+| ------------------------- | ----------------- | ---------------------------------------------------- |
+| `BRIDGE_EXPOSE`           | `all`             | Comma list of agents to expose (`codex`, `claude`, `gemini`). |
+| `BRIDGE_MAX_DEPTH`        | `3`               | Max agent→agent recursion depth (loop guard).        |
+| `BRIDGE_TIMEOUT_MS`       | `600000`          | Timeout per blocking call (10 min).                  |
+| `BRIDGE_JOB_TIMEOUT_MS`   | `3600000`         | Timeout per background job (1 h).                    |
+| `BRIDGE_MAX_OUTPUT_BYTES` | `1000000`         | Output cap (protects the caller's context).          |
+| `BRIDGE_CLARIFY`          | `1`               | Tell delegated agents to ask instead of guess. `0` to disable. |
+| `BRIDGE_SANDBOX`          | `workspace-write` | Codex sandbox (`read-only`/`workspace-write`/`danger-full-access`). |
+| `BRIDGE_CLAUDE_PERMISSION`| `acceptEdits`     | Claude permission mode (`bypassPermissions` for full autonomy). |
+| `BRIDGE_GEMINI_APPROVAL`  | `auto_edit`       | Gemini approval mode (`default`/`auto_edit`/`yolo`/`plan`). |
+| `BRIDGE_GEMINI_MODEL`     | (CLI default)     | Default Gemini model.                                |
+| `BRIDGE_CODEX_MODEL`      | (CLI default)     | Default Codex model.                                 |
+| `BRIDGE_CODEX_REASONING`  | (CLI default)     | Default Codex reasoning effort.                      |
+| `BRIDGE_CLAUDE_MODEL`     | (CLI default)     | Default Claude model.                                |
+| `BRIDGE_DEBUG`            | (off)             | Path of a file to append diagnostic logs to.         |
+
+## Security notes
+
+- **The caller's sandbox does not propagate.** Hosts run MCP servers *outside* their own
+  sandbox, so a tightly sandboxed Codex session can still delegate to a Claude that runs
+  with normal user privileges (and vice versa). A delegated agent's limits come entirely
+  from the `BRIDGE_*` policy you configured — never from the caller's restrictions. Choose
+  `BRIDGE_SANDBOX` / `BRIDGE_CLAUDE_PERMISSION` as if the delegated agent were launched
+  directly by you, because effectively it is.
+- **Codex delegate:** headless Codex never prompts — actions outside its sandbox simply
+  fail. Note that `workspace-write` blocks network for shell commands by default (e.g.
+  `npm install` inside a task may fail).
+- **Claude delegate:** `acceptEdits` auto-approves file edits but refuses Bash commands
+  outside your allowlist (headless mode cannot prompt). `bypassPermissions` removes all
+  gates — use deliberately.
+- **Gemini delegate:** `auto_edit` auto-approves edits; shell commands are denied (no
+  prompt is possible headless). `yolo` approves everything. The bridge passes
+  `--skip-trust` so gemini's folder-trust feature doesn't silently downgrade the
+  approval mode — your `BRIDGE_GEMINI_APPROVAL` is the single source of policy.
+- **Loop guard:** `BRIDGE_DEPTH` is threaded into each spawned child and incremented; at
+  `BRIDGE_MAX_DEPTH` further `ask_*` calls are refused, so A→B→A→B recursion cannot burn
+  your subscriptions. There is no per-session call-count or cost budget yet — the host
+  agent (and your subscription limits) govern how many delegations happen.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+| --- | --- |
+| Codex replies "user cancelled MCP tool call" | Headless Codex auto-cancels MCP approval prompts. Set `default_tools_approval_mode = "approve"` on the server entry in `~/.codex/config.toml`. |
+| Delegated `claude` fails: `API Error: 403 Request not allowed` | Your Anthropic traffic needs a proxy, and Codex stripped `HTTP_PROXY`/`HTTPS_PROXY` from the bridge's env. Re-declare them in `[mcp_servers.qantara.env]`. |
+| `codex exec` hangs on "Reading additional input from stdin..." | When scripting Codex, close stdin (`$null | codex exec …` in PowerShell, `codex exec … < /dev/null` in sh). |
+| `continue_session` doesn't resume across separate `codex exec` runs | Session ids live in the bridge process's memory; each headless run spawns a fresh bridge. Works as expected in interactive hosts. |
+| A blocking call dies at 10 minutes | Use `background: true` (1 h budget), or raise `BRIDGE_TIMEOUT_MS`. |
+| `ask_gemini` fails with exit code 41 / "set an Auth method" | The gemini CLI isn't logged in. Run `gemini` once interactively, or set `GEMINI_API_KEY` in the bridge's env block. |
+| Gemini `continue_session` doesn't find the session | Gemini sessions are project-scoped (keyed by cwd) — resume only works with the same `cwd` as the original call. |
+
+## Adding another agent
+
+1. Create `src/runners/<name>.ts` implementing the `AgentRunner` interface from
+   [`src/registry.ts`](src/registry.ts).
+2. `register(<name>Runner)` in [`src/server.ts`](src/server.ts).
+
+No changes to the MCP layer or core are needed — an `ask_<name>` tool appears automatically.
+
+## Smoke tests
+
+```powershell
+node smoke.mjs            # calls each runner directly with a trivial task
+node mcp-test.mjs         # connects an MCP client, lists tools, calls one
+node mcp-test-claude.mjs  # drives the claude runner through MCP
+node mcp-test-gemini.mjs  # drives the gemini runner through MCP
+node mcp-test-jobs.mjs    # background jobs: start, poll, result, cancel, list
+node mcp-test-session.mjs # explicit resume: teach a word, resume by session_id
+```
+
+## Roadmap
+
+- **Git worktree isolation** — run each delegation in a temp worktree and return a
+  reviewable diff instead of editing the shared tree.
+- Live progress for background jobs (parse the child's JSON stream incrementally).
+- Per-session call-count / cost budget guard.
+- More adapters (Aider, …). Gemini CLI is already included.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * qantara CLI entry point.
+ *   qantara              → run the MCP server on stdio (what hosts invoke)
+ *   qantara setup        → detect installed agent CLIs and register the bridge
+ *                          into each host's config (--dry-run to preview)
+ *   qantara --version    → print the package version
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const cmd = process.argv[2];
+if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
+    process.stdout.write(`qantara ${pkg.version}\n`);
+}
+else if (cmd === "setup") {
+    const { runSetup } = await import("./setup.js");
+    await runSetup(process.argv.slice(3));
+}
+else if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+    process.stdout.write("qantara — an MCP bridge that lets coding agents delegate to each other\n\n" +
+        "Usage:\n" +
+        "  qantara            Run the MCP server on stdio (hosts invoke this)\n" +
+        "  qantara setup      Register the bridge into Claude Code / Codex / Gemini\n" +
+        "  qantara setup --dry-run   Show what setup would change, without writing\n" +
+        "  qantara --version  Print the package version\n");
+}
+else {
+    await import("./server.js");
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAE5B,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;IAC7D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CACpB,YAAY,CACV,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,EACnE,MAAM,CACP,CACF,CAAC;IACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;AACnD,CAAC;KAAM,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;IAC3B,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;IAChD,MAAM,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC;KAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;IAC9D,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,4EAA4E;QAC1E,UAAU;QACV,wEAAwE;QACxE,8EAA8E;QAC9E,6EAA6E;QAC7E,kDAAkD,CACrD,CAAC;AACJ,CAAC;KAAM,CAAC;IACN,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;AAC9B,CAAC"}

package/dist/config.js

@@ -0,0 +1,63 @@
+/**
+ * Central, env-driven configuration. All knobs are environment variables so the
+ * same binary can be registered into different hosts with different scoping
+ * (e.g. expose only `codex` inside Claude Code, only `claude` inside Codex).
+ */
+function num(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : fallback;
+}
+function list(name) {
+    const raw = process.env[name];
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export const config = {
+    /** Hard timeout per blocking agent invocation. */
+    timeoutMs: num("BRIDGE_TIMEOUT_MS", 600_000),
+    /** Hard timeout per background job (longer: jobs don't block the caller). */
+    jobTimeoutMs: num("BRIDGE_JOB_TIMEOUT_MS", 3_600_000),
+    /** Max bytes of captured output, to protect the calling model's context. */
+    maxOutputBytes: num("BRIDGE_MAX_OUTPUT_BYTES", 1_000_000),
+    /** Which agents to expose as tools (empty => all registered). */
+    expose: list("BRIDGE_EXPOSE"),
+    /**
+     * Tell delegated agents that a supervising agent can answer follow-up
+     * questions (via session resume), so they ask instead of guessing when a
+     * task is ambiguous. Disable with BRIDGE_CLARIFY=0.
+     */
+    clarify: process.env.BRIDGE_CLARIFY !== "0",
+    /** Recursion / fan-out guard. */
+    maxDepth: num("BRIDGE_MAX_DEPTH", 3),
+    /** Current depth, threaded in from a parent bridge invocation (0 at the top). */
+    depth: num("BRIDGE_DEPTH", 0),
+    /** Codex execution settings. */
+    codex: {
+        sandbox: process.env.BRIDGE_SANDBOX ?? "workspace-write",
+        model: process.env.BRIDGE_CODEX_MODEL, // undefined => CLI default
+        reasoning: process.env.BRIDGE_CODEX_REASONING, // undefined => CLI default
+    },
+    /** Claude execution settings. */
+    claude: {
+        permissionMode: process.env.BRIDGE_CLAUDE_PERMISSION ?? "acceptEdits",
+        model: process.env.BRIDGE_CLAUDE_MODEL, // undefined => CLI default
+    },
+    /** Gemini execution settings. */
+    gemini: {
+        // default | auto_edit | yolo | plan — auto_edit mirrors Claude's acceptEdits.
+        approvalMode: process.env.BRIDGE_GEMINI_APPROVAL ?? "auto_edit",
+        model: process.env.BRIDGE_GEMINI_MODEL, // undefined => CLI default
+    },
+};
+/** Env to pass to a spawned child agent so depth increments and propagates. */
+export function childEnv(currentDepth) {
+    return { BRIDGE_DEPTH: String(currentDepth + 1) };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,SAAS,GAAG,CAAC,IAAY,EAAE,QAAgB;IACzC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3C,CAAC;AAED,SAAS,IAAI,CAAC,IAAY;IACxB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,OAAO,GAAG;SACP,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,kDAAkD;IAClD,SAAS,EAAE,GAAG,CAAC,mBAAmB,EAAE,OAAO,CAAC;IAC5C,6EAA6E;IAC7E,YAAY,EAAE,GAAG,CAAC,uBAAuB,EAAE,SAAS,CAAC;IACrD,4EAA4E;IAC5E,cAAc,EAAE,GAAG,CAAC,yBAAyB,EAAE,SAAS,CAAC;IAEzD,iEAAiE;IACjE,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC;IAE7B;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,GAAG;IAE3C,iCAAiC;IACjC,QAAQ,EAAE,GAAG,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACpC,iFAAiF;IACjF,KAAK,EAAE,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC;IAE7B,gCAAgC;IAChC,KAAK,EAAE;QACL,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,iBAAiB;QACxD,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,2BAA2B;QAClE,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,2BAA2B;KAC3E;IAED,iCAAiC;IACjC,MAAM,EAAE;QACN,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,aAAa;QACrE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,2BAA2B;KACpE;IAED,iCAAiC;IACjC,MAAM,EAAE;QACN,8EAA8E;QAC9E,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,WAAW;QAC/D,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,2BAA2B;KACpE;CACO,CAAC;AAEX,+EAA+E;AAC/E,MAAM,UAAU,QAAQ,CAAC,YAAoB;IAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC,EAAE,CAAC;AACpD,CAAC"}

package/dist/debug.js

@@ -0,0 +1,25 @@
+import { appendFileSync } from "node:fs";
+const target = process.env.BRIDGE_DEBUG;
+// Startup diagnostic. Hosts may launch the bridge with a stripped environment
+// (Codex passes only a whitelist of core OS vars), so logging the received env
+// keys up front makes those problems visible without a debugger.
+debug(`bridge process started | ` +
+    `BRIDGE_EXPOSE=${process.env.BRIDGE_EXPOSE ?? "(unset)"} | ` +
+    `BRIDGE_DEPTH=${process.env.BRIDGE_DEPTH ?? "(unset)"} | ` +
+    `cwd=${process.cwd()} | ` +
+    `envKeys=${Object.keys(process.env).sort().join(",")}`);
+/**
+ * Appends a timestamped line to the file named in BRIDGE_DEBUG (if set).
+ * Used to diagnose runs where stderr is not visible (e.g. spawned by a host).
+ */
+export function debug(msg) {
+    if (!target)
+        return;
+    try {
+        appendFileSync(target, `[${new Date().toISOString()}] ${msg}\n`);
+    }
+    catch {
+        // best-effort logging only
+    }
+}
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;AAExC,8EAA8E;AAC9E,+EAA+E;AAC/E,iEAAiE;AACjE,KAAK,CACH,2BAA2B;IACzB,iBAAiB,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,SAAS,KAAK;IAC5D,gBAAgB,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,SAAS,KAAK;IAC1D,OAAO,OAAO,CAAC,GAAG,EAAE,KAAK;IACzB,WAAW,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CACzD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,GAAW;IAC/B,IAAI,CAAC,MAAM;QAAE,OAAO;IACpB,IAAI,CAAC;QACH,cAAc,CAAC,MAAM,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,2BAA2B;IAC7B,CAAC;AACH,CAAC"}

package/dist/exec.js

@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+import { debug } from "./debug.js";
+export class ExecError extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.result = result;
+        this.name = "ExecError";
+    }
+}
+/**
+ * Spawn a command with an args array (never a shell string) so arbitrary task
+ * text cannot be interpreted by the shell. Enforces a timeout and an output cap.
+ *
+ * On Windows, `.cmd` shims (npm-installed CLIs) are not directly executable by
+ * spawn without a shell, so we resolve the actual command up front via PATHEXT.
+ */
+export function runCommand(command, args, opts) {
+    return new Promise((resolve, reject) => {
+        // On Windows, .cmd/.bat shims require shell:true to be invoked. We keep the
+        // args array form so values are still passed as discrete argv entries.
+        const isWindows = process.platform === "win32";
+        debug(`spawn command=${command} args=${JSON.stringify(args)} cwd=${opts.cwd ?? "(inherit)"} ` +
+            `shell=${isWindows} PATH_present=${Boolean(process.env.PATH || process.env.Path)}`);
+        const child = spawn(command, args, {
+            cwd: opts.cwd,
+            env: { ...process.env, ...opts.env },
+            shell: isWindows, // needed for npm .cmd shims on Windows
+            windowsHide: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        let truncated = false;
+        let timedOut = false;
+        let cancelled = false;
+        let settled = false;
+        const cap = opts.maxOutputBytes;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, opts.timeoutMs);
+        const onAbort = () => {
+            cancelled = true;
+            child.kill("SIGKILL");
+        };
+        if (opts.signal) {
+            if (opts.signal.aborted)
+                onAbort();
+            else
+                opts.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        if (opts.stdin !== undefined) {
+            child.stdin.write(opts.stdin);
+            child.stdin.end();
+        }
+        child.stdout.on("data", (chunk) => {
+            if (stdout.length < cap) {
+                stdout += chunk.toString("utf8");
+                if (stdout.length >= cap) {
+                    stdout = stdout.slice(0, cap);
+                    truncated = true;
+                }
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            if (stderr.length < cap) {
+                stderr += chunk.toString("utf8");
+                if (stderr.length >= cap)
+                    stderr = stderr.slice(0, cap);
+            }
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            debug(`child error for ${command}: ${err.message}`);
+            // ENOENT => binary missing; surface a clear, actionable message.
+            const hint = err.code === "ENOENT"
+                ? ` (is "${command}" installed and on PATH?)`
+                : "";
+            reject(new ExecError(`Failed to launch "${command}"${hint}: ${err.message}`));
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            debug(`child close ${command} code=${code} stdoutLen=${stdout.length} ` +
+                `stderrTail=${JSON.stringify(stderr.slice(-300))}`);
+            opts.signal?.removeEventListener("abort", onAbort);
+            const result = { code, stdout, stderr, timedOut, truncated };
+            if (cancelled) {
+                reject(new ExecError(`"${command}" was cancelled`, result));
+                return;
+            }
+            if (timedOut) {
+                reject(new ExecError(`"${command}" timed out after ${opts.timeoutMs}ms`, result));
+                return;
+            }
+            resolve(result);
+        });
+    });
+}
+//# sourceMappingURL=exec.js.map

package/dist/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"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"}

package/dist/jobs.js

@@ -0,0 +1,22 @@
+const jobs = new Map();
+let counter = 0;
+export function createJob(agent, task) {
+    counter += 1;
+    const job = {
+        id: `${agent}-${counter}`,
+        agent,
+        taskSummary: task.split("\n")[0].slice(0, 120),
+        status: "running",
+        startedAt: Date.now(),
+        abort: new AbortController(),
+    };
+    jobs.set(job.id, job);
+    return job;
+}
+export function getJob(id) {
+    return jobs.get(id);
+}
+export function listJobs() {
+    return [...jobs.values()];
+}
+//# sourceMappingURL=jobs.js.map

package/dist/jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.js","sourceRoot":"","sources":["../src/jobs.ts"],"names":[],"mappings":"AAsBA,MAAM,IAAI,GAAG,IAAI,GAAG,EAAe,CAAC;AACpC,IAAI,OAAO,GAAG,CAAC,CAAC;AAEhB,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,IAAY;IACnD,OAAO,IAAI,CAAC,CAAC;IACb,MAAM,GAAG,GAAQ;QACf,EAAE,EAAE,GAAG,KAAK,IAAI,OAAO,EAAE;QACzB,KAAK;QACL,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QAC9C,MAAM,EAAE,SAAS;QACjB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,KAAK,EAAE,IAAI,eAAe,EAAE;KAC7B,CAAC;IACF,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACtB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,EAAU;IAC/B,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;AAC5B,CAAC"}

package/dist/registry.js

@@ -0,0 +1,24 @@
+/**
+ * The single abstraction the whole bridge is built on. Every backend agent
+ * (Codex, Claude, and later Gemini / Antigravity / Aider / ...) is just an
+ * adapter implementing this interface. Adding a new agent = one new adapter
+ * file + one registry entry, with no changes to the MCP server or core.
+ */
+const registry = new Map();
+export function register(runner) {
+    registry.set(runner.name, runner);
+}
+export function getRunner(name) {
+    return registry.get(name);
+}
+/**
+ * Returns the runners that should be exposed as tools, filtered by the
+ * `expose` allow-list (empty/`all` => every registered runner).
+ */
+export function exposedRunners(expose) {
+    const all = [...registry.values()];
+    if (expose.length === 0 || expose.includes("all"))
+        return all;
+    return all.filter((r) => expose.includes(r.name));
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmDH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;AAEhD,MAAM,UAAU,QAAQ,CAAC,MAAmB;IAC1C,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAgB;IAC7C,MAAM,GAAG,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAC9D,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACpD,CAAC"}