mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-26 18:31:34 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The runner package is useful only when the application can start, observe, and recover a native Codex run safely. > - Existing direct adapters must keep their current execution and finalization paths. > - The application boundary therefore needs additive persistence, authorization, coordination, and recovery behind an explicit experimental adapter. > - This pull request adds that Codex-only boundary without activating generalized providers, remote environments, or the later task/SDK surfaces. ## Linked Issues or Issue Description **Subsystem affected** Shared contracts, database persistence, adapter utilities, server native-runtime services, and the experimental Paperclip Runner adapter. **Problem or motivation** The already-landed runner package has a qualified Codex path, but the application needs durable native-run state, guarded runtime selection, authenticated coordination, tool security, finalization, and recovery before the experimental adapter can be exercised safely. **Proposed solution** Add a Codex-only `paperclip_runner` application path behind the existing default-off native-runner setting. Bind native state and coordination to company/run identity, preserve persisted-run recovery, and leave every direct adapter on its existing legacy execution path. **Alternatives considered** The earlier stack boundary introduced a generalized executor and remote-environment lifecycle here. That made this PR depend on implementations in higher PRs and changed reusable sandbox behavior globally. Those pieces are now deferred together to #12592. **Roadmap alignment** ROADMAP.md does not list a conflicting native-runner integration project. This change adds the application boundary for the existing Runner architecture. ## What Changed - Added native run/result/finalization/provider-trace persistence, shared validators, and idempotent migration/replay coverage. - Added guarded Codex-only runtime selection, authenticated PRP coordination, recovery, finalization, and interaction services. - Added run/company-bound tool-gateway authorization, credential redaction, SSRF protections, and replay-safe behavior. - Added the explicit `paperclip_runner` adapter behind the default-off rollout setting. - Preserved legacy answered-question wake projection and direct-adapter execution/finalization paths. - Hardened cancellation so only owned in-memory child processes are signaled; persisted recycled PIDs/process groups are never trusted. - Retained the narrow Claude ACPX isolated-context security follow-up discovered after #12590. - Deferred the generalized executor, provider ingress, remote lifecycle, SDK/lab/eval work, release-process changes, and lockfile. ## Verification - Changed-file delta against `master`: 133 files. - GitHub Actions is the authoritative verification environment for this PR. - Full CI, security, and Greptile review will run on this lowest unmerged stack PR. - Local tests/build/typecheck were not run because this checkout is resource constrained. - Static diff/reference checks pass, and `pnpm-lock.yaml` is unchanged. ## Risks - This touches central heartbeat and agent-route code, so legacy compatibility is the primary risk. - Runtime selection remains Codex-only and explicit; direct Codex, Claude, OpenCode, process, HTTP, and plugin adapters remain on their existing paths. - Fresh native starts fail closed while the rollout flag is off; persisted native records remain readable and recoverable. - Cancellation, company/run binding, tool calls, status decisions, and completion writes are guarded or replay-safe. > 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. ## Model Used OpenAI Codex, GPT-5.6, with repository tools, code execution, and parallel agent review. ## 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 linked existing issues or described the issue in-PR following the relevant issue template - [x] I have not referenced internal or instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal Paperclip ticket id - [ ] I have run tests locally and they pass — GitHub Actions is authoritative for this resource-constrained checkout - [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 risks above - [ ] All Paperclip CI and security gates are green - [ ] Greptile is 5/5 with no open actionable findings - [x] I will address all Greptile and reviewer comments before merge ## Stack - Position: 3 of 5 overall; lowest of 3 currently unmerged - Base: `master` - Previous: [#12590](https://github.com/paperclipai/paperclip/pull/12590), qualified Claude ACPX runtime — merged - Next: [#12592](https://github.com/paperclipai/paperclip/pull/12592), generalized Codex executor, task experience, and developer SDKs --------- Co-authored-by: Dev Agent <dev@paperclip.ing>
88 lines
3.0 KiB
TypeScript
88 lines
3.0 KiB
TypeScript
import { readFileSync } from "node:fs";
|
|
import { fileURLToPath } from "node:url";
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
const packageJsonPath = fileURLToPath(
|
|
new URL("../../package.json", import.meta.url),
|
|
);
|
|
const runnerShimPath = fileURLToPath(
|
|
new URL("../vendor/paperclip-runner/index.ts", import.meta.url),
|
|
);
|
|
const evidenceClassifierPath = fileURLToPath(
|
|
new URL("../services/native-runtime/evidence-classifier.ts", import.meta.url),
|
|
);
|
|
const workspaceDiffReprojectionPath = fileURLToPath(
|
|
new URL("../services/provider-trace-workspace-diff-reprojection.ts", import.meta.url),
|
|
);
|
|
|
|
describe("server package build script", () => {
|
|
it("builds the compiled package entry during prepack", () => {
|
|
const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
|
|
scripts?: Record<string, string>;
|
|
};
|
|
|
|
expect(packageJson.scripts?.prepack).toBe(
|
|
"pnpm run prepare:ui-dist && pnpm run build",
|
|
);
|
|
});
|
|
|
|
it("copies static runtime asset directories into dist", () => {
|
|
const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
|
|
scripts?: Record<string, string>;
|
|
};
|
|
const buildScript = packageJson.scripts?.build ?? "";
|
|
|
|
expect(buildScript).toContain(
|
|
"mkdir -p dist/onboarding-assets dist/built-ins",
|
|
);
|
|
expect(buildScript).toContain(
|
|
"cp -R src/onboarding-assets/. dist/onboarding-assets/",
|
|
);
|
|
expect(buildScript).toContain("cp -R src/built-ins/. dist/built-ins/");
|
|
});
|
|
|
|
it("vendors the private runner runtime without a production workspace dependency", () => {
|
|
const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
|
|
scripts?: Record<string, string>;
|
|
dependencies?: Record<string, string>;
|
|
devDependencies?: Record<string, string>;
|
|
};
|
|
|
|
expect(
|
|
packageJson.dependencies?.["@paperclipai/paperclip-runner"],
|
|
).toBeUndefined();
|
|
expect(packageJson.devDependencies?.["@paperclipai/paperclip-runner"]).toBe(
|
|
"workspace:*",
|
|
);
|
|
expect(packageJson.scripts?.["prepare:runner-vendor"]).toBe(
|
|
"pnpm --filter @paperclipai/paperclip-runner build",
|
|
);
|
|
expect(packageJson.scripts?.build).toContain(
|
|
"cp -R ../packages/paperclip-runner/dist/. dist/vendor/paperclip-runner/",
|
|
);
|
|
});
|
|
|
|
it("loads runner source when the source server starts before workspace builds", () => {
|
|
const shim = readFileSync(runnerShimPath, "utf8");
|
|
|
|
expect(shim).toContain(
|
|
'"../../../../packages/paperclip-runner/src/index.ts"',
|
|
);
|
|
expect(shim).not.toContain(
|
|
'export * from "@paperclipai/paperclip-runner"',
|
|
);
|
|
});
|
|
|
|
it("routes source-mode runtime imports through the runner shim", () => {
|
|
for (const consumerPath of [
|
|
evidenceClassifierPath,
|
|
workspaceDiffReprojectionPath,
|
|
]) {
|
|
const consumer = readFileSync(consumerPath, "utf8");
|
|
|
|
expect(consumer).toContain('vendor/paperclip-runner/index.js"');
|
|
expect(consumer).not.toContain('from "@paperclipai/paperclip-runner"');
|
|
}
|
|
});
|
|
});
|