mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-14 17:22:00 +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>
150 lines
5.0 KiB
TypeScript
150 lines
5.0 KiB
TypeScript
import type { TranscriptEntry } from "@paperclipai/adapter-utils";
|
|
import { parseAcpxStdoutLine } from "@paperclipai/adapter-utils/acpx-engine/ui";
|
|
|
|
function asRecord(value: unknown): Record<string, unknown> | null {
|
|
if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
|
|
return value as Record<string, unknown>;
|
|
}
|
|
|
|
function asNumber(value: unknown): number {
|
|
return typeof value === "number" && Number.isFinite(value) ? value : 0;
|
|
}
|
|
|
|
function errorText(value: unknown): string {
|
|
if (typeof value === "string") return value;
|
|
const rec = asRecord(value);
|
|
if (!rec) return "";
|
|
const msg =
|
|
(typeof rec.message === "string" && rec.message) ||
|
|
(typeof rec.error === "string" && rec.error) ||
|
|
(typeof rec.code === "string" && rec.code) ||
|
|
"";
|
|
if (msg) return msg;
|
|
try {
|
|
return JSON.stringify(rec);
|
|
} catch {
|
|
return "";
|
|
}
|
|
}
|
|
|
|
function safeJsonParse(text: string): unknown {
|
|
try {
|
|
return JSON.parse(text);
|
|
} catch {
|
|
return null;
|
|
}
|
|
}
|
|
|
|
export function parseClaudeStdoutLine(line: string, ts: string): TranscriptEntry[] {
|
|
const parsed = asRecord(safeJsonParse(line));
|
|
if (!parsed) {
|
|
return [{ kind: "stdout", ts, text: line }];
|
|
}
|
|
|
|
const type = typeof parsed.type === "string" ? parsed.type : "";
|
|
if (type.startsWith("acpx.")) {
|
|
return parseAcpxStdoutLine(line, ts);
|
|
}
|
|
|
|
if (type === "system" && parsed.subtype === "init") {
|
|
return [
|
|
{
|
|
kind: "init",
|
|
ts,
|
|
model: typeof parsed.model === "string" ? parsed.model : "unknown",
|
|
sessionId: typeof parsed.session_id === "string" ? parsed.session_id : "",
|
|
},
|
|
];
|
|
}
|
|
|
|
if (type === "assistant") {
|
|
const message = asRecord(parsed.message) ?? {};
|
|
const content = Array.isArray(message.content) ? message.content : [];
|
|
const entries: TranscriptEntry[] = [];
|
|
for (const blockRaw of content) {
|
|
const block = asRecord(blockRaw);
|
|
if (!block) continue;
|
|
const blockType = typeof block.type === "string" ? block.type : "";
|
|
if (blockType === "text") {
|
|
const text = typeof block.text === "string" ? block.text : "";
|
|
if (text) entries.push({ kind: "assistant", ts, text });
|
|
} else if (blockType === "thinking") {
|
|
const text = typeof block.thinking === "string" ? block.thinking : "";
|
|
if (text) entries.push({ kind: "thinking", ts, text });
|
|
} else if (blockType === "tool_use") {
|
|
entries.push({
|
|
kind: "tool_call",
|
|
ts,
|
|
name: typeof block.name === "string" ? block.name : "unknown",
|
|
toolUseId:
|
|
typeof block.id === "string"
|
|
? block.id
|
|
: typeof block.tool_use_id === "string"
|
|
? block.tool_use_id
|
|
: undefined,
|
|
input: block.input ?? {},
|
|
});
|
|
}
|
|
}
|
|
return entries.length > 0 ? entries : [{ kind: "stdout", ts, text: line }];
|
|
}
|
|
|
|
if (type === "user") {
|
|
const message = asRecord(parsed.message) ?? {};
|
|
const content = Array.isArray(message.content) ? message.content : [];
|
|
const entries: TranscriptEntry[] = [];
|
|
for (const blockRaw of content) {
|
|
const block = asRecord(blockRaw);
|
|
if (!block) continue;
|
|
const blockType = typeof block.type === "string" ? block.type : "";
|
|
if (blockType === "text") {
|
|
const text = typeof block.text === "string" ? block.text : "";
|
|
if (text) entries.push({ kind: "user", ts, text });
|
|
} else if (blockType === "tool_result") {
|
|
const toolUseId = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
|
|
const isError = block.is_error === true;
|
|
let text = "";
|
|
if (typeof block.content === "string") {
|
|
text = block.content;
|
|
} else if (Array.isArray(block.content)) {
|
|
const parts: string[] = [];
|
|
for (const part of block.content) {
|
|
const p = asRecord(part);
|
|
if (p && typeof p.text === "string") parts.push(p.text);
|
|
}
|
|
text = parts.join("\n");
|
|
}
|
|
entries.push({ kind: "tool_result", ts, toolUseId, content: text, isError });
|
|
}
|
|
}
|
|
if (entries.length > 0) return entries;
|
|
// fall through to stdout for user messages without recognized blocks
|
|
}
|
|
|
|
if (type === "result") {
|
|
const usage = asRecord(parsed.usage) ?? {};
|
|
const inputTokens = asNumber(usage.input_tokens);
|
|
const outputTokens = asNumber(usage.output_tokens);
|
|
const cachedTokens = asNumber(usage.cache_read_input_tokens);
|
|
const costUsd = asNumber(parsed.total_cost_usd);
|
|
const subtype = typeof parsed.subtype === "string" ? parsed.subtype : "";
|
|
const isError = parsed.is_error === true;
|
|
const errors = Array.isArray(parsed.errors) ? parsed.errors.map(errorText).filter(Boolean) : [];
|
|
const text = typeof parsed.result === "string" ? parsed.result : "";
|
|
return [{
|
|
kind: "result",
|
|
ts,
|
|
text,
|
|
inputTokens,
|
|
outputTokens,
|
|
cachedTokens,
|
|
costUsd,
|
|
subtype,
|
|
isError,
|
|
errors,
|
|
}];
|
|
}
|
|
|
|
return [{ kind: "stdout", ts, text: line }];
|
|
}
|