@mnemom/mnemom 0.17.32 → 0.17.34-next.1

package/dist/lib/runner/oidc.js

@@ -0,0 +1,89 @@
+/**
+ * `agent run --once --oidc`'s credential (ruling 34.12 (5), (6); 34.14 (2); Doors W4.12).
+ *
+ * The runner fetches the GitHub Actions ID token itself, for audience `mnemom-executor`, and posts
+ * it as {oidc_token} to exec_oidc_exchange, whose auth is github_oidc (the token in the body, no
+ * key header). The answer is a one-lease org-scope executor key, used for that single job. Every
+ * failure fails closed, whatever --fail-mode says, because no job is held yet: an exchange refusal
+ * is oidc_<code> for S1's OIDC_EXCHANGE_REFUSALS, anything else oidc_unavailable. The token never
+ * reaches argv, a log line or an outcome.
+ *
+ * S1 names the route but not its answer's field; `executor_key` is this runner's reading, open
+ * with the Durable lead until S1 freezes it (no api handler exists yet to read it from).
+ */
+import { OIDC_EXCHANGE_AUDIENCE, OIDC_EXCHANGE_REFUSALS, routePath, } from "../../vendor/durable-contract/index.js";
+import { errorCode } from "./executor-client.js";
+const unavailable = (detail) => ({
+    ok: false,
+    reason: "oidc_unavailable",
+    detail,
+});
+async function readJson(res) {
+    try {
+        return JSON.parse(await res.text());
+    }
+    catch {
+        return null;
+    }
+}
+/** The Actions ID token for `mnemom-executor`, or why there is none. */
+export async function actionsIdToken(fetch, requestUrl, requestToken) {
+    let url;
+    try {
+        url = new URL(requestUrl);
+    }
+    catch {
+        return { ok: false, detail: "ACTIONS_ID_TOKEN_REQUEST_URL is not a URL" };
+    }
+    url.searchParams.set("audience", OIDC_EXCHANGE_AUDIENCE);
+    try {
+        const res = await fetch(url.toString(), {
+            method: "GET",
+            headers: { accept: "application/json", authorization: `bearer ${requestToken}` },
+        });
+        if (res.status !== 200)
+            return { ok: false, detail: `ID token request answered ${res.status}` };
+        const value = (await readJson(res))?.value;
+        if (typeof value !== "string" || value === "") {
+            return { ok: false, detail: "ID token answer has no value" };
+        }
+        return { ok: true, token: value };
+    }
+    catch (e) {
+        return { ok: false, detail: `ID token request failed: ${e.message}` };
+    }
+}
+/** Fetch the ID token and exchange it for a one-lease executor key. */
+export async function exchangeOidc(opts) {
+    const id = await actionsIdToken(opts.fetch, opts.requestUrl, opts.requestToken);
+    if (!id.ok)
+        return unavailable(id.detail);
+    const base = opts.apiUrl.replace(/\/+$/, "");
+    let res;
+    try {
+        res = await opts.fetch(`${base}${routePath("exec_oidc_exchange")}`, {
+            method: "POST",
+            headers: { accept: "application/json", "content-type": "application/json" },
+            body: JSON.stringify({ oidc_token: id.token }),
+        });
+    }
+    catch (e) {
+        return unavailable(`exchange failed: ${e.message}`);
+    }
+    const body = await readJson(res);
+    if (res.status === 200) {
+        const key = body?.executor_key;
+        if (typeof key === "string" && key !== "")
+            return { ok: true, executorKey: key };
+        return unavailable("exchange answer has no executor_key");
+    }
+    const code = errorCode(body);
+    if (code !== null && OIDC_EXCHANGE_REFUSALS.includes(code)) {
+        return {
+            ok: false,
+            reason: `oidc_${code}`,
+            detail: `exchange refused: ${code}`,
+        };
+    }
+    return unavailable(`exchange answered ${res.status}${code ? ` ${code}` : ""}`);
+}

package/dist/lib/runner/options.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `mnemom agent run`'s options and credential (ruling 34.12 (1), (2), (5), (6)).
+ *
+ * Every usage or config error is decided here, before any network call, so it exits 2 with a
+ * message on stderr and no outcome line, with or without --json.
+ */
+import { type RunnerFailMode } from "./settings.js";
+export declare const EXECUTOR_KEY_ENV = "MNEMOM_EXECUTOR_KEY";
+export declare const ACTIONS_ID_TOKEN_URL_ENV = "ACTIONS_ID_TOKEN_REQUEST_URL";
+export declare const ACTIONS_ID_TOKEN_TOKEN_ENV = "ACTIONS_ID_TOKEN_REQUEST_TOKEN";
+export interface RunFlags {
+    watch?: boolean;
+    once?: boolean;
+    failMode?: string;
+    json?: boolean;
+    oidc?: boolean;
+}
+export type RunCredential = {
+    kind: "executor_key";
+    key: string;
+} | {
+    kind: "oidc";
+    requestUrl: string;
+    requestToken: string;
+};
+export interface RunPlan {
+    form: "watch" | "once";
+    failMode: RunnerFailMode;
+    json: boolean;
+    credential: RunCredential;
+    /** Warnings to print on stderr (an unknown fail mode reads as closed). */
+    warnings: string[];
+}
+export type RunPlanResult = {
+    ok: true;
+    plan: RunPlan;
+} | {
+    ok: false;
+    usage: string;
+};
+export declare function resolveRunPlan(flags: RunFlags, env: NodeJS.ProcessEnv): RunPlanResult;

package/dist/lib/runner/options.js

@@ -0,0 +1,47 @@
+/**
+ * `mnemom agent run`'s options and credential (ruling 34.12 (1), (2), (5), (6)).
+ *
+ * Every usage or config error is decided here, before any network call, so it exits 2 with a
+ * message on stderr and no outcome line, with or without --json.
+ */
+import { resolveFailMode, RUNNER_FAIL_MODE_ENV } from "./settings.js";
+export const EXECUTOR_KEY_ENV = "MNEMOM_EXECUTOR_KEY";
+export const ACTIONS_ID_TOKEN_URL_ENV = "ACTIONS_ID_TOKEN_REQUEST_URL";
+export const ACTIONS_ID_TOKEN_TOKEN_ENV = "ACTIONS_ID_TOKEN_REQUEST_TOKEN";
+const usage = (message) => ({ ok: false, usage: message });
+const set = (v) => v !== undefined && v.trim() !== "";
+export function resolveRunPlan(flags, env) {
+    if (Boolean(flags.watch) === Boolean(flags.once)) {
+        return usage("mnemom agent run: give exactly one of --watch or --once");
+    }
+    const form = flags.watch ? "watch" : "once";
+    if (flags.oidc && form === "watch") {
+        return usage("mnemom agent run: --oidc is valid only with --once");
+    }
+    const fail = resolveFailMode(flags.failMode, env[RUNNER_FAIL_MODE_ENV]);
+    const warnings = fail.warning ? [`mnemom agent run: ${fail.warning}`] : [];
+    let credential;
+    if (flags.oidc) {
+        if (set(env[EXECUTOR_KEY_ENV])) {
+            return usage(`mnemom agent run: --oidc with ${EXECUTOR_KEY_ENV} set holds two credentials; unset one`);
+        }
+        const requestUrl = env[ACTIONS_ID_TOKEN_URL_ENV];
+        const requestToken = env[ACTIONS_ID_TOKEN_TOKEN_ENV];
+        if (!set(requestUrl) || !set(requestToken)) {
+            return usage(`mnemom agent run: --oidc needs ${ACTIONS_ID_TOKEN_URL_ENV} and ${ACTIONS_ID_TOKEN_TOKEN_ENV} ` +
+                "(a GitHub Actions job with `permissions: id-token: write`)");
+        }
+        credential = { kind: "oidc", requestUrl, requestToken };
+    }
+    else {
+        const key = env[EXECUTOR_KEY_ENV];
+        if (!set(key)) {
+            return usage(`mnemom agent run: no credential; set ${EXECUTOR_KEY_ENV} or use --once --oidc`);
+        }
+        credential = { kind: "executor_key", key: key.trim() };
+    }
+    return {
+        ok: true,
+        plan: { form, failMode: fail.mode, json: Boolean(flags.json), credential, warnings },
+    };
+}

package/dist/lib/runner/outcome.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The thin runner's v1 outcome line (ruling 34.12 (6), (8); Doors W-L13).
+ *
+ * Each job ends with exactly one JSON line, the last on stdout for that job. The fields, outcomes,
+ * reasons and exit codes are S1's (shared/durable-contract doors.ts), imported and never restated:
+ * a reason outside S1's closed lists is a bug in the runner, so `outcomeLine` throws on one rather
+ * than print a line no consumer can read.
+ */
+import { type RUNNER_MERGE_STRATEGIES, RUNNER_REFUSED_REASONS, type RunnerOutcome } from "../../vendor/durable-contract/index.js";
+export type RefusedReason = (typeof RUNNER_REFUSED_REASONS)[number];
+export type MergeStrategyName = (typeof RUNNER_MERGE_STRATEGIES)[number];
+export interface OutcomeFields {
+    outcome: RunnerOutcome;
+    session_id: string | null;
+    lease_epoch: number | null;
+    contract_sha256: string | null;
+    contract_version: number | null;
+    merge_strategy: MergeStrategyName | null;
+    pr_url: string | null;
+    reason: string | null;
+}
+/** What the runner knows of its job so far; each field fills in as the job gets further. */
+export interface JobFacts {
+    session_id?: string | null;
+    lease_epoch?: number | null;
+    contract_sha256?: string | null;
+    contract_version?: number | null;
+    merge_strategy?: MergeStrategyName | null;
+    pr_url?: string | null;
+}
+/** `phase_<order>_<name>`: the name lowercased, anything outside [a-z0-9_] replaced by `_`. */
+export declare function phaseReason(order: number, name: string): string;
+export declare function isRefusedReason(v: string): v is RefusedReason;
+/** done: every field of the job, no reason. */
+export declare function doneOutcome(facts: JobFacts): OutcomeFields;
+export declare function noJobOutcome(): OutcomeFields;
+/** failed: the job's own failure; pr_url only when the PR was opened before it. */
+export declare function failedOutcome(facts: JobFacts, reason: string): OutcomeFields;
+/**
+ * refused: session fields only once a session was claimed, merge_strategy only once a verified
+ * bundle was held (the caller leaves it unset until then), never a pr_url.
+ */
+export declare function refusedOutcome(facts: JobFacts, reason: RefusedReason): OutcomeFields;
+/** The outcome line: S1's fields in S1's order, each present (null, never omitted). */
+export declare function outcomeLine(o: OutcomeFields): string;
+export declare function exitCodeFor(outcome: RunnerOutcome): number;
+export declare const USAGE_EXIT_CODE: 2;

package/dist/lib/runner/outcome.js

@@ -0,0 +1,89 @@
+/**
+ * The thin runner's v1 outcome line (ruling 34.12 (6), (8); Doors W-L13).
+ *
+ * Each job ends with exactly one JSON line, the last on stdout for that job. The fields, outcomes,
+ * reasons and exit codes are S1's (shared/durable-contract doors.ts), imported and never restated:
+ * a reason outside S1's closed lists is a bug in the runner, so `outcomeLine` throws on one rather
+ * than print a line no consumer can read.
+ */
+import { RUNNER_EXIT_CODES, RUNNER_FAILED_PHASE_RE, RUNNER_FAILED_REASONS, RUNNER_OUTCOME_FIELDS, RUNNER_REFUSED_REASONS, } from "../../vendor/durable-contract/index.js";
+/** `phase_<order>_<name>`: the name lowercased, anything outside [a-z0-9_] replaced by `_`. */
+export function phaseReason(order, name) {
+    return `phase_${order}_${name.toLowerCase().replace(/[^a-z0-9_]/g, "_")}`;
+}
+export function isRefusedReason(v) {
+    return RUNNER_REFUSED_REASONS.includes(v);
+}
+function reasonOk(outcome, reason) {
+    if (outcome === "done" || outcome === "no_job")
+        return reason === null;
+    if (reason === null)
+        return false;
+    if (outcome === "failed")
+        return (RUNNER_FAILED_REASONS.includes(reason) ||
+            RUNNER_FAILED_PHASE_RE.test(reason));
+    return isRefusedReason(reason);
+}
+const pick = (facts, keep) => ({
+    session_id: keep ? (facts.session_id ?? null) : null,
+    lease_epoch: keep ? (facts.lease_epoch ?? null) : null,
+    contract_sha256: keep ? (facts.contract_sha256 ?? null) : null,
+    contract_version: keep ? (facts.contract_version ?? null) : null,
+});
+/** done: every field of the job, no reason. */
+export function doneOutcome(facts) {
+    return {
+        outcome: "done",
+        ...pick(facts, true),
+        merge_strategy: facts.merge_strategy ?? null,
+        pr_url: facts.pr_url ?? null,
+        reason: null,
+    };
+}
+export function noJobOutcome() {
+    return {
+        outcome: "no_job",
+        ...pick({}, false),
+        merge_strategy: null,
+        pr_url: null,
+        reason: null,
+    };
+}
+/** failed: the job's own failure; pr_url only when the PR was opened before it. */
+export function failedOutcome(facts, reason) {
+    return {
+        outcome: "failed",
+        ...pick(facts, true),
+        merge_strategy: facts.merge_strategy ?? null,
+        pr_url: facts.pr_url ?? null,
+        reason,
+    };
+}
+/**
+ * refused: session fields only once a session was claimed, merge_strategy only once a verified
+ * bundle was held (the caller leaves it unset until then), never a pr_url.
+ */
+export function refusedOutcome(facts, reason) {
+    return {
+        outcome: "refused",
+        ...pick(facts, facts.session_id != null),
+        merge_strategy: facts.merge_strategy ?? null,
+        pr_url: null,
+        reason,
+    };
+}
+/** The outcome line: S1's fields in S1's order, each present (null, never omitted). */
+export function outcomeLine(o) {
+    if (!reasonOk(o.outcome, o.reason)) {
+        throw new Error(`runner bug: reason ${JSON.stringify(o.reason)} is not valid for ${o.outcome}`);
+    }
+    const values = { v: 1, ...o };
+    const out = {};
+    for (const f of RUNNER_OUTCOME_FIELDS)
+        out[f] = values[f] ?? null;
+    return JSON.stringify(out);
+}
+export function exitCodeFor(outcome) {
+    return RUNNER_EXIT_CODES[outcome];
+}
+export const USAGE_EXIT_CODE = RUNNER_EXIT_CODES.usage;

package/dist/lib/runner/phases.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Running a verified bundle's phases (Doors W-L13, W3.11).
+ *
+ * The runner holds no prompts: each phase's prompt, capability ids or code come only from the
+ * verified bundle, in its order. A capabilities phase runs headless Claude Code with exactly the
+ * tools its capability ids grant (an unknown id fails the phase; nothing is ever widened). A code
+ * phase runs the bundle's JavaScript in a child node. Both get a scrubbed environment: a fresh
+ * HOME, the model URL of the runner's own proxy and the model credential, never the executor key,
+ * the lease key or a GitHub token.
+ */
+import type { ServedPhase } from "./bundle.js";
+/** W-L12's capability ids (workflow mnemom.door2 v1), and the Claude Code tools each grants. */
+export declare const CAPABILITY_TOOLS: Readonly<Record<string, {
+    tools: string[];
+    allowed: string[];
+}>>;
+/** Env names a phase may inherit: the model credential and a working PATH. Nothing else. */
+export declare const PHASE_ENV_PASSTHROUGH: readonly ["PATH", "ANTHROPIC_API_KEY", "LANG", "TZ"];
+export type ToolGrant = {
+    ok: true;
+    tools: string[];
+    allowed: string[];
+    opensPr: boolean;
+} | {
+    ok: false;
+    unknown: string[];
+};
+export declare function toolsFor(capabilityIds: readonly string[]): ToolGrant;
+export declare function phaseEnv(parent: NodeJS.ProcessEnv, home: string, modelUrl: string): Record<string, string>;
+/** One child process to start: the command, its argv and stdin. */
+export interface PhaseInvocation {
+    command: string;
+    args: string[];
+    stdin: string | null;
+}
+/** argv for one capabilities phase; the prompt is the bundle's, passed through unchanged. */
+export declare function claudeInvocation(prompt: string, grant: Extract<ToolGrant, {
+    ok: true;
+}>): PhaseInvocation;
+export declare function codeInvocation(source: string): PhaseInvocation;
+export type PhasePlan = {
+    ok: true;
+    invocation: PhaseInvocation;
+    opensPr: boolean;
+} | {
+    ok: false;
+    detail: string;
+};
+export declare function planPhase(phase: ServedPhase): PhasePlan;

package/dist/lib/runner/phases.js

@@ -0,0 +1,99 @@
+/**
+ * Running a verified bundle's phases (Doors W-L13, W3.11).
+ *
+ * The runner holds no prompts: each phase's prompt, capability ids or code come only from the
+ * verified bundle, in its order. A capabilities phase runs headless Claude Code with exactly the
+ * tools its capability ids grant (an unknown id fails the phase; nothing is ever widened). A code
+ * phase runs the bundle's JavaScript in a child node. Both get a scrubbed environment: a fresh
+ * HOME, the model URL of the runner's own proxy and the model credential, never the executor key,
+ * the lease key or a GitHub token.
+ */
+/** W-L12's capability ids (workflow mnemom.door2 v1), and the Claude Code tools each grants. */
+export const CAPABILITY_TOOLS = Object.freeze({
+    "repo.read": { tools: ["Read", "Glob", "Grep"], allowed: ["Read", "Glob", "Grep"] },
+    "repo.write": { tools: ["Edit", "Write"], allowed: ["Edit", "Write"] },
+    "shell.run": { tools: ["Bash"], allowed: ["Bash"] },
+    "git.commit": {
+        tools: ["Bash"],
+        allowed: ["Bash(git add:*)", "Bash(git commit:*)", "Bash(git status:*)", "Bash(git diff:*)"],
+    },
+    // The runner opens the PR itself once every phase has passed; the model gets no tool for it.
+    "pr.open": { tools: [], allowed: [] },
+});
+/** Env names a phase may inherit: the model credential and a working PATH. Nothing else. */
+export const PHASE_ENV_PASSTHROUGH = ["PATH", "ANTHROPIC_API_KEY", "LANG", "TZ"];
+export function toolsFor(capabilityIds) {
+    const unknown = capabilityIds.filter((id) => !Object.hasOwn(CAPABILITY_TOOLS, id));
+    if (unknown.length > 0)
+        return { ok: false, unknown };
+    const tools = new Set();
+    const allowed = new Set();
+    for (const id of capabilityIds) {
+        for (const t of CAPABILITY_TOOLS[id].tools)
+            tools.add(t);
+        for (const a of CAPABILITY_TOOLS[id].allowed)
+            allowed.add(a);
+    }
+    // A plain Bash grant already covers the git patterns.
+    if (allowed.has("Bash"))
+        for (const a of [...allowed])
+            if (a.startsWith("Bash("))
+                allowed.delete(a);
+    return {
+        ok: true,
+        tools: [...tools].sort(),
+        allowed: [...allowed].sort(),
+        opensPr: capabilityIds.includes("pr.open"),
+    };
+}
+export function phaseEnv(parent, home, modelUrl) {
+    const env = {};
+    for (const name of PHASE_ENV_PASSTHROUGH) {
+        const v = parent[name];
+        if (v !== undefined)
+            env[name] = v;
+    }
+    env.HOME = home;
+    env.ANTHROPIC_BASE_URL = modelUrl;
+    env.MNEMOM_RUNNER_MODEL_URL = modelUrl;
+    env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
+    return env;
+}
+/** argv for one capabilities phase; the prompt is the bundle's, passed through unchanged. */
+export function claudeInvocation(prompt, grant) {
+    const args = [
+        "-p",
+        "--output-format",
+        "json",
+        "--permission-mode",
+        "dontAsk",
+        "--setting-sources",
+        "user",
+        "--strict-mcp-config",
+        "--no-session-persistence",
+        "--tools",
+        grant.tools.length > 0 ? grant.tools.join(",") : "",
+    ];
+    if (grant.allowed.length > 0)
+        args.push("--allowedTools", grant.allowed.join(","));
+    return { command: "claude", args, stdin: prompt };
+}
+export function codeInvocation(source) {
+    return { command: process.execPath, args: ["--input-type=module", "-"], stdin: source };
+}
+export function planPhase(phase) {
+    if (phase.runner.kind === "code") {
+        if (phase.runner.language !== "javascript") {
+            return {
+                ok: false,
+                detail: `code phase language ${phase.runner.language} is not javascript`,
+            };
+        }
+        return { ok: true, invocation: codeInvocation(phase.runner.source), opensPr: false };
+    }
+    const grant = toolsFor(phase.runner.capability_ids);
+    if (!grant.ok) {
+        return { ok: false, detail: `unknown capability ids: ${grant.unknown.join(", ")}` };
+    }
+    return { ok: true, invocation: claudeInvocation(phase.prompt, grant), opensPr: grant.opensPr };
+}

package/dist/lib/runner/proxy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The runner's own model proxy (ruling 34.11, 34.12 (7); Doors W3.11).
+ *
+ * A served phase's Claude Code (and a code phase's child) points ANTHROPIC_BASE_URL here, on
+ * loopback. The proxy forwards each request to the gateway and decides every Mnemom header itself:
+ * any `x-mnemom-*` the phase sent is dropped, the lease key goes in X-Mnemom-Api-Key, and the job's
+ * sealed contract goes in `x-mnemom-contract` (exactly one, the sealed version). The phase never
+ * sees the lease key. A 409 `contract_mismatch` from the gateway (34.11) is reported to the job,
+ * which refetches and continues only on a higher sealed version, else fails closed.
+ */
+import { request as httpRequest, type IncomingMessage, type ServerResponse } from "node:http";
+export declare const LEASE_KEY_HEADER = "x-mnemom-api-key";
+export interface ProxyState {
+    /** The sealed header value to send; swapped in place after an accepted amend. */
+    contractValue: string;
+    leaseKey: string;
+}
+export interface ForwardedRequest {
+    method: string;
+    path: string;
+    contract: string;
+    status: number;
+}
+export interface ModelProxy {
+    url: string;
+    /** Every request forwarded so far, with the contract header it carried. */
+    forwarded: ForwardedRequest[];
+    /** Set when the gateway answered 409 contract_mismatch; the job decides what to do. */
+    contractMismatch: {
+        expected_version: number | null;
+    } | null;
+    close(): Promise<void>;
+}
+/** Outbound headers for one request: the phase's own, minus anything the proxy decides. */
+export declare function outboundHeaders(incoming: IncomingMessage["headers"], state: ProxyState): Record<string, string | string[] | undefined>;
+/** The largest 409 body the proxy reads for a contract mismatch. */
+export declare const MISMATCH_BODY_MAX: number;
+/** The client for the gateway's scheme: TLS for https, plain only for a local http gateway. */
+export declare function requestFor(protocol: string): typeof httpRequest;
+/**
+ * The phase's answer when the gateway fails: a 502 if nothing was sent yet, else the connection is
+ * cut, so a truncated body is never mistaken for a whole one.
+ */
+export declare function upstreamFailed(res: Pick<ServerResponse, "headersSent" | "writeHead" | "end" | "destroy">, e: Error): void;
+export declare function startModelProxy(gatewayUrl: string, state: ProxyState): Promise<ModelProxy>;

package/dist/lib/runner/proxy.js

@@ -0,0 +1,153 @@
+/**
+ * The runner's own model proxy (ruling 34.11, 34.12 (7); Doors W3.11).
+ *
+ * A served phase's Claude Code (and a code phase's child) points ANTHROPIC_BASE_URL here, on
+ * loopback. The proxy forwards each request to the gateway and decides every Mnemom header itself:
+ * any `x-mnemom-*` the phase sent is dropped, the lease key goes in X-Mnemom-Api-Key, and the job's
+ * sealed contract goes in `x-mnemom-contract` (exactly one, the sealed version). The phase never
+ * sees the lease key. A 409 `contract_mismatch` from the gateway (34.11) is reported to the job,
+ * which refetches and continues only on a higher sealed version, else fails closed.
+ */
+import { createServer, request as httpRequest, } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { applySealedContract, CONTRACT_HEADER } from "./contract-header.js";
+export const LEASE_KEY_HEADER = "x-mnemom-api-key";
+/** Hop-by-hop headers (RFC 9110 7.6.1) and the ones the proxy owns. */
+const DROP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-connection",
+    "transfer-encoding",
+    "upgrade",
+    "te",
+    "trailer",
+    "host",
+    "content-length",
+]);
+/** Outbound headers for one request: the phase's own, minus anything the proxy decides. */
+export function outboundHeaders(incoming, state) {
+    const kept = {};
+    for (const [name, value] of Object.entries(incoming)) {
+        const lower = name.toLowerCase();
+        if (DROP.has(lower) || lower.startsWith("x-mnemom-"))
+            continue;
+        kept[lower] = value;
+    }
+    kept[LEASE_KEY_HEADER] = state.leaseKey;
+    return applySealedContract(kept, state.contractValue);
+}
+/** The largest 409 body the proxy reads for a contract mismatch. */
+export const MISMATCH_BODY_MAX = 64 * 1024;
+function mismatchVersion(body) {
+    try {
+        const b = JSON.parse(body);
+        const code = typeof b.error === "object" && b.error ? b.error.code : (b.error ?? b.code);
+        if (code !== "contract_mismatch")
+            return undefined;
+        const v = (typeof b.error === "object" && b.error ? b.error.details?.expected_version : undefined) ??
+            b.expected_version;
+        return Number.isSafeInteger(v) ? v : null;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The client for the gateway's scheme: TLS for https, plain only for a local http gateway. */
+export function requestFor(protocol) {
+    return protocol === "https:" ? httpsRequest : httpRequest;
+}
+/**
+ * The phase's answer when the gateway fails: a 502 if nothing was sent yet, else the connection is
+ * cut, so a truncated body is never mistaken for a whole one.
+ */
+export function upstreamFailed(res, e) {
+    if (res.headersSent) {
+        res.destroy(e);
+        return;
+    }
+    res.writeHead(502, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "runner_proxy_upstream", message: e.message } }));
+}
+export async function startModelProxy(gatewayUrl, state) {
+    const upstream = new URL(gatewayUrl);
+    const send = requestFor(upstream.protocol);
+    const basePath = upstream.pathname.replace(/\/+$/, "");
+    const forwarded = [];
+    const proxy = {
+        url: "",
+        forwarded,
+        contractMismatch: null,
+        close: async () => { },
+    };
+    const server = createServer((req, res) => {
+        const headers = outboundHeaders(req.headers, state);
+        const sent = headers[CONTRACT_HEADER];
+        const out = send({
+            protocol: upstream.protocol,
+            hostname: upstream.hostname,
+            port: upstream.port || undefined,
+            method: req.method,
+            path: `${basePath}${req.url ?? "/"}`,
+            headers,
+        }, (up) => {
+            const status = up.statusCode ?? 502;
+            forwarded.push({
+                method: req.method ?? "GET",
+                path: req.url ?? "/",
+                contract: sent,
+                status,
+            });
+            if (status === 409) {
+                // Buffered to read the mismatch, up to a cap; a larger body is relayed unread.
+                const chunks = [];
+                let size = 0;
+                up.on("error", (e) => upstreamFailed(res, e));
+                const onData = (c) => {
+                    chunks.push(c);
+                    size += c.length;
+                    if (size <= MISMATCH_BODY_MAX)
+                        return;
+                    up.off("data", onData);
+                    up.off("end", onEnd);
+                    res.writeHead(status, up.headers);
+                    for (const b of chunks)
+                        res.write(b);
+                    up.pipe(res);
+                };
+                const onEnd = () => {
+                    const body = Buffer.concat(chunks);
+                    const v = mismatchVersion(body.toString("utf8"));
+                    if (v !== undefined)
+                        proxy.contractMismatch = { expected_version: v };
+                    res.writeHead(status, up.headers);
+                    res.end(body);
+                };
+                up.on("data", onData);
+                up.on("end", onEnd);
+                return;
+            }
+            res.writeHead(status, up.headers);
+            // A gateway that drops mid-body errors the response, not the request.
+            up.on("error", (e) => upstreamFailed(res, e));
+            up.pipe(res);
+        });
+        out.on("error", (e) => {
+            forwarded.push({
+                method: req.method ?? "GET",
+                path: req.url ?? "/",
+                contract: sent,
+                status: 502,
+            });
+            upstreamFailed(res, e);
+        });
+        req.pipe(out);
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address();
+    proxy.url = `http://127.0.0.1:${port}`;
+    proxy.close = () => new Promise((resolve) => {
+        server.closeAllConnections?.();
+        server.close(() => resolve());
+    });
+    return proxy;
+}