machine-bridge-mcp 1.2.8 → 1.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "description": "Cross-client MCP bridge for local agent context, structured browser and application automation, files, Git, processes, resources, and durable jobs over stdio or OAuth relay.",
   "type": "module",
   "license": "MIT",
@@ -47,7 +47,7 @@
     "worker:types": "node scripts/generate-worker-types.mjs",
     "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit && npm run typecheck:local",
     "syntax": "node scripts/syntax-check.mjs",
-    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release:acceptance:test && npm run release-state:test && npm run release-ci:test && npm run network-retry:test && npm run worker-deployment:test && npm run relay:test && npm run secure-file:test && npm run worker-secret-file:test && npm run sarif-security:test && npm run security-properties:test && npm run shell:test && npm run architecture:test && npm run markdown:test && npm run project-metadata:test && npm run numbers:test && npm run records:test && npm run state-inventory:test && npm run commit-message:test && npm run policy:test && npm run account:test && npm run worker-oauth-controller:test && npm run policy-docs:check && npm run tool-docs:check && npm run runtime-infrastructure:test && npm run runtime-boundaries:test && npm run runtime-handlers:test && npm run cli-entrypoint:test && npm run cli-service:test && npm run lifecycle:test && npm run logging-structure:test && npm run coverage:test && npm run worker-runtime-infrastructure:test && npm run lint:test && npm run lint && npm run typecheck && npm run syntax && npm run deadline:test && npm run process-lock:test && npm run service-lifecycle:test && npm run service-environment:test && npm run service-platform:test && npm run catalog:test && npm run agent-context:test && npm run capability-ranking:test && npm run browser-command:test && npm run browser-devtools-input:test && npm run browser-service-worker:test && npm run browser-page-automation:test && npm run browser-bridge:test && npm run app-automation:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run install:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test && npm run oauth-browser:test",
+    "check": "npm run check:full",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",
     "release:check": "node scripts/github-release.mjs --check",
@@ -79,6 +79,7 @@
     "release-state:test": "node tests/release-state-test.mjs",
     "release-ci:test": "node tests/release-ci-test.mjs",
     "agent-context:test": "node tests/agent-context-test.mjs",
+    "agent-boundaries:test": "node tests/agent-boundaries-test.mjs",
     "browser-bridge:test": "node tests/browser-bridge-test.mjs",
     "app-automation:test": "node tests/app-automation-test.mjs",
     "process-lock:test": "node tests/process-lock-test.mjs",
@@ -122,7 +123,13 @@
     "release:candidate": "npm run check && node scripts/local-release-acceptance.mjs --prepare",
     "release:accept": "node scripts/local-release-acceptance.mjs --record",
     "release:acceptance:verify": "node scripts/local-release-acceptance.mjs --verify",
-    "github:push": "node scripts/github-push.mjs"
+    "github:push": "node scripts/github-push.mjs",
+    "check:fast": "node scripts/run-checks.mjs fast",
+    "check:full": "node scripts/run-checks.mjs full",
+    "check-plan:test": "node tests/check-plan-test.mjs",
+    "check:platform": "node scripts/run-checks.mjs platform",
+    "release": "node scripts/github-release.mjs --publish",
+    "release:candidate:start": "node scripts/start-release-candidate.mjs"
   },
   "dependencies": {
     "https-proxy-agent": "9.1.0",

package/scripts/check-plan.mjs

@@ -0,0 +1,91 @@
+export const FAST_CHECK_TASKS = Object.freeze([
+  "privacy:check",
+  "release-impact:check",
+  "release:acceptance:test",
+  "release-state:test",
+  "release-ci:test",
+  "network-retry:test",
+  "secure-file:test",
+  "worker-secret-file:test",
+  "sarif-security:test",
+  "shell:test",
+  "architecture:test",
+  "markdown:test",
+  "project-metadata:test",
+  "numbers:test",
+  "records:test",
+  "state-inventory:test",
+  "commit-message:test",
+  "policy:test",
+  "account:test",
+  "worker-oauth-controller:test",
+  "policy-docs:check",
+  "tool-docs:check",
+  "runtime-infrastructure:test",
+  "runtime-boundaries:test",
+  "runtime-handlers:test",
+  "cli-entrypoint:test",
+  "cli-service:test",
+  "lifecycle:test",
+  "logging-structure:test",
+  "worker-runtime-infrastructure:test",
+  "lint:test",
+  "lint",
+  "typecheck",
+  "syntax",
+  "deadline:test",
+  "catalog:test",
+  "capability-ranking:test",
+  "agent-boundaries:test",
+  "browser-command:test",
+  "check-plan:test",
+]);
+
+export const PLATFORM_ONLY_CHECK_TASKS = Object.freeze([
+  "privacy:test",
+  "release-impact:test",
+  "worker-deployment:test",
+  "relay:test",
+  "security-properties:test",
+  "process-lock:test",
+  "service-lifecycle:test",
+  "service-environment:test",
+  "service-platform:test",
+  "agent-context:test",
+  "browser-devtools-input:test",
+  "browser-service-worker:test",
+  "browser-page-automation:test",
+  "app-automation:test",
+  "self-test",
+  "atomic-fs:test",
+  "ssh-key:test",
+  "full-access:test",
+  "managed-jobs:test",
+]);
+
+export const FULL_ONLY_CHECK_TASKS = Object.freeze([
+  "coverage:test",
+  "browser-bridge:test",
+  "package:test",
+  "install:test",
+  "stdio:integration-test",
+  "worker:integration-test",
+  "oauth-browser:test",
+]);
+
+export const PLATFORM_CHECK_TASKS = Object.freeze([
+  ...FAST_CHECK_TASKS,
+  ...PLATFORM_ONLY_CHECK_TASKS,
+]);
+
+export const FULL_CHECK_TASKS = Object.freeze([
+  ...PLATFORM_CHECK_TASKS,
+  ...FULL_ONLY_CHECK_TASKS,
+]);
+
+export function checkTasks(mode) {
+  if (mode === "fast") return FAST_CHECK_TASKS;
+  if (mode === "platform") return PLATFORM_CHECK_TASKS;
+  if (mode === "full") return FULL_CHECK_TASKS;
+  throw new Error(`unknown check mode: ${mode}`);
+}

package/scripts/coverage-check.mjs

@@ -24,8 +24,12 @@ const tests = [
   "tests/state-inventory-test.mjs",
   "tests/worker-deployment-test.mjs",
   "tests/agent-context-test.mjs",
+  "tests/agent-boundaries-test.mjs",
   "tests/capability-ranking-test.mjs",
   "tests/browser-bridge-test.mjs",
+  "tests/relay-connection-test.mjs",
+  "tests/managed-jobs-test.mjs",
+  "tests/account-admin-test.mjs",
   "tests/monotonic-deadline-test.mjs",
 ];
 
@@ -54,6 +58,7 @@ try {
     "src/local/process-tracker.mjs": [65, 35],
     "src/local/log.mjs": [60, 40],
     "src/local/runtime.mjs": [75, 55],
+    "src/local/runtime-paths.mjs": [90, 50],
     "src/local/cli.mjs": [48, 21.9],
     "src/local/cli-service.mjs": [90, 65],
     "src/local/cli-options.mjs": [65, 35],
@@ -66,6 +71,9 @@ try {
     "src/local/worker-health.mjs": [85, 60],
     "src/local/worker-deployment.mjs": [80, 55],
     "src/local/agent-contract.mjs": [95, 40],
+    "src/local/agent-context-projection.mjs": [95, 60],
+    "src/local/agent-skill-discovery.mjs": [85, 60],
+    "src/local/agent-text-file.mjs": [90, 60],
     "src/local/capability-ranking.mjs": [95, 70],
     "src/local/browser-extension-protocol.mjs": [95, 35],
     "src/local/browser-operation-service.mjs": [80, 50],
@@ -73,9 +81,23 @@ try {
     "src/local/runtime-diagnostics.mjs": [75, 65],
     "src/local/runtime-capabilities.mjs": [75, 45],
     "src/local/monotonic-deadline.mjs": [100, 100],
+    "src/local/state.mjs": [85, 45],
+    "src/local/relay-connection.mjs": [90, 55],
+    "src/local/managed-jobs.mjs": [85, 50],
+    "src/local/managed-job-projection.mjs": [90, 60],
+    "src/local/managed-job-storage.mjs": [75, 50],
+    "src/local/managed-job-runner.mjs": [80, 50],
+    "src/local/browser-bridge.mjs": [80, 55],
+    "src/local/browser-request-registry.mjs": [95, 35],
+    "src/local/browser-broker-routes.mjs": [85, 55],
+    "src/local/browser-broker-server.mjs": [80, 50],
+    "src/worker/oauth-controller.ts": [85, 65],
+    "src/worker/oauth-authorization-page.ts": [90, 60],
     "src/worker/pending-calls.ts": [90, 35],
     "src/worker/policy.ts": [100, 25],
     "src/worker/errors.ts": [100, 40],
+    "src/worker/mcp-jsonrpc.ts": [95, 55],
+    "src/worker/websocket-protocol.ts": [100, 50],
   };
   const failures = [];
   for (const [file, [minimumFunctions, minimumBlocks]] of Object.entries(thresholds)) {

package/scripts/github-push.mjs

@@ -18,7 +18,7 @@ try {
   if (acceptance.required) {
     const path = `release-acceptance/v${acceptance.metadata.package_version}.json`;
     run("git", ["ls-files", "--error-unmatch", path], { capture: true });
-    console.log(`Verified repository-owner local acceptance for ${acceptance.metadata.filename}.`);
+    console.log(`Verified interactive local candidate acceptance for ${acceptance.metadata.filename}.`);
   }
 
   run("git", ["push", "--set-upstream", "origin", "HEAD"]);

package/scripts/github-release.mjs

@@ -342,7 +342,7 @@ function assertLocalAcceptance() {
   try {
     const result = verifyCurrentReleaseAcceptance(root);
     if (result.required) {
-      console.log(`Repository-owner local acceptance matches ${result.metadata.filename} (${result.metadata.shasum}).`);
+      console.log(`Interactive local candidate acceptance matches ${result.metadata.filename} (${result.metadata.shasum}).`);
     }
   } catch (error) {
     fail(String(error?.message || error));

package/scripts/local-release-acceptance.mjs

@@ -2,10 +2,13 @@
 
 import {
   mkdirSync,
+  mkdtempSync,
   readFileSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
@@ -50,10 +53,12 @@ function prepareCandidate() {
   writeFileSync(candidateManifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
   const phrase = confirmationPhrase(pkg.name, pkg.version);
   console.log(`Release candidate created: ${join(candidateDirectory, metadata.filename)}`);
-  console.log("Test this exact tarball on the maintainer machine using the documented normal startup path.");
-  console.log("After the repository owner confirms it works, record that confirmation with:");
+  console.log("The repository owner must start this exact candidate in a local terminal with:");
+  console.log("npm run release:candidate:start -- --allow-worker-deploy");
+  console.log("Leave the candidate running while the coding agent verifies connection readiness and representative functionality through Machine Bridge.");
+  console.log("After that observed live verification succeeds, the coding agent records acceptance with:");
   console.log(`npm run release:accept -- --confirm \"${phrase}\"`);
-  console.log("Do not push this release-relevant branch before that command succeeds and its acceptance record is committed.");
+  console.log("Automated tests alone do not authorize acceptance or the first GitHub push.");
 }
 
 function recordAcceptance() {
@@ -61,7 +66,7 @@ function recordAcceptance() {
   const supplied = argumentValue("--confirm");
   const expected = confirmationPhrase(pkg.name, pkg.version);
   if (supplied !== expected) {
-    throw new Error(`owner confirmation must exactly match: ${expected}`);
+    throw new Error(`interactive candidate verification confirmation must exactly match: ${expected}`);
   }
   const pending = readJson(candidateManifestPath, "release candidate manifest");
   if (pending.result !== "pending" || pending.package_name !== pkg.name || pending.package_version !== pkg.version) {
@@ -89,12 +94,13 @@ function recordAcceptance() {
     shasum: current.shasum,
     integrity: current.integrity,
     accepted_at: new Date().toISOString(),
+    package_content_sha256: computePortablePackageDigest(),
   };
   verifyAcceptanceRecord(record, current);
   const path = acceptancePath(root, pkg.version);
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, "utf8");
-  console.log(`Local owner acceptance recorded: ${path}`);
+  console.log(`Interactive local candidate acceptance recorded: ${path}`);
   console.log("Commit this record with the candidate. Any packaged-file change invalidates it.");
 }
 
@@ -107,6 +113,50 @@ function verifyAcceptance() {
   console.log(`Local release acceptance matches ${result.metadata.filename} (${result.metadata.shasum}).`);
 }
 
+function computePortablePackageDigest() {
+  const npmCli = process.env.npm_execpath;
+  if (!npmCli) throw new Error("portable package digest requires npm_execpath");
+  const temporary = mkdtempSync(join(tmpdir(), "mbm-release-index-"));
+  const indexPath = join(temporary, "index");
+  const env = { ...process.env, GIT_INDEX_FILE: indexPath };
+  try {
+    runChecked("git", ["read-tree", "HEAD"], { env });
+    runChecked("git", ["add", "--all", "--", "."], { env });
+    const packed = runChecked(process.execPath, [
+      npmCli,
+      "pack",
+      "--ignore-scripts",
+      "--silent",
+      "--dry-run",
+      "--json",
+    ], { env });
+    const verifier = runChecked(process.execPath, [
+      join(root, ".github", "scripts", "verify-release-acceptance.mjs"),
+      "--print-digest",
+    ], { env, input: packed.stdout });
+    const digest = verifier.stdout.trim();
+    if (!/^[0-9a-f]{64}$/.test(digest)) throw new Error("portable package digest output is invalid");
+    return digest;
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+function runChecked(file, args, { env = process.env, input } = {}) {
+  const result = spawnSync(file, args, {
+    cwd: root,
+    encoding: "utf8",
+    env,
+    input,
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`${file} ${args[0] || ""} failed: ${String(result.stderr || result.stdout).trim()}`);
+  }
+  return result;
+}
+
 function readPackage() {
   return readJson(join(root, "package.json"), "package.json");
 }
@@ -127,7 +177,7 @@ function argumentValue(name) {
 }
 
 function confirmationPhrase(name, version) {
-  return `I TESTED ${name} ${version} LOCALLY AND IT WORKS`;
+  return `I VERIFIED ${name} ${version} CANDIDATE ON THE OWNER MACHINE AND IT WORKS`;
 }
 
 function fail(message) {

package/scripts/release-acceptance.mjs

@@ -11,13 +11,21 @@ import { spawnSync } from "node:child_process";
 
 export const ACCEPTANCE_SCHEMA_VERSION = 1;
 export const ACCEPTANCE_POLICY_VERSION = "1.2.8";
-export const ACCEPTANCE_CONFIRMATION = "repository-owner-local-test";
+export const AGENT_VERIFIED_ACCEPTANCE_VERSION = "1.2.9";
+export const ACCEPTANCE_CONFIRMATION = "owner-started-agent-verified-local-candidate";
+export const LEGACY_ACCEPTANCE_CONFIRMATION = "repository-owner-local-test";
 const MAX_ACCEPTANCE_BYTES = 64 * 1024;
 
 export function requiresLocalAcceptance(version) {
   return compareVersions(parseVersion(version), parseVersion(ACCEPTANCE_POLICY_VERSION)) >= 0;
 }
 
+export function acceptanceConfirmationForVersion(version) {
+  return compareVersions(parseVersion(version), parseVersion(AGENT_VERIFIED_ACCEPTANCE_VERSION)) >= 0
+    ? ACCEPTANCE_CONFIRMATION
+    : LEGACY_ACCEPTANCE_CONFIRMATION;
+}
+
 export function acceptancePath(root, version) {
   return join(root, "release-acceptance", `v${version}.json`);
 }
@@ -92,11 +100,15 @@ export function verifyAcceptanceRecord(record, metadata) {
     throw new Error(`unsupported release acceptance schema: ${record.schema_version}`);
   }
   if (record.result !== "passed") throw new Error("local release acceptance result is not passed");
-  if (record.confirmation !== ACCEPTANCE_CONFIRMATION) {
-    throw new Error("local release acceptance confirmation is missing");
+  const expectedConfirmation = acceptanceConfirmationForVersion(metadata.package_version);
+  if (record.confirmation !== expectedConfirmation) {
+    throw new Error("local release acceptance confirmation is missing or does not match the active verification workflow");
   }
   const acceptedAt = Date.parse(String(record.accepted_at || ""));
   if (!Number.isFinite(acceptedAt)) throw new Error("local release acceptance timestamp is invalid");
+  if (!/^[0-9a-f]{64}$/.test(String(record.package_content_sha256 || ""))) {
+    throw new Error("local release acceptance portable package-content digest is missing or invalid");
+  }
   for (const key of ["package_name", "package_version", "filename", "shasum", "integrity"]) {
     if (record[key] !== metadata[key]) {
       throw new Error(`local release acceptance ${key} does not match the current npm package`);

package/scripts/release-state.mjs

@@ -1,7 +1,7 @@
 export function tagSyncError({ scope = "local", tag, head, commit }) {
   const label = scope === "remote" ? "remote tag" : "local tag";
   if (!commit) {
-    return `${label} ${tag} is missing; run npm run release:publish before npm publish`;
+    return `${label} ${tag} is missing; run npm run release before npm publish`;
   }
   if (commit !== head) {
     return `${label} ${tag} points to ${commit}, not HEAD ${head}`;

package/scripts/run-checks.mjs

@@ -0,0 +1,29 @@
+import { spawnSync } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { checkTasks } from "./check-plan.mjs";
+
+const mode = process.argv[2] || "full";
+const tasks = checkTasks(mode);
+const npmCli = process.env.npm_execpath;
+if (!npmCli) throw new Error("check runner must run through npm so npm_execpath is available");
+const planStartedAt = performance.now();
+
+console.log(`running ${mode} verification plan (${tasks.length} tasks)`);
+for (const [index, task] of tasks.entries()) {
+  const taskStartedAt = performance.now();
+  console.log(`\n[${index + 1}/${tasks.length}] npm run ${task}`);
+  const result = spawnSync(process.execPath, [npmCli, "run", task], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+  });
+  const elapsedSeconds = ((performance.now() - taskStartedAt) / 1000).toFixed(1);
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    console.error(`verification task failed after ${elapsedSeconds}s: ${task}`);
+    process.exit(result.status || 1);
+  }
+  console.log(`completed ${task} in ${elapsedSeconds}s`);
+}
+const totalSeconds = ((performance.now() - planStartedAt) / 1000).toFixed(1);
+console.log(`\n${mode} verification plan passed in ${totalSeconds}s`);

package/scripts/start-release-candidate.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { verifyTarball } from "./release-acceptance.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const candidateDirectory = join(root, ".release-candidate");
+const manifestPath = join(candidateDirectory, "manifest.json");
+const installPrefix = join(candidateDirectory, "runtime");
+const npmCli = process.env.npm_execpath;
+
+if (!npmCli) fail("candidate startup must run through npm so npm_execpath is available");
+
+try {
+  const manifest = readJson(manifestPath, "release candidate manifest");
+  if (manifest.result !== "pending") throw new Error("release candidate manifest is not pending");
+  const tarball = join(candidateDirectory, String(manifest.filename || ""));
+  verifyTarball(tarball, manifest);
+
+  const npmVersion = runNpm(["--version"], root).stdout.trim();
+  if (Number(npmVersion.split(".")[0]) < 12) {
+    throw new Error(`candidate startup requires npm 12 or newer; current ${npmVersion}`);
+  }
+
+  rmSync(installPrefix, { recursive: true, force: true });
+  mkdirSync(installPrefix, { recursive: true });
+  runNpm([
+    "install",
+    "--global",
+    "--prefix", installPrefix,
+    "--omit=optional",
+    "--allow-scripts=esbuild,workerd,sharp,fsevents",
+    tarball,
+  ], root);
+
+  const globalRoot = runNpm(["root", "--global", "--prefix", installPrefix], root).stdout.trim();
+  const installedPackage = join(globalRoot, manifest.package_name);
+  const installed = readJson(join(installedPackage, "package.json"), "installed candidate package");
+  if (installed.version !== manifest.package_version) {
+    throw new Error(`installed candidate version ${installed.version} does not match ${manifest.package_version}`);
+  }
+
+  console.log(`Verified candidate tarball: ${manifest.filename} (${manifest.shasum})`);
+  console.log(`Installed isolated candidate: ${installedPackage}`);
+  const installOnly = process.argv.includes("--install-only");
+  const allowWorkerDeploy = process.argv.includes("--allow-worker-deploy");
+  if (installOnly) {
+    console.log("Candidate installation check passed; startup was skipped by --install-only.");
+    process.exit(0);
+  }
+
+  if (!allowWorkerDeploy) {
+    throw new Error("foreground candidate startup may update the configured same-name Worker; rerun with --allow-worker-deploy to authorize that live candidate deployment");
+  }
+
+  const forwardedArgs = process.argv.slice(2).filter((value) => value !== "--install-only" && value !== "--allow-worker-deploy");
+  const cli = join(installedPackage, "bin", "machine-mcp.mjs");
+  console.log("Authorized live candidate deployment: startup may update the configured same-name Worker when its version or deployment hash differs.");
+  console.log("Starting the exact candidate in the foreground. Leave this process running while the coding agent verifies the Worker, relay, and local runtime end to end.");
+  const child = spawn(process.execPath, [cli, ...forwardedArgs], {
+    cwd: root,
+    env: process.env,
+    stdio: "inherit",
+    windowsHide: true,
+  });
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, () => {
+      try { child.kill(signal); } catch {
+        // The child may already have exited.
+      }
+    });
+  }
+  child.once("error", (error) => fail(error?.message || error));
+  child.once("exit", (code, signal) => {
+    if (signal) {
+      console.error(`release candidate exited from ${signal}`);
+      process.exitCode = 1;
+      return;
+    }
+    process.exitCode = code ?? 1;
+  });
+} catch (error) {
+  fail(error?.message || error);
+}
+
+function runNpm(args, cwd) {
+  const result = spawnSync(process.execPath, [npmCli, ...args], {
+    cwd,
+    encoding: "utf8",
+    env: process.env,
+    timeout: 300_000,
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`npm ${args[0]} failed: ${result.stderr || result.stdout}`);
+  return result;
+}
+
+function readJson(path, label) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`${label} is unavailable or invalid: ${error.message}`);
+  }
+}
+
+function fail(message) {
+  console.error(`release candidate startup failed: ${message}`);
+  process.exit(1);
+}

package/src/local/agent-context-projection.mjs

@@ -0,0 +1,158 @@
+// @ts-check
+import { createHash } from "node:crypto";
+
+/** @typedef {(value: string) => string} DisplayPath */
+/**
+ * @typedef {object} InstructionItem
+ * @property {string} [source]
+ * @property {string} [path]
+ * @property {string} scope
+ * @property {number} bytes
+ * @property {string} sha256
+ * @property {number} precedence
+ * @property {string} content
+ */
+/**
+ * @typedef {object} SkillSummary
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ * @property {string} entrypoint
+ * @property {string} sourceRoot
+ * @property {number} bytes
+ * @property {string} sha256
+ */
+/**
+ * @typedef {object} CommandSummary
+ * @property {string} name
+ * @property {string} description
+ * @property {string[]} argv
+ * @property {string} cwd
+ * @property {number} timeoutSeconds
+ * @property {boolean} allowExtraArgs
+ * @property {string} source
+ * @property {string} [sourceType]
+ * @property {string} [script]
+ */
+/**
+ * @typedef {object} ProjectionState
+ * @property {string[]} configFiles
+ * @property {InstructionItem | null} builtinInstructions
+ * @property {InstructionItem | null} automaticProjectContext
+ * @property {InstructionItem | null} modelInstructions
+ * @property {InstructionItem[]} instructions
+ * @property {Map<string, CommandSummary>} commands
+ */
+
+/** @param {ProjectionState} state @param {SkillSummary[]} skills */
+export function capabilityFingerprint(state, skills) {
+  return sha256(JSON.stringify({
+    configs: state.configFiles,
+    instructions: [
+      state.builtinInstructions?.sha256 || "",
+      state.automaticProjectContext?.sha256 || "",
+      state.modelInstructions?.sha256 || "",
+      ...state.instructions.map((item) => item.sha256),
+    ],
+    skills: skills.map((skill) => [skill.id, skill.sha256]),
+    commands: [...state.commands.values()].map((command) => [command.name, command.argv]),
+  }));
+}
+
+/** @param {SkillSummary} skill @param {DisplayPath} displayPath */
+export function publicSkill(skill, displayPath) {
+  return {
+    id: skill.id,
+    name: skill.name,
+    description: skill.description,
+    entrypoint: displayPath(skill.entrypoint),
+    source_root: displayPath(skill.sourceRoot),
+    bytes: skill.bytes,
+    sha256: skill.sha256,
+  };
+}
+
+/** @param {SkillSummary[]} skills @param {DisplayPath} displayPath @param {number} maxSkills @param {number} budgetChars */
+export function contextSkillSummaries(skills, displayPath, maxSkills, budgetChars) {
+  /** @type {Array<ReturnType<typeof publicSkill> & {description_truncated?: boolean}>} */
+  const selected = [];
+  let used = 0;
+  for (const skill of skills) {
+    if (selected.length >= maxSkills) return { skills: selected, truncated: true };
+    const item = publicSkill(skill, displayPath);
+    const fullSize = JSON.stringify(item).length;
+    if (used + fullSize <= budgetChars) {
+      selected.push(item);
+      used += fullSize;
+      continue;
+    }
+    const withoutDescription = { ...item, description: "", description_truncated: true };
+    const baseSize = JSON.stringify(withoutDescription).length;
+    const available = budgetChars - used - baseSize;
+    if (available >= 32) selected.push({ ...withoutDescription, description: item.description.slice(0, available) });
+    return { skills: selected, truncated: true };
+  }
+  return { skills: selected, truncated: false };
+}
+
+/** @param {Array<{entrypoint: string, message: string}>} warnings @param {DisplayPath} displayPath */
+export function publicSkillWarnings(warnings, displayPath) {
+  return warnings.map((warning) => ({ entrypoint: displayPath(warning.entrypoint), message: warning.message }));
+}
+
+/** @param {Map<string, CommandSummary>} commands @param {DisplayPath} displayPath */
+export function publicCommands(commands, displayPath) {
+  return [...commands.values()]
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((command) => ({
+      name: command.name,
+      description: command.description,
+      argv: [...command.argv],
+      cwd: displayPath(command.cwd),
+      timeout_seconds: command.timeoutSeconds,
+      allow_extra_args: command.allowExtraArgs,
+      source: displayPath(command.source),
+      source_type: command.sourceType || "agent-config",
+      ...(command.script ? { package_script: command.script } : {}),
+    }));
+}
+
+/** @param {ProjectionState} state */
+export function effectiveInstructionItems(state) {
+  return [
+    ...(state.builtinInstructions ? [state.builtinInstructions] : []),
+    ...(state.automaticProjectContext ? [state.automaticProjectContext] : []),
+    ...(state.modelInstructions ? [state.modelInstructions] : []),
+    ...state.instructions,
+  ];
+}
+
+/** @param {InstructionItem | null} item @param {boolean} includeContent */
+export function publicVirtualInstruction(item, includeContent) {
+  if (!item) return null;
+  return {
+    source: item.source,
+    scope: item.scope,
+    bytes: item.bytes,
+    sha256: item.sha256,
+    precedence: item.precedence,
+    ...(includeContent ? { content: item.content } : {}),
+  };
+}
+
+/** @param {InstructionItem[]} instructions @param {DisplayPath} displayPath */
+export function renderEffectiveInstructions(instructions, displayPath) {
+  return instructions.map((item) => {
+    const source = item.source || displayPath(item.path || "");
+    return [
+      `--- BEGIN ${source} (precedence ${item.precedence}) ---`,
+      item.content,
+      `--- END ${source} ---`,
+    ].join("\n");
+  }).join("\n\n");
+}
+
+/** @param {unknown} value */
+export function sha256(value) {
+  return createHash("sha256").update(String(value)).digest("hex");
+}