@miraland-labs/conduit-bridge 0.1.0

package/dist/driver.js

@@ -0,0 +1,201 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+export const evidenceKinds = ["change", "test", "preview", "research", "documentation"];
+/** Grants → Claude Code tool allow-list. Privileged grants are never mapped. */
+export function claudeToolsForGrants(grants, verificationCommands = []) {
+    const tools = [];
+    if (grants.includes("repo_read"))
+        tools.push("Read", "Glob", "Grep");
+    if (grants.includes("repo_write"))
+        tools.push("Edit", "Write");
+    if (grants.includes("test_run")) {
+        tools.push(...verificationCommands.filter(isBoundedVerificationCommand).map((command) => `Bash(${command}:*)`));
+    }
+    if (grants.includes("branch_create")) {
+        tools.push("Bash(git status:*)", "Bash(git diff:*)", "Bash(git add:*)", "Bash(git commit:*)", "Bash(git branch:*)", "Bash(git switch:*)");
+    }
+    if (grants.includes("pr_create"))
+        tools.push("Bash(git push:*)", "Bash(gh pr create:*)");
+    return tools;
+}
+export const claudeDeniedTools = [
+    "Bash(git merge:*)", "Bash(git rebase:*)", "Bash(git reset --hard:*)", "Bash(git push --force:*)",
+    "Bash(npm run deploy:*)", "Bash(pnpm deploy:*)", "Bash(yarn deploy:*)", "Bash(wrangler deploy:*)",
+    "Bash(kubectl:*)", "Bash(terraform apply:*)",
+];
+function isBoundedVerificationCommand(command) {
+    return /^(npm run (verify|typecheck|lint|test|build)|pnpm (verify|typecheck|lint|test|build)|yarn (verify|typecheck|lint|test|build)|cargo (test|check)|go test(?: \.\/\.\.\.)?|make (test|check))$/.test(command);
+}
+export function buildAssignmentPrompt(context) {
+    const packageContext = context.workPackage;
+    const spec = context.spec;
+    const role = packageContext?.work_role ?? spec.work_role ?? "implement";
+    const goal = packageContext?.goal ?? spec.goal ?? context.objective;
+    const scope = packageContext?.scope?.length ? packageContext.scope : spec.scope;
+    const boundaries = packageContext?.boundaries?.length ? packageContext.boundaries : spec.boundaries;
+    const acceptance = packageContext?.acceptance?.length ? packageContext.acceptance : spec.acceptance;
+    const changeScope = packageContext?.change_scope?.length ? packageContext.change_scope : spec.change_scope;
+    const evidence = packageContext?.required_evidence?.length ? packageContext.required_evidence : spec.required_evidence;
+    const rework = packageContext?.rework_feedback ?? context.reworkFeedback;
+    const lines = [
+        `You are completing one delegated Conduit assignment as the ${role} role. Work only inside the current workspace.`,
+        "",
+        `GOAL\n${goal}`,
+    ];
+    if (packageContext?.initiative?.title || packageContext?.initiative?.desired_outcome) {
+        lines.push("", "INITIATIVE CONTEXT");
+        if (packageContext.initiative.title)
+            lines.push(`- Title: ${packageContext.initiative.title}`);
+        if (packageContext.initiative.desired_outcome)
+            lines.push(`- Desired outcome: ${packageContext.initiative.desired_outcome}`);
+    }
+    if (scope?.length)
+        lines.push("", `SCOPE\n${scope.map((item) => `- ${item}`).join("\n")}`);
+    if (boundaries?.length)
+        lines.push("", `BOUNDARIES — never violate these\n${boundaries.map((item) => `- ${item}`).join("\n")}`);
+    if (acceptance?.length)
+        lines.push("", `ACCEPTANCE CRITERIA — the delivery is judged against these\n${acceptance.map((item) => `- ${item}`).join("\n")}`);
+    if (evidence?.length)
+        lines.push("", `REQUIRED EVIDENCE\n${evidence.map((item) => `- ${item}`).join("\n")}`);
+    if (changeScope?.length)
+        lines.push("", `CHANGE SCOPE — only modify paths under\n${changeScope.map((item) => `- ${item}`).join("\n")}`);
+    if (spec.repository?.base_commit)
+        lines.push("", `The workspace is expected to be at or after base commit ${spec.repository.base_commit}.`);
+    if (context.currentHead)
+        lines.push(`The workspace is currently at commit ${context.currentHead}; treat that as the true current state.`);
+    if (packageContext?.decisions?.length) {
+        lines.push("", "PROJECT DECISIONS (explicit human decisions — treat as binding context)", ...packageContext.decisions.map((item) => `- Q: ${item.question}\n  A: ${item.decision}`));
+    }
+    if (rework)
+        lines.push("", `REWORK FEEDBACK — an independent review returned this delivery; address every point\n${rework}`);
+    lines.push("", "RULES", "- Stay within the change scope and boundaries.", "- Run the relevant verification commands if your permissions allow it, and report their real results.", "- Never merge, deploy, push to protected branches, or touch production.", "- Do not invent evidence. Report unknown when you could not verify a criterion.", "", "When the work is finished, end your reply with exactly one fenced ```json block:", '{"outcome": "one-paragraph summary", "changes": ["path — what changed"], "verification": ["command — result"], "acceptance_results": [{"criterion": "exact criterion text", "status": "met|not_met|unknown"}], "evidence": [{"kind": "change|test|preview|research|documentation", "name": "concise evidence name", "uri": "external URL if one exists", "digest": "optional digest", "details": ["observable result"], "acceptance_criteria": ["exact criterion text supported by this evidence"]}], "assumptions": [], "risks": [], "limitations": [], "head_commit": "full sha of your final commit, omit if none"}');
+    return lines.join("\n");
+}
+/** Parse the agent's final fenced JSON block into a bounded report. */
+export function parseAgentReport(text, acceptance) {
+    const blocks = [...text.matchAll(/```json\s*([\s\S]*?)```/g)];
+    const last = blocks.at(-1)?.[1];
+    if (!last)
+        throw new Error("Agent did not emit the required structured report");
+    let raw;
+    try {
+        raw = JSON.parse(last);
+    }
+    catch {
+        throw new Error("Agent emitted malformed report JSON");
+    }
+    const stringList = z.array(z.string().trim().min(1).max(4_000)).max(100);
+    const parsed = z.object({
+        outcome: z.string().trim().min(1).max(20_000),
+        changes: stringList,
+        verification: stringList,
+        acceptance_results: z.array(z.object({ criterion: z.string().trim().min(1).max(4_000), status: z.enum(["met", "not_met", "unknown"]) })).max(100),
+        evidence: z.array(z.object({
+            kind: z.enum(evidenceKinds), name: z.string().trim().min(1).max(500), uri: z.string().url().max(4_000).optional(),
+            digest: z.string().trim().min(1).max(500).optional(), details: stringList, acceptance_criteria: stringList,
+        })).max(100),
+        assumptions: stringList, risks: stringList, limitations: stringList,
+        head_commit: z.string().regex(/^[0-9a-f]{7,64}$/i).optional(),
+        pull_request_url: z.string().url().max(4_000).optional(),
+    }).strict().safeParse(raw);
+    if (!parsed.success)
+        throw new Error(`Agent report is invalid: ${parsed.error.issues[0]?.message ?? "unknown validation error"}`);
+    const reported = parsed.data.acceptance_results.map((item) => item.criterion);
+    if (new Set(reported).size !== reported.length || acceptance.some((criterion) => !reported.includes(criterion))) {
+        throw new Error("Agent report must include every acceptance criterion exactly once");
+    }
+    return { ...parsed.data, acceptance_results: parsed.data.acceptance_results.map((item) => ({ ...item, evidence_artifact_ids: [] })) };
+}
+export const claudeCodeDriver = {
+    name: "claude-code",
+    async run(input) {
+        const fuelSource = input.fuelSource === "local" ? "local" : "conduit";
+        if (fuelSource === "local" && !hasLocalVendorLogin()) {
+            return {
+                status: "failed",
+                resultText: null,
+                sessionId: null,
+                error: "machine set to local fuel but claude-code has no login",
+            };
+        }
+        const tools = claudeToolsForGrants(input.grants, input.verificationCommands);
+        // Fail closed: omitting --allowedTools would leave only the deny-list and
+        // broaden the agent beyond the grant contract (privileged grants map to none).
+        if (!tools.length) {
+            return {
+                status: "failed",
+                resultText: null,
+                sessionId: null,
+                error: "No Bridge-mapped tools for active grants; refusing to start agent without an allow-list",
+            };
+        }
+        const args = ["-p", input.prompt, "--output-format", "json"];
+        if (input.resumeSessionId)
+            args.push("--resume", input.resumeSessionId);
+        args.push("--allowedTools", tools.join(","));
+        args.push("--disallowedTools", claudeDeniedTools.join(","));
+        if (input.grants.includes("repo_write"))
+            args.push("--permission-mode", "acceptEdits");
+        const { code, stdout, stderr } = await execute(input.executable ?? "claude", args, input.workspace, input.timeoutMs ?? 20 * 60_000, fuelSource === "conduit" ? input.fuel : undefined, fuelSource);
+        let message = null;
+        try {
+            message = JSON.parse(stdout);
+        }
+        catch {
+            message = null;
+        }
+        const sessionId = message?.session_id ?? null;
+        if (code !== 0 || !message || message.is_error) {
+            return { status: "failed", resultText: message?.result ?? null, sessionId, error: (message?.result || stderr || `agent exited with code ${code}`).slice(0, 20_000) };
+        }
+        return { status: "completed", resultText: message.result ?? "", sessionId };
+    },
+};
+export const DRIVERS = { "claude-code": claudeCodeDriver };
+function execute(executable, args, cwd, timeoutMs, fuel, fuelSource = "conduit") {
+    return new Promise((resolve, reject) => {
+        const child = spawn(executable, args, { cwd, stdio: ["ignore", "pipe", "pipe"], env: boundedEnvironment(fuel, fuelSource) });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => { child.kill("SIGTERM"); setTimeout(() => child.kill("SIGKILL"), 10_000).unref(); }, timeoutMs);
+        child.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+        child.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
+        child.on("error", (error) => { clearTimeout(timer); reject(error); });
+        child.on("close", (code) => { clearTimeout(timer); resolve({ code, stdout, stderr: stderr.slice(0, 20_000) }); });
+    });
+}
+const LOCAL_VENDOR_ENV = [
+    "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_BASE_URL",
+    "OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_API_BASE",
+];
+function boundedEnvironment(fuel, fuelSource = "conduit") {
+    // Proxy and TLS variables stay: fueled agents must reach Conduit's /v1 on
+    // machines that only have network access through a proxy.
+    const allowed = ["PATH", "HOME", "USER", "LOGNAME", "SHELL", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL", "TERM", "NO_COLOR", "FORCE_COLOR",
+        "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "no_proxy", "SSL_CERT_FILE", "NODE_EXTRA_CA_CERTS",
+        ...(fuelSource === "local" ? LOCAL_VENDOR_ENV : [])];
+    const env = Object.fromEntries(allowed.flatMap((name) => process.env[name] === undefined ? [] : [[name, process.env[name]]]));
+    if (fuelSource === "conduit" && fuel) {
+        const v1 = `${fuel.baseUrl.replace(/\/+$/, "")}/v1`;
+        env.ANTHROPIC_API_KEY = fuel.gatewayKey;
+        env.ANTHROPIC_BASE_URL = v1;
+        env.OPENAI_API_KEY = fuel.gatewayKey;
+        env.OPENAI_BASE_URL = v1;
+    }
+    return env;
+}
+/** True when local fuel can use a host vendor login (env key or Claude credentials dir). */
+export function hasLocalVendorLogin(env = process.env) {
+    if (env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN || env.OPENAI_API_KEY)
+        return true;
+    const home = env.HOME;
+    if (!home)
+        return false;
+    return existsSync(join(home, ".claude"));
+}
+/** Exported for tests — builds the stripped process env with optional Conduit fuel. */
+export function agentProcessEnv(fuel, fuelSource = "conduit") {
+    return boundedEnvironment(fuel, fuelSource);
+}

package/dist/execution.js

@@ -0,0 +1,264 @@
+import { z } from "zod";
+import { ConduitRequestError } from "./client.js";
+import { redactSecrets } from "./config.js";
+import { buildAssignmentPrompt, evidenceKinds, parseAgentReport } from "./driver.js";
+import { buildWorkspaceBrief } from "./brief.js";
+const assignmentSchema = z.object({
+    id: z.string().uuid(),
+    attempt_id: z.string().uuid(),
+    execution_mode: z.enum(["agent", "human"]).optional().default("agent"),
+});
+const taskDetailSchema = z.object({
+    objective: z.string(),
+    project_id: z.string().uuid(),
+    spec_json: z.string().nullable(),
+    grants_json: z.string().nullable(),
+    delivery_state: z.string(),
+    delivery_summary: z.string().nullable(),
+    execution_mode: z.enum(["agent", "human"]).optional().default("agent"),
+});
+const taskSpecSchema = z.object({
+    goal: z.string().optional(), scope: z.array(z.string()).optional(), boundaries: z.array(z.string()).optional(),
+    acceptance: z.array(z.string()).optional(), required_evidence: z.array(z.enum(evidenceKinds)).optional(),
+    change_scope: z.array(z.string()).optional(), work_role: z.string().optional(),
+    repository: z.object({ url: z.string().optional(), base_commit: z.string().optional() }).nullable().optional(),
+    risk_level: z.string().optional(),
+});
+const workPackageSchema = z.object({
+    work_role: z.string().nullable().optional(),
+    goal: z.string().nullable().optional(),
+    scope: z.array(z.string()).optional(),
+    boundaries: z.array(z.string()).optional(),
+    acceptance: z.array(z.string()).optional(),
+    change_scope: z.array(z.string()).optional(),
+    required_evidence: z.array(z.string()).optional(),
+    initiative: z.object({
+        title: z.string().nullable().optional(),
+        desired_outcome: z.string().nullable().optional(),
+        boundaries: z.array(z.string()).optional(),
+    }).optional(),
+    decisions: z.array(z.object({ question: z.string(), decision: z.string() })).optional(),
+    rework_feedback: z.string().nullable().optional(),
+}).nullable().optional();
+export async function renewLeases(client, config) {
+    for (const active of Object.values(config.activeAttempts)) {
+        if (Date.parse(active.leaseExpiresAt) - Date.now() < 120_000) {
+            try {
+                const response = await client.attemptRequest(active.taskId, "lease", { idempotency_key: `bridge:lease:${active.attemptId}:${Math.floor(Date.now() / 60_000)}` });
+                await client.updateAttempt(active.taskId, { leaseExpiresAt: String(response.lease_expires_at) });
+            }
+            catch (error) {
+                if (error instanceof ConduitRequestError && error.code === "invalid_lease")
+                    await client.clearAttempt(active.taskId);
+                else
+                    throw error;
+            }
+        }
+    }
+}
+export async function recoverActiveAttempt(client, config, driver, workspace, brief, timeoutMs) {
+    const active = Object.values(config.activeAttempts)[0];
+    if (!active)
+        return false;
+    if (active.phase === "agent_running") {
+        await queueTerminal(client, active.taskId, {
+            action: "fail",
+            body: { error: "Bridge restarted during agent execution; Conduit may retry this work safely.", idempotency_key: `bridge:restart:${active.attemptId}` },
+        });
+        return true;
+    }
+    if (client.attempt(active.taskId).phase === "agent_finished") {
+        await submitFinishedDelivery(client, active.taskId);
+        return true;
+    }
+    if (client.attempt(active.taskId).phase === "terminal_pending") {
+        await flushTerminal(client, active.taskId);
+        return true;
+    }
+    await runClaimedAssignment(client, config, driver, workspace, brief, active.taskId, timeoutMs);
+    return true;
+}
+export async function executeNextAssignment(client, config, driver, workspace, brief, timeoutMs) {
+    if (Object.keys(config.activeAttempts).length)
+        return recoverActiveAttempt(client, config, driver, workspace, brief, timeoutMs);
+    const data = await client.request("/runner/v1/assignments");
+    const assignments = z.array(assignmentSchema).parse(data.assignments ?? []);
+    const assignment = assignments[0];
+    if (!assignment)
+        return false;
+    if (assignment.execution_mode === "human") {
+        console.log(`Human takeover assignment ${assignment.id} — use Bridge MCP tools to claim and submit (agent runner skips).`);
+        return false;
+    }
+    console.log(`Claiming assignment ${assignment.id} (attempt ${assignment.attempt_id})`);
+    await client.claim(assignment.id, assignment.attempt_id);
+    await runClaimedAssignment(client, config, driver, workspace, brief, assignment.id, timeoutMs);
+    return true;
+}
+async function runClaimedAssignment(client, config, driver, workspace, brief, taskId, timeoutMs) {
+    const active = client.attempt(taskId);
+    const detail = await client.request(`/runner/v1/tasks/${taskId}`);
+    const task = taskDetailSchema.parse(detail.task);
+    const workPackage = workPackageSchema.parse(detail.work_package) ?? null;
+    const spec = parseTaskSpec(task.spec_json);
+    const grants = z.array(z.string()).parse(task.grants_json ? JSON.parse(task.grants_json) : []);
+    const reworkFeedback = task.delivery_state === "changes_requested" && task.delivery_summary && !task.delivery_summary.startsWith("{") ? task.delivery_summary : null;
+    // Recompile current state at claim time — earlier packages may have moved the repo.
+    const liveBrief = await buildWorkspaceBrief(workspace).catch(() => brief);
+    const prompt = buildAssignmentPrompt({ taskId, objective: task.objective, spec, grants, workspace, currentHead: liveBrief?.base_commit ?? null, reworkFeedback, workPackage });
+    await client.attemptRequest(taskId, "progress", { phase: "changing", message: `Starting ${driver.name} for this assignment${reworkFeedback ? " with review feedback" : ""}.`, idempotency_key: `bridge:progress:${active.attemptId}:start` });
+    const fuelSource = config.fuelSource === "local" ? "local" : "conduit";
+    await client.updateAttempt(taskId, { phase: "agent_running", fuelMode: fuelSource });
+    let fuel;
+    if (fuelSource === "conduit") {
+        const gatewayKey = await client.ensureFuel(task.project_id);
+        fuel = { baseUrl: config.baseUrl, gatewayKey };
+    }
+    const renewTimer = setInterval(() => { void renewLeases(client, config).catch((error) => console.error(`Lease renewal failed: ${redactSecrets(error instanceof Error ? error.message : "unknown")}`)); }, 60_000);
+    try {
+        const result = await driver.run({
+            prompt,
+            workspace,
+            grants,
+            verificationCommands: liveBrief?.verification ?? [],
+            resumeSessionId: config.sessions?.[taskId],
+            timeoutMs,
+            fuel,
+            fuelSource,
+        });
+        if (result.sessionId)
+            config.sessions = { ...config.sessions, [taskId]: result.sessionId };
+        if (result.status === "failed") {
+            await queueTerminal(client, taskId, { action: "fail", body: { error: result.error ?? "Agent execution failed", idempotency_key: `bridge:fail:${active.attemptId}` } });
+            console.error(`Assignment ${taskId} failed: ${redactSecrets(result.error ?? "unknown")}`);
+            return;
+        }
+        let report;
+        try {
+            report = parseAgentReport(result.resultText ?? "", spec.acceptance ?? []);
+            validateDeliveryReport(report, spec);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Agent delivery report was invalid";
+            await queueTerminal(client, taskId, { action: "fail", body: { error: message, retryable: false, idempotency_key: `bridge:invalid-delivery:${active.attemptId}` } });
+            console.error(`Assignment ${taskId} could not produce a valid Delivery: ${redactSecrets(message)}`);
+            return;
+        }
+        await client.updateAttempt(taskId, { phase: "agent_finished", delivery: { spec, report } });
+        await submitFinishedDelivery(client, taskId);
+        console.log(`Assignment ${taskId} delivered for review and acceptance.`);
+    }
+    finally {
+        clearInterval(renewTimer);
+    }
+}
+async function submitFinishedDelivery(client, taskId) {
+    const active = client.attempt(taskId);
+    if (!active.delivery)
+        throw new Error("Finished agent run is missing its persisted Delivery data");
+    const terminal = await prepareDelivery(client, active.attemptId, taskId, active.delivery.report);
+    await client.attemptRequest(taskId, "progress", { phase: "preparing_delivery", message: "Agent finished; submitting the Delivery.", idempotency_key: `bridge:progress:${active.attemptId}:delivery` });
+    await queueTerminal(client, taskId, terminal);
+}
+function parseTaskSpec(value) {
+    if (!value)
+        return {};
+    try {
+        return taskSpecSchema.parse(JSON.parse(value));
+    }
+    catch {
+        throw new Error("Assigned task contains an invalid execution contract");
+    }
+}
+async function prepareDelivery(client, attemptId, taskId, report) {
+    const fuelMode = client.attempt(taskId).fuelMode === "local" ? "local" : "conduit";
+    const evidence = [];
+    const evidenceByCriterion = new Map();
+    for (const [index, item] of report.evidence.entries()) {
+        const uri = item.uri ?? `urn:conduit:attempt:${attemptId}:evidence:${index + 1}`;
+        const response = await client.attemptRequest(taskId, "artifacts", {
+            kind: item.kind, name: item.name, uri, digest: item.digest,
+            metadata: { details: item.details, acceptance_criteria: item.acceptance_criteria },
+            idempotency_key: `bridge:artifact:${attemptId}:${index + 1}`,
+        });
+        const artifactId = z.string().uuid().parse(response.artifact_id);
+        evidence.push({ artifact_id: artifactId, kind: item.kind });
+        for (const criterion of item.acceptance_criteria)
+            evidenceByCriterion.set(criterion, [...(evidenceByCriterion.get(criterion) ?? []), artifactId]);
+    }
+    const acceptanceResults = report.acceptance_results.map((result) => ({ ...result, evidence_artifact_ids: evidenceByCriterion.get(result.criterion) ?? [] }));
+    const { head_commit, pull_request_url, evidence: _evidence, ...body } = report;
+    const references = [
+        ...(pull_request_url ? [{ kind: "pull_request", uri: pull_request_url }] : []),
+        ...report.evidence.flatMap((item) => item.uri ? [{ kind: referenceKind(item.kind), uri: item.uri }] : []),
+    ];
+    return {
+        action: "complete",
+        body: {
+            delivery_packet: { ...body, acceptance_results: acceptanceResults, ...(head_commit ? { head_commit } : {}), ...(pull_request_url ? { pull_request_url } : {}), references, fuel_mode: fuelMode },
+            evidence,
+            idempotency_key: `bridge:complete:${attemptId}`,
+        },
+    };
+}
+export function validateDeliveryReport(report, spec) {
+    validateChangeScope(report, spec.change_scope ?? []);
+    const supplied = new Set(report.evidence.map((item) => item.kind));
+    const missing = (spec.required_evidence ?? []).filter((kind) => !supplied.has(kind));
+    if (missing.length)
+        throw new Error(`Agent report is missing required evidence: ${missing.join(", ")}`);
+    const unsupported = report.acceptance_results
+        .filter((result) => result.status === "met" && !report.evidence.some((item) => item.acceptance_criteria.includes(result.criterion)))
+        .map((result) => result.criterion);
+    if (unsupported.length)
+        throw new Error(`Met acceptance criteria require mapped evidence: ${unsupported.join("; ")}`);
+}
+function referenceKind(kind) {
+    if (kind === "change")
+        return "commit";
+    if (kind === "test")
+        return "ci";
+    if (kind === "preview")
+        return "preview";
+    if (kind === "documentation")
+        return "document";
+    return "other";
+}
+export function validateChangeScope(report, changeScope) {
+    if (!changeScope.length)
+        return;
+    if (!report.head_commit)
+        throw new Error("Repository changes require a delivered head commit");
+    const paths = report.changes.map((change) => change.split(/\s+[—-]\s+/, 1)[0].trim().replaceAll("\\", "/"));
+    const outside = paths.filter((path) => !path || path.startsWith("/") || path.split("/").includes("..") || !changeScope.some((scope) => pathMatchesScope(path, scope)));
+    if (outside.length)
+        throw new Error(`Agent reported changes outside the approved scope: ${outside.join(", ")}`);
+}
+function pathMatchesScope(path, scope) {
+    const normalized = scope.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
+    if (normalized.endsWith("/**")) {
+        const prefix = normalized.slice(0, -3);
+        return path === prefix || path.startsWith(`${prefix}/`);
+    }
+    return path === normalized;
+}
+async function queueTerminal(client, taskId, terminal) {
+    await client.updateAttempt(taskId, { phase: "terminal_pending", terminal });
+    await flushTerminal(client, taskId);
+}
+export async function flushTerminal(client, taskId) {
+    const active = client.attempt(taskId);
+    if (!active.terminal)
+        throw new Error("Pending terminal operation is missing its replay payload");
+    try {
+        await client.attemptRequest(taskId, active.terminal.action, active.terminal.body);
+        await client.clearAttempt(taskId);
+    }
+    catch (error) {
+        if (error instanceof ConduitRequestError && error.code === "invalid_lease") {
+            await client.clearAttempt(taskId);
+            return;
+        }
+        throw error;
+    }
+}

package/dist/mcp.js

@@ -0,0 +1,54 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ConduitClient } from "./client.js";
+import { loadConfig } from "./config.js";
+const result = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+const executionPhaseSchema = z.enum(["inspecting", "changing", "verifying", "preparing_delivery"]);
+/** Keep aligned with src/conductor/delivery.ts deliveryPacketSchema. */
+export const deliveryPacketSchema = z.object({
+    outcome: z.string().trim().min(1).max(20_000),
+    head_commit: z.string().regex(/^[0-9a-f]{7,64}$/i, "Head commit must be a Git commit SHA").optional(),
+    pull_request_url: z.string().url().max(4_000).optional(),
+    changes: z.array(z.string().trim().min(1).max(4_000)).max(100),
+    acceptance_results: z.array(z.object({
+        criterion: z.string().min(1).max(4_000),
+        status: z.enum(["met", "not_met", "unknown"]),
+        evidence_artifact_ids: z.array(z.string().uuid()).max(100),
+    })).max(100),
+    verification: z.array(z.string().trim().min(1).max(4_000)).max(100),
+    assumptions: z.array(z.string().trim().min(1).max(4_000)).max(100),
+    risks: z.array(z.string().trim().min(1).max(4_000)).max(100),
+    limitations: z.array(z.string().trim().min(1).max(4_000)).max(100),
+    references: z.array(z.object({
+        kind: z.enum(["commit", "pull_request", "ci", "preview", "document", "other"]),
+        uri: z.string().url().max(4_000),
+    })).max(100),
+});
+export const BRIDGE_MCP_TOOLS = [
+    "list_assignments",
+    "get_assignment",
+    "claim_assignment",
+    "report_progress",
+    "raise_question",
+    "add_artifact",
+    "submit_delivery",
+    "fail_assignment",
+];
+export function createBridgeMcpServer(client) {
+    const server = new McpServer({ name: "conduit", version: "0.1.0" });
+    server.registerTool("list_assignments", { description: "List work assigned to this machine" }, async () => result(await client.request("/runner/v1/assignments")));
+    server.registerTool("get_assignment", { description: "Get one assigned task", inputSchema: { task_id: z.string().uuid() } }, async ({ task_id }) => result(await client.request(`/runner/v1/tasks/${task_id}`)));
+    server.registerTool("claim_assignment", { description: "Claim an assignment and store its lease", inputSchema: { task_id: z.string().uuid(), attempt_id: z.string().uuid() } }, async ({ task_id, attempt_id }) => result(await client.claim(task_id, attempt_id)));
+    server.registerTool("report_progress", { description: "Report the current execution phase and concise observable progress", inputSchema: { task_id: z.string().uuid(), phase: executionPhaseSchema, message: z.string().min(1), idempotency_key: z.string().min(1) } }, async (input) => result(await client.attemptRequest(input.task_id, "progress", { phase: input.phase, message: input.message, idempotency_key: input.idempotency_key })));
+    server.registerTool("raise_question", { description: "Raise a structured blocker for human judgment", inputSchema: { task_id: z.string().uuid(), question: z.string().min(1), impact: z.string().min(1), options: z.array(z.string()).default([]), recommendation: z.string().optional(), idempotency_key: z.string().min(1) } }, async (input) => result(await client.attemptRequest(input.task_id, "blockers", input)));
+    server.registerTool("add_artifact", { description: "Attach external delivery evidence metadata", inputSchema: { task_id: z.string().uuid(), kind: z.string().min(1), name: z.string().min(1), uri: z.string().url(), digest: z.string().optional(), metadata: z.record(z.unknown()).optional(), idempotency_key: z.string().min(1) } }, async (input) => result(await client.attemptRequest(input.task_id, "artifacts", input)));
+    server.registerTool("submit_delivery", { description: "Submit a structured Delivery Packet for human acceptance", inputSchema: { task_id: z.string().uuid(), packet: deliveryPacketSchema, evidence: z.array(z.object({ artifact_id: z.string().uuid(), kind: z.string() })).default([]), idempotency_key: z.string().min(1) } }, async (input) => result(await client.attemptRequest(input.task_id, "complete", { delivery_packet: input.packet, evidence: input.evidence, idempotency_key: input.idempotency_key })));
+    server.registerTool("fail_assignment", { description: "Report a terminal failed attempt", inputSchema: { task_id: z.string().uuid(), error: z.string().min(1), idempotency_key: z.string().min(1) } }, async (input) => result(await client.attemptRequest(input.task_id, "fail", input)));
+    return server;
+}
+export async function runMcp() {
+    const client = new ConduitClient(await loadConfig());
+    const server = createBridgeMcpServer(client);
+    await server.connect(new StdioServerTransport());
+}