mercury-agent 0.18.2 → 0.20.0

package/src/agent/image-contract.ts

@@ -0,0 +1,77 @@
+/**
+ * The host-vs-image contract: what the *host's* copy of Mercury believes the
+ * agent image must contain.
+ *
+ * On 2026-09-01 the first paying client's bot was born with `/health` green
+ * while every container it would spawn was doomed — the host ran mercury
+ * 0.17.0 against an August image with no `/app/src/text/`. Nothing compared
+ * the two. This list is that comparison's left-hand side, and
+ * `mercury preflight`'s `image.contract` check stats every entry inside the
+ * image the service would actually spawn.
+ *
+ * **The generator is `container/Dockerfile`.** These are its `COPY`
+ * destinations (excluding `--from=` stage copies and the `/tmp/` staging copy,
+ * which do not survive into `/app`). `tests/preflight-image-contract.test.ts`
+ * parses the Dockerfile and asserts set equality, so a `COPY` added or removed
+ * without an edit here turns the suite red rather than silently narrowing the
+ * contract.
+ */
+
+/**
+ * The image's recorded mercury version: the manifest `container/Dockerfile`
+ * generates at build time (`src/agent/image-manifest.ts`; `version` comes from
+ * the `MERCURY_VERSION` build arg). A `RUN` output, not a `COPY`, so the check
+ * reads it separately from the contract list below.
+ */
+export const IMAGE_VERSION_FILE = "/app/image-manifest.json";
+
+/**
+ * Paths that must exist inside the agent image. A trailing `/` marks a
+ * directory (`resources/` is copied wholesale); everything else is a file.
+ */
+export const IMAGE_CONTRACT_PATHS: readonly string[] = [
+  "/app/package.json",
+  "/app/src/agent/container-entry.ts",
+  "/app/src/agent/model-capabilities-core.ts",
+  "/app/src/agent/pi-failure-class.ts",
+  "/app/src/agent/pi-jsonl-parser.ts",
+  "/app/src/agent/preferences-prompt.ts",
+  "/app/src/cli/mrctl.ts",
+  "/app/src/cli/mrctl-http.ts",
+  "/app/src/extensions/reserved.ts",
+  "/app/src/extensions/permission-guard.ts",
+  "/app/src/text/sanitize-text.ts",
+  "/app/src/types.ts",
+  "/app/resources/",
+  "/app/container/Dockerfile",
+  "/app/src/agent/image-manifest.ts",
+];
+
+/**
+ * Parse a Dockerfile's contract-bearing `COPY` destinations.
+ *
+ * Shared by the check's pin test and anything else that needs the generator's
+ * own answer. Skips `COPY --from=<stage>` (build-stage tooling: bun, node, go
+ * — not Mercury source) and any destination under `/tmp/` (staging that a
+ * later `RUN` deletes). Continuation lines (`\` at end) are joined first, so a
+ * wrapped `COPY` is read as one instruction — under CRLF too: the escape is a
+ * backslash then an optional CR then the newline, not `\r`.
+ */
+export function parseDockerfileCopyDestinations(dockerfile: string): string[] {
+  const joined = dockerfile.replace(/\\\r?\n\s*/g, " ");
+  const destinations: string[] = [];
+  for (const rawLine of joined.split("\n")) {
+    const line = rawLine.trim();
+    if (!/^COPY\s/i.test(line)) continue;
+    // Drop flags (`--from=…`, `--chown=…`). A stage copy is not part of the
+    // Mercury contract — it is the toolchain the base image is built from.
+    const tokens = line.split(/\s+/).slice(1);
+    if (tokens.some((t) => /^--from=/i.test(t))) continue;
+    const operands = tokens.filter((t) => !t.startsWith("--"));
+    const dest = operands[operands.length - 1];
+    if (!dest) continue;
+    if (dest.startsWith("/tmp/")) continue;
+    destinations.push(dest);
+  }
+  return destinations;
+}

package/src/agent/image-manifest.ts

@@ -0,0 +1,180 @@
+/**
+ * The agent image's self-description.
+ *
+ * Two questions have no answer today, which is how a host on 0.18.2 ran a
+ * container built from 0.18.0-beta.0 for a day with `/health` green
+ * throughout: *what mercury version is this image* and *which files from the
+ * repo does it carry*. This module answers the second and carries the first,
+ * and it is run **inside the image at build time** against the Dockerfile that
+ * is building it — not against a copy in the repo — so the manifest cannot
+ * describe a build that did not happen.
+ *
+ * The host side (release-gate R1.1(c)) parses its own `container/Dockerfile`
+ * with this same function and compares: same version, same COPY sources. A
+ * difference means the image and the host disagree about what the container
+ * is, which is exactly the 0.17.0 shape.
+ */
+
+import { createHash } from "node:crypto";
+
+/** One build-context path a `COPY` instruction puts into the image. */
+export interface CopyEntry {
+  /** Path in the build context, verbatim as the Dockerfile writes it. */
+  source: string;
+  /** Path inside the image. */
+  dest: string;
+}
+
+export interface ImageManifest {
+  /** Mercury version this image was built from, passed in as a build arg. */
+  version: string;
+  /** SHA-256 of the Dockerfile that built it, for an exact-match check. */
+  dockerfileSha256: string;
+  /** Sorted, de-duplicated build-context sources. The drift check reads this. */
+  copySources: string[];
+  /** Every source with where it landed, for diagnosing a mismatch. */
+  entries: CopyEntry[];
+}
+
+/**
+ * Join Dockerfile line continuations so a wrapped instruction parses as one.
+ * Comment lines are dropped first: a `#` line inside a continuation is a
+ * comment in Dockerfile syntax, not part of the instruction.
+ */
+function logicalLines(dockerfile: string): string[] {
+  const out: string[] = [];
+  let pending = "";
+  for (const raw of dockerfile.split(/\r?\n/)) {
+    const line = raw.trimEnd();
+    if (/^\s*#/.test(line)) continue;
+    if (line.endsWith("\\")) {
+      pending += `${line.slice(0, -1)} `;
+      continue;
+    }
+    out.push(pending + line);
+    pending = "";
+  }
+  if (pending) out.push(pending);
+  return out;
+}
+
+/**
+ * Every `COPY` that takes a path from the build context.
+ *
+ * `COPY --from=<stage>` is deliberately excluded: those pull from another
+ * image (bun, node, go), not from this repo, so they are not files a host can
+ * check against its own checkout — and including them would make the drift
+ * check fail whenever an upstream base image changes, which is not drift.
+ */
+export function parseCopyInstructions(dockerfile: string): CopyEntry[] {
+  const entries: CopyEntry[] = [];
+  for (const line of logicalLines(dockerfile)) {
+    const match = /^\s*COPY\s+(.+)$/i.exec(line);
+    if (!match) continue;
+    const rest = match[1].trim();
+    // The JSON-array form quotes its arguments and would parse here as a
+    // source literally named `["src",`. Refuse rather than silently record
+    // nonsense: a manifest that is quietly wrong is worse than no manifest,
+    // and this whole module exists because something looked fine and was not.
+    if (rest.startsWith("[")) {
+      throw new Error(
+        `image-manifest: COPY in exec (JSON array) form is not supported, and ` +
+          `parsing it silently would produce a wrong manifest: ${line.trim()}`,
+      );
+    }
+    let fromAnotherStage = false;
+    const args: string[] = [];
+    for (const token of rest.split(/\s+/)) {
+      if (token.startsWith("--")) {
+        if (token.startsWith("--from=")) fromAnotherStage = true;
+        continue;
+      }
+      args.push(token);
+    }
+    if (fromAnotherStage) continue;
+    if (args.length < 2) {
+      throw new Error(
+        `image-manifest: COPY needs at least a source and a destination: ${line.trim()}`,
+      );
+    }
+    const dest = args[args.length - 1] as string;
+    for (const source of args.slice(0, -1)) {
+      entries.push({ source, dest });
+    }
+  }
+  return entries;
+}
+
+/** Build the manifest for a Dockerfile's text and a mercury version. */
+export function buildImageManifest(
+  dockerfile: string,
+  version: string,
+): ImageManifest {
+  const entries = parseCopyInstructions(dockerfile);
+  const copySources = [...new Set(entries.map((e) => e.source))].sort();
+  return {
+    version,
+    // Hashed with line endings normalised. The image is built on Linux and the
+    // host comparing against it may be a Windows checkout with CRLF, which is
+    // the same Dockerfile; without this the check would report drift on every
+    // Windows box and be switched off within a day.
+    dockerfileSha256: createHash("sha256")
+      .update(dockerfile.replace(/\r\n/g, "\n"))
+      .digest("hex"),
+    copySources,
+    entries,
+  };
+}
+
+/**
+ * Compare a host's own Dockerfile against the manifest an image reports.
+ * Returns the differences, empty when the two agree.
+ */
+export function diffImageManifest(
+  hostDockerfile: string,
+  hostVersion: string,
+  image: ImageManifest,
+): string[] {
+  const host = buildImageManifest(hostDockerfile, hostVersion);
+  const problems: string[] = [];
+  if (host.version !== image.version) {
+    problems.push(
+      `version: host is ${host.version}, image reports ${image.version}`,
+    );
+  }
+  for (const source of host.copySources) {
+    if (!image.copySources.includes(source)) {
+      problems.push(`missing from image: ${source}`);
+    }
+  }
+  for (const source of image.copySources) {
+    if (!host.copySources.includes(source)) {
+      problems.push(`in image but not in this host's Dockerfile: ${source}`);
+    }
+  }
+  // Reported last and only when the lists already agree: an identical COPY
+  // list with a different hash means the image was built from a Dockerfile
+  // that differs somewhere else (a RUN, a base image, an ENV), which is real
+  // drift but a much weaker signal than a missing file.
+  if (
+    problems.length === 0 &&
+    host.dockerfileSha256 !== image.dockerfileSha256
+  ) {
+    problems.push(
+      `Dockerfile differs outside its COPY list (host ${host.dockerfileSha256.slice(0, 12)}, image ${image.dockerfileSha256.slice(0, 12)})`,
+    );
+  }
+  return problems;
+}
+
+// Build-time entry point: `bun run image-manifest.ts <dockerfile> <version>`.
+// Writes the manifest to stdout; the Dockerfile redirects it into the image.
+if (import.meta.main) {
+  const [dockerfilePath, version] = process.argv.slice(2);
+  if (!dockerfilePath || !version) {
+    console.error("usage: image-manifest.ts <dockerfile-path> <version>");
+    process.exit(2);
+  }
+  const text = await Bun.file(dockerfilePath).text();
+  console.log(JSON.stringify(buildImageManifest(text, version), null, 2));
+}

package/src/agent/image-refresh.ts

@@ -0,0 +1,318 @@
+/**
+ * When a floating agent-image tag has to be fetched again.
+ *
+ * `ensureImage()` used to return the moment `docker image inspect` succeeded.
+ * The default image is a **floating** tag
+ * (`ghcr.io/…/mercury-agent:latest`, `DEFAULT_AGENT_CONTAINER_IMAGE`), so once
+ * a host had pulled it that tag was never fetched again for the life of the
+ * machine: a box upgraded through npm kept running last month's container
+ * against this month's host code, with `/health` at 200 and nothing in the
+ * log. That is the "green /health, dead bot" mechanism, and it bit the owner
+ * on 2026-09-05.
+ *
+ * The rule here is the narrow half of release-gate R0.4: **a floating tag is
+ * re-pulled whenever the host's Mercury version is not the one that pulled
+ * it.** Pinning the default to `:${pkg.version}` is the other half and waits
+ * on R0.3 — Mercury publishes no per-version tag today, so pinning first would
+ * make every fresh install fail on a tag nobody pushed.
+ *
+ * The decision is pure and the flow (`ensureAgentImage`) drives its pull and
+ * inspect through injected deps, so both can be tested without a daemon. Only
+ * the pull record's read and write live in `container-runner.ts`, which is
+ * where the data dir is.
+ */
+
+/** What the last successful pull recorded, read back from `<dataDir>`. */
+export interface ImagePullRecord {
+  /** The Mercury version whose boot pulled `image`. */
+  version: string;
+  /** The image reference that was pulled. */
+  image: string;
+}
+
+export type ImageRefreshDecision =
+  | { refresh: false; why: "digest-pinned" | "no-registry-host" | "current" }
+  | {
+      refresh: true;
+      why: "never-recorded" | "version-changed" | "ref-changed";
+    };
+
+/** File under `<dataDir>` holding the last {@link ImagePullRecord}. */
+export const IMAGE_PULL_RECORD_FILE = "image-pull.json";
+
+/**
+ * Whether this reference can be re-fetched from a registry at all.
+ *
+ * Two references must never be pulled:
+ *
+ * - **Digest-pinned** (`…@sha256:…`) — it cannot drift, so a pull is pure cost.
+ * - **No registry host** — in this project a bare name is a *local* build:
+ *   `mercury build` tags `mercury-agent:latest` (`LOCAL_BUILD_IMAGE_TAG`) and
+ *   the derived extension image is `mercury-agent-ext:<hash>`. Neither exists
+ *   in any registry, so a pull would fail on every boot and the warning would
+ *   be noise about an image that is exactly where the operator put it.
+ *
+ * Docker's own rule for "is the first path component a registry host": it
+ * contains a `.` or a `:`, or it is literally `localhost`. A bare
+ * Docker-Hub-hosted name (`someuser/mercury-agent:latest`) therefore is not
+ * refreshed — the trade taken deliberately, because a false pull attempt on
+ * every local build is a worse daily cost than a missed refresh on a shape
+ * nothing in this project uses. The boot log still names the ref and its image
+ * id, so drift on such a tag is visible rather than silent.
+ */
+export function isPullableRef(image: string): boolean {
+  const ref = image.trim();
+  if (!ref) return false;
+  if (ref.includes("@")) return false;
+  const firstSlash = ref.indexOf("/");
+  if (firstSlash === -1) return false;
+  const host = ref.slice(0, firstSlash);
+  return host === "localhost" || host.includes(".") || host.includes(":");
+}
+
+/**
+ * Should the image already present locally be pulled again?
+ *
+ * `record === null` means no boot ever recorded a pull — which is the state of
+ * every host that upgraded before this code existed, including the one that
+ * carried a month-old container on 2026-09-05. Absence refreshes: it costs one
+ * pull, once, and it is the only way those hosts ever converge.
+ */
+export function decideImageRefresh(input: {
+  image: string;
+  hostVersion: string;
+  record: ImagePullRecord | null;
+}): ImageRefreshDecision {
+  const { image, hostVersion, record } = input;
+  if (image.includes("@")) return { refresh: false, why: "digest-pinned" };
+  if (!isPullableRef(image)) return { refresh: false, why: "no-registry-host" };
+  if (!record) return { refresh: true, why: "never-recorded" };
+  if (record.image !== image) return { refresh: true, why: "ref-changed" };
+  if (record.version !== hostVersion) {
+    return { refresh: true, why: "version-changed" };
+  }
+  return { refresh: false, why: "current" };
+}
+
+/** Facts about the image the service will actually spawn. */
+export interface ImageFacts {
+  /** Content id (`sha256:…`) — the thing that changes when a tag moves. */
+  id: string | null;
+  /** First `RepoDigests` entry, absent for an image never pulled. */
+  digest: string | null;
+  /** `org.opencontainers.image.version`, or null until release-gate R0.1. */
+  version: string | null;
+  created: string | null;
+}
+
+/**
+ * `docker image inspect --format` template that yields one JSON object per
+ * image. Written as literal text plus `json` actions rather than a `dict`
+ * call, which older daemons' template engines do not provide.
+ */
+export const IMAGE_FACTS_FORMAT =
+  '{"id":{{json .Id}},"repoDigests":{{json .RepoDigests}},' +
+  '"created":{{json .Created}},"labels":{{json .Config.Labels}}}';
+
+/** Labels a Mercury image may record its version under, most specific first. */
+const VERSION_LABELS = [
+  "org.opencontainers.image.version",
+  "com.mercury.version",
+];
+
+/**
+ * Parse {@link IMAGE_FACTS_FORMAT} output. Never throws: an unreadable answer
+ * costs the boot log its detail, not the boot.
+ */
+export function parseImageFacts(stdout: string): ImageFacts {
+  const empty: ImageFacts = {
+    id: null,
+    digest: null,
+    version: null,
+    created: null,
+  };
+  const line = stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .pop();
+  if (!line) return empty;
+  let parsed: {
+    id?: unknown;
+    repoDigests?: unknown;
+    created?: unknown;
+    labels?: unknown;
+  };
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return empty;
+  }
+  const digests = Array.isArray(parsed.repoDigests)
+    ? parsed.repoDigests.filter((d): d is string => typeof d === "string")
+    : [];
+  const labels =
+    parsed.labels && typeof parsed.labels === "object"
+      ? (parsed.labels as Record<string, unknown>)
+      : {};
+  let version: string | null = null;
+  for (const key of VERSION_LABELS) {
+    const value = labels[key];
+    if (typeof value === "string" && value) {
+      version = value;
+      break;
+    }
+  }
+  return {
+    id: typeof parsed.id === "string" ? parsed.id : null,
+    digest: digests[0] ?? null,
+    version,
+    created: typeof parsed.created === "string" ? parsed.created : null,
+  };
+}
+
+/** The docker call `ensureAgentImage` makes, injected so it can be driven. */
+export interface ImageExecResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+export interface EnsureAgentImageDeps {
+  exec(args: string[], timeoutMs: number): Promise<ImageExecResult>;
+  /** The host's Mercury version, or null when the manifest is unreadable. */
+  hostVersion: string | null;
+  readRecord(): ImagePullRecord | null;
+  writeRecord(record: ImagePullRecord): void;
+  log: {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+  };
+}
+
+/** What the boot line reports, returned so a caller (or a test) can read it. */
+export interface EnsureAgentImageResult {
+  image: string;
+  facts: ImageFacts | null;
+  previousId: string | null;
+  refresh: "pulled" | "refreshed" | "skipped" | "failed";
+  reason: string;
+}
+
+const INSPECT_TIMEOUT_MS = 10_000;
+const PULL_TIMEOUT_MS = 300_000;
+
+async function inspect(
+  image: string,
+  deps: EnsureAgentImageDeps,
+): Promise<ImageFacts | null> {
+  const result = await deps.exec(
+    ["image", "inspect", "--format", IMAGE_FACTS_FORMAT, image],
+    INSPECT_TIMEOUT_MS,
+  );
+  if (result.code !== 0) return null;
+  return parseImageFacts(result.stdout);
+}
+
+/**
+ * Make `image` present and current, then say what was resolved.
+ *
+ * Throws only when the image is absent *and* cannot be pulled — that host has
+ * nothing to run. A **refresh** that fails warns and returns: the box already
+ * has a working image, and refusing to boot because a registry was unreachable
+ * would turn a visibility fix into an outage.
+ *
+ * The record is written only after a pull that returned 0. Recording a pull
+ * that did not happen is how a tag stays frozen while the bookkeeping says it
+ * is fresh.
+ */
+export async function ensureAgentImage(
+  image: string,
+  deps: EnsureAgentImageDeps,
+): Promise<EnsureAgentImageResult> {
+  const { hostVersion } = deps;
+  let facts = await inspect(image, deps);
+  const previousId = facts?.id ?? null;
+  let refresh: EnsureAgentImageResult["refresh"] = "skipped";
+  let reason: string;
+
+  if (!facts) {
+    reason = "not-present";
+    // Pull output is captured, not streamed: the HTTP server is already
+    // answering (warming) while this runs, and a synchronous inherit-stdio
+    // pull used to freeze it for up to five minutes.
+    deps.log.info("Agent image not found locally, pulling (can take minutes)", {
+      image,
+    });
+    const pull = await deps.exec(["pull", image], PULL_TIMEOUT_MS);
+    if (pull.code !== 0) {
+      const detail = pull.timedOut
+        ? `timed out after ${PULL_TIMEOUT_MS}ms`
+        : pull.stderr.trim().slice(-2000);
+      throw new Error(
+        `Failed to pull agent image: ${image}${detail ? ` (${detail})` : ""}\n` +
+          `Build it locally with: mercury build\n` +
+          `Or pull manually: docker pull ${image}`,
+      );
+    }
+    deps.log.info("Agent image pulled successfully", { image });
+    refresh = "pulled";
+    facts = await inspect(image, deps);
+    if (hostVersion) deps.writeRecord({ version: hostVersion, image });
+  } else if (!hostVersion) {
+    // No readable host version means there is no comparison to make. Named in
+    // the boot line rather than folded into "current" — a silent skip here
+    // would be the same shape as the bug this exists to fix.
+    reason = "host-version-unreadable";
+  } else {
+    const decision = decideImageRefresh({
+      image,
+      hostVersion,
+      record: deps.readRecord(),
+    });
+    reason = decision.why;
+    if (decision.refresh) {
+      deps.log.info("Agent image tag may be stale, re-pulling", {
+        image,
+        reason: decision.why,
+        hostVersion,
+      });
+      const pull = await deps.exec(["pull", image], PULL_TIMEOUT_MS);
+      if (pull.code === 0) {
+        refresh = "refreshed";
+        facts = (await inspect(image, deps)) ?? facts;
+        deps.writeRecord({ version: hostVersion, image });
+      } else {
+        refresh = "failed";
+        deps.log.warn(
+          `Could not refresh the agent image ${image} - continuing on the copy this host already has, which may predate mercury ${hostVersion}. Pull it by hand (docker pull ${image}) or check the registry credential.`,
+          {
+            image,
+            timedOut: pull.timedOut,
+            detail: pull.stderr.trim().slice(-500),
+          },
+        );
+      }
+    }
+  }
+
+  // The boot line R0.4 asks for: the reference actually resolved, its id and
+  // digest, and the version label when the image carries one (it does not
+  // until R0.1 stamps it - null here is that gap, stated rather than hidden).
+  deps.log.info("Agent image resolved", {
+    image,
+    imageId: facts?.id ?? null,
+    digest: facts?.digest ?? null,
+    imageVersion: facts?.version ?? null,
+    created: facts?.created ?? null,
+    hostVersion,
+    refresh,
+    reason,
+    ...(previousId && facts?.id && previousId !== facts.id
+      ? { previousImageId: previousId }
+      : {}),
+  });
+
+  return { image, facts, previousId, refresh, reason };
+}