mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 11:54:35 +01:00
## Thinking Path > - Paperclip coordinates agents across local, SSH, and sandbox environments. > - Native Runner must launch artifacts for the execution host. > - A Linux controller currently selects Linux OpenCode assets for a macOS SSH host. > - Remote launch-file validation also accepts only ELF executables. > - The standard Core image must carry a verified Mac runtime for this host pair. > - This pull request adds that runtime and selects it for Apple Silicon SSH hosts. > - Self-hosted and hosted controllers can use the same generic implementation. ## Linked Issues or Issue Description **What happened?** A native OpenCode run on an Apple Silicon SSH host receives Linux controller artifacts. Its private launch-file verifier also rejects Mach-O files. A working legacy CLI agent does not exercise this path. **Expected behavior** The controller must select and verify the target's native daemon, Node, OpenCode executable, and proxy. Existing Linux targets and legacy agents must keep their current behavior. **Steps to reproduce** 1. Run a standard Linux Core image. 2. Select an SSH environment on an Apple Silicon Mac. 3. Start a native OpenCode agent with a compatible model connection. 4. Observe the incompatible runtime selection before useful agent work. **Paperclip version or commit** Base: `324ec1f537a9ba1e84239faa81bcef326a5dd1b7`. **Deployment mode** Docker or another Linux controller, with macOS ARM64 execution over SSH. Related work: #21662 covers local OpenCode confinement. #22236 covers SSH process cleanup. This change does not depend on either PR. No duplicate macOS OpenCode runtime PR was found. ## What Changed - Select a verified `darwin-arm64` runtime for OpenCode SSH targets. Preserve the Linux image default and explicit operator overrides. - Verify Mach-O launch files against the admitted architecture, file digests, and remote account. Keep existing Linux receipt and recovery behavior. - Build the Mac runtime on an Apple Silicon CI host with standalone Node 24.21.0. Keep OpenCode pinned to 1.18.34. - Package the sealed OpenCode runtime artifacts and required package metadata. Omit other harness distributions and their optional qualification inventories. - Verify archive provenance and safe extraction on Linux. Include the runtime in standard and merge-queue Core images. Avoid storing the transport archive in an image layer. - Reuse artifacts only from successful protected master image builds with identical runtime inputs. Test cache trust boundaries and register the script tests in CI. - Document runtime delivery, manual image inputs, and the initial Apple Silicon scope. No Cloud source, schema, or agent configuration changes. ## Verification - `pnpm -r typecheck` — passed. - `pnpm build` — passed. - Focused OpenCode artifact selection and private staging tests — 21 passed. - Focused native executor tests for OpenCode, SSH, and provider packs — 60 passed. - Real Rust daemon transport tests with the OpenCode protocol fixture — 4 passed. - Installed OpenCode 1.18.34 server qualification with a local provider fixture — 3 passed. - Runtime packaging, cache trust, workflow, image-contract, and merge-queue tests — 26 passed. - The CI release-workflow test group, including canary reuse and provenance — 218 passed. - Docker workflow and build-stamp guards — 29 passed after adding the Mac digest expectation, updating the excluded-source COPY expectation, and removing the redundant production commit ARG. - The source SDK registry, public-type, and evidence checks — 59 passed after updating only the root package metadata hash. Lock, compiler, parser, and model pins did not change. - Fresh-host provider-pack upload harness — 7 passed. The new regression first failed with `package_version:acpx`, then passed after the required metadata was preserved. - Node version policy — passed against a clean tracked-file snapshot. Generated local provider assets make the direct workspace scan fail; they are absent from the CI checkout. - Built, packaged, installed, and verified the actual Mac runtime. Both the controller verifier and the remote startup verifier accept its pins, target, sealed files, manifest, and package metadata. The pre-change private launch verifier rejects the real Mach-O files; the candidate accepts those same files. The dedicated archive is about 101 MB. - Live native smoke: real Mac daemon, private staged Mach-O files, OpenCode 1.18.34, and a local GLM-5.3 backend. The model read two files, edited the implementation, ran three tests, completed the semantic finish call, and summarized the three passes. An independent test run passed. The test file stayed unchanged. This used the existing `allow` mode and a scratch account-home fixture on a Mac. It does not prove hosted SSH dispatch. - The full CI workflow passed on `ae74808631f1933edec89aa1e80db7f2b756aca3`: server test shards, Runner Rust and native server tests, type checking, builds, browser suites, image checks, the native Mac producer, and Linux runtime installation. Greptile is 5/5 with no unresolved threads. - Local `pnpm test:run` used a disposable PostgreSQL 18 fixture after embedded Postgres failed to start because its macOS package lacks dynamic libraries. All six chat shards passed (1,971 tests). The redundant unsharded local run was interrupted during the general-server group after all current-head CI test jobs passed. The later local workspace and serialized groups did not run. The owned PostgreSQL fixture is stopped. This is not a local full-suite pass. Retained review failures: the first PR revision omitted package metadata and did not ignore downloaded image inputs. The fresh-host upload regression reproduced the metadata failure before its fix. Generated inputs are now ignored. CI also exposed a missing Node policy exception for the pinned Mac producer; the exception is limited to that producer job. A later policy attempt exposed an old exact-dependency assertion in canary reuse tests. The assertion now covers the added runtime and evaluates the publication gate for success, failure, cancellation, and skip outcomes. The Runner support suite then found that the new test registration changed a pinned root package input; the standard source registry generator updated that one hash, and all 59 affected tests passed. The server matrix then found four outdated image guard expectations and a duplicate production commit ARG. The focused image guards now pass after updating those expectations and keeping one commit ARG before Mac verification. Retained failures: the first producer attempt used Homebrew Node, which failed the relocation check. The successful producer used standalone Node 24.21.0. Live smoke attempts also encountered a stopped tunnel, an upstream model failure, and the existing Rust restriction on OpenCode permission requests in `ask` mode. The successful tool trace used the existing `allow` mode. Its initial reporter looked for tool names in generic item events; verification of the retained canonical tool events and an independent rerun confirmed the result. The upstream model failure is not explained by a later pass. Not run locally: a full Docker image build, because the existing Docker daemon does not respond. The PR adds native producer qualification and Linux installation verification to CI. Hosted deployment, remote service-account dispatch, and hosted continuation remain acceptance steps after deployment. ## Risks - A cold Mac runtime build adds CI time when Runner or producer inputs change. Reuse is bounded and accepts only a successful protected master producer. The artifact digest and runtime input identity remain verified. - Standard images gain a dedicated Mac runtime payload. Manual image builds can omit it; Mac OpenCode SSH runs then fail with a named missing-runtime error. Linux behavior remains available. - This release covers Apple Silicon SSH distribution. It does not qualify Intel Mac distribution or expand other harness support. - The OpenCode permission bridge keeps its existing behavior. This PR does not add `ask` approval support. - No saved run/session schema or provider pin changes. Existing Linux receipts retain their interpretation. A surviving admitted Runner bypasses new artifact discovery. Legacy agents are not converted. Existing account-change and old-receipt restoration tests remain in coverage. - No migration, cluster change, new sandbox image requirement, or Cloud control-plane change. A staging application rebuild and deployment are separate from this PR. ## Model Used OpenAI GPT-6, through Codex, with repository tools, code execution, tests, and SSH inspection. The session does not expose a more specific model ID or context-window size. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
204 lines
11 KiB
JavaScript
204 lines
11 KiB
JavaScript
// Build-before-merge image handoff between the merge queue and master.
|
|
//
|
|
// A `merge_group` run of docker-merge-group.yml builds the production image for
|
|
// the exact merge-group commit with no registry credentials, probes it, and
|
|
// uploads an OCI archive plus a record of what it built. When the merge queue
|
|
// then fast-forwards master to that commit, docker.yml may push those exact
|
|
// bytes instead of rebuilding them. Anything that does not prove the match
|
|
// returns no promotion, and docker.yml falls back to its normal build.
|
|
import assert from "node:assert/strict";
|
|
import { execFileSync } from "node:child_process";
|
|
import { createHash } from "node:crypto";
|
|
import { appendFile, readFile, writeFile } from "node:fs/promises";
|
|
import { pathToFileURL } from "node:url";
|
|
|
|
export const repository = "paperclipai/paperclip";
|
|
export const repositoryId = 1170821064;
|
|
export const workflowPath = ".github/workflows/docker-merge-group.yml";
|
|
export const recordSchema = "paperclip/merge-group-image/v1";
|
|
export const artifactName = arch => `merge-group-image-${arch}`;
|
|
|
|
const architectures = ["amd64", "arm64"];
|
|
const indexTypes = ["application/vnd.oci.image.index.v1+json", "application/vnd.docker.distribution.manifest.list.v2+json"];
|
|
const manifestTypes = ["application/vnd.oci.image.manifest.v1+json", "application/vnd.docker.distribution.manifest.v2+json"];
|
|
// How long a master push waits for a merge-queue build that is still running.
|
|
// A build takes about 12 minutes and the exact-source gate about 14.
|
|
const findWaitMs = 15 * 60_000;
|
|
const findPollMs = 20_000;
|
|
const fullSha = /^[a-f0-9]{40}$/;
|
|
const digestPattern = /^sha256:[a-f0-9]{64}$/;
|
|
const sha256 = bytes => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
|
|
|
|
/**
|
|
* Choose the merge-queue build a master push may promote. Only a completed,
|
|
* successful run of this repository's merge-group workflow, on a merge-queue
|
|
* branch for master, for exactly this commit, qualifies.
|
|
*
|
|
* The commit must match, not only the tree: the image stamps the commit SHA
|
|
* (PAPERCLIP_BUILD_COMMIT, build-info.json, the provider pack revision). The
|
|
* merge queue lands the commit it tested for every merge method, squash
|
|
* included, by fast-forwarding master to it; a push that did not come through
|
|
* the queue has no matching run and builds from source.
|
|
*/
|
|
export function selectVerifiedRun({ sha, runs }) {
|
|
assert.match(sha ?? "", fullSha);
|
|
const eligible = runs.filter(run => run.head_sha === sha && run.event === "merge_group" && run.path === workflowPath &&
|
|
run.repository?.id === repositoryId && run.head_repository?.id === repositoryId &&
|
|
typeof run.head_branch === "string" && run.head_branch.startsWith("gh-readonly-queue/master/"));
|
|
if (eligible.length === 0) return { reason: "no merge-queue image build exists for this commit" };
|
|
const passed = eligible.filter(run => run.status === "completed" && run.conclusion === "success").sort((a, b) => b.id - a.id);
|
|
// The queue can land a commit while its image is still building. `pending`
|
|
// tells the caller that waiting can still produce a usable run.
|
|
if (passed.length === 0 && eligible.some(run => run.status !== "completed")) {
|
|
return { pending: true, reason: "the merge-queue image build for this commit did not finish in time" };
|
|
}
|
|
if (passed.length === 0) return { reason: "the merge-queue image build for this commit did not succeed" };
|
|
return { runId: passed[0].id };
|
|
}
|
|
|
|
/** The run's unexpired image artifact for one architecture, if there is exactly one. */
|
|
export function selectArtifact({ artifacts, arch }) {
|
|
assert.ok(architectures.includes(arch));
|
|
const matches = artifacts.filter(item => item.name === artifactName(arch) && !item.expired);
|
|
return matches.length === 1 ? { artifactId: matches[0].id } : { reason: `expected one unexpired ${artifactName(arch)} artifact, found ${matches.length}` };
|
|
}
|
|
|
|
/**
|
|
* The digest of the image an OCI archive holds, checked against the archive's
|
|
* own content-addressed blobs. `readEntry` returns the bytes of a tar entry.
|
|
*/
|
|
export function archiveImageDigest({ readEntry, arch }) {
|
|
assert.ok(architectures.includes(arch));
|
|
const layout = JSON.parse(readEntry("index.json").toString("utf8"));
|
|
assert.equal(layout.manifests?.length, 1, "The OCI archive must hold exactly one image");
|
|
const top = layout.manifests[0];
|
|
assert.match(top.digest ?? "", digestPattern);
|
|
const blob = name => {
|
|
const bytes = readEntry(`blobs/sha256/${name.slice("sha256:".length)}`);
|
|
assert.equal(sha256(bytes), name, `Archive blob ${name} does not match its digest`);
|
|
return JSON.parse(bytes.toString("utf8"));
|
|
};
|
|
const image = blob(top.digest);
|
|
const platformImages = indexTypes.includes(image.mediaType)
|
|
? (image.manifests ?? []).filter(item => item.platform?.os === "linux")
|
|
: [{ digest: top.digest, platform: undefined }];
|
|
assert.equal(platformImages.length, 1, "The OCI archive must hold exactly one Linux image");
|
|
const manifest = platformImages[0].digest === top.digest ? image : blob(platformImages[0].digest);
|
|
assert.ok(manifestTypes.includes(manifest.mediaType), "The OCI archive does not hold an image manifest");
|
|
const config = blob(manifest.config.digest);
|
|
assert.equal(config.os, "linux");
|
|
assert.equal(config.architecture, arch, `The OCI archive holds a ${config.architecture} image, not ${arch}`);
|
|
return top.digest;
|
|
}
|
|
|
|
/** What the merge-group build attests about the archive it uploads. */
|
|
export function createRecord({ sha, tree, arch, digest }) {
|
|
assert.match(sha ?? "", fullSha);
|
|
assert.match(tree ?? "", fullSha);
|
|
assert.ok(architectures.includes(arch));
|
|
assert.match(digest ?? "", digestPattern);
|
|
return { schema: recordSchema, repository, sha, tree, arch, digest };
|
|
}
|
|
|
|
/**
|
|
* Prove the archive is the build of the tree this master push publishes. The
|
|
* commit SHA covers its tree; the tree is compared too, so a record can never
|
|
* vouch for different content under a reused name.
|
|
*/
|
|
export function verifyRecord({ record, sha, tree, arch, archiveDigest }) {
|
|
assert.equal(record?.schema, recordSchema, "Unknown merge-group image record");
|
|
assert.equal(record.repository, repository);
|
|
assert.equal(record.sha, sha, "The merge-group build is for a different commit");
|
|
assert.equal(record.tree, tree, "The merge-group build is for a different tree");
|
|
assert.equal(record.arch, arch, "The merge-group build is for a different architecture");
|
|
assert.match(record.digest ?? "", digestPattern);
|
|
assert.equal(archiveDigest, record.digest, "The archive is not the image the merge-group build recorded");
|
|
return record.digest;
|
|
}
|
|
|
|
/**
|
|
* Files that produce, promote or vouch for a merge-group image. The merge-group
|
|
* run uses the queued commits' own copies, so a push that changes any of them
|
|
* is built from source on master instead: promotion then trusts only a
|
|
* pipeline that master already ran before this push. docker.yml runs this
|
|
* check from the copy of this script in the push's `before` commit, so a push
|
|
* cannot remove the check it is subject to.
|
|
*/
|
|
export const pipelineFiles = [workflowPath, ".github/workflows/docker.yml", ".github/workflows/macos-runner-runtime.yml", "scripts/macos-runner-runtime.mjs", "scripts/macos-runner-runtime-cache.mjs", "scripts/merge-group-image.mjs", "scripts/assert-orphan-reaping.sh"];
|
|
|
|
export function assertPipelineUnchanged(changedFiles) {
|
|
const changed = changedFiles.filter(file => pipelineFiles.includes(file));
|
|
assert.equal(changed.length, 0, `This push changes the merge-group image pipeline (${changed.join(", ")})`);
|
|
}
|
|
|
|
/** Pipeline files changed by everything this push landed: `since` (the push's `before`) to HEAD. */
|
|
export function changedSince(since, cwd = process.cwd()) {
|
|
assert.match(since ?? "", fullSha, "--since must be the push's full `before` SHA");
|
|
// Throws unless `since` is an ancestor: a push is a fast-forward of master.
|
|
execFileSync("git", ["merge-base", "--is-ancestor", since, "HEAD"], { cwd, stdio: "ignore" });
|
|
return execFileSync("git", ["diff", "--name-only", since, "HEAD", "--", ...pipelineFiles], { cwd, encoding: "utf8" }).split("\n").filter(Boolean);
|
|
}
|
|
const tarReader = archive => entry => execFileSync("tar", ["-xOf", archive, entry], { maxBuffer: 16 * 1024 * 1024 });
|
|
const gitTree = () => execFileSync("git", ["rev-parse", "HEAD^{tree}"], { encoding: "utf8" }).trim();
|
|
const option = name => {
|
|
const index = process.argv.indexOf(`--${name}`);
|
|
const value = index > 0 ? process.argv[index + 1] : undefined;
|
|
assert.ok(value, `--${name} is required`);
|
|
return value;
|
|
};
|
|
const output = async (key, value) => {
|
|
if (process.env.GITHUB_OUTPUT) await appendFile(process.env.GITHUB_OUTPUT, `${key}=${value}\n`);
|
|
console.log(`${key}=${value}`);
|
|
};
|
|
|
|
async function main(command) {
|
|
const sha = process.env.GITHUB_SHA;
|
|
const arch = option("arch");
|
|
if (command === "record") {
|
|
// Runs in the credential-free merge-group build.
|
|
assert.equal(process.env.GITHUB_EVENT_NAME, "merge_group", "Records are written only by merge-group builds");
|
|
const digest = archiveImageDigest({ readEntry: tarReader(option("archive")), arch });
|
|
await writeFile(option("out"), `${JSON.stringify(createRecord({ sha, tree: gitTree(), arch, digest }), null, 2)}\n`);
|
|
return output("digest", digest);
|
|
}
|
|
assert.ok(process.env.GITHUB_REPOSITORY === repository && process.env.GITHUB_REF === "refs/heads/master" &&
|
|
process.env.GITHUB_EVENT_NAME === "push", "Promotion runs only for canonical master pushes");
|
|
if (command === "find") {
|
|
const token = process.env.GITHUB_TOKEN;
|
|
assert.ok(token, "GITHUB_TOKEN is required");
|
|
const api = async path => {
|
|
const response = await fetch(`https://api.github.com/repos/${repository}${path}`, { redirect: "error",
|
|
headers: { Authorization: `Bearer ${token}`, Accept: "application/vnd.github+json" }, signal: AbortSignal.timeout(30_000) });
|
|
assert.ok(response.ok, `GitHub API ${path}: HTTP ${response.status}`);
|
|
return response.json();
|
|
};
|
|
// Publication waits for the exact-source gate in any case, so waiting here
|
|
// for an unfinished build costs nothing while the build is the shorter of
|
|
// the two. Past the deadline the push builds from source.
|
|
const deadline = Date.now() + findWaitMs;
|
|
let run;
|
|
for (;;) {
|
|
const { workflow_runs: runs } = await api(`/actions/workflows/docker-merge-group.yml/runs?event=merge_group&head_sha=${sha}&per_page=20`);
|
|
run = selectVerifiedRun({ sha, runs });
|
|
if (!run.pending || Date.now() >= deadline) break;
|
|
console.log("The merge-queue image build for this commit is still running. Waiting.");
|
|
await new Promise(resolve => setTimeout(resolve, findPollMs));
|
|
}
|
|
if (!run.runId) { console.log(`No promotion: ${run.reason}. Building from source.`); return; }
|
|
const { artifacts } = await api(`/actions/runs/${run.runId}/artifacts?per_page=100`);
|
|
const artifact = selectArtifact({ artifacts, arch });
|
|
if (!artifact.artifactId) { console.log(`No promotion: ${artifact.reason}. Building from source.`); return; }
|
|
return output("run_id", run.runId);
|
|
}
|
|
if (command === "verify") {
|
|
const directory = option("dir");
|
|
assertPipelineUnchanged(changedSince(option("since")));
|
|
const record = JSON.parse(await readFile(`${directory}/record.json`, "utf8"));
|
|
const archiveDigest = archiveImageDigest({ readEntry: tarReader(`${directory}/image.tar`), arch });
|
|
return output("digest", verifyRecord({ record, sha, tree: gitTree(), arch, archiveDigest }));
|
|
}
|
|
throw new Error(`Unknown command: ${command}`);
|
|
}
|
|
|
|
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main(process.argv[2]);
|