@bridge_gpt/mcp-server 0.2.55 → 0.2.56

package/README.md

@@ -351,7 +351,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.55", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -373,7 +373,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.55", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -395,7 +395,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.55", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -418,7 +418,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.55", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -437,7 +437,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.55", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.56", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -985,9 +985,9 @@ npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
 | Flag | Default | Meaning |
 |---|---|---|
 | `--agent claude\|cursor-agent` | `claude` | Agent command to launch in each worktree |
-| `--workflow implement\|review-and-implement` | `implement` | Slash command each spawned worktree runs. `implement` is byte-identical to today's `/implement-ticket <KEY> [--auto]`. `review-and-implement` spawns `/review-and-implement <KEY> [--auto] [--rounds=<n>]`, which runs `/review-ticket` then, after a per-ticket halt gate, `/implement-ticket` in the same session. `--auto` applies to the selected workflow as a whole. |
+| `--workflow implement\|review-and-implement` | `implement` | Slash command each spawned worktree runs. `review-and-implement` reviews the ticket, then hands approval to a fresh implementation session in the same worktree. `--auto` applies to both phases. |
 | `--rounds 1\|2` | unset | Review round count forwarded to the review phase. Review-only — valid only with `--workflow review-and-implement`. |
-| `--tier cheap\|basic\|premium` | unset (difficulty routing) | Coarse model-routing override. Bypasses **only** the per-ticket difficulty/tier lookup (`GET /jira/tickets/{KEY}/model-tier`) and applies this one tier to every ticket; the tier is still mapped to a model through the centralized agent registry and any configured `difficulty_model_tier_overrides`, then validated. It is **not** a raw `--model` alias and never carries an API key or credential. A malformed value fails open to premium routing. Used by the `/review-and-implement` handoff to reuse the review-time tier. |
+| `--tier cheap\|basic\|premium` | unset (difficulty routing) | Coarse model-routing override. Bypasses **only** the per-ticket difficulty/tier lookup (`GET /jira/tickets/{KEY}/model-tier`) and applies this one tier to every ticket; Claude/Cursor use their registry aliases and repository overrides, while Codex uses the authenticated Bridge catalog. It is **not** a raw `--model` alias and never carries an API key or credential. A malformed value fails open to premium routing when its alias is available. Used by the `/review-and-implement` handoff to reuse the review-time tier. |
 | `--terminal terminal\|iterm` | auto-detect via `$TERM_PROGRAM` | Override the macOS terminal app (honored on macOS only) |
 | `--dry-run` | off | Print intended actions; create no worktrees, open no tabs (any OS) |
 | `--branch KEY=BRANCH` | `feature/<KEY>` | Use a custom branch for that ticket (repeatable) |
@@ -997,15 +997,17 @@ npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
 | `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_CONDUCTOR_*` env + Claude hook injection, lifecycle ledger events, and a supervisor peer tab). **Default off** — a plain run spawns `cd <worktree> && <agent> '/implement-ticket <KEY>'`. |
 | `-h`, `--help` | — | Show usage |
 
-Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent's `'/implement-ticket <KEY>'` — `claude '/implement-ticket <KEY>'` by default, or `cursor-agent '/implement-ticket <KEY>'` with `--agent cursor-agent`. The `/implement-ticket <KEY>` prompt is unchanged for both agents. To launch Cursor Agent instead of Claude Code:
+Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent. Claude is the default. Cursor with `--auto` runs headlessly after a bounded authentication/readiness check; manual Cursor runs remain interactive for human review gates. To launch Cursor Agent instead of Claude Code:
 
 ```
 npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
 ```
 
-**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket's `difficulty` (1-2 → cheap, 3-6 → basic, 7-10 → premium) and injects it as a `--model` flag at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand); this CLI alone maps a tier to the agent-specific alias (`claude`: `haiku`/`sonnet`/`opus`; `cursor-agent`: version-suffixed strings validated against `cursor-agent --list-models`). It is gated per repo by `difficulty_model_routing_enabled` (default **ON**) with an optional `difficulty_model_tier_overrides` JSON map (tier → alias). Routing is **fail-open**: missing credentials, an evaluation failure/timeout, a backend `fallback`, an invalid/unavailable alias, an unadvertised Cursor model, or an agent without `--model` support all default to the **premium** (Opus) model — and when even the premium alias cannot be resolved/validated for the agent, `--model` is omitted (the agent uses its default) — each surfaced as a per-ticket warning rather than failing the spawn. `--dry-run` does **not** create worktrees or open tabs, but it **does** resolve routing read-only to preview the `--model` each tab would use.
+**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket's `difficulty` (1-2 → cheap, 3-6 → basic, 7-10 → premium) and may inject `--model` at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand). Claude and Cursor map that tier through their agent registry aliases; Cursor validates against `cursor-agent --list-models`. Routing is gated per repo by `difficulty_model_routing_enabled` (default **ON**). Claude/Cursor may use `difficulty_model_tier_overrides` (tier → alias) and retain their premium fallback behavior on an unknown tier or transient failure. When an alias cannot be validated, the CLI omits `--model` and launches the agent default. `--dry-run` resolves routing read-only to preview the command without creating worktrees or opening tabs.
 
-**Coarse `--tier` override.** Passing `--tier cheap|basic|premium` bypasses **only** the per-ticket difficulty lookup above and applies that one tier to every ticket; the tier is still resolved to an alias through the same agent registry + `difficulty_model_tier_overrides` and validated the same way (including the live `cursor-agent --list-models` check). It is never treated as a raw `--model` alias, and no API key or credential belongs in the spawned command (the CLI resolves credentials itself via `resolveBapiCredentials`). A malformed/unrecognized `--tier` value is **fail-open**: the CLI logs one concise warning and routes every ticket on the premium (Opus) fallback rather than aborting. `/review-and-implement` uses this flag to hand its review-time tier snapshot to the fresh implementation session.
+For Codex, `GET /jira/codex-model-catalog?repo_name=...` is the sole tier-to-model authority. Bridge derives its three bare CLI IDs and SHA-256 mapping revision at request time from `MODEL_REGISTRY`; the launcher fetches and validates that catalog once per invocation. Repository `difficulty_model_tier_overrides` do not apply to Codex. A failed access, config, tier, catalog, revision, or alias check omits `--model` and launches the configured Codex default. The catalog expresses **Bridge provider policy only**: it cannot confirm that the local Codex login or subscription can use a model. The CLI has no supported non-interactive entitlement probe, so routing emits that limitation as a diagnostic and never uses Bridge's OpenAI API key as proof of local access.
+
+**Coarse `--tier` override.** Passing `--tier cheap|basic|premium` bypasses only the per-ticket difficulty lookup and applies that tier to every ticket. Claude/Cursor use the same alias resolution as normal routing; Codex uses the fetched catalog. It is never a raw model alias, and no API key or credential belongs in the spawned command. A malformed tier requests the premium fallback when its alias is available; otherwise the agent default launches. `/review-and-implement` uses this flag to hand its review-time tier snapshot to the fresh implementation session.
 
 **Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default**. With `--conductor`, a run mints a conductor `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree; it also sets `BRIDGE_MCP_PROFILE=conductor` so workers get the conductor MCP tools. Observability is best-effort — a conductor failure never blocks a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally.) See **[CONDUCTOR.md](./docs/CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.
 

package/build/agent-capabilities/types.js

@@ -5,6 +5,10 @@ export const AGENT_AUTH = {
         note: "Claude Code authenticates via keychain/OAuth — cannot be verified from the environment.",
     },
     "cursor-agent": { kind: "env", varName: "CURSOR_API_KEY" },
+    codex: {
+        kind: "interactive",
+        note: "Codex authenticates via login/OAuth — cannot be verified from the environment.",
+    },
 };
 /** Default hard timeout per headless probe run (ms). The cursor `-p` hang bug is version-sensitive. */
 export const DEFAULT_PROBE_TIMEOUT_MS = 90_000;

package/build/agent-registry.js

@@ -26,7 +26,7 @@ export function isModelTier(value) {
 }
 /**
  * The registry: the ONLY place mapping an agent name to its command/spec. Seeded
- * with exactly `claude` (default) and `cursor-agent`. `as const satisfies` keeps
+ * with `claude` (default), `cursor-agent`, and `codex`. `as const satisfies` keeps
  * the literal keys (so `AgentName` is a precise union) while type-checking each
  * value against `AgentSpec`.
  */
@@ -108,6 +108,20 @@ export const AGENT_REGISTRY = {
             premium: "claude-opus-4-8-thinking-high",
         },
     },
+    codex: {
+        name: "codex",
+        command: "codex",
+        promptArgStyle: "positional",
+        installHint: {
+            darwin: "npm install -g @openai/codex",
+            linux: "npm install -g @openai/codex",
+            win32: "npm install -g @openai/codex",
+        },
+        authNote: "Codex authenticates interactively on first run — follow its login prompt if asked.",
+        // The launch boundary validates a fresh Bridge catalog before injection.
+        supportsModelOverride: true,
+        modelFlag: "--model",
+    },
 };
 /** The default agent used when `--agent` is omitted. */
 export const DEFAULT_AGENT_NAME = "claude";
@@ -130,7 +144,7 @@ export function resolveAgentSpec(name) {
         return null;
     return AGENT_REGISTRY[resolved];
 }
-/** Comma-delimited valid agent names for CLI validation errors (`claude, cursor-agent`). */
+/** Comma-delimited registry names for CLI validation errors (`claude, cursor-agent, codex`). */
 export function formatValidAgentNames() {
     return listAgentNames().join(", ");
 }
@@ -154,10 +168,13 @@ export function resolveModelAlias(agent, tier, overrides) {
         return null;
     if (!tier)
         return null;
+    // Codex has no static or repository-override model authority.
+    if (agent.name === "codex")
+        return null;
     const override = overrides?.[tier];
     const candidate = typeof override === "string" && override.trim().length > 0
         ? override.trim()
-        : agent.tierModels[tier];
+        : agent.tierModels?.[tier];
     if (typeof candidate !== "string" || !isValidModelAlias(candidate))
         return null;
     if (agent.staticModelAliasAllowlist && !agent.staticModelAliasAllowlist.includes(candidate)) {

package/build/codex-launch-scope.js

@@ -0,0 +1,49 @@
+/** Per-process Codex MCP scope, derived from the same manifest and shim as worktree provisioning. */
+import { readBridgeConfig } from "./bridge-config.js";
+import os from "node:os";
+import { codexBridgeTableNames } from "./mcp-host-config.js";
+import { MCP_HOST_TARGETS, resolveHostTargetPath } from "./mcp-host-targets.js";
+import { buildMcpServerEntriesForManifest, normalizeWorktreePathForRegistration, } from "./mcp-provisioning.js";
+import { MCP_SERVER_NAME } from "./mcp-identity.js";
+function tomlEntry(entry) {
+    return `{ command = ${JSON.stringify(entry.command)}, args = [${entry.args.map((arg) => JSON.stringify(arg)).join(", ")}] }`;
+}
+/** A missing Bridge target is a launch failure, never a fallback to user-scoped config. */
+export async function resolveCodexLaunchScope(root, deps, codexConfigPath = resolveHostTargetPath(MCP_HOST_TARGETS.codex, { cwd: root, homedir: os.homedir() })) {
+    const normalized = normalizeWorktreePathForRegistration(root, deps);
+    if (!normalized.ok)
+        return { ok: false, error: "Codex MCP scope unavailable: invalid repository path." };
+    let manifest;
+    try {
+        const read = await readBridgeConfig(normalized.path, { readFile: deps.readFile });
+        if (!read.ok)
+            return { ok: false, error: "Codex MCP scope unavailable: .bridge/config is missing or invalid." };
+        manifest = read.manifest;
+    }
+    catch {
+        return { ok: false, error: "Codex MCP scope unavailable: could not read .bridge/config." };
+    }
+    const built = buildMcpServerEntriesForManifest(manifest, normalized.path, deps.mcpServerInvocation, deps.bridgeApiBaseUrl);
+    const bridge = built.entries[MCP_SERVER_NAME];
+    if (!bridge)
+        return { ok: false, error: "Codex MCP scope unavailable: .bridge/config has no Bridge target." };
+    let existingConfig = "";
+    try {
+        existingConfig = await deps.readFile(codexConfigPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            return { ok: false, error: "Codex MCP scope unavailable: could not inspect Codex host config." };
+        }
+    }
+    const registeredNames = codexBridgeTableNames(existingConfig);
+    if (registeredNames.length > 1) {
+        return { ok: false, error: "Codex MCP scope unavailable: duplicate Bridge registrations in Codex host config." };
+    }
+    const bridgeKey = registeredNames[0] ?? MCP_SERVER_NAME;
+    const argv = ["-C", normalized.path];
+    for (const [name, entry] of Object.entries(built.entries)) {
+        argv.push("-c", `mcp_servers.${name === MCP_SERVER_NAME ? bridgeKey : name}=${tomlEntry(entry)}`);
+    }
+    return { ok: true, argv };
+}

package/build/codex-skill-adapter.js

@@ -4,8 +4,8 @@
  * Codex discovers repository-local skills from `.agents/skills/<name>/SKILL.md`.
  * Bridge command sources use a standalone `$ARGUMENTS` marker, which is a
  * Claude/Cursor command convention rather than a Codex input variable. This
- * adapter replaces only that marker with the documented explicit-skill input
- * contract while retaining every other byte of the canonical workflow.
+ * adapter replaces that marker with the explicit-skill input contract and
+ * translates references to shipped slash commands into Codex skill names.
  */
 export const CODEX_SKILLS_DIR = ".agents/skills";
 function commandStem(filename) {
@@ -19,7 +19,7 @@ export function codexSkillNameForCommand(filename) {
     return `bridge-${commandStem(filename)}`;
 }
 /** Render the one Codex-native skill artifact for a canonical command. */
-export function renderCodexSkill(filename, command) {
+export function renderCodexSkill(filename, command, knownCommands = [commandStem(filename)]) {
     const stem = commandStem(filename);
     const skillName = codexSkillNameForCommand(filename);
     const invocation = `$${skillName}`;
@@ -28,10 +28,12 @@ export function renderCodexSkill(filename, command) {
         `Treat the text after \`${invocation}\` in the user's message as this workflow's input.`,
         "If no input follows the invocation, follow the canonical workflow's existing usage/error behavior.",
     ].join("\n");
+    const commandPattern = new RegExp(`(?<![A-Za-z0-9_./-])/(${knownCommands.join("|")})(?=[^A-Za-z0-9-]|$)`, "g");
     const adaptedCommand = command
         .split("\n")
         .map((line) => (line.trim() === "$ARGUMENTS" ? inputContract : line))
-        .join("\n");
+        .join("\n")
+        .replace(commandPattern, (_match, name) => `$bridge-${name}`);
     return {
         skillName,
         relativePath: `${CODEX_SKILLS_DIR}/${skillName}/SKILL.md`,
@@ -49,7 +51,8 @@ export function renderCodexSkill(filename, command) {
 }
 /** Build the complete, deterministically ordered Codex skill bundle. */
 export function codexSkillAssets(commands) {
+    const names = Object.keys(commands).map(commandStem).sort((a, b) => b.length - a.length);
     return Object.entries(commands)
         .sort(([left], [right]) => left.localeCompare(right))
-        .map(([filename, command]) => renderCodexSkill(filename, command));
+        .map(([filename, command]) => renderCodexSkill(filename, command, names));
 }

package/build/command-host.js

@@ -0,0 +1,9 @@
+/** Specialize the shared front-door command for a known installation host. */
+export function renderCommandForHost(filename, content, host) {
+    if (filename !== "review-and-start.md" || host !== "cursor")
+        return content;
+    const marker = "**Command host default: none.**";
+    if (!content.includes(marker))
+        throw new Error("review-and-start host default marker is missing");
+    return content.replace(marker, "**Command host default: cursor.**");
+}

package/build/command-provisioning.js

@@ -26,9 +26,11 @@
  */
 import path from "path";
 import { COMMANDS } from "./commands.generated.js";
+import { codexSkillAssets } from "./codex-skill-adapter.js";
 import { ensureGitInfoExcluded } from "./git-ignore-utils.js";
 /** The exact exclude entry appended for the command directory (POSIX-relative). */
 const COMMAND_DIR_EXCLUDE_ENTRY = ".claude/commands/";
+const CODEX_SKILLS_EXCLUDE_ENTRY = ".agents/skills/";
 /** Bounded, secret-free error surfaced when the packaged bundle is empty. */
 const EMPTY_BUNDLE_ERROR = "Command provisioning failed: the packaged command bundle is empty — reinstall or rebuild the MCP server package.";
 /**
@@ -51,7 +53,7 @@ function isEnoentError(err) {
  * for an expected filesystem/Git failure, and never leaks raw exception text,
  * command output, or file contents.
  */
-export async function provisionCommandsForWorktree(worktreeRoot, deps) {
+export async function provisionCommandsForWorktree(worktreeRoot, deps, includeCodexSkills = false) {
     const api = pathApiForCommandProvisioningPlatform(deps.platform);
     const normalizedRoot = api.isAbsolute(worktreeRoot)
         ? api.normalize(worktreeRoot)
@@ -97,6 +99,26 @@ export async function provisionCommandsForWorktree(worktreeRoot, deps) {
                 "Command provisioning failed: could not write one or more packaged command assets.";
         }
     }
+    // Codex launch requires the full bundle. Fill only, preserving customer assets.
+    if (!fillError && includeCodexSkills) {
+        try {
+            for (const asset of codexSkillAssets(COMMANDS)) {
+                const target = api.join(normalizedRoot, asset.relativePath);
+                try {
+                    await deps.readFile(target);
+                }
+                catch (err) {
+                    if (!isEnoentError(err))
+                        throw err;
+                    await deps.mkdir(api.dirname(target), { recursive: true });
+                    await deps.writeFile(target, asset.content);
+                }
+            }
+        }
+        catch {
+            fillError = "Command provisioning failed: could not write one or more Codex skill assets.";
+        }
+    }
     // Phase 3 — ALWAYS attempt exclusion, even after a partial or failed fill, so
     // partially bootstrapped files are never left visible to Git. The primary fill
     // failure is preserved if both the fill and the exclusion fail.
@@ -109,10 +131,19 @@ export async function provisionCommandsForWorktree(worktreeRoot, deps) {
             runCommand: deps.runCommand,
             platform: deps.platform,
         });
+        if (includeCodexSkills) {
+            await ensureGitInfoExcluded(normalizedRoot, CODEX_SKILLS_EXCLUDE_ENTRY, {
+                readFile: deps.readFile,
+                writeFile: deps.writeFile,
+                mkdir: deps.mkdir,
+                runCommand: deps.runCommand,
+                platform: deps.platform,
+            });
+        }
     }
     catch {
         excludeError =
-            "Command provisioning failed: could not add '.claude/commands/' to the worktree Git exclude file.";
+            "Command provisioning failed: could not add generated command assets to the worktree Git exclude file.";
     }
     if (fillError)
         return { ok: false, error: fillError };
@@ -129,7 +160,7 @@ export async function provisionCommandsForWorktree(worktreeRoot, deps) {
  * proceed. A defensive per-row catch guarantees one unexpected failure cannot
  * abort later rows or reject the overall call.
  */
-export async function provisionCommandsForCreatedWorktrees(rows, deps) {
+export async function provisionCommandsForCreatedWorktrees(rows, deps, includeCodexSkills = false) {
     const out = [];
     for (const row of rows) {
         if (row.status !== "created" || !row.path) {
@@ -137,7 +168,7 @@ export async function provisionCommandsForCreatedWorktrees(rows, deps) {
             continue;
         }
         try {
-            const result = await provisionCommandsForWorktree(row.path, deps);
+            const result = await provisionCommandsForWorktree(row.path, deps, includeCodexSkills);
             if (result.ok) {
                 out.push(row);
             }