agent-dealer 0.2.0 → 1.0.0

package/bundle/server/dist/adapters/linear-inbox.test.js

@@ -0,0 +1,35 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildIssueFilter, parseLinearIssueRef } from "./linear-inbox.js";
+test("parseLinearIssueRef accepts identifier, URL, and UUID", () => {
+    assert.equal(parseLinearIssueRef("NOT-103"), "NOT-103");
+    assert.equal(parseLinearIssueRef("  not-90  "), "NOT-90");
+    assert.equal(parseLinearIssueRef("https://linear.app/not-so-fat/issue/NOT-103/sequential-issue-queue"), "NOT-103");
+    assert.equal(parseLinearIssueRef("7a2e7533-65f8-4752-a903-d419f47b2093"), "7a2e7533-65f8-4752-a903-d419f47b2093");
+    assert.equal(parseLinearIssueRef(""), null);
+    assert.equal(parseLinearIssueRef("not a ticket"), null);
+});
+test("buildIssueFilter omits assignee when assigneeMe is false", () => {
+    const filter = buildIssueFilter({
+        stateFilter: ["Backlog", "Todo", "In Progress", "In Review"],
+        teamId: "team-1",
+        assigneeMe: false,
+        syncEnabled: true,
+    }, "viewer-1");
+    assert.deepEqual(filter, {
+        state: { name: { in: ["Backlog", "Todo", "In Progress", "In Review"] } },
+        team: { id: { eq: "team-1" } },
+    });
+});
+test("buildIssueFilter includes assignee when assigneeMe is true", () => {
+    const filter = buildIssueFilter({
+        stateFilter: ["Todo"],
+        teamId: null,
+        assigneeMe: true,
+        syncEnabled: true,
+    }, "viewer-1");
+    assert.deepEqual(filter, {
+        state: { name: { in: ["Todo"] } },
+        assignee: { id: { eq: "viewer-1" } },
+    });
+});

package/bundle/server/dist/adapters/linear-sync.js

@@ -1,13 +1,9 @@
-import { addArtifact, getLatestArtifact, listArtifacts } from "../repository/runs.js";
+import { addArtifact } from "../repository/runs.js";
 import { getLinearIntakeConfig } from "../repository/intake-settings.js";
 import { getLinearIssue } from "./linear-inbox.js";
 const LINEAR_API = "https://api.linear.app/graphql";
 const STATE_BY_EVENT = {
     // TODO(P2): configurable per team — see docs/LINEAR_INTEGRATION.md
-    planning_started: "Todo",
-    plan_approved: "In Progress",
-    review: "In Review",
-    retry: "In Progress",
     done: "Done",
 };
 const workflowStateCache = new Map();
@@ -56,87 +52,9 @@ async function issueUpdateState(issueId, stateId) {
       issueUpdate(id: $issueId, input: { stateId: $stateId }) { success }
     }`, { issueId, stateId });
 }
-function planExcerpt(run) {
-    const plan = getLatestArtifact(run.id, "approved_plan");
-    if (!plan?.contentJson)
-        return "";
-    try {
-        const parsed = JSON.parse(plan.contentJson);
-        const md = parsed.markdown?.trim() ?? "";
-        return md.length > 600 ? `${md.slice(0, 600)}…` : md;
-    }
-    catch {
-        return "";
-    }
-}
-function resultExcerpt(run) {
-    const result = getLatestArtifact(run.id, "execution_result");
-    if (result?.contentJson) {
-        try {
-            const parsed = JSON.parse(result.contentJson);
-            const text = parsed.resultText?.trim() ?? "";
-            if (text)
-                return text.length > 500 ? `${text.slice(0, 500)}…` : text;
-        }
-        catch {
-            /* fall through */
-        }
-    }
-    const doc = listArtifacts(run.id).find((a) => a.kind === "document");
-    if (doc?.contentJson) {
-        try {
-            const parsed = JSON.parse(doc.contentJson);
-            const text = parsed.markdown?.trim() ?? "";
-            if (text)
-                return text.length > 500 ? `${text.slice(0, 500)}…` : text;
-        }
-        catch {
-            /* ignore */
-        }
-    }
-    return "";
-}
-function buildComment(run, event) {
+function buildComment(run) {
     const label = run.externalLabel ?? run.externalId ?? run.id;
     const link = `${webBaseUrl()}/?run=${run.id}`;
-    if (event === "planning_started") {
-        return [
-            `**agent-dealer** — planning started for ${label}`,
-            ``,
-            `_Agent is drafting a plan._`,
-            ``,
-            `[Open run](${link})`,
-        ].join("\n");
-    }
-    if (event === "plan_approved") {
-        const excerpt = planExcerpt(run);
-        return [
-            `**agent-dealer** — plan approved for ${label}`,
-            ``,
-            excerpt ? excerpt : `_Plan approved — see run for details._`,
-            ``,
-            `[Open run](${link})`,
-        ].join("\n");
-    }
-    if (event === "review") {
-        const excerpt = resultExcerpt(run);
-        return [
-            `**agent-dealer** — execution complete, awaiting review (${label})`,
-            ``,
-            excerpt ? excerpt : `_Result ready for human review._`,
-            ``,
-            `[Review run](${link})`,
-        ].join("\n");
-    }
-    if (event === "retry") {
-        return [
-            `**agent-dealer** — retry requested for ${label}`,
-            ``,
-            `_Re-executing with human feedback._`,
-            ``,
-            `[Open run](${link})`,
-        ].join("\n");
-    }
     return [
         `**agent-dealer** — approved and marked done (${label})`,
         ``,
@@ -146,28 +64,12 @@ function buildComment(run, event) {
 function recordSyncAttempt(run, event, ok, detail) {
     addArtifact(run.id, "linear_sync", { event, ok, at: new Date().toISOString(), ...detail }, "system");
 }
-function hasSuccessfulSync(runId, event) {
-    return listArtifacts(runId).some((a) => {
-        if (a.kind !== "linear_sync" || !a.contentJson)
-            return false;
-        try {
-            const parsed = JSON.parse(a.contentJson);
-            return parsed.event === event && parsed.ok === true;
-        }
-        catch {
-            return false;
-        }
-    });
-}
 /** Non-blocking Linear write-back — callers should `.catch()` and never fail the human action. */
 export async function syncLinearForRun(run, event) {
     const settings = getLinearIntakeConfig();
     if (!settings.syncEnabled || !process.env.LINEAR_API_KEY || !run.externalId) {
         return;
     }
-    if (event === "planning_started" && hasSuccessfulSync(run.id, event)) {
-        return;
-    }
     const issue = await getLinearIssue(run.externalId);
     if (!issue?.teamId) {
         recordSyncAttempt(run, event, false, { error: "Issue or teamId not found" });
@@ -177,7 +79,7 @@ export async function syncLinearForRun(run, event) {
     const states = await getWorkflowStates(issue.teamId);
     const stateId = states.get(targetStateName.toLowerCase());
     try {
-        await commentCreate(run.externalId, buildComment(run, event));
+        await commentCreate(run.externalId, buildComment(run));
         if (stateId) {
             await issueUpdateState(run.externalId, stateId);
         }

package/bundle/server/dist/adapters/managed-repo.js

@@ -0,0 +1,168 @@
+// packages/server/src/adapters/managed-repo.ts
+//
+// NOT-149: Dealer owns local clones and session worktrees. Issues store a portable
+// GitHub identity (`github.com/owner/repo`); this module resolves that into a
+// deterministic checkout under executionRoot. Legacy issue.repo values that are still
+// local filesystem paths are recoverable only when the path still exists — never by
+// guessing a remote from a missing origin.
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { looksLikeLocalRepoPath, parseGitHubRepoInput, } from "@agent-dealer/shared";
+import { getExecutionRoot } from "../paths.js";
+import { withRepoLock } from "../runners/process-registry.js";
+const run = promisify(execFile);
+async function git(cwd, args) {
+    try {
+        const result = await run("git", args, { ...(cwd ? { cwd } : {}), encoding: "utf8" });
+        return { stdout: String(result.stdout), stderr: String(result.stderr) };
+    }
+    catch (err) {
+        const e = err;
+        throw new Error(`git ${args.join(" ")} failed: ${e.stderr?.trim() || e.message}`);
+    }
+}
+export function managedRepoPath(identity) {
+    return path.join(getExecutionRoot(), "repos", identity);
+}
+export function managedWorktreePath(identity, sessionId, role) {
+    return path.join(getExecutionRoot(), "worktrees", identity, `${sessionId}-${role}`);
+}
+export function managedWorktreesRoot(identity) {
+    return path.join(getExecutionRoot(), "worktrees", identity);
+}
+/**
+ * Classify an issue.repo value without cloning. Throws when a legacy local path is
+ * gone or when a non-local value is not a valid GitHub identity.
+ */
+export function classifyIssueRepo(repoField) {
+    const trimmed = repoField.trim();
+    if (looksLikeLocalRepoPath(trimmed)) {
+        if (!fs.existsSync(trimmed)) {
+            throw new Error(`Legacy issue repo path is missing (${trimmed}). Re-create the issue with a GitHub URL, or restore the checkout — Dealer will not guess a remote.`);
+        }
+        return { kind: "legacy_local", repoPath: trimmed, identity: null };
+    }
+    const parsed = parseGitHubRepoInput(trimmed);
+    return {
+        kind: "managed",
+        identity: parsed.identity,
+        parsed,
+        repoPath: managedRepoPath(parsed.identity),
+    };
+}
+/**
+ * Ensure a managed clone exists and is fetched; return the local path to use as the
+ * git worktree parent. For legacy local-path issues, returns the existing path as-is.
+ *
+ * When `cloneUrlOverride` is set (tests), clones from that URL/path instead of GitHub.
+ */
+export async function ensureIssueRepoCheckout(repoField, opts) {
+    const classified = classifyIssueRepo(repoField);
+    if (classified.kind === "legacy_local") {
+        return classified;
+    }
+    const dest = classified.repoPath;
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const cloneUrl = opts?.cloneUrlOverride ?? classified.parsed.cloneUrl;
+    // Serialize clone/fetch against the shared managed clone — same lock createRoleWorktree
+    // uses — so two issues on one GitHub repo cannot race the first clone or prune fetch.
+    return withRepoLock(dest, async () => {
+        if (!fs.existsSync(path.join(dest, ".git")) && !fs.existsSync(path.join(dest, "HEAD"))) {
+            // Prefer a regular clone (not bare) so existing worktree helpers that expect a
+            // working tree + .git directory keep working; worktrees still hang off this repo.
+            await git(undefined, ["clone", "--filter=blob:none", cloneUrl, dest]);
+        }
+        else {
+            // Refresh remotes; ignore failure when offline — local objects may still suffice.
+            try {
+                await git(dest, ["fetch", "--prune", "origin"]);
+            }
+            catch {
+                /* keep cached clone */
+            }
+        }
+        let defaultBranch;
+        if (opts?.fetchDefaultBranch !== false) {
+            defaultBranch = await resolveRemoteDefaultBranch(dest);
+        }
+        return { ...classified, defaultBranch };
+    });
+}
+/** Read origin/HEAD or fall back to main/master. */
+export async function resolveRemoteDefaultBranch(repoPath) {
+    try {
+        const { stdout } = await git(repoPath, ["symbolic-ref", "refs/remotes/origin/HEAD"]);
+        const m = stdout.trim().match(/refs\/remotes\/origin\/(.+)$/);
+        if (m?.[1])
+            return m[1];
+    }
+    catch {
+        /* fall through */
+    }
+    for (const candidate of ["main", "master"]) {
+        try {
+            await git(repoPath, ["show-ref", "--verify", "--quiet", `refs/remotes/origin/${candidate}`]);
+            return candidate;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    try {
+        const { stdout } = await git(repoPath, ["rev-parse", "--abbrev-ref", "HEAD"]);
+        const branch = stdout.trim();
+        if (branch && branch !== "HEAD")
+            return branch;
+    }
+    catch {
+        /* fall through */
+    }
+    return "main";
+}
+/**
+ * Try to derive a portable GitHub identity from a legacy local checkout's `origin`.
+ * Returns null when origin is missing or not GitHub — callers must surface that to the
+ * operator instead of inventing a remote.
+ */
+export async function tryResolveOriginGitHubIdentity(localRepoPath) {
+    try {
+        const { stdout } = await git(localRepoPath, ["remote", "get-url", "origin"]);
+        const url = stdout.trim();
+        if (!url)
+            return null;
+        return parseGitHubRepoInput(url).identity;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Where role worktrees live for a resolved issue checkout (managed or legacy).
+ * Managed: `<executionRoot>/worktrees/github.com/<owner>/<repo>`
+ * Legacy: `<repo>/.agent-dealer-worktrees` (pre-NOT-149 layout, still recoverable).
+ */
+export function worktreesRootForResolution(resolution) {
+    if (resolution.kind === "managed") {
+        return managedWorktreesRoot(resolution.identity);
+    }
+    return path.join(resolution.repoPath, ".agent-dealer-worktrees");
+}
+export function roleWorktreePathForResolution(resolution, sessionId, role) {
+    if (resolution.kind === "managed") {
+        return managedWorktreePath(resolution.identity, sessionId, role);
+    }
+    return path.join(worktreesRootForResolution(resolution), `${sessionId}-${role}`);
+}
+/**
+ * Single base-branch rule for worktree cut, PR create/identity, and review merge-base (NOT-149).
+ * Managed checkouts use the freshly fetched remote default; legacy local paths keep
+ * `issue.baseBranch`. Call sites must not invent a second rule.
+ */
+export function resolveCheckoutBaseBranch(issueBaseBranch, checkout) {
+    if (checkout.kind === "managed" && checkout.defaultBranch) {
+        return checkout.defaultBranch;
+    }
+    return issueBaseBranch;
+}

package/bundle/server/dist/adapters/managed-repo.test.js

@@ -0,0 +1,63 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-managed-repo-"));
+const { migrate } = await import("../db/index.js");
+migrate();
+const { classifyIssueRepo, ensureIssueRepoCheckout, managedRepoPath, managedWorktreePath, resolveRemoteDefaultBranch, tryResolveOriginGitHubIdentity, } = await import("./managed-repo.js");
+const { getExecutionRoot } = await import("../paths.js");
+function initFixtureRepo() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fixture-repo-"));
+    execFileSync("git", ["init", "-b", "main"], { cwd: dir });
+    execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: dir });
+    execFileSync("git", ["config", "user.name", "Test"], { cwd: dir });
+    fs.writeFileSync(path.join(dir, "README.md"), "hi\n");
+    execFileSync("git", ["add", "."], { cwd: dir });
+    execFileSync("git", ["commit", "-m", "init"], { cwd: dir });
+    return dir;
+}
+test("resolveCheckoutBaseBranch: managed uses remote default; legacy keeps issue base", async () => {
+    const { resolveCheckoutBaseBranch } = await import("./managed-repo.js");
+    assert.equal(resolveCheckoutBaseBranch("develop", { kind: "managed", defaultBranch: "main" }), "main");
+    assert.equal(resolveCheckoutBaseBranch("develop", { kind: "legacy_local" }), "develop");
+    assert.equal(resolveCheckoutBaseBranch("main", { kind: "managed" }), "main");
+});
+test("classifyIssueRepo: GitHub identity maps to managed path under execution root", () => {
+    const r = classifyIssueRepo("acme/app");
+    assert.equal(r.kind, "managed");
+    if (r.kind === "managed") {
+        assert.equal(r.identity, "github.com/acme/app");
+        assert.equal(r.repoPath, path.join(getExecutionRoot(), "repos", "github.com/acme/app"));
+        assert.equal(managedRepoPath(r.identity), r.repoPath);
+        assert.equal(managedWorktreePath(r.identity, "sess-1", "developer"), path.join(getExecutionRoot(), "worktrees", "github.com/acme/app", "sess-1-developer"));
+    }
+});
+test("classifyIssueRepo: legacy local path is recoverable when present, errors when missing", () => {
+    const fixture = initFixtureRepo();
+    const ok = classifyIssueRepo(fixture);
+    assert.equal(ok.kind, "legacy_local");
+    if (ok.kind === "legacy_local")
+        assert.equal(ok.repoPath, fixture);
+    assert.throws(() => classifyIssueRepo(path.join(os.tmpdir(), "missing-dealer-repo-xyz")), /Legacy issue repo path is missing/);
+});
+test("ensureIssueRepoCheckout clones from override into managed layout and reads default branch", async () => {
+    const fixture = initFixtureRepo();
+    const resolved = await ensureIssueRepoCheckout("test-org/fixture-app", {
+        cloneUrlOverride: fixture,
+    });
+    assert.equal(resolved.kind, "managed");
+    assert.ok(fs.existsSync(path.join(resolved.repoPath, ".git")));
+    assert.equal(resolved.defaultBranch, "main");
+    assert.equal(await resolveRemoteDefaultBranch(resolved.repoPath), "main");
+});
+test("tryResolveOriginGitHubIdentity returns null when origin is not GitHub", async () => {
+    const fixture = initFixtureRepo();
+    assert.equal(await tryResolveOriginGitHubIdentity(fixture), null);
+    execFileSync("git", ["remote", "add", "origin", "https://github.com/acme/from-origin.git"], {
+        cwd: fixture,
+    });
+    assert.equal(await tryResolveOriginGitHubIdentity(fixture), "github.com/acme/from-origin");
+});

package/bundle/server/dist/adapters/outbound-delivery.js

@@ -0,0 +1,83 @@
+// packages/server/src/adapters/outbound-delivery.ts
+//
+// Deck-header delivery of an approved outbound draft (NOT-106 / NOT-95). The coordinator
+// connects to Agent Deck's MCP with `x-agent-deck-deck-id` (no Authorization). An ambiguous
+// transport failure (request may have reached the provider) is never silently retried.
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { assertCallServiceToolSuccess, extractPermalink, getAgentDeckMcpUrl, toCallServiceToolPayload, } from "./agent-deck.js";
+const TIMEOUT_MESSAGE_RE = /timed out after \d+ms$/;
+/** Thrown for every transport failure, typed by whether the request may already have reached
+ * Deck's `call_service_tool` (NOT-95). */
+export class OutboundDeliveryTransportError extends Error {
+    dispatched;
+    constructor(message, dispatched) {
+        super(message);
+        this.name = "OutboundDeliveryTransportError";
+        this.dispatched = dispatched;
+    }
+}
+/** Connects with the deck header and calls `call_service_tool` exactly once. */
+export async function callServiceToolOnDeck(opts) {
+    const mcpBase = getAgentDeckMcpUrl().replace(/\/mcp\/?$/, "");
+    const transport = new StreamableHTTPClientTransport(new URL(`${mcpBase}/mcp`), {
+        requestInit: {
+            headers: { "x-agent-deck-deck-id": opts.deckId },
+        },
+    });
+    const client = new Client({ name: "agent-dealer-deliver", version: "0.0.1" });
+    const connectAndCall = async () => {
+        try {
+            await client.connect(transport);
+        }
+        catch (e) {
+            throw new OutboundDeliveryTransportError(e instanceof Error ? e.message : String(e), false);
+        }
+        try {
+            return await client.callTool({ name: "call_service_tool", arguments: opts.payload });
+        }
+        catch (e) {
+            throw new OutboundDeliveryTransportError(e instanceof Error ? e.message : String(e), true);
+        }
+        finally {
+            await client.close().catch(() => { });
+        }
+    };
+    return await Promise.race([
+        connectAndCall(),
+        new Promise((_, reject) => setTimeout(() => reject(new OutboundDeliveryTransportError(`Outbound deliver timed out after ${opts.timeoutMs}ms`, true)), opts.timeoutMs)),
+    ]);
+}
+/**
+ * Delivers one approved outbound draft under the profile/run deck header. Never throws —
+ * failures come back typed so the caller can park only on `ambiguous` (NOT-95).
+ */
+export async function deliverOutboundDraft(deckId, toolCall, opts) {
+    const payload = toCallServiceToolPayload(toolCall);
+    const timeoutMs = opts?.timeoutMs ?? Number(process.env.DELIVER_TIMEOUT_MS ?? 60_000);
+    const callTool = opts?.callTool ?? ((p) => callServiceToolOnDeck({ deckId, payload: p, timeoutMs }));
+    let toolResult;
+    try {
+        toolResult = await callTool(payload);
+    }
+    catch (err) {
+        if (err instanceof OutboundDeliveryTransportError) {
+            if (err.dispatched) {
+                return { ok: false, kind: "ambiguous", reason: `${err.message} — whether the message was actually sent is unknown` };
+            }
+            return { ok: false, kind: "infra_failure", reason: err.message };
+        }
+        const reason = err instanceof Error ? err.message : String(err);
+        if (TIMEOUT_MESSAGE_RE.test(reason)) {
+            return { ok: false, kind: "ambiguous", reason: `${reason} — whether the message was actually sent is unknown` };
+        }
+        return { ok: false, kind: "infra_failure", reason };
+    }
+    try {
+        assertCallServiceToolSuccess(toolResult);
+    }
+    catch (err) {
+        return { ok: false, kind: "infra_failure", reason: err instanceof Error ? err.message : String(err) };
+    }
+    return { ok: true, toolResult, permalink: extractPermalink(toolResult) };
+}

package/bundle/server/dist/adapters/outbound-delivery.test.js

@@ -0,0 +1,53 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { deliverOutboundDraft, OutboundDeliveryTransportError } from "./outbound-delivery.js";
+const DECK = "deck-test-1";
+const TOOL_CALL = { serviceName: "slack", toolName: "chat_postMessage", arguments: {} };
+test("a pre-dispatch transport failure (never reached Deck) is an ordinary infra failure", async () => {
+    const result = await deliverOutboundDraft(DECK, TOOL_CALL, {
+        callTool: async () => {
+            throw new OutboundDeliveryTransportError("connect ECONNREFUSED", false);
+        },
+    });
+    assert.equal(result.ok, false);
+    if (!result.ok)
+        assert.equal(result.kind, "infra_failure");
+});
+test("a post-dispatch transport failure (e.g. ECONNRESET after callTool started) is ambiguous, never auto-retried", async () => {
+    const result = await deliverOutboundDraft(DECK, TOOL_CALL, {
+        callTool: async () => {
+            throw new OutboundDeliveryTransportError("read ECONNRESET", true);
+        },
+    });
+    assert.equal(result.ok, false);
+    if (!result.ok)
+        assert.equal(result.kind, "ambiguous");
+});
+test("the race timeout is ambiguous", async () => {
+    const result = await deliverOutboundDraft(DECK, TOOL_CALL, {
+        callTool: async () => {
+            throw new OutboundDeliveryTransportError("Outbound deliver timed out after 60000ms", true);
+        },
+    });
+    assert.equal(result.ok, false);
+    if (!result.ok)
+        assert.equal(result.kind, "ambiguous");
+});
+test("a plain Error from a legacy callTool seam falls back to the timeout-text heuristic", async () => {
+    const timedOut = await deliverOutboundDraft(DECK, TOOL_CALL, {
+        callTool: async () => {
+            throw new Error("Outbound deliver timed out after 60000ms");
+        },
+    });
+    assert.equal(timedOut.ok, false);
+    if (!timedOut.ok)
+        assert.equal(timedOut.kind, "ambiguous");
+    const other = await deliverOutboundDraft(DECK, TOOL_CALL, {
+        callTool: async () => {
+            throw new Error("some other failure");
+        },
+    });
+    assert.equal(other.ok, false);
+    if (!other.ok)
+        assert.equal(other.kind, "infra_failure");
+});

package/bundle/server/dist/adapters/reflect-authority.js

@@ -0,0 +1,43 @@
+// packages/server/src/adapters/reflect-authority.ts
+//
+// Deck-header Agent Deck MCP calls for coordinator-side post-review reflection (NOT-106).
+// Reflection runs after the issue's workflow instance is already terminal — there is no
+// worker/worktree to hand a per-attempt MCP config to, so the coordinator process itself
+// connects with `x-agent-deck-deck-id` (no Authorization).
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { getAgentDeckMcpUrl } from "./agent-deck.js";
+import { assertToolResultOk, parseDeckToolResult, } from "./agent-deck-bind.js";
+/** One-shot: connect under the deck header, run `fn`, always close. */
+export async function withDeckClient(deckId, timeoutMs, fn) {
+    const mcpBase = getAgentDeckMcpUrl().replace(/\/mcp\/?$/, "");
+    const transport = new StreamableHTTPClientTransport(new URL(`${mcpBase}/mcp`), {
+        requestInit: { headers: { "x-agent-deck-deck-id": deckId } },
+    });
+    const client = new Client({ name: "agent-dealer-reflect", version: "0.0.1" });
+    await client.connect(transport);
+    try {
+        const callTool = (name, args) => Promise.race([
+            client.callTool({ name, arguments: args }),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`${name} timed out after ${timeoutMs}ms`)), timeoutMs)),
+        ]);
+        return await fn(callTool);
+    }
+    finally {
+        await client.close();
+    }
+}
+/**
+ * Call one Deck MCP tool under the launch deck header. Never throws — network/timeout/
+ * tool errors become `infra_failure`.
+ */
+export async function callDeckTool(opts) {
+    try {
+        const result = await withDeckClient(opts.deckId, opts.timeoutMs, (callTool) => callTool(opts.toolName, opts.arguments));
+        assertToolResultOk(result, opts.toolName);
+        return { ok: true, data: parseDeckToolResult(result) };
+    }
+    catch (err) {
+        return { ok: false, kind: "infra_failure", reason: err.message ?? String(err) };
+    }
+}

package/bundle/server/dist/cli-env.js

@@ -75,3 +75,29 @@ export function cursorBinExists() {
     const bin = resolveCursorBin();
     return bin !== "cursor-agent" && bin !== "cursor" ? fs.existsSync(bin) : false;
 }
+/** Resolve Codex CLI binary (`codex` from OpenAI Codex install). */
+export function resolveCodexBin() {
+    const home = process.env.HOME ?? os.homedir();
+    if (process.env.CODEX_CLI)
+        return process.env.CODEX_CLI;
+    return (firstExisting([
+        path.join(home, ".local/bin/codex"),
+        path.join(home, ".codex/bin/codex"),
+        "/opt/homebrew/bin/codex",
+        "/usr/local/bin/codex",
+    ]) ?? "codex");
+}
+export function codexBinExists() {
+    const bin = resolveCodexBin();
+    return bin !== "codex" ? fs.existsSync(bin) : false;
+}
+/**
+ * Where codex itself would look for `config.toml` *and* its file-backed login
+ * credentials (`auth.json`) absent an override — mirrors codex's own default
+ * (`$CODEX_HOME`, else `~/.codex`). Used by `agent-deck-bind.ts` to find `auth.json` to
+ * carry into a per-attempt isolated `CODEX_HOME` (config.toml there is deliberately
+ * *not* copied — that's the ambient MCP config execution authority exists to replace).
+ */
+export function resolveAmbientCodexHome() {
+    return process.env.CODEX_HOME ?? path.join(process.env.HOME ?? os.homedir(), ".codex");
+}

package/bundle/server/dist/cli-env.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { cursorInvokeArgs } from "./cli-env.js";
+import { cursorInvokeArgs, resolveCodexBin } from "./cli-env.js";
 test("cursorInvokeArgs passes through for cursor-agent", () => {
     const prev = process.env.CURSOR_CLI;
     process.env.CURSOR_CLI = "/home/user/.local/bin/cursor-agent";
@@ -28,3 +28,16 @@ test("cursorInvokeArgs prepends agent subcommand for legacy cursor shim", () =>
             process.env.CURSOR_CLI = prev;
     }
 });
+test("resolveCodexBin respects CODEX_CLI override", () => {
+    const prev = process.env.CODEX_CLI;
+    process.env.CODEX_CLI = "/tmp/custom-codex";
+    try {
+        assert.equal(resolveCodexBin(), "/tmp/custom-codex");
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.CODEX_CLI;
+        else
+            process.env.CODEX_CLI = prev;
+    }
+});