mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 11:54:35 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Adapter packages are the bridge between the control plane and local agent harnesses such as Claude Code, Codex, and Gemini CLI. > - ACP support was concentrated in a separate `acpx_local` adapter, which made ACP feel like a separate agent choice instead of an execution capability of the harness adapters. > - Claude, Codex, and Gemini now have ACP-capable harnesses, so the native adapter should own ACP selection, fallback, config, transcript parsing, and environment diagnostics. > - The standalone ACPX adapter still needs a compatibility path for existing rows, but it should not be offered as an active adapter for new agents. > - This pull request moves the shared ACP runtime into `@paperclipai/acpx-engine`, wires Claude/Codex/Gemini local adapters to prefer ACP when prerequisites are available, and retires `acpx_local` to a tombstone. > - The benefit is one adapter per harness, richer ACP transcripts by default where possible, and a migration path for existing Claude/Codex ACPX agents. ## Linked Issues or Issue Description Closes #5932 — the broken default `acpx_local` Claude path is replaced by native `claude_local` ACP support, existing Claude/Codex ACPX rows migrate to native adapters, and new agents no longer choose the standalone ACPX adapter. Refs #4893 — original merged ACPX local adapter runtime that this PR replaces with native per-harness ACP engines. Refs #6590 — prior ACPX-Claude seamlessness work folded into the new native Claude ACP path. Refs #197 — related open generic ACP/Kiro adapter work; this PR does not close it because Kiro/custom generic ACP remains a separate adapter decision. Refs #7018 — related Kimi-specific `acpx_local` shell failure; this PR retires the built-in standalone adapter but does not add a native Kimi adapter. Refs #8864 — related ACPX prompt/API guidance PR; this PR moves runtime guidance into the shared/native ACP engine path instead of the old standalone adapter. Refs #8881 — related `acpx_local` POSIX shell failure from the old `acpx` pin; this PR updates ACP dependencies but does not claim custom/OMP ACP support as a first-class native adapter. Refs #8964 — related open `acpx_local` stderr cleanup PR; this PR makes the old runtime path obsolete for new agents but keeps it as a non-closing reference. Problem description: - The standalone `acpx_local` adapter duplicates Claude/Codex agent choices that already have first-class local adapters. - ACP should be an execution engine capability of each harness adapter when the underlying harness supports ACP. - Existing `acpx_local` agents should either migrate to native harness adapters or fail with an explicit retirement message instead of silently falling back to the process adapter. ## What Changed - Added `@paperclipai/acpx-engine` as the shared ACP execution, session-codec, CLI formatter, and UI parser package. - Wired `claude_local`, `codex_local`, and `gemini_local` to auto-select ACP by default when prerequisites pass, with `engine=cli` opt-out and `engine=acp` strict mode. - Added ACP config schema/UI fields, environment checks, session-codec preservation, transcript parsing, and adapter capability metadata for the native adapters. - Retired `acpx_local` to a server tombstone, removed its UI/package/runtime image surface, and added a migration for existing Claude/Codex ACPX agents. - Updated package manifests, lockfile, release tooling, docs, Kubernetes sandbox defaults, and tests. ## Verification - `corepack pnpm --filter @paperclipai/acpx-engine typecheck` - `corepack pnpm --filter @paperclipai/adapter-claude-local typecheck` - `corepack pnpm --filter @paperclipai/adapter-codex-local typecheck` - `corepack pnpm --filter @paperclipai/adapter-gemini-local typecheck` - `corepack pnpm --filter @paperclipai/acpx-engine exec vitest run` - `corepack pnpm --filter @paperclipai/adapter-claude-local exec vitest run src/server/acp.test.ts src/server/execute.acp-fallback.test.ts src/ui/build-config.test.ts` - `corepack pnpm --filter @paperclipai/adapter-codex-local exec vitest run src/server/acp.test.ts src/ui/build-config.test.ts` - `corepack pnpm --filter @paperclipai/adapter-gemini-local exec vitest run src/server/acp.test.ts src/ui/build-config.test.ts src/ui/parse-stdout.test.ts` - `corepack pnpm --filter @paperclipai/plugin-sdk ensure-build-deps && corepack pnpm --filter @paperclipai/server exec tsc --noEmit` - `corepack pnpm --filter @paperclipai/server exec vitest run src/__tests__/adapter-routes.test.ts src/__tests__/adapter-session-codecs.test.ts src/__tests__/adapter-models.test.ts` - `corepack pnpm --filter @paperclipai/ui typecheck` - `corepack pnpm --filter @paperclipai/ui exec vitest run src/adapters/metadata.test.ts src/adapters/adapter-display-registry.test.ts src/components/AgentConfigForm.test.ts src/components/AgentConfigForm.render.test.tsx src/components/transcript/RunTranscriptView.test.tsx` - `node --test scripts/bootstrap-npm-package.test.mjs scripts/release-package-map.test.mjs scripts/verify-release-registry-state.test.mjs` Note: the server typecheck script calls `pnpm` internally; this dev shell exposes pnpm through Corepack only, so I ran the two script steps manually with `corepack pnpm`. ## Risks - Migration changes existing `acpx_local` Claude/Codex agents to native adapter types and clears old ACPX task sessions/runtime state. - Custom ACP commands remain on the retired tombstone and will need a separate future adapter/plugin path. - ACP auto-selection depends on local Node and ACP server command prerequisites; remote and unsupported environments fall back to CLI unless `engine=acp` is explicit. - `@paperclipai/acpx-engine` is a new public package and needs npm trusted-publishing bootstrap before release automation can publish it. > 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 OpenAI GPT-5 via Codex coding agent. Exact hosted model build and context-window size are not exposed in this runtime. Tool use included shell execution, repository editing, GitHub CLI operations, and local test/typecheck execution. ## 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>
124 lines
4.3 KiB
TypeScript
124 lines
4.3 KiB
TypeScript
import type { AdapterRegistryEntry } from "./adapter-registry.js";
|
|
|
|
export interface AdapterDefaults {
|
|
runtimeImage: string;
|
|
envKeys: string[];
|
|
allowFqdns: string[];
|
|
probeCommand: string[];
|
|
/** Non-secret env injected as the base layer for the Job (process-env wins on top). */
|
|
defaultEnv?: Record<string, string>;
|
|
}
|
|
|
|
const REGISTRY: Record<string, AdapterDefaults> = {
|
|
claude_local: {
|
|
runtimeImage: "ghcr.io/paperclipai/agent-runtime-claude:v1",
|
|
envKeys: ["ANTHROPIC_API_KEY"],
|
|
allowFqdns: ["api.anthropic.com"],
|
|
probeCommand: ["claude", "--version"],
|
|
},
|
|
codex_local: {
|
|
runtimeImage: "ghcr.io/paperclipai/agent-runtime-codex:v1",
|
|
envKeys: ["OPENAI_API_KEY"],
|
|
allowFqdns: ["api.openai.com"],
|
|
probeCommand: ["codex", "--version"],
|
|
},
|
|
gemini_local: {
|
|
runtimeImage: "ghcr.io/paperclipai/agent-runtime-gemini:v1",
|
|
envKeys: ["GOOGLE_API_KEY", "GEMINI_API_KEY"],
|
|
allowFqdns: ["generativelanguage.googleapis.com"],
|
|
probeCommand: ["gemini", "--version"],
|
|
},
|
|
cursor_local: {
|
|
runtimeImage: "ghcr.io/paperclipai/agent-runtime-cursor:v1",
|
|
envKeys: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
|
|
allowFqdns: ["api.anthropic.com", "api.openai.com"],
|
|
probeCommand: ["cursor-agent", "--version"],
|
|
},
|
|
opencode_local: {
|
|
runtimeImage: "ghcr.io/paperclipai/agent-runtime-opencode:v1",
|
|
envKeys: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENROUTER_API_KEY"],
|
|
allowFqdns: ["api.anthropic.com", "api.openai.com", "openrouter.ai"],
|
|
probeCommand: ["opencode", "--version"],
|
|
},
|
|
pi_local: {
|
|
runtimeImage: "ghcr.io/paperclipai/agent-runtime-pi:v1",
|
|
envKeys: ["ANTHROPIC_API_KEY"],
|
|
allowFqdns: ["api.anthropic.com"],
|
|
probeCommand: ["pi", "--version"],
|
|
},
|
|
};
|
|
|
|
export const KNOWN_ADAPTER_TYPES: ReadonlySet<string> = new Set(Object.keys(REGISTRY));
|
|
|
|
function fromRegistryEntry(entry: AdapterRegistryEntry): AdapterDefaults {
|
|
// Only runtimeImage is strictly required. The array fields are optional and
|
|
// default to []: the operator emits them with `omitempty`, so a genuinely
|
|
// empty allowFqdns/envKeys/probeCommand arrives as undefined, which is valid
|
|
// (no extra egress / no forwarded secrets / no probe), NOT an error.
|
|
if (!entry.runtimeImage) {
|
|
throw new Error(
|
|
`Adapter "${entry.adapterType}" is missing required runtime field: runtimeImage`,
|
|
);
|
|
}
|
|
return {
|
|
runtimeImage: entry.runtimeImage,
|
|
envKeys: entry.envKeys ?? [],
|
|
allowFqdns: entry.allowFqdns ?? [],
|
|
probeCommand: entry.probeCommand ?? [],
|
|
defaultEnv: entry.defaultEnv,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Resolve the runtime defaults for an adapter. When a `registry` is supplied it
|
|
* is authoritative (replace semantics): the type MUST be present and complete,
|
|
* else this throws. With no registry, falls back to the built-in REGISTRY.
|
|
*/
|
|
export function getAdapterDefaults(
|
|
adapterType: string,
|
|
registry?: readonly AdapterRegistryEntry[],
|
|
): AdapterDefaults {
|
|
if (registry && registry.length > 0) {
|
|
const entry = registry.find((e) => e.adapterType === adapterType);
|
|
if (!entry) {
|
|
throw new Error(`Adapter "${adapterType}" is not in the configured adapter registry`);
|
|
}
|
|
return fromRegistryEntry(entry);
|
|
}
|
|
const defaults = REGISTRY[adapterType];
|
|
if (!defaults) {
|
|
throw new Error(`Unknown adapter type: ${adapterType}`);
|
|
}
|
|
return defaults;
|
|
}
|
|
|
|
/**
|
|
* Resolve the adapter type for a single run: prefer the run's adapter (the agent's,
|
|
* from the lease params) so one environment can serve mixed harnesses; fall back to
|
|
* the environment's configured default adapter when the run does not specify one.
|
|
*/
|
|
export function resolveRunAdapterType(
|
|
runAdapterType: string | null | undefined,
|
|
configAdapterType: string,
|
|
): string {
|
|
const trimmed = typeof runAdapterType === "string" ? runAdapterType.trim() : "";
|
|
return trimmed.length > 0 ? trimmed : configAdapterType;
|
|
}
|
|
|
|
/**
|
|
* Build the per-run env for the Job: the non-secret `defaultEnv` is the base
|
|
* and the process-env values (the secret API keys named by `envKeys`) override
|
|
* it. Pure for testability.
|
|
*/
|
|
export function buildAdapterEnv(
|
|
defaults: AdapterDefaults,
|
|
processEnv: NodeJS.ProcessEnv = process.env,
|
|
): Record<string, string> {
|
|
const out: Record<string, string> = { ...(defaults.defaultEnv ?? {}) };
|
|
for (const k of defaults.envKeys) {
|
|
const v = processEnv[k];
|
|
if (v) out[k] = v;
|
|
}
|
|
return out;
|
|
}
|