mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-07 16:11:46 +02:00
Dotta
d0718c226c
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The ACPX pieces already verify profiles, installations, recovery identity, permissions, runtime files, credentials, and models independently. > - A production host must compose those checks in one fail-closed order and clean every acquired resource on partial startup. > - Directly importing a third-party ACP runtime here would mix dependency adoption with the security lifecycle. > - This pull request defines a narrow injected runtime port and admits it only after all package-local boundaries pass. > - The benefit is a testable host lifecycle without adding `acpx`, changing the lockfile, or making the adapter selectable. ## Linked Issues or Issue Description **Agent or provider** The qualified Pi, Claude, and Codex ACPX profiles; Codex additionally uses the managed credential lease. **Why this adapter is useful** The runner needs one owner for startup ordering, immutable identity checks, exact model verification, and cleanup. Otherwise a failure after credential staging or command admission can leave secret files or executable leases alive, and a resumed provider can attach to a different profile, workspace, model, or permission mode. **How the agent is invoked** A later dependency-adapter pull request will implement the injected runtime port with the pinned ACPX library. This host passes that adapter an opaque verified command lease, canonical workspace, private state directory, profile-bound session key, qualified permission policy, launch-only environment, and bounded instructions. It does not expose the runtime directly or add a user-selectable adapter. **Additional context** This pull request is stacked on #12398. Installation verification has a production default; only the third-party runtime opener is injected. Tests use a fake port so this boundary remains package-local and dependency-free. ## What Changed - Add a minimal ACP runtime port for identity, status, model selection, and bounded shutdown. - Derive the qualified profile and canonical recovery binding before any provider startup. - Reject expected-identity drift and irrelevant managed-Codex inputs before opening the provider. - Verify that even an injected installation result matches the closed profile digest. - Prepare the private sandbox and stage Codex credentials only for the Codex profile. - Acquire an opaque verified command lease and pass only the composed launch boundary to the runtime port. - Apply the canonical permission policy and collision-resistant provider session key. - Select and verify the exact effective model before returning an admitted host. - Create a strict versioned identity record and compare resumed provider identifiers with the expected record. - Keep the runtime private and expose only cloned identity, binding, runtime-root, and persistence-safe environment views. - On startup or shutdown failure, attempt runtime close, credential cleanup, and command-lease cleanup in order and aggregate every error. - Add tests for Codex secret isolation, Claude selector verification, recovery drift, injected digest drift, partial-start cleanup, and cleanup retry. ## Verification - Runner TypeScript typecheck — passed. - Runner protocol and TypeScript tests — passed: 12 protocol tests and 426 Vitest tests, including 6 runtime-host tests. - `pnpm -r typecheck` — passed for all applicable workspaces. - `pnpm build` — passed, including runner binary, server, UI, and workspace packages. - Prettier and `git diff --check` — passed. - The diff contains 2 files and does not change `pnpm-lock.yaml`, a workflow, a dependency, a public package export, server selection, or UI behavior. ## Risks The main risk is leaking a partially admitted resource when a later admission step fails. Resource acquisition is linear and all failure paths use the same ordered cleanup routine. The runtime port is deliberately minimal and privately owned by the host; it cannot bypass profile, model, recovery, sandbox, credential, or command admission. The actual ACPX implementation and its process-supervision behavior remain a separate review unit. ## Model Used OpenAI Codex with GPT-5 and repository tool use. ## 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 an existing public item or described the issue in this PR - [x] I have not referenced internal or instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal task identifier - [x] I have run the affected tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have documented the admission and cleanup boundary - [ ] All applicable GitHub Actions are green - [ ] Greptile is 5/5 with every actionable comment resolved - [x] I will address all review findings before requesting merge