mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-19 01:46:15 +02: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>
90 lines
2.5 KiB
TypeScript
90 lines
2.5 KiB
TypeScript
export type {
|
|
AdapterAgent,
|
|
AdapterRuntime,
|
|
UsageSummary,
|
|
AdapterBillingType,
|
|
AdapterRuntimeServiceReport,
|
|
AdapterExecutionResult,
|
|
AdapterInvocationMeta,
|
|
AdapterExecutionContext,
|
|
AdapterEnvironmentCheckLevel,
|
|
AdapterEnvironmentCheck,
|
|
AdapterEnvironmentTestStatus,
|
|
AdapterEnvironmentTestResult,
|
|
AdapterEnvironmentTestContext,
|
|
AdapterSkillSyncMode,
|
|
AdapterSkillState,
|
|
AdapterSkillOrigin,
|
|
AdapterSkillEntry,
|
|
AdapterSkillSnapshot,
|
|
AdapterSkillContext,
|
|
AdapterSessionCodec,
|
|
AdapterModel,
|
|
AdapterModelProfileKey,
|
|
AdapterModelProfileDefinition,
|
|
HireApprovedPayload,
|
|
HireApprovedHookResult,
|
|
ConfigFieldOption,
|
|
ConfigFieldSchema,
|
|
AdapterConfigSchema,
|
|
AdapterRuntimeCommandSpec,
|
|
AcpTargetDescriptor,
|
|
ServerAdapterModule,
|
|
QuotaWindow,
|
|
ProviderQuotaResult,
|
|
TranscriptEntry,
|
|
StdoutLineParser,
|
|
CLIAdapterModule,
|
|
CreateConfigValues,
|
|
} from "./types.js";
|
|
export type {
|
|
SessionCompactionPolicy,
|
|
NativeContextManagement,
|
|
AdapterSessionManagement,
|
|
ResolvedSessionCompactionPolicy,
|
|
} from "./session-compaction.js";
|
|
export {
|
|
ADAPTER_SESSION_MANAGEMENT,
|
|
LEGACY_SESSIONED_ADAPTER_TYPES,
|
|
getAdapterSessionManagement,
|
|
readSessionCompactionOverride,
|
|
resolveSessionCompactionPolicy,
|
|
hasSessionCompactionThresholds,
|
|
} from "./session-compaction.js";
|
|
export {
|
|
REDACTED_HOME_PATH_USER,
|
|
redactHomePathUserSegments,
|
|
redactHomePathUserSegmentsInValue,
|
|
redactTranscriptEntryPaths,
|
|
} from "./log-redaction.js";
|
|
export {
|
|
REDACTED_COMMAND_TEXT_VALUE,
|
|
redactCommandText,
|
|
} from "./command-redaction.js";
|
|
export { buildSandboxNpmInstallCommand } from "./sandbox-install-command.js";
|
|
export { createRuntimeProgressReporter } from "./runtime-progress.js";
|
|
export type {
|
|
RuntimeProgressSink,
|
|
RuntimeProgressPhase,
|
|
RuntimeProgressDirection,
|
|
RuntimeProgressTarget,
|
|
RuntimeProgressReporter,
|
|
RuntimeProgressReporterOptions,
|
|
RuntimeStatusPhase,
|
|
RuntimeStatusSink,
|
|
RuntimeStatusUpdate,
|
|
} from "./runtime-progress.js";
|
|
export { inferOpenAiCompatibleBiller } from "./billing.js";
|
|
// Keep the root adapter-utils entry browser-safe because the UI imports it.
|
|
// The sandbox callback bridge stays available via its dedicated subpath export.
|
|
export type {
|
|
SandboxCallbackBridgeRequest,
|
|
SandboxCallbackBridgeResponse,
|
|
SandboxCallbackBridgeAsset,
|
|
SandboxCallbackBridgeDirectories,
|
|
SandboxCallbackBridgeRouteRule,
|
|
SandboxCallbackBridgeQueueClient,
|
|
SandboxCallbackBridgeWorkerHandle,
|
|
StartedSandboxCallbackBridgeServer,
|
|
} from "./sandbox-callback-bridge.js";
|