@openagentsinc/pylon 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# `@openagentsinc/pylon`
+
+Bootstrap the latest tagged standalone `Pylon` release asset from GitHub
+Releases and run the first-run smoke path without Cargo.
+
+## Usage
+
+```bash
+npx @openagentsinc/pylon
+npx @openagentsinc/pylon --version 0.1.0
+npx @openagentsinc/pylon --model gemma-4-e2b --diagnostic-repeats 2
+```
+
+The launcher:
+
+- resolves the latest tagged `pylon-v...` release by default, or a specific
+  tagged `Pylon` version when `--version` is provided
+- resolves the correct `pylon-v<version>-<os>-<arch>.tar.gz` asset for the
+  current machine
+- downloads the archive and published SHA-256 checksum
+- verifies the checksum before extracting
+- caches the unpacked binaries under `~/.openagents/pylon/bootstrap/`
+- runs `pylon --help`, `init`, `status --json`, and `inventory --json`
+- runs `pylon gemma download <model>`
+- runs `pylon gemma diagnose <model> --json`
+
+## Publish
+
+Publish directly from this package directory:
+
+```bash
+cd packages/pylon-bootstrap
+npm publish
+```

package/bin/pylon.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@openagentsinc/pylon",
+  "version": "0.1.0",
+  "description": "Bootstrap the standalone OpenAgents Pylon release asset and run first-run smoke checks.",
+  "type": "module",
+  "bin": {
+    "pylon": "./bin/pylon.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OpenAgentsInc/openagents.git",
+    "directory": "packages/pylon-bootstrap"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0"
+}

package/src/cli.js

@@ -0,0 +1,169 @@
+import {
+  DEFAULT_DIAGNOSTIC_MAX_OUTPUT_TOKENS,
+  DEFAULT_DIAGNOSTIC_REPEATS,
+  DEFAULT_MODEL_ID,
+  DEFAULT_RELEASE_API_BASE,
+  DEFAULT_RELEASE_REPO,
+  bootstrapInstalledPylon,
+  ensureReleaseInstall,
+  renderBootstrapSummary,
+} from "./index.js";
+
+function parseIntegerFlag(value, label) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+export function usage() {
+  return `Usage:
+  npx @openagentsinc/pylon [options]
+
+Description:
+  Download the latest tagged standalone Pylon release asset for this machine,
+  or a specific tagged Pylon version when --version is set. Verify its
+  checksum, cache the binaries locally, and run the first-run smoke path.
+
+Options:
+  --version <x.y.z>                    Resolve a specific Pylon release.
+  --install-root <path>                Override the launcher cache/install root.
+  --config-path <path>                 Override OPENAGENTS_PYLON_CONFIG_PATH.
+  --pylon-home <path>                  Override OPENAGENTS_PYLON_HOME.
+  --model <model-id>                   Model to download and diagnose.
+                                       Default: ${DEFAULT_MODEL_ID}
+  --diagnostic-repeats <n>             Repeat count for pylon gemma diagnose.
+                                       Default: ${DEFAULT_DIAGNOSTIC_REPEATS}
+  --diagnostic-max-output-tokens <n>   Max output tokens for diagnostics.
+                                       Default: ${DEFAULT_DIAGNOSTIC_MAX_OUTPUT_TOKENS}
+  --skip-model-download                Skip pylon gemma download.
+  --skip-diagnostics                   Skip pylon gemma diagnose.
+  --json                               Emit a machine-readable JSON summary.
+
+Test and maintainer options:
+  --repo <owner/name>                  Override the GitHub release repo.
+  --api-base <url>                     Override the GitHub API base URL.
+  -h, --help                           Show this help text.
+`;
+}
+
+export function parseArgs(argv) {
+  const options = {
+    version: null,
+    repo: DEFAULT_RELEASE_REPO,
+    apiBase: DEFAULT_RELEASE_API_BASE,
+    installRoot: null,
+    configPath: null,
+    pylonHome: null,
+    model: DEFAULT_MODEL_ID,
+    diagnosticRepeats: DEFAULT_DIAGNOSTIC_REPEATS,
+    diagnosticMaxOutputTokens: DEFAULT_DIAGNOSTIC_MAX_OUTPUT_TOKENS,
+    skipModelDownload: false,
+    skipDiagnostics: false,
+    json: false,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case "--version":
+        options.version = argv[++index];
+        if (!options.version) {
+          throw new Error("--version requires a value.");
+        }
+        break;
+      case "--install-root":
+        options.installRoot = argv[++index];
+        if (!options.installRoot) {
+          throw new Error("--install-root requires a value.");
+        }
+        break;
+      case "--config-path":
+        options.configPath = argv[++index];
+        if (!options.configPath) {
+          throw new Error("--config-path requires a value.");
+        }
+        break;
+      case "--pylon-home":
+        options.pylonHome = argv[++index];
+        if (!options.pylonHome) {
+          throw new Error("--pylon-home requires a value.");
+        }
+        break;
+      case "--model":
+        options.model = argv[++index];
+        if (!options.model) {
+          throw new Error("--model requires a value.");
+        }
+        break;
+      case "--diagnostic-repeats":
+        options.diagnosticRepeats = parseIntegerFlag(
+          argv[++index],
+          "--diagnostic-repeats",
+        );
+        break;
+      case "--diagnostic-max-output-tokens":
+        options.diagnosticMaxOutputTokens = parseIntegerFlag(
+          argv[++index],
+          "--diagnostic-max-output-tokens",
+        );
+        break;
+      case "--skip-model-download":
+        options.skipModelDownload = true;
+        break;
+      case "--skip-diagnostics":
+        options.skipDiagnostics = true;
+        break;
+      case "--json":
+        options.json = true;
+        break;
+      case "--repo":
+        options.repo = argv[++index];
+        if (!options.repo) {
+          throw new Error("--repo requires a value.");
+        }
+        break;
+      case "--api-base":
+        options.apiBase = argv[++index];
+        if (!options.apiBase) {
+          throw new Error("--api-base requires a value.");
+        }
+        break;
+      case "-h":
+      case "--help":
+        options.help = true;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+export async function main(argv = process.argv.slice(2), dependencies = {}) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    console.log(usage());
+    return null;
+  }
+
+  const install = await ensureReleaseInstall(options, dependencies);
+  const summary = await bootstrapInstalledPylon(
+    {
+      ...options,
+      ...install,
+      version: install.version,
+    },
+    dependencies,
+  );
+
+  if (options.json) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log(renderBootstrapSummary(summary));
+  }
+  return summary;
+}

package/src/index.js

@@ -0,0 +1,585 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { createReadStream } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+export const DEFAULT_RELEASE_REPO = "OpenAgentsInc/openagents";
+export const DEFAULT_RELEASE_API_BASE = "https://api.github.com";
+export const DEFAULT_MODEL_ID = "gemma-4-e4b";
+export const DEFAULT_DIAGNOSTIC_REPEATS = 3;
+export const DEFAULT_DIAGNOSTIC_MAX_OUTPUT_TOKENS = 96;
+const PYLON_RELEASE_TAG_PREFIX = "pylon-v";
+
+function normalizeVersion(value) {
+  return value.replace(/^pylon-v/, "").replace(/^v/, "");
+}
+
+async function pathExists(value) {
+  try {
+    await fs.access(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultInstallRoot() {
+  return path.join(os.homedir(), ".openagents", "pylon", "bootstrap");
+}
+
+function requestHeaders() {
+  const headers = {
+    accept: "application/vnd.github+json",
+    "user-agent": "@openagentsinc/pylon bootstrap",
+  };
+  if (process.env.GITHUB_TOKEN) {
+    headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  }
+  return headers;
+}
+
+export function resolvePlatformTarget(
+  platform = process.platform,
+  arch = process.arch,
+) {
+  const osLabel =
+    {
+      darwin: "darwin",
+      linux: "linux",
+    }[platform] ?? null;
+  if (!osLabel) {
+    throw new Error(
+      `Unsupported platform \`${platform}\`. The npm launcher only supports darwin and linux in v1.`,
+    );
+  }
+
+  const archLabel =
+    {
+      arm64: "arm64",
+      aarch64: "arm64",
+      x64: "x86_64",
+      x86_64: "x86_64",
+    }[arch] ?? null;
+  if (!archLabel) {
+    throw new Error(
+      `Unsupported architecture \`${arch}\`. The npm launcher only supports arm64 and x64 in v1.`,
+    );
+  }
+
+  return { os: osLabel, arch: archLabel };
+}
+
+export function buildArchiveBasename(version, target) {
+  const normalizedVersion = normalizeVersion(version);
+  return `pylon-v${normalizedVersion}-${target.os}-${target.arch}`;
+}
+
+export function buildAssetNames(version, target) {
+  const archiveBasename = buildArchiveBasename(version, target);
+  return {
+    archiveBasename,
+    archiveName: `${archiveBasename}.tar.gz`,
+    checksumName: `${archiveBasename}.tar.gz.sha256`,
+  };
+}
+
+export function parseSha256File(payload, expectedAssetName) {
+  const match = payload
+    .trim()
+    .match(/^([a-fA-F0-9]{64})\s+\*?([^\r\n]+)$/m);
+  if (!match) {
+    throw new Error("Release checksum file did not contain a valid SHA-256 line.");
+  }
+
+  const [, sha256, filename] = match;
+  if (
+    expectedAssetName &&
+    path.basename(filename.trim()) !== path.basename(expectedAssetName)
+  ) {
+    throw new Error(
+      `Release checksum file was for \`${filename.trim()}\`, expected \`${expectedAssetName}\`.`,
+    );
+  }
+
+  return sha256.toLowerCase();
+}
+
+async function fetchJson(fetchImpl, url) {
+  const response = await fetchImpl(url, {
+    headers: requestHeaders(),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `GitHub release lookup failed for ${url} (${response.status} ${response.statusText}).`,
+    );
+  }
+  return response.json();
+}
+
+async function fetchText(fetchImpl, url) {
+  const response = await fetchImpl(url, {
+    headers: requestHeaders(),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Download failed for ${url} (${response.status} ${response.statusText}).`,
+    );
+  }
+  return response.text();
+}
+
+async function downloadFile(fetchImpl, url, destination) {
+  const response = await fetchImpl(url, {
+    headers: requestHeaders(),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Download failed for ${url} (${response.status} ${response.statusText}).`,
+    );
+  }
+  const payload = Buffer.from(await response.arrayBuffer());
+  await fs.mkdir(path.dirname(destination), { recursive: true });
+  await fs.writeFile(destination, payload);
+}
+
+async function sha256File(filePath) {
+  const hash = createHash("sha256");
+  const stream = createReadStream(filePath);
+  return new Promise((resolve, reject) => {
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("end", () => resolve(hash.digest("hex")));
+    stream.on("error", reject);
+  });
+}
+
+export function normalizeRequestedVersion(value) {
+  if (!value || value === "latest") {
+    return null;
+  }
+  return normalizeVersion(value);
+}
+
+export function isPylonReleaseTag(tagName) {
+  return (
+    typeof tagName === "string" &&
+    tagName.startsWith(PYLON_RELEASE_TAG_PREFIX)
+  );
+}
+
+export function selectLatestPylonRelease(releases) {
+  if (!Array.isArray(releases)) {
+    throw new Error("GitHub release lookup did not return a release list.");
+  }
+
+  const release = releases.find(
+    (candidate) => !candidate?.draft && isPylonReleaseTag(candidate?.tag_name),
+  );
+  if (!release) {
+    throw new Error(
+      `GitHub release lookup did not find any published ${PYLON_RELEASE_TAG_PREFIX} releases.`,
+    );
+  }
+
+  return release;
+}
+
+export async function fetchReleaseMetadata({
+  fetchImpl = globalThis.fetch,
+  apiBase = DEFAULT_RELEASE_API_BASE,
+  repo = DEFAULT_RELEASE_REPO,
+  version = null,
+} = {}) {
+  const normalizedVersion = normalizeRequestedVersion(version);
+  const endpoint = normalizedVersion
+    ? `/repos/${repo}/releases/tags/${encodeURIComponent(
+        `${PYLON_RELEASE_TAG_PREFIX}${normalizedVersion}`,
+      )}`
+    : `/repos/${repo}/releases?per_page=100`;
+  const url = `${apiBase.replace(/\/$/, "")}${endpoint}`;
+  const payload = await fetchJson(fetchImpl, url);
+  return normalizedVersion ? payload : selectLatestPylonRelease(payload);
+}
+
+export function selectReleaseAssets(release, target) {
+  const tagName = release?.tag_name;
+  if (!tagName) {
+    throw new Error("GitHub release metadata did not include a tag name.");
+  }
+  const version = normalizeVersion(tagName);
+  const { archiveBasename, archiveName, checksumName } = buildAssetNames(
+    version,
+    target,
+  );
+  const assets = Array.isArray(release.assets) ? release.assets : [];
+  const archiveAsset = assets.find((asset) => asset.name === archiveName);
+  const checksumAsset = assets.find((asset) => asset.name === checksumName);
+
+  if (!archiveAsset || !checksumAsset) {
+    throw new Error(
+      `Release ${tagName} is missing ${archiveName} or ${checksumName}.`,
+    );
+  }
+
+  return {
+    tagName,
+    version,
+    archiveBasename,
+    archiveAsset: {
+      name: archiveAsset.name,
+      url: archiveAsset.browser_download_url,
+    },
+    checksumAsset: {
+      name: checksumAsset.name,
+      url: checksumAsset.browser_download_url,
+    },
+  };
+}
+
+export function buildInstallPaths(installRoot, version, target) {
+  const { archiveBasename, archiveName, checksumName } = buildAssetNames(
+    version,
+    target,
+  );
+  const normalizedRoot = path.resolve(installRoot ?? defaultInstallRoot());
+  const versionsDir = path.join(normalizedRoot, "versions");
+  const downloadsDir = path.join(normalizedRoot, "downloads", `pylon-v${normalizeVersion(version)}`);
+  const installDir = path.join(versionsDir, archiveBasename);
+
+  return {
+    installRoot: normalizedRoot,
+    versionsDir,
+    downloadsDir,
+    installDir,
+    archiveBasename,
+    archivePath: path.join(downloadsDir, archiveName),
+    checksumPath: path.join(downloadsDir, checksumName),
+    manifestPath: path.join(installDir, "install.json"),
+    pylonPath: path.join(installDir, "pylon"),
+    pylonTuiPath: path.join(installDir, "pylon-tui"),
+  };
+}
+
+export async function runProcess(
+  command,
+  args,
+  { cwd, env } = {},
+) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => {
+      reject(
+        new Error(
+          `Failed to start ${command}: ${error instanceof Error ? error.message : String(error)}`,
+        ),
+      );
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      reject(
+        new Error(
+          `${command} ${args.join(" ")} exited with code ${code}${
+            stderr.trim() ? `: ${stderr.trim()}` : ""
+          }`,
+        ),
+      );
+    });
+  });
+}
+
+async function extractArchive(archivePath, destinationDir, runProcessImpl) {
+  await fs.mkdir(destinationDir, { recursive: true });
+  await runProcessImpl("tar", ["-xzf", archivePath, "-C", destinationDir]);
+}
+
+function buildPylonEnv({ configPath, pylonHome } = {}) {
+  const env = { ...process.env };
+  if (configPath) {
+    env.OPENAGENTS_PYLON_CONFIG_PATH = path.resolve(configPath);
+  }
+  if (pylonHome) {
+    env.OPENAGENTS_PYLON_HOME = path.resolve(pylonHome);
+  }
+  return env;
+}
+
+async function runPylonCommand(pylonPath, args, options, runProcessImpl) {
+  return runProcessImpl(pylonPath, args, {
+    env: buildPylonEnv(options),
+  });
+}
+
+async function runPylonJson(pylonPath, args, options, runProcessImpl) {
+  const { stdout } = await runPylonCommand(
+    pylonPath,
+    args,
+    options,
+    runProcessImpl,
+  );
+  try {
+    return JSON.parse(stdout);
+  } catch (error) {
+    throw new Error(
+      `Pylon returned invalid JSON for \`${[path.basename(pylonPath), ...args].join(" ")}\`: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
+export async function ensureReleaseInstall(
+  options = {},
+  {
+    fetchImpl = globalThis.fetch,
+    runProcessImpl = runProcess,
+  } = {},
+) {
+  if (typeof fetchImpl !== "function") {
+    throw new Error("A global fetch implementation is required to bootstrap Pylon.");
+  }
+
+  const target = resolvePlatformTarget(options.platform, options.arch);
+  const installRoot = options.installRoot ?? defaultInstallRoot();
+  const release = await fetchReleaseMetadata({
+    fetchImpl,
+    apiBase: options.apiBase ?? DEFAULT_RELEASE_API_BASE,
+    repo: options.repo ?? DEFAULT_RELEASE_REPO,
+    version: options.version ?? null,
+  });
+  const selected = selectReleaseAssets(release, target);
+  const paths = buildInstallPaths(installRoot, selected.version, target);
+
+  const binariesPresent =
+    (await pathExists(paths.pylonPath)) && (await pathExists(paths.pylonTuiPath));
+  if (binariesPresent) {
+    return {
+      ...selected,
+      ...paths,
+      target,
+      expectedSha256: await fs
+        .readFile(paths.manifestPath, "utf8")
+        .then((payload) => JSON.parse(payload).sha256)
+        .catch(() => null),
+      cached: true,
+    };
+  }
+
+  const checksumPayload = await fetchText(fetchImpl, selected.checksumAsset.url);
+  const expectedSha256 = parseSha256File(
+    checksumPayload,
+    selected.archiveAsset.name,
+  );
+  await fs.mkdir(paths.downloadsDir, { recursive: true });
+  await fs.writeFile(paths.checksumPath, `${checksumPayload.trim()}\n`);
+
+  let archiveReady = false;
+  if (await pathExists(paths.archivePath)) {
+    archiveReady = (await sha256File(paths.archivePath)) === expectedSha256;
+  }
+  if (!archiveReady) {
+    await downloadFile(fetchImpl, selected.archiveAsset.url, paths.archivePath);
+  }
+
+  const actualSha256 = await sha256File(paths.archivePath);
+  if (actualSha256 !== expectedSha256) {
+    throw new Error(
+      `SHA-256 verification failed for ${selected.archiveAsset.name}: expected ${expectedSha256}, got ${actualSha256}.`,
+    );
+  }
+
+  await fs.rm(paths.installDir, { recursive: true, force: true });
+  await extractArchive(paths.archivePath, paths.versionsDir, runProcessImpl);
+
+  if (!(await pathExists(paths.pylonPath)) || !(await pathExists(paths.pylonTuiPath))) {
+    throw new Error(
+      `Release archive extracted without the expected pylon binaries at ${paths.installDir}.`,
+    );
+  }
+
+  await Promise.allSettled([
+    fs.chmod(paths.pylonPath, 0o755),
+    fs.chmod(paths.pylonTuiPath, 0o755),
+  ]);
+
+  await fs.writeFile(
+    paths.manifestPath,
+    `${JSON.stringify(
+      {
+        version: selected.version,
+        tagName: selected.tagName,
+        target,
+        archive: selected.archiveAsset.name,
+        sha256: expectedSha256,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  return {
+    ...selected,
+    ...paths,
+    target,
+    expectedSha256,
+    cached: false,
+  };
+}
+
+export async function bootstrapInstalledPylon(
+  options,
+  {
+    runProcessImpl = runProcess,
+  } = {},
+) {
+  const pylonPath = path.resolve(options.pylonPath);
+  const pylonTuiPath = path.resolve(options.pylonTuiPath);
+  const model = options.model ?? DEFAULT_MODEL_ID;
+  const diagnosticRepeats =
+    options.diagnosticRepeats ?? DEFAULT_DIAGNOSTIC_REPEATS;
+  const diagnosticMaxOutputTokens =
+    options.diagnosticMaxOutputTokens ?? DEFAULT_DIAGNOSTIC_MAX_OUTPUT_TOKENS;
+
+  await runPylonCommand(pylonPath, ["--help"], options, runProcessImpl);
+  const init = await runPylonJson(pylonPath, ["init"], options, runProcessImpl);
+  const status = await runPylonJson(
+    pylonPath,
+    ["status", "--json"],
+    options,
+    runProcessImpl,
+  );
+  const inventory = await runPylonJson(
+    pylonPath,
+    ["inventory", "--json"],
+    options,
+    runProcessImpl,
+  );
+
+  let download = null;
+  if (!options.skipModelDownload) {
+    download = await runPylonJson(
+      pylonPath,
+      ["gemma", "download", model, "--json"],
+      options,
+      runProcessImpl,
+    );
+  }
+
+  let diagnostic = null;
+  if (!options.skipDiagnostics) {
+    diagnostic = await runPylonJson(
+      pylonPath,
+      [
+        "gemma",
+        "diagnose",
+        model,
+        "--max-output-tokens",
+        String(diagnosticMaxOutputTokens),
+        "--repeats",
+        String(diagnosticRepeats),
+        "--json",
+      ],
+      options,
+      runProcessImpl,
+    );
+  }
+
+  const diagnosticResult =
+    diagnostic?.results?.find((result) => result.model_id === model) ??
+    diagnostic?.results?.[0] ??
+    null;
+
+  return {
+    version: options.version,
+    tagName: options.tagName ?? `pylon-v${options.version}`,
+    target: options.target,
+    cached: Boolean(options.cached),
+    binaries: {
+      pylon: pylonPath,
+      pylonTui: pylonTuiPath,
+    },
+    configPath: init?.config_path ?? options.configPath ?? null,
+    pylonHome: options.pylonHome ? path.resolve(options.pylonHome) : null,
+    init,
+    status,
+    inventory,
+    model,
+    download,
+    diagnostic,
+    diagnosticResult,
+  };
+}
+
+export function renderBootstrapSummary(summary) {
+  const lines = [
+    `Pylon release: ${summary.version} (${summary.target.os}-${summary.target.arch})`,
+    `Archive source: ${summary.tagName}`,
+    `Installed from cache: ${summary.cached ? "yes" : "no"}`,
+    `Pylon binary: ${summary.binaries.pylon}`,
+    `Pylon TUI: ${summary.binaries.pylonTui}`,
+    `Config path: ${summary.configPath ?? "unknown"}`,
+  ];
+
+  const statusState =
+    summary.status?.snapshot?.runtime?.authoritative_status ?? "unknown";
+  const inventoryRows = Array.isArray(summary.inventory?.rows)
+    ? summary.inventory.rows.length
+    : 0;
+  lines.push(`Status state: ${statusState}`);
+  lines.push(`Inventory rows: ${inventoryRows}`);
+
+  if (summary.download) {
+    const result =
+      summary.download?.results?.find((row) => row.model_id === summary.model) ??
+      summary.download?.results?.[0] ??
+      null;
+    lines.push(
+      `Model download (${summary.model}): ${result?.status ?? "completed"}`,
+    );
+  }
+
+  if (summary.diagnostic) {
+    const result = summary.diagnosticResult;
+    lines.push(
+      `Diagnostic (${summary.model}): ${result?.status ?? "unknown"}`,
+    );
+    if (result?.receipt?.mean_total_s != null) {
+      lines.push(
+        `Mean total latency: ${result.receipt.mean_total_s.toFixed(3)}s`,
+      );
+    }
+    if (result?.receipt?.mean_ttft_s != null) {
+      lines.push(
+        `Mean first token latency: ${result.receipt.mean_ttft_s.toFixed(3)}s`,
+      );
+    }
+    if (result?.receipt?.mean_decode_tok_s != null) {
+      lines.push(
+        `Mean decode throughput: ${result.receipt.mean_decode_tok_s.toFixed(2)} tok/s`,
+      );
+    }
+    if (summary.diagnostic.report_path) {
+      lines.push(`Diagnostic report: ${summary.diagnostic.report_path}`);
+    }
+    if (result?.reason) {
+      lines.push(`Diagnostic note: ${result.reason}`);
+    }
+  }
+
+  return lines.join("\n");
+}