fix(runner): bundle the Copilot metadata probe as a standalone entrypoint (#22436)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The Paperclip Runner ships a provider pack with pinned provider
runtimes and small entrypoints
> - Most provider entrypoints, such as the Kimi metadata probe and the
ACPX sidecar, are esbuild bundles that run as one file
> - The Copilot metadata probe is plain `tsc` output that imports
sibling driver modules
> - So an environment that installs only selected provider-pack files
cannot run the Copilot probe
> - This pull request makes the Copilot metadata probe a standalone
verified entrypoint, like the Kimi probe
> - The benefit is that every metadata probe has the same self-contained
shape, and a consumer can ship the probe as one file

## Linked Issues or Issue Description

No public issue exists. This is an enhancement.

**What existing behavior does this improve?**
The Copilot metadata probe entrypoint
(`dist/cli/copilot-metadata-probe.js`, the
`paperclip-runner-copilot-metadata-probe` bin and provider-pack shim).

**Subsystem affected**
Paperclip Runner provider pack build (`packages/paperclip-runner`).

**Current behavior**
The probe is plain `tsc` output. It imports
`../drivers/copilot-metadata-probe.js` and more modules. It fails when a
consumer installs only selected provider-pack artifacts. The Kimi probe
does not have this problem because
`scripts/build-verified-provider-entrypoints.mjs` bundles it.

**Proposed behavior**
The build bundles the Copilot probe into one self-contained file, like
the Kimi probe. The bundle still finds the pinned Copilot assets when it
runs from `dist/cli/`.

**Reason and benefit**
Every metadata probe has the same standalone shape. A consumer can ship
the probe as one file. An alternative was to ship the full
`dist/drivers` tree with the probe, but that keeps the multi-file shape.

**Breaking changes**
None. The bin name, the output path and the probe output do not change.

## What Changed

- `scripts/build-verified-provider-entrypoints.mjs`: add
`copilot-metadata-probe` (source `src/cli/copilot-metadata-probe.ts`,
outputs `dist/cli/copilot-metadata-probe.js` and `.cjs`) with the same
format and flags as `kimi-metadata-probe`. The bundler asserts one
output and only `node:` imports.
- `src/cli/copilot-metadata-probe.ts`: move the top-level `await` into
`main()`. esbuild cannot emit top-level `await` in the CommonJS bundle.
Output and exit codes do not change.
- `src/drivers/acpx/provider-assets-root.ts`: when no package root is
bound, accept the bundled `dist/cli/copilot-metadata-probe.(js|cjs)`
module URL for the `copilot` provider only. This is the same rule the
bundled ACPX sidecar uses. Before this change, the bundle's
`import.meta.url` is the `dist/cli` file, not
`dist/drivers/acpx/copilot-installation.js`, so the module-URL lookup
failed. The bound `PAPERCLIP_ACPX_PROVIDER_PACKAGE_ROOT` path does not
change.
- Tests: a bundler test that runs both bundles alone in a temporary pack
layout, and an asset-root test for the bundled probe path that also
proves other providers do not get the new path.

## Verification

- `node --test scripts/build-verified-provider-entrypoints.test.mjs` (44
tests, includes the new standalone-run test)
- `pnpm exec vitest run src/drivers/acpx/provider-assets-root.test.ts
src/drivers/copilot-metadata-probe.test.ts
src/drivers/acpx/copilot-installation.test.ts`
- `node --test scripts/kimi-metadata-probe.test.mjs
scripts/provider-pack-executable-shims.test.mjs
test/acpx-codex-package-contract.test.mjs`
- `pnpm exec vitest run
server/src/__tests__/copilot-connection-probe.test.ts`
- `pnpm --filter @paperclipai/paperclip-runner run typecheck:typescript`
- Manual check on darwin-arm64 with the pinned Copilot closure
installed, child process spawn denied by a preload:
- Bundled `.js` and `.cjs`, no bound root: installation verification
passes and the probe reaches the spawn step.
- Same run without the `provider-assets-root.ts` change:
`COPILOT_INSTALLATION_INVALID`.
- Bundled `.js` with `PAPERCLIP_ACPX_PROVIDER_PACKAGE_ROOT` bound:
installation verification passes.
- `pnpm verify` requires broader coverage (the bundler is a broad
input), so CI supplies it.

## Risks

- Low risk. The bin name, output path and shim do not change. The probe
output and exit codes do not change.
- The new module-URL rule accepts only
`/dist/cli/copilot-metadata-probe.(js|cjs)` and only for `copilot`. It
resolves to the package that holds `dist/cli`, the same as the sidecar
rule.
- The build now also writes `dist/cli/copilot-metadata-probe.cjs`.
Nothing reads it yet.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Provider: Anthropic Claude
- Model: Claude Opus 5.5 (`claude-opus-5-5`)
- Mode: agentic coding with tool use (shell, file edits, test runs)

## 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Nicky LeachandClaude Opus 5.5 authored and GitHub committed 2026-11-20 16:09:31 -08:00
1 parent ae2afd525b
commit 5371c83152
5 files changed
+60 -4

No files matched your search

@@ -20,6 +20,12 @@ export const verifiedProviderEntrypoints = Object.freeze([
output: resolve(packageRoot, "dist/cli/kimi-metadata-probe.js"),
verifiedOutput: resolve(packageRoot, "dist/cli/kimi-metadata-probe.cjs"),
}),
Object.freeze({
name: "copilot-metadata-probe",
source: resolve(packageRoot, "src/cli/copilot-metadata-probe.ts"),
output: resolve(packageRoot, "dist/cli/copilot-metadata-probe.js"),
verifiedOutput: resolve(packageRoot, "dist/cli/copilot-metadata-probe.cjs"),
}),
Object.freeze({
name: "provision-antigravity",
source: resolve(packageRoot, "scripts/provision-antigravity.mjs"),
@@ -1,5 +1,8 @@
import assert from "node:assert/strict";
import { stat } from "node:fs/promises";
import { spawnSync } from "node:child_process";
import { mkdir, mkdtemp, realpath, rm, stat, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
import {
@@ -24,6 +27,36 @@ test("provider entrypoints include self-contained ESM and descriptor-safe Common
}
});
test("Copilot metadata probe runs as one standalone bundle in a selected pack layout", async (t) => {
const bundles = await bundleVerifiedProviderEntrypoints({ write: false });
const bundle = bundles.find(({ entrypoint }) => entrypoint.name === "copilot-metadata-probe");
assert.ok(bundle, "The provider pack build must include the Copilot metadata probe");
for (const result of [bundle.result, bundle.verifiedResult]) {
for (const output of Object.values(result.metafile.outputs)) {
for (const dependency of output.imports) assert.match(dependency.path, /^node:/);
}
}
const root = await realpath(await mkdtemp(join(tmpdir(), "paperclip-copilot-metadata-cli-")));
t.after(() => rm(root, { recursive: true, force: true }));
await mkdir(join(root, "dist/cli"), { recursive: true });
await writeFile(join(root, "package.json"), '{"name":"@paperclipai/paperclip-runner","type":"module"}');
for (const [name, result] of [["copilot-metadata-probe.js", bundle.result], ["copilot-metadata-probe.cjs", bundle.verifiedResult]]) {
const entry = join(root, "dist/cli", name);
await writeFile(entry, result.outputFiles[0].contents);
const run = spawnSync(process.execPath, [entry], {
cwd: root, env: { PATH: "/usr/bin:/bin", COPILOT_GITHUB_TOKEN: "test-token" }, encoding: "utf8", timeout: 20_000,
});
assert.ifError(run.error);
assert.equal(run.status, 1, run.stderr);
assert.deepEqual(JSON.parse(run.stdout), {
status: "failed",
code: "COPILOT_INSTALLATION_INVALID",
message: "The selected environment does not have the verified Copilot runtime installed.",
promptSent: false,
});
}
});
test("written provider entrypoints satisfy qualified launch permissions", async (t) => {
if (process.platform === "win32") {
t.skip("POSIX launch permissions do not apply on Windows");
@@ -1,5 +1,10 @@
#!/usr/bin/env node
import { probeCopilotMetadata } from "../drivers/copilot-metadata-probe.js";
const result = await probeCopilotMetadata(process.env.COPILOT_GITHUB_TOKEN ?? "", process.env.PAPERCLIP_COPILOT_PROBE_MODEL);
process.stdout.write(`${JSON.stringify(result)}\n`);
if (result.status === "failed") process.exitCode = 1;
async function main() {
const result = await probeCopilotMetadata(process.env.COPILOT_GITHUB_TOKEN ?? "", process.env.PAPERCLIP_COPILOT_PROBE_MODEL);
process.stdout.write(`${JSON.stringify(result)}\n`);
if (result.status === "failed") process.exitCode = 1;
}
void main();
@@ -19,6 +19,17 @@ it("uses one fixed provider directory for source, compiled and bundled runner la
expect(() => resolveRunnerProviderAssetsRoot(pathToFileURL(join(path, "workspace/arbitrary.ts")).href, "cursor")).toThrow("verified package layout");
});
it("resolves Copilot assets from the bundled metadata probe without widening other providers", async () => {
vi.stubEnv("PAPERCLIP_ACPX_PROVIDER_PACKAGE_ROOT", undefined);
vi.stubEnv("PAPERCLIP_ACPX_PROVIDER_PACKAGE_MANIFEST", undefined);
const path = await root();
for (const relative of ["dist/cli/copilot-metadata-probe.js", "dist/cli/copilot-metadata-probe.cjs"]) {
const moduleUrl = pathToFileURL(join(path, relative)).href;
expect(resolveRunnerProviderAssetsRoot(moduleUrl, "copilot")).toBe(join(path, "provider-assets/copilot"));
expect(() => resolveRunnerProviderAssetsRoot(moduleUrl, "cursor")).toThrow("verified package layout");
}
});
it("resolves descriptor sidecars only through the runner-bound canonical package manifest", async () => {
const path = await root();
await writeFile(join(path, "package.json"), JSON.stringify({ name: "@paperclipai/paperclip-runner" }));
@@ -65,6 +65,7 @@ export function resolveRunnerProviderAssetsRoot(moduleUrl: string, provider: Nat
if (provider !== "copilot") packageRoot = join(packageRoot, "dist/vendor/paperclip-runner");
} else if (new RegExp(`/(?:src|dist)/drivers/acpx/${provider}-installation\\.(?:ts|js)$`).test(url.pathname)) packageRoot = fileURLToPath(new URL("../../../", url));
else if (/\/dist\/cli\/acpx-runtime-sidecar\.(?:cjs|js)$/.test(url.pathname)) packageRoot = fileURLToPath(new URL("../../", url));
else if (provider === "copilot" && /\/dist\/cli\/copilot-metadata-probe\.(?:cjs|js)$/.test(url.pathname)) packageRoot = fileURLToPath(new URL("../../", url));
else if (new RegExp(`/dist/vendor/paperclip-runner/drivers/acpx/${provider}-installation\\.(?:js)$`).test(url.pathname)) packageRoot = fileURLToPath(new URL("../../", url));
else if (/\/dist\/vendor\/paperclip-runner\/cli\/acpx-runtime-sidecar\.(?:cjs|js)$/.test(url.pathname)) packageRoot = fileURLToPath(new URL("../", url));
else throw new Error("Provider factory is outside a verified package layout");