@akira-tl/forgerelay 1.0.1 → 1.1.1

package/scripts/debug/accept/support.mjs

@@ -198,20 +198,20 @@ export function curlRequest({ method = "GET", url, headers = {}, body }) {
   return { status, headers: responseHeaders, body: responseBody };
 }
 
-export async function waitForHealth(child) {
+export async function waitForHealth(child, baseUrl = debugBaseUrl) {
   for (let attempt = 0; attempt < 60; attempt += 1) {
     if (child.exitCode !== null) {
       throw new Error(`debug server exited before health check: ${child.exitCode}`);
     }
     try {
-      const response = jsonRequest(`${debugBaseUrl}/healthz`);
+      const response = jsonRequest(`${baseUrl}/healthz`);
       if (response.status === 200) return response.json;
     } catch {
       // Server is still starting.
     }
     await delay(100);
   }
-  throw new Error("debug server did not become healthy on 127.0.0.1:7677");
+  throw new Error(`debug server did not become healthy at ${baseUrl}`);
 }
 
 export async function stopServer(child) {
@@ -397,13 +397,13 @@ export function readHookEntries(path) {
     .map((line) => JSON.parse(line));
 }
 
-export async function assertDebugPortFree() {
+export async function assertPortFree(port) {
   await new Promise((resolvePromise, rejectPromise) => {
-    const socket = connect({ host: "127.0.0.1", port: 7677 });
+    const socket = connect({ host: "127.0.0.1", port });
     socket.setTimeout(500);
     socket.once("connect", () => {
       socket.destroy();
-      rejectPromise(new Error("debug port 7677 is already in use; stop the existing debug server first"));
+      rejectPromise(new Error(`debug port ${port} is already in use; stop the existing debug server first`));
     });
     socket.once("error", (error) => {
       socket.destroy();
@@ -420,6 +420,10 @@ export async function assertDebugPortFree() {
   });
 }
 
+export async function assertDebugPortFree() {
+  await assertPortFree(7677);
+}
+
 export function assertCurlAvailable() {
   const result = spawnSync("curl", ["--version"], { encoding: "utf8" });
   if (result.status !== 0) {

package/scripts/debug/accept.mjs

@@ -263,7 +263,16 @@ try {
   assert.ok(Array.isArray(codeIntelligenceSchema.oneOf));
   assert.deepEqual(
     codeIntelligenceSchema.oneOf.map((variant) => variant.properties.operation.const),
-    ["definition", "hover", "references", "documentSymbols", "workspaceSymbols", "diagnostics"],
+    [
+      "definition",
+      "hover",
+      "references",
+      "documentSymbols",
+      "workspaceSymbols",
+      "diagnostics",
+      "managed.status",
+      "managed.install",
+    ],
   );
   for (const operation of ["references", "documentSymbols", "workspaceSymbols", "diagnostics"]) {
     const boundedSchema = codeIntelligenceSchema.oneOf.find(
@@ -311,7 +320,9 @@ try {
     "host-integration",
     "shell-processes",
     "code-intelligence",
+    "external-mcp",
     "workspace-tasks",
+    "workspace-checkpoints",
     "batch-execution",
   ]);
   const hooksGuide = callTool(oauth.accessToken, sessionId, 78, "read", {

package/scripts/debug/relay-accept/support.mjs

@@ -119,6 +119,46 @@ export function assertSafeRelayInspection(result, { executionWorkspaceId, execut
   assert.doesNotMatch(json, /"ws_[0-9a-f]{10}"/);
 }
 
+const RELAY_IMAGE_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=";
+
+export function installRelayImageFixture(executionCheckout) {
+  writeFileSync(join(executionCheckout, "relay-image.png"), Buffer.from(RELAY_IMAGE_BASE64, "base64"));
+  return RELAY_IMAGE_BASE64;
+}
+
+export function assertRelayedImageResult(result, expectedBase64, gatewayStateDir) {
+  assertToolOk(result, "read image through Workspace Relay");
+  const image = result.content.find((entry) => entry.type === "image");
+  assert.ok(image, "Workspace Relay did not preserve MCP ImageContent");
+  assert.equal(image.mimeType, "image/png");
+  assert.equal(image.data, expectedBase64);
+  assert.deepEqual(result.structuredContent.media, {
+    type: "image",
+    mimeType: "image/png",
+    bytes: Buffer.byteLength(expectedBase64, "base64"),
+  });
+  assert.equal(JSON.stringify(result.structuredContent).includes(expectedBase64), false);
+  assert.equal(JSON.stringify(result._meta ?? {}).includes(expectedBase64), false);
+  assertDirectoryDoesNotContain(gatewayStateDir, expectedBase64);
+  pass("Relay ImageContent passthrough", "Execution 7678 image bytes and MIME reached Gateway 7677 unchanged without Gateway persistence");
+}
+
+function assertDirectoryDoesNotContain(root, needle) {
+  if (!existsSync(root)) return;
+  const target = Buffer.from(needle, "utf8");
+  const pending = [root];
+  while (pending.length > 0) {
+    const directory = pending.pop();
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) pending.push(path);
+      else if (entry.isFile()) {
+        assert.equal(readFileSync(path).includes(target), false, `Gateway persisted relayed image base64 in ${path}`);
+      }
+    }
+  }
+}
+
 export function assertToolOk(result, label) {
   assert.equal(result.isError, undefined, `${label}: ${toolText(result)}`);
 }

package/scripts/debug/relay-accept.mjs

@@ -3,18 +3,11 @@ import { spawn, spawnSync } from "node:child_process";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { once } from "node:events";
 import { connect } from "node:net";
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { debugRoot, repoRoot } from "./runtime.mjs";
-import { relayAcceptanceTopology, assertPortsFree, setupGitProject, runGit, taskStateFiles, findTaskStateFile, assertTaskBodyAbsentFromGateway, assertSafeRelayInspection, assertToolOk, toolText, pass } from "./relay-accept/support.mjs";
+import { relayAcceptanceTopology, assertPortsFree, setupGitProject, runGit, taskStateFiles, findTaskStateFile, assertTaskBodyAbsentFromGateway, assertSafeRelayInspection, installRelayImageFixture, assertRelayedImageResult, assertToolOk, toolText, pass } from "./relay-accept/support.mjs";
 
 const {
   gatewayPort, executionPort, gatewayBaseUrl, gatewayMcpUrl, executionBaseUrl,
@@ -30,6 +23,7 @@ await assertPortsFree([gatewayPort, executionPort]);
 rmSync(acceptanceRoot, { recursive: true, force: true });
 mkdirSync(gatewayLocalProject, { recursive: true });
 mkdirSync(executionCheckout, { recursive: true });
+const relayImageBase64 = installRelayImageFixture(executionCheckout);
 mkdirSync(gatewayConfigDir, { recursive: true });
 mkdirSync(executionConfigDir, { recursive: true });
 writeFileSync(join(gatewayLocalProject, "sentinel.txt"), "gateway-local-content\n");
@@ -112,6 +106,10 @@ try {
   assert.equal(openedB.structuredContent.workspaceId, checkoutRelayId);
   pass("relay persistent identity", `two Gateway conversations reused ${checkoutRelayId}`);
 
+  assertRelayedImageResult(callTool(gatewayMcpUrl, oauth.accessToken, sessionB, nextId(), "read", {
+    workspaceId: checkoutRelayId, path: "relay-image.png",
+  }, conversationB), relayImageBase64, gatewayStateDir);
+
   const checkoutList = callTool(gatewayMcpUrl, oauth.accessToken, sessionA, nextId(), "capability", {
     workspaceId: checkoutRelayId,
     name: "workspace.tasks",
@@ -508,6 +506,7 @@ try {
     ports: [gatewayPort, executionPort],
     verified: [
       "persistent relay checkout identity across Gateway conversations",
+      "MCP ImageContent passthrough from Execution 7678 through Gateway 7677",
       "Execution-owned Task state and body-free reminders",
       "safe relayed inspection projection",
       "close/reopen/delete parity",

package/scripts/debug/runtime.mjs

@@ -90,21 +90,24 @@ export function createInteractiveDebugEnvironment({
 
 export function createDebugEnvironment({
   ownerToken,
+  configDir = debugConfigDir,
   stateDir = resolve(debugRoot, "state"),
   worktreeRoot = resolve(debugRoot, "worktrees"),
   hookLog = debugHookLog,
   widgets = process.env.FORGERELAY_DEBUG_WIDGETS ?? "off",
 } = {}) {
   const token = ownerToken ?? process.env.FORGERELAY_DEBUG_OWNER_TOKEN ?? createDebugOwnerToken();
+  const resolvedConfigDir = resolve(configDir);
   mkdirSync(debugRoot, { recursive: true });
 
   return {
     ownerToken: token,
+    configDir: resolvedConfigDir,
     env: {
       ...process.env,
       HOST: "127.0.0.1",
       PORT: "7677",
-      FORGERELAY_CONFIG_DIR: debugConfigDir,
+      FORGERELAY_CONFIG_DIR: resolvedConfigDir,
       FORGERELAY_PUBLIC_BASE_URL: debugBaseUrl,
       FORGERELAY_ALLOWED_ROOTS: repoRoot,
       FORGERELAY_STATE_DIR: stateDir,

package/scripts/debug/runtime.test.mjs

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import test from "node:test";
 
 import {
+  createDebugEnvironment,
   createInteractiveDebugEnvironment,
   interactiveDebugConfigDir,
   interactiveDebugUrls,
@@ -64,6 +65,14 @@ test("interactive debug uses one dedicated persisted config under ~/.forgerelay/
   assert.equal(result.env.FORGERELAY_LOG_LEVEL, "debug");
 });
 
+test("acceptance debug environment may isolate its writable config directory", () => {
+  const isolatedConfigDir = join(tmpdir(), "forgerelay-acceptance-config");
+  const result = createDebugEnvironment({ configDir: isolatedConfigDir });
+
+  assert.equal(result.configDir, isolatedConfigDir);
+  assert.equal(result.env.FORGERELAY_CONFIG_DIR, isolatedConfigDir);
+});
+
 test("interactive debug config directory may be explicitly relocated without falling back to product config", async (t) => {
   const { home } = await withDebugConfig(t);
   const customDir = join(home, "custom-debug-config");

package/scripts/release/parity-sandbox.mjs

@@ -0,0 +1,35 @@
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+export function createParitySandbox(repoRoot) {
+  const sandbox = mkdtempSync(join(tmpdir(), "forgerelay-release-parity-node22-"));
+  copyTrackedTree(repoRoot, sandbox);
+  initializeGitIndex(sandbox);
+  return sandbox;
+}
+
+function initializeGitIndex(sandbox) {
+  execFileSync("git", ["init", "--quiet"], {
+    cwd: sandbox,
+    stdio: "ignore",
+  });
+  execFileSync("git", ["add", "--force", "--all", "--", "."], {
+    cwd: sandbox,
+    stdio: "ignore",
+  });
+}
+
+function copyTrackedTree(repoRoot, destinationRoot) {
+  const files = execFileSync("git", ["ls-files", "-z"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  }).split("\0").filter(Boolean);
+  for (const relativePath of files) {
+    const source = join(repoRoot, relativePath);
+    const destination = join(destinationRoot, relativePath);
+    mkdirSync(dirname(destination), { recursive: true });
+    cpSync(source, destination, { recursive: true, force: true });
+  }
+}

package/scripts/release/release-gate.test.mjs

@@ -1,8 +1,10 @@
 import assert from "node:assert/strict";
-import { readFile } from "node:fs/promises";
+import { execFileSync, spawnSync } from "node:child_process";
+import { readFile, realpath, rm } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
+import { createParitySandbox } from "./parity-sandbox.mjs";
 
 const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 
@@ -67,6 +69,44 @@ test("architecture gate treats the append-only release-note archive as an explic
   assert.match(architecture, /"docs\/releases"/);
 });
 
+test("release parity sandbox gives architecture an isolated non-empty Git index", async () => {
+  const sandbox = createParitySandbox(repoRoot);
+  try {
+    const architecture = spawnSync(process.execPath, ["scripts/ci/architecture.mjs"], {
+      cwd: sandbox,
+      encoding: "utf8",
+      windowsHide: true,
+      shell: false,
+    });
+    assert.equal(
+      architecture.status,
+      0,
+      architecture.stderr || architecture.stdout || "architecture check did not exit cleanly",
+    );
+    assert.doesNotMatch(architecture.stdout, /Architecture check passed: 0 tracked files;/);
+
+    const gitRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: sandbox,
+      encoding: "utf8",
+    }).trim();
+    const [canonicalGitRoot, canonicalSandbox, canonicalRepoRoot] = await Promise.all([
+      realpath(gitRoot),
+      realpath(sandbox),
+      realpath(repoRoot),
+    ]);
+    assert.equal(canonicalGitRoot, canonicalSandbox);
+    assert.notEqual(canonicalGitRoot, canonicalRepoRoot);
+
+    const tracked = execFileSync("git", ["ls-files", "-z"], {
+      cwd: sandbox,
+      encoding: "utf8",
+    }).split("\0").filter(Boolean);
+    assert.ok(tracked.length > 0, "parity sandbox must expose copied tracked files through its own Git index");
+  } finally {
+    await rm(sandbox, { recursive: true, force: true });
+  }
+});
+
 test("release runtime and local parity share the checked-in Node contract", async () => {
   const nodeVersion = (await readFile(resolve(repoRoot, ".nvmrc"), "utf8")).trim();
   assert.equal(nodeVersion, "22.19.0");
@@ -77,6 +117,7 @@ test("release runtime and local parity share the checked-in Node contract", asyn
   const source = await readFile(resolve(repoRoot, "scripts/release-parity.mjs"), "utf8");
   assert.match(source, /readFileSync\(join\(repoRoot, "\.nvmrc"\), "utf8"\)/);
   assert.match(source, /const NPM_VERSION = "11\.19\.1"/);
+  assert.match(source, /const sandbox = createParitySandbox\(repoRoot\)/);
   const ciWorkflow = await readFile(resolve(repoRoot, ".github/workflows/ci.yml"), "utf8");
   assert.match(ciWorkflow, /npm install --global npm@11\.19\.1/);
   assert.ok(source.includes('["npm", "ci", "--no-audit", "--no-fund"]'));

package/scripts/release-parity.mjs

@@ -1,21 +1,20 @@
 #!/usr/bin/env node
 
 import { execFileSync, spawnSync } from "node:child_process";
-import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { readFileSync, rmSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createParitySandbox } from "./release/parity-sandbox.mjs";
 
 const NPM_VERSION = "11.19.1";
 const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const NODE_VERSION = readFileSync(join(repoRoot, ".nvmrc"), "utf8").trim();
-const debugRoot = join(repoRoot, ".forgerelay-debug");
-const sandbox = mkdtempSync(join(ensureDirectory(debugRoot), "release-parity-node22-"));
 const npx = process.platform === "win32" ? "npx.cmd" : "npx";
 
 assertCleanReleaseHead();
+const sandbox = createParitySandbox(repoRoot);
 
 try {
-  copyTrackedTree(sandbox);
   const env = {
     ...process.env,
     FORGERELAY_ALLOWED_ROOTS: sandbox,
@@ -61,24 +60,6 @@ function assertCleanReleaseHead() {
   }
 }
 
-function ensureDirectory(path) {
-  mkdirSync(path, { recursive: true });
-  return `${path}/`;
-}
-
-function copyTrackedTree(destinationRoot) {
-  const files = execFileSync("git", ["ls-files", "-z"], {
-    cwd: repoRoot,
-    encoding: "utf8",
-  }).split("\0").filter(Boolean);
-  for (const relativePath of files) {
-    const source = join(repoRoot, relativePath);
-    const destination = join(destinationRoot, relativePath);
-    mkdirSync(dirname(destination), { recursive: true });
-    cpSync(source, destination, { recursive: true, force: true });
-  }
-}
-
 function runNodeNpm(cwd, env, command, label) {
   run(
     cwd,

package/scripts/release-proof.mjs

@@ -164,6 +164,29 @@ function testEndpoint(name, fallback) {
   return fallback;
 }
 
+function githubAuthHeaders() {
+  const token = process.env.GH_TOKEN?.trim()
+    || process.env.GITHUB_TOKEN?.trim()
+    || localGhToken();
+  return {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "ForgeRelay-release-tag-gate",
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+  };
+}
+
+function localGhToken() {
+  if (process.env.NODE_ENV === "test") return "";
+  try {
+    return execFileSync("gh", ["auth", "token", "--hostname", "github.com"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
 async function artifactExists(label, url, headers = {}) {
   let response;
   try {
@@ -195,10 +218,7 @@ async function assertReleaseTagMutable(tag, version) {
   ).toString();
   const [npmPublished, githubReleased] = await Promise.all([
     artifactExists(`npm package ${pkg.name}@${version}`, npmUrl),
-    artifactExists(`GitHub Release ${tag}`, githubUrl, {
-      Accept: "application/vnd.github+json",
-      "User-Agent": "ForgeRelay-release-tag-gate",
-    }),
+    artifactExists(`GitHub Release ${tag}`, githubUrl, githubAuthHeaders()),
   ]);
   if (npmPublished) {
     throw new Error(`npm package ${pkg.name}@${version} already exists; release tag ${tag} is immutable`);

package/scripts/release-proof.test.mjs

@@ -22,11 +22,18 @@ async function runProof(cwd, action, env = {}) {
   });
 }
 
-async function artifactApiEnv(t, { npmStatus = 404, githubStatus = 404 } = {}) {
+async function artifactApiEnv(
+  t,
+  { npmStatus = 404, githubStatus = 404, githubRequiredToken } = {},
+) {
   const server = createServer((request, response) => {
     if (request.url?.startsWith("/npm/")) response.statusCode = npmStatus;
-    else if (request.url?.startsWith("/github/")) response.statusCode = githubStatus;
-    else response.statusCode = 500;
+    else if (request.url?.startsWith("/github/")) {
+      response.statusCode = githubRequiredToken
+        && request.headers.authorization !== `Bearer ${githubRequiredToken}`
+        ? 403
+        : githubStatus;
+    } else response.statusCode = 500;
     response.end();
   });
   await new Promise((resolve, reject) => {
@@ -41,6 +48,7 @@ async function artifactApiEnv(t, { npmStatus = 404, githubStatus = 404 } = {}) {
     NODE_ENV: "test",
     FORGERELAY_TEST_NPM_REGISTRY_URL: `${base}/npm/`,
     FORGERELAY_TEST_GITHUB_API_URL: `${base}/github/`,
+    ...(githubRequiredToken ? { GH_TOKEN: githubRequiredToken } : {}),
   };
 }
 
@@ -121,7 +129,7 @@ test("release tag hook gate uses repository facts instead of requiring a local p
   await git(root, ["add", "tracked.txt"]);
   await git(root, ["commit", "--allow-empty", "-m", "new head"]);
   await runProof(root, "write");
-  const mutableEnv = await artifactApiEnv(t);
+  const mutableEnv = await artifactApiEnv(t, { githubRequiredToken: "release-test-token" });
   const deletion = await runProof(root, "check-hook", {
     ...mutableEnv,
     FORGERELAY_HOOK_PAYLOAD: JSON.stringify({ command: "git push --delete origin v1.2.3" }),