Skip to content

The open-source app everyone uses to manage agents at work

Add ACPX local adapter runtime (#4893)

Dotta4272c1604dd1
diff --git a/Dockerfile b/Dockerfile
index 35f1121965..6fa685d935 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -22,6 +22,7 @@ COPY packages/shared/package.json packages/shared/
COPY packages/db/package.json packages/db/
COPY packages/adapter-utils/package.json packages/adapter-utils/
COPY packages/mcp-server/package.json packages/mcp-server/
+COPY packages/adapters/acpx-local/package.json packages/adapters/acpx-local/
COPY packages/adapters/claude-local/package.json packages/adapters/claude-local/
COPY packages/adapters/codex-local/package.json packages/adapters/codex-local/
COPY packages/adapters/cursor-local/package.json packages/adapters/cursor-local/
diff --git a/cli/package.json b/cli/package.json
index a2d0b3bf8d..73ab7c24fb 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -37,6 +37,7 @@
},
"dependencies": {
"@clack/prompts": "^0.10.0",
+ "@paperclipai/adapter-acpx-local": "workspace:*",
"@paperclipai/adapter-claude-local": "workspace:*",
"@paperclipai/adapter-codex-local": "workspace:*",
"@paperclipai/adapter-cursor-local": "workspace:*",
diff --git a/cli/src/adapters/registry.ts b/cli/src/adapters/registry.ts
index e4443f55ab..59799cf475 100644
--- a/cli/src/adapters/registry.ts
+++ b/cli/src/adapters/registry.ts
@@ -1,4 +1,5 @@
import type { CLIAdapterModule } from "@paperclipai/adapter-utils";
+import { printAcpxStreamEvent } from "@paperclipai/adapter-acpx-local/cli";
import { printClaudeStreamEvent } from "@paperclipai/adapter-claude-local/cli";
import { printCodexStreamEvent } from "@paperclipai/adapter-codex-local/cli";
import { printCursorStreamEvent } from "@paperclipai/adapter-cursor-local/cli";
@@ -14,6 +15,11 @@ const claudeLocalCLIAdapter: CLIAdapterModule = {
formatStdoutEvent: printClaudeStreamEvent,
};
+const acpxLocalCLIAdapter: CLIAdapterModule = {
+ type: "acpx_local",
+ formatStdoutEvent: printAcpxStreamEvent,
+};
+
const codexLocalCLIAdapter: CLIAdapterModule = {
type: "codex_local",
formatStdoutEvent: printCodexStreamEvent,
@@ -46,6 +52,7 @@ const openclawGatewayCLIAdapter: CLIAdapterModule = {
const adaptersByType = new Map<string, CLIAdapterModule>(
[
+ acpxLocalCLIAdapter,
claudeLocalCLIAdapter,
codexLocalCLIAdapter,
openCodeLocalCLIAdapter,
diff --git a/docs/pr-screenshots/pap-2944/skills-claude-dark.png b/docs/pr-screenshots/pap-2944/skills-claude-dark.png
new file mode 100644
index 0000000000..35720124f4
Binary files /dev/null and b/docs/pr-screenshots/pap-2944/skills-claude-dark.png differ
diff --git a/docs/pr-screenshots/pap-2944/skills-claude-light.png b/docs/pr-screenshots/pap-2944/skills-claude-light.png
new file mode 100644
index 0000000000..5c97755cc5
Binary files /dev/null and b/docs/pr-screenshots/pap-2944/skills-claude-light.png differ
diff --git a/docs/pr-screenshots/pap-2944/skills-codex-dark.png b/docs/pr-screenshots/pap-2944/skills-codex-dark.png
new file mode 100644
index 0000000000..dd396b3067
Binary files /dev/null and b/docs/pr-screenshots/pap-2944/skills-codex-dark.png differ
diff --git a/docs/pr-screenshots/pap-2944/skills-codex-light.png b/docs/pr-screenshots/pap-2944/skills-codex-light.png
new file mode 100644
index 0000000000..4642da7bbd
Binary files /dev/null and b/docs/pr-screenshots/pap-2944/skills-codex-light.png differ
diff --git a/docs/pr-screenshots/pap-2944/skills-custom-dark.png b/docs/pr-screenshots/pap-2944/skills-custom-dark.png
new file mode 100644
index 0000000000..a4f5cb1e18
Binary files /dev/null and b/docs/pr-screenshots/pap-2944/skills-custom-dark.png differ
diff --git a/docs/pr-screenshots/pap-2944/skills-custom-light.png b/docs/pr-screenshots/pap-2944/skills-custom-light.png
new file mode 100644
index 0000000000..ab9873a1ed
Binary files /dev/null and b/docs/pr-screenshots/pap-2944/skills-custom-light.png differ
diff --git a/docs/pr-screenshots/pap-2944/skills-empty-library-dark.png b/docs/pr-screenshots/pap-2944/skills-empty-library-dark.png
new file mode 100644
index 0000000000..bee4fd1e0c
Binary files /dev/null and b/docs/pr-screenshots/pap-2944/skills-empty-library-dark.png differ
diff --git a/docs/pr-screenshots/pap-2944/skills-empty-library-light.png b/docs/pr-screenshots/pap-2944/skills-empty-library-light.png
new file mode 100644
index 0000000000..80fa0636bc
Binary files /dev/null and b/docs/pr-screenshots/pap-2944/skills-empty-library-light.png differ
diff --git a/docs/pr-screenshots/pap-2944/skills-loading-dark.png b/docs/pr-screenshots/pap-2944/skills-loading-dark.png
new file mode 100644
index 0000000000..93c58be098
Binary files /dev/null and b/docs/pr-screenshots/pap-2944/skills-loading-dark.png differ
diff --git a/docs/pr-screenshots/pap-2944/skills-loading-light.png b/docs/pr-screenshots/pap-2944/skills-loading-light.png
new file mode 100644
index 0000000000..61c0ceea59
Binary files /dev/null and b/docs/pr-screenshots/pap-2944/skills-loading-light.png differ
diff --git a/packages/adapter-utils/src/command-redaction.ts b/packages/adapter-utils/src/command-redaction.ts
new file mode 100644
index 0000000000..9a5f37160d
--- /dev/null
+++ b/packages/adapter-utils/src/command-redaction.ts
@@ -0,0 +1,21 @@
+export const REDACTED_COMMAND_TEXT_VALUE = "***REDACTED***";
+
+const COMMAND_CLI_SECRET_OPTION_RE =
+ /(\B-{1,2}(?:api[-_]?key|(?:access[-_]?|auth[-_]?)?token|token|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)(?:\s+|=)(["']?))[^\s"'`]+(\2)/gi;
+const COMMAND_ENV_SECRET_ASSIGNMENT_RE =
+ /(\b[A-Za-z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD|PASSWD|AUTHORIZATION|JWT)[A-Za-z0-9_]*\s*=\s*)[^\s"'`]+/gi;
+const COMMAND_AUTHORIZATION_BEARER_RE = /(\bAuthorization\s*:\s*Bearer\s+)[^\s"'`]+/gi;
+const COMMAND_OPENAI_KEY_RE = /\bsk-[A-Za-z0-9_-]{12,}\b/g;
+const COMMAND_GITHUB_TOKEN_RE = /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g;
+const COMMAND_JWT_RE =
+ /\b[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}(?:\.[A-Za-z0-9_-]{8,})?\b/g;
+
+export function redactCommandText(command: string, redactedValue = REDACTED_COMMAND_TEXT_VALUE): string {
+ return command
+ .replace(COMMAND_AUTHORIZATION_BEARER_RE, `$1${redactedValue}`)
+ .replace(COMMAND_CLI_SECRET_OPTION_RE, `$1${redactedValue}$3`)
+ .replace(COMMAND_ENV_SECRET_ASSIGNMENT_RE, `$1${redactedValue}`)
+ .replace(COMMAND_OPENAI_KEY_RE, redactedValue)
+ .replace(COMMAND_GITHUB_TOKEN_RE, redactedValue)
+ .replace(COMMAND_JWT_RE, redactedValue);
+}
diff --git a/packages/adapter-utils/src/index.ts b/packages/adapter-utils/src/index.ts
index c563ab2134..0c144b7ad7 100644
--- a/packages/adapter-utils/src/index.ts
+++ b/packages/adapter-utils/src/index.ts
@@ -55,6 +55,10 @@ export {
redactHomePathUserSegmentsInValue,
redactTranscriptEntryPaths,
} from "./log-redaction.js";
+export {
+ REDACTED_COMMAND_TEXT_VALUE,
+ redactCommandText,
+} from "./command-redaction.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.
diff --git a/packages/adapter-utils/src/server-utils.test.ts b/packages/adapter-utils/src/server-utils.test.ts
index f5e8f716de..16ad53031d 100644
--- a/packages/adapter-utils/src/server-utils.test.ts
+++ b/packages/adapter-utils/src/server-utils.test.ts
@@ -1,9 +1,14 @@
import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
import { describe, expect, it } from "vitest";
import {
applyPaperclipWorkspaceEnv,
appendWithByteCap,
+ buildInvocationEnvForLogs,
DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
+ materializePaperclipSkillCopy,
renderPaperclipWakePrompt,
runningProcesses,
runChildProcess,
@@ -39,6 +44,82 @@ async function waitForTextMatch(read: () => string, pattern: RegExp, timeoutMs =
return read().match(pattern);
}
+describe("buildInvocationEnvForLogs", () => {
+ it("redacts inline secrets from resolved command metadata", () => {
+ const loggedEnv = buildInvocationEnvForLogs(
+ { SAFE_VALUE: "visible" },
+ {
+ resolvedCommand: "env OPENAI_API_KEY=sk-live-example custom-acp --token ghp_example_secret",
+ },
+ );
+
+ expect(loggedEnv.SAFE_VALUE).toBe("visible");
+ expect(loggedEnv.PAPERCLIP_RESOLVED_COMMAND).toBe(
+ "env OPENAI_API_KEY=***REDACTED*** custom-acp --token ***REDACTED***",
+ );
+ });
+});
+
+describe("materializePaperclipSkillCopy", () => {
+ it("refuses to materialize into an ancestor of the source", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-skill-copy-"));
+ try {
+ const source = path.join(root, "parent", "skill");
+ await fs.mkdir(source, { recursive: true });
+ await fs.writeFile(path.join(source, "SKILL.md"), "# skill\n", "utf8");
+
+ await expect(materializePaperclipSkillCopy(source, path.join(root, "parent"))).rejects.toThrow(
+ /ancestor/,
+ );
+ await expect(fs.readFile(path.join(source, "SKILL.md"), "utf8")).resolves.toBe("# skill\n");
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("does not delete and recopy an unchanged materialized skill target", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-skill-copy-"));
+ try {
+ const source = path.join(root, "source");
+ const target = path.join(root, "target");
+ await fs.mkdir(source, { recursive: true });
+ await fs.writeFile(path.join(source, "SKILL.md"), "# skill\n", "utf8");
+
+ const first = await materializePaperclipSkillCopy(source, target);
+ expect(first.copiedFiles).toBe(1);
+ await fs.writeFile(path.join(target, "local-marker.txt"), "keep\n", "utf8");
+
+ const second = await materializePaperclipSkillCopy(source, target);
+ expect(second.copiedFiles).toBe(0);
+ await expect(fs.readFile(path.join(target, "local-marker.txt"), "utf8")).resolves.toBe("keep\n");
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("breaks stale materialization locks left by dead processes", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-skill-copy-"));
+ try {
+ const source = path.join(root, "source");
+ const target = path.join(root, "target");
+ const lock = `${target}.lock`;
+ await fs.mkdir(source, { recursive: true });
+ await fs.writeFile(path.join(source, "SKILL.md"), "# skill\n", "utf8");
+ await fs.mkdir(lock, { recursive: true });
+ await fs.writeFile(
+ path.join(lock, "owner.json"),
+ JSON.stringify({ pid: 999_999_999, createdAt: "2000-01-01T00:00:00.000Z" }),
+ "utf8",
+ );
+
+ await expect(materializePaperclipSkillCopy(source, target)).resolves.toMatchObject({ copiedFiles: 1 });
+ await expect(fs.readFile(path.join(target, "SKILL.md"), "utf8")).resolves.toBe("# skill\n");
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+});
+
describe("runChildProcess", () => {
it("does not arm a timeout when timeoutSec is 0", async () => {
const result = await runChildProcess(
diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.ts
index 425a1f3f0f..bb4eb40de6 100644
--- a/packages/adapter-utils/src/server-utils.ts
+++ b/packages/adapter-utils/src/server-utils.ts
@@ -1,7 +1,9 @@
import { spawn, type ChildProcess } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
import { constants as fsConstants, promises as fs, type Dirent } from "node:fs";
import path from "node:path";
import { buildSshSpawnTarget, type SshRemoteExecutionSpec } from "./ssh.js";
+import { redactCommandText } from "./command-redaction.js";
import type {
AdapterSkillEntry,
AdapterSkillSnapshot,
@@ -76,10 +78,14 @@ export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
export const MAX_EXCERPT_BYTES = 32 * 1024;
const TERMINAL_RESULT_SCAN_OVERLAP_CHARS = 64 * 1024;
const SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
+const REDACTED_LOG_VALUE = "***REDACTED***";
const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
"../../skills",
"../../../../../skills",
];
+const MATERIALIZED_SKILL_SENTINEL = ".paperclip-materialized-skill.json";
+const MATERIALIZED_SKILL_LOCK_OWNER = "owner.json";
+const MATERIALIZED_SKILL_LOCK_STALE_MS = 30_000;
export const DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE = [
"You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
@@ -111,6 +117,11 @@ export interface InstalledSkillTarget {
kind: "symlink" | "directory" | "file";
}
+export interface MaterializedPaperclipSkillCopyResult {
+ copiedFiles: number;
+ skippedSymlinks: string[];
+}
+
interface PersistentSkillSnapshotOptions {
adapterType: string;
availableEntries: PaperclipSkillEntry[];
@@ -780,11 +791,15 @@ export function renderPaperclipWakePrompt(
export function redactEnvForLogs(env: Record<string, string>): Record<string, string> {
const redacted: Record<string, string> = {};
for (const [key, value] of Object.entries(env)) {
- redacted[key] = SENSITIVE_ENV_KEY.test(key) ? "***REDACTED***" : value;
+ redacted[key] = SENSITIVE_ENV_KEY.test(key) ? REDACTED_LOG_VALUE : value;
}
return redacted;
}
+export function redactCommandTextForLogs(command: string): string {
+ return redactCommandText(command, REDACTED_LOG_VALUE);
+}
+
export function buildInvocationEnvForLogs(
env: Record<string, string>,
options: {
@@ -806,7 +821,7 @@ export function buildInvocationEnvForLogs(
const resolvedCommand = options.resolvedCommand?.trim();
if (resolvedCommand) {
- merged[options.resolvedCommandEnvKey ?? "PAPERCLIP_RESOLVED_COMMAND"] = resolvedCommand;
+ merged[options.resolvedCommandEnvKey ?? "PAPERCLIP_RESOLVED_COMMAND"] = redactCommandTextForLogs(resolvedCommand);
}
return redactEnvForLogs(merged);
@@ -1395,6 +1410,190 @@ export async function ensurePaperclipSkillSymlink(
return "repaired";
}
+async function hashSkillDirectory(root: string): Promise<string> {
+ const hash = createHash("sha256");
+
+ async function visit(candidate: string, relativePath: string): Promise<void> {
+ const stat = await fs.lstat(candidate);
+ if (stat.isSymbolicLink()) {
+ hash.update(`symlink:${relativePath}\n`);
+ return;
+ }
+ if (stat.isDirectory()) {
+ hash.update(`dir:${relativePath}\n`);
+ const entries = await fs.readdir(candidate, { withFileTypes: true });
+ entries.sort((left, right) => left.name.localeCompare(right.name));
+ for (const entry of entries) {
+ const childRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+ await visit(path.join(candidate, entry.name), childRelativePath);
+ }
+ return;
+ }
+ if (stat.isFile()) {
+ hash.update(`file:${relativePath}:${stat.mode}\n`);
+ hash.update(await fs.readFile(candidate));
+ hash.update("\n");
+ return;
+ }
+ hash.update(`other:${relativePath}:${stat.mode}\n`);
+ }
+
+ await visit(root, "");
+ return hash.digest("hex");
+}
+
+async function materializedSkillFingerprintMatches(targetRoot: string, sourceFingerprint: string): Promise<boolean> {
+ try {
+ const raw = JSON.parse(await fs.readFile(path.join(targetRoot, MATERIALIZED_SKILL_SENTINEL), "utf8")) as unknown;
+ const parsed = parseObject(raw);
+ return parsed.version === 1 && parsed.sourceFingerprint === sourceFingerprint;
+ } catch {
+ return false;
+ }
+}
+
+async function acquireMaterializeLock(lockDir: string): Promise<() => Promise<void>> {
+ await fs.mkdir(path.dirname(lockDir), { recursive: true });
+ const deadline = Date.now() + MATERIALIZED_SKILL_LOCK_STALE_MS;
+ while (true) {
+ try {
+ await fs.mkdir(lockDir);
+ await fs.writeFile(
+ path.join(lockDir, MATERIALIZED_SKILL_LOCK_OWNER),
+ `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`,
+ "utf8",
+ );
+ return async () => {
+ await fs.rm(lockDir, { recursive: true, force: true });
+ };
+ } catch (err) {
+ const code = err && typeof err === "object" ? (err as { code?: unknown }).code : null;
+ if (code !== "EEXIST") throw err;
+ if (await removeStaleMaterializeLock(lockDir, MATERIALIZED_SKILL_LOCK_STALE_MS)) continue;
+ if (Date.now() >= deadline) {
+ throw new Error(`Timed out waiting for Paperclip skill materialization lock at ${lockDir}`);
+ }
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ }
+ }
+}
+
+function isPidAlive(pid: number): boolean {
+ if (!Number.isInteger(pid) || pid <= 0) return false;
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch (err) {
+ const code = err && typeof err === "object" ? (err as { code?: unknown }).code : null;
+ return code === "EPERM";
+ }
+}
+
+async function removeStaleMaterializeLock(lockDir: string, staleMs: number): Promise<boolean> {
+ const ownerPath = path.join(lockDir, MATERIALIZED_SKILL_LOCK_OWNER);
+ let shouldRemove = false;
+ try {
+ const raw = JSON.parse(await fs.readFile(ownerPath, "utf8")) as unknown;
+ const owner = parseObject(raw);
+ const pid = typeof owner.pid === "number" ? owner.pid : 0;
+ const createdAt = typeof owner.createdAt === "string" ? Date.parse(owner.createdAt) : Number.NaN;
+ const ageMs = Number.isFinite(createdAt) ? Date.now() - createdAt : staleMs + 1;
+ shouldRemove = !isPidAlive(pid) || ageMs > staleMs;
+ } catch {
+ const stat = await fs.stat(lockDir).catch(() => null);
+ shouldRemove = !stat || Date.now() - stat.mtimeMs > staleMs;
+ }
+ if (!shouldRemove) return false;
+ await fs.rm(lockDir, { recursive: true, force: true }).catch(() => {});
+ return true;
+}
+
+export async function materializePaperclipSkillCopy(
+ source: string,
+ target: string,
+): Promise<MaterializedPaperclipSkillCopyResult> {
+ const sourceRoot = path.resolve(source);
+ const targetRoot = path.resolve(target);
+ const relativeTarget = path.relative(sourceRoot, targetRoot);
+ const relativeSource = path.relative(targetRoot, sourceRoot);
+ if (
+ !relativeTarget ||
+ (!relativeTarget.startsWith("..") && !path.isAbsolute(relativeTarget)) ||
+ !relativeSource ||
+ (!relativeSource.startsWith("..") && !path.isAbsolute(relativeSource))
+ ) {
+ throw new Error("Refusing to materialize a skill into itself, an ancestor, or one of its descendants.");
+ }
+
+ const rootStat = await fs.lstat(sourceRoot);
+ if (rootStat.isSymbolicLink()) {
+ throw new Error("Refusing to materialize a skill root that is itself a symlink.");
+ }
+ if (!rootStat.isDirectory()) {
+ throw new Error("Paperclip skills must be directories.");
+ }
+
+ const result: MaterializedPaperclipSkillCopyResult = {
+ copiedFiles: 0,
+ skippedSymlinks: [],
+ };
+
+ const lockDir = `${targetRoot}.lock`;
+ const releaseLock = await acquireMaterializeLock(lockDir);
+ const tempRoot = `${targetRoot}.tmp-${process.pid}-${randomUUID()}`;
+
+ async function copyEntry(sourcePath: string, targetPath: string, relativePath: string): Promise<void> {
+ const stat = await fs.lstat(sourcePath);
+ if (stat.isSymbolicLink()) {
+ result.skippedSymlinks.push(relativePath || ".");
+ return;
+ }
+
+ if (stat.isDirectory()) {
+ await fs.mkdir(targetPath, { recursive: true });
+ const entries = await fs.readdir(sourcePath, { withFileTypes: true });
+ entries.sort((left, right) => left.name.localeCompare(right.name));
+ for (const entry of entries) {
+ const childRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+ await copyEntry(path.join(sourcePath, entry.name), path.join(targetPath, entry.name), childRelativePath);
+ }
+ return;
+ }
+
+ if (stat.isFile()) {
+ await fs.mkdir(path.dirname(targetPath), { recursive: true });
+ await fs.copyFile(sourcePath, targetPath, fsConstants.COPYFILE_FICLONE).catch(async () => {
+ await fs.copyFile(sourcePath, targetPath);
+ });
+ await fs.chmod(targetPath, stat.mode).catch(() => {});
+ result.copiedFiles += 1;
+ }
+ }
+
+ try {
+ const sourceFingerprint = await hashSkillDirectory(sourceRoot);
+ if (await materializedSkillFingerprintMatches(targetRoot, sourceFingerprint)) return result;
+ await copyEntry(sourceRoot, tempRoot, "");
+ await fs.writeFile(
+ path.join(tempRoot, MATERIALIZED_SKILL_SENTINEL),
+ `${JSON.stringify({
+ version: 1,
+ sourceFingerprint,
+ copiedFiles: result.copiedFiles,
+ skippedSymlinks: result.skippedSymlinks,
+ }, null, 2)}\n`,
+ "utf8",
+ );
+ if (await materializedSkillFingerprintMatches(targetRoot, sourceFingerprint)) return result;
+ await fs.rm(targetRoot, { recursive: true, force: true });
+ await fs.rename(tempRoot, targetRoot);
+ return result;
+ } finally {
+ await fs.rm(tempRoot, { recursive: true, force: true }).catch(() => {});
+ await releaseLock();
+ }
+}
+
export async function removeMaintainerOnlySkillSymlinks(
skillsHome: string,
allowedSkillNames: Iterable<string>,
diff --git a/packages/adapter-utils/src/session-compaction.ts b/packages/adapter-utils/src/session-compaction.ts
index 90fe544b5d..c42cbf8f4d 100644
--- a/packages/adapter-utils/src/session-compaction.ts
+++ b/packages/adapter-utils/src/session-compaction.ts
@@ -37,6 +37,7 @@ const ADAPTER_MANAGED_SESSION_POLICY: SessionCompactionPolicy = {
};
export const LEGACY_SESSIONED_ADAPTER_TYPES = new Set([
+ "acpx_local",
"claude_local",
"codex_local",
"cursor",
@@ -47,6 +48,11 @@ export const LEGACY_SESSIONED_ADAPTER_TYPES = new Set([
]);
export const ADAPTER_SESSION_MANAGEMENT: Record<string, AdapterSessionManagement> = {
+ acpx_local: {
+ supportsSessionResume: true,
+ nativeContextManagement: "confirmed",
+ defaultSessionCompaction: ADAPTER_MANAGED_SESSION_POLICY,
+ },
claude_local: {
supportsSessionResume: true,
nativeContextManagement: "confirmed",
diff --git a/packages/adapters/acpx-local/package.json b/packages/adapters/acpx-local/package.json
new file mode 100644
index 0000000000..b061a11364
--- /dev/null
+++ b/packages/adapters/acpx-local/package.json
@@ -0,0 +1,64 @@
+{
+ "name": "@paperclipai/adapter-acpx-local",
+ "version": "0.3.1",
+ "license": "MIT",
+ "homepage": "https://github.com/paperclipai/paperclip",
+ "bugs": {
+ "url": "https://github.com/paperclipai/paperclip/issues"
+ },
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/paperclipai/paperclip",
+ "directory": "packages/adapters/acpx-local"
+ },
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts",
+ "./server": "./src/server/index.ts",
+ "./ui": "./src/ui/index.ts",
+ "./cli": "./src/cli/index.ts"
+ },
+ "publishConfig": {
+ "access": "public",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js"
+ },
+ "./server": {
+ "types": "./dist/server/index.d.ts",
+ "import": "./dist/server/index.js"
+ },
+ "./ui": {
+ "types": "./dist/ui/index.d.ts",
+ "import": "./dist/ui/index.js"
+ },
+ "./cli": {
+ "types": "./dist/cli/index.d.ts",
+ "import": "./dist/cli/index.js"
+ }
+ },
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts"
+ },
+ "files": [
+ "dist",
+ "skills"
+ ],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "typecheck": "tsc --noEmit"
+ },
+ "dependencies": {
+ "@agentclientprotocol/claude-agent-acp": "^0.31.4",
+ "@paperclipai/adapter-utils": "workspace:*",
+ "@zed-industries/codex-acp": "^0.12.0",
+ "acpx": "^0.6.1",
+ "picocolors": "^1.1.1"
+ },
+ "devDependencies": {
+ "@types/node": "^24.6.0",
+ "typescript": "^5.7.3"
+ }
+}
diff --git a/packages/adapters/acpx-local/src/cli/format-event.test.ts b/packages/adapters/acpx-local/src/cli/format-event.test.ts
new file mode 100644
index 0000000000..34e2b6b3e6
--- /dev/null
+++ b/packages/adapters/acpx-local/src/cli/format-event.test.ts
@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { printAcpxStreamEvent } from "./format-event.js";
+
+function emit(payload: Record<string, unknown>): string {
+ return JSON.stringify(payload);
+}
+
+interface CapturedOutput {
+ log: string[];
+ stdout: string[];
+}
+
+function captureOutput(): { capture: CapturedOutput; restore: () => void } {
+ const log: string[] = [];
+ const stdout: string[] = [];
+ const logSpy = vi.spyOn(console, "log").mockImplementation((value?: unknown) => {
+ log.push(String(value ?? ""));
+ });
+ const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(((chunk: unknown) => {
+ stdout.push(String(chunk ?? ""));
+ return true;
+ }) as typeof process.stdout.write);
+ return {
+ capture: { log, stdout },
+ restore: () => {
+ logSpy.mockRestore();
+ stdoutSpy.mockRestore();
+ },
+ };
+}
+
+function strip(value: string): string {
+ return value.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+describe("printAcpxStreamEvent", () => {
+ let captured: CapturedOutput;
+ let restore: () => void;
+
+ beforeEach(() => {
+ const result = captureOutput();
+ captured = result.capture;
+ restore = result.restore;
+ });
+
+ afterEach(() => {
+ restore();
+ });
+
+ it("renders acpx.session as a labeled session header", () => {
+ printAcpxStreamEvent(
+ emit({
+ type: "acpx.session",
+ agent: "claude",
+ acpSessionId: "acp-1",
+ mode: "persistent",
+ permissionMode: "approve-all",
+ }),
+ false,
+ );
+ expect(captured.log.map(strip)).toEqual(["claude session: acp-1 [persistent / approve-all]"]);
+ });
+
+ it("streams output text_delta to stdout for live progress", () => {
+ printAcpxStreamEvent(
+ emit({ type: "acpx.text_delta", text: "hello", channel: "output" }),
+ false,
+ );
+ expect(captured.log).toEqual([]);
+ expect(captured.stdout.map(strip)).toEqual(["hello"]);
+ });
+
+ it("renders thought text_delta on its own line", () => {
+ printAcpxStreamEvent(
+ emit({ type: "acpx.text_delta", text: "thinking…", channel: "thought" }),
+ false,
+ );
+ expect(captured.log.map(strip)).toEqual(["thinking…"]);
+ });
+
+ it("renders tool_call with status and id", () => {
+ printAcpxStreamEvent(
+ emit({
+ type: "acpx.tool_call",
+ name: "read",
+ toolCallId: "tool-1",
+ status: "running",
+ text: "read README.md",
+ }),
+ false,
+ );
+ expect(captured.log.map(strip)).toEqual([
+ "tool_call: read [running] (tool-1)",
+ "read README.md",
+ ]);
+ });
+
+ it("renders status events with optional context window", () => {
+ printAcpxStreamEvent(
+ emit({ type: "acpx.status", tag: "context_window", used: 100, size: 200000 }),
+ false,
+ );
+ expect(captured.log.map(strip)).toEqual(["status: context_window (100/200000 ctx)"]);
+ });
+
+ it("renders acpx.result and acpx.error", () => {
+ printAcpxStreamEvent(emit({ type: "acpx.result", summary: "completed", stopReason: "end_turn" }), false);
+ printAcpxStreamEvent(emit({ type: "acpx.error", message: "auth required" }), false);
+ expect(captured.log.map(strip)).toEqual(["result: completed", "error: auth required"]);
+ });
+
+ it("falls back to plain output for non-JSON lines", () => {
+ printAcpxStreamEvent("not json", false);
+ expect(captured.log).toEqual(["not json"]);
+ });
+
+ it("still emits unknown / non-JSON lines when debug is enabled", () => {
+ printAcpxStreamEvent("not json", true);
+ expect(strip(captured.log[0])).toBe("not json");
+ });
+});
diff --git a/packages/adapters/acpx-local/src/cli/format-event.ts b/packages/adapters/acpx-local/src/cli/format-event.ts
new file mode 100644
index 0000000000..9794ba1351
--- /dev/null
+++ b/packages/adapters/acpx-local/src/cli/format-event.ts
@@ -0,0 +1,121 @@
+import pc from "picocolors";
+
+function parseJson(line: string): Record<string, unknown> | null {
+ try {
+ const parsed = JSON.parse(line);
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+ return parsed as Record<string, unknown>;
+ } catch {
+ return null;
+ }
+}
+
+function asString(value: unknown, fallback = ""): string {
+ return typeof value === "string" ? value : fallback;
+}
+
+function asNumber(value: unknown, fallback = 0): number {
+ return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function stringify(value: unknown): string {
+ if (typeof value === "string") return value;
+ if (value === null || value === undefined) return "";
+ try {
+ return JSON.stringify(value, null, 2);
+ } catch {
+ return String(value);
+ }
+}
+
+function pickToolUseId(parsed: Record<string, unknown>): string {
+ return (
+ asString(parsed.toolCallId) ||
+ asString(parsed.toolUseId) ||
+ asString(parsed.id)
+ );
+}
+
+function statusLine(parsed: Record<string, unknown>): string {
+ const text = asString(parsed.text).trim();
+ const tag = asString(parsed.tag).trim();
+ const used = asNumber(parsed.used, -1);
+ const size = asNumber(parsed.size, -1);
+ const parts: string[] = [];
+ if (text) parts.push(text);
+ if (tag && !text) parts.push(tag);
+ if (used >= 0 && size > 0) parts.push(`(${used}/${size} ctx)`);
+ return parts.join(" ") || tag || "status";
+}
+
+export function printAcpxStreamEvent(raw: string, debug: boolean): void {
+ const line = raw.trim();
+ if (!line) return;
+ const parsed = parseJson(line);
+ if (!parsed) {
+ if (debug) console.log(pc.gray(line));
+ else console.log(line);
+ return;
+ }
+
+ const type = asString(parsed.type);
+ if (type === "acpx.session") {
+ const agent = asString(parsed.agent, "acpx");
+ const session =
+ asString(parsed.acpSessionId) ||
+ asString(parsed.sessionId) ||
+ asString(parsed.runtimeSessionName);
+ const mode = asString(parsed.mode);
+ const permissionMode = asString(parsed.permissionMode);
+ const tail = [mode, permissionMode].filter(Boolean).join(" / ");
+ const suffix = tail ? ` [${tail}]` : "";
+ console.log(pc.blue(`${agent} session${session ? `: ${session}` : ""}${suffix}`));
+ return;
+ }
+ if (type === "acpx.text_delta") {
+ const text = asString(parsed.text);
+ if (!text) return;
+ const channel = asString(parsed.channel) || asString(parsed.stream);
+ const isThought = channel === "thought" || channel === "thinking";
+ if (isThought) console.log(pc.gray(text));
+ else process.stdout.write(pc.green(text));
+ return;
+ }
+ if (type === "acpx.tool_call") {
+ const name = asString(parsed.name, "acp_tool");
+ const status = asString(parsed.status);
+ const id = pickToolUseId(parsed);
+ const header = status ? `tool_call: ${name} [${status}]` : `tool_call: ${name}`;
+ const idSuffix = id ? ` (${id})` : "";
+ const isError = status === "failed" || status === "cancelled";
+ console.log((isError ? pc.red : pc.yellow)(`${header}${idSuffix}`));
+ if (parsed.input !== undefined) {
+ console.log(pc.gray(stringify(parsed.input)));
+ } else {
+ const text = asString(parsed.text).trim();
+ if (text) console.log(pc.gray(text));
+ }
+ return;
+ }
+ if (type === "acpx.tool_result") {
+ const isError = parsed.isError === true || parsed.error !== undefined;
+ console.log((isError ? pc.red : pc.cyan)(`tool_result: ${asString(parsed.name, "acp_tool")}`));
+ const content = stringify(parsed.content ?? parsed.output ?? parsed.error);
+ if (content) console.log((isError ? pc.red : pc.gray)(content));
+ return;
+ }
+ if (type === "acpx.status") {
+ console.log(pc.gray(`status: ${statusLine(parsed)}`));
+ return;
+ }
+ if (type === "acpx.result") {
+ const summary = asString(parsed.summary, asString(parsed.stopReason, asString(parsed.subtype, "complete")));
+ console.log(pc.blue(`result: ${summary}`));
+ return;
+ }
+ if (type === "acpx.error") {
+ console.log(pc.red(`error: ${asString(parsed.message, line)}`));
+ return;
+ }
+ console.log(debug ? pc.gray(line) : line);
+}
diff --git a/packages/adapters/acpx-local/src/cli/index.ts b/packages/adapters/acpx-local/src/cli/index.ts
new file mode 100644
index 0000000000..51a60e2af1
--- /dev/null
+++ b/packages/adapters/acpx-local/src/cli/index.ts
@@ -0,0 +1 @@
+export { printAcpxStreamEvent } from "./format-event.js";
diff --git a/packages/adapters/acpx-local/src/index.ts b/packages/adapters/acpx-local/src/index.ts
new file mode 100644
index 0000000000..1e4933c011
--- /dev/null
+++ b/packages/adapters/acpx-local/src/index.ts
@@ -0,0 +1,47 @@
+export const type = "acpx_local";
+export const label = "ACPX (local)";
+
+export const DEFAULT_ACPX_LOCAL_AGENT = "claude";
+export const DEFAULT_ACPX_LOCAL_MODE = "persistent";
+export const DEFAULT_ACPX_LOCAL_PERMISSION_MODE = "approve-all";
+export const DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS = "deny";
+export const DEFAULT_ACPX_LOCAL_TIMEOUT_SEC = 0;
+
+export const acpxAgentOptions = [
+ { id: "claude", label: "Claude via ACPX" },
+ { id: "codex", label: "Codex via ACPX" },
+ { id: "custom", label: "Custom ACP command" },
+] as const;
+
+export const agentConfigurationDoc = `# acpx_local agent configuration
+
+Adapter: acpx_local
+
+Use when:
+- The agent should run through Agent Client Protocol via ACPX on the Paperclip host or a managed execution environment.
+- You want one built-in adapter that can target Claude, Codex, or a custom ACP server command.
+- You need Paperclip-managed session identity and live streamed ACP events in later ACPX runtime phases.
+
+Don't use when:
+- You need today's stable Claude Code or Codex CLI wrapper behavior. Use claude_local or codex_local until acpx_local runtime execution is enabled.
+- The host cannot satisfy ACPX's Node >=22.12.0 prerequisite.
+- The agent runtime is not an ACP server and cannot be launched through ACPX.
+
+Core fields:
+- agent (string, optional): claude, codex, or custom. Defaults to claude.
+- agentCommand (string, optional): custom ACP command when agent=custom, or an override for a built-in ACP agent command.
+- mode (string, optional): persistent or oneshot. Defaults to persistent.
+- cwd (string, optional): default absolute working directory fallback for the agent process.
+- permissionMode (string, optional): defaults to approve-all, meaning ACPX permission requests are auto-approved.
+- nonInteractivePermissions (string, optional): fallback behavior when ACPX cannot ask interactively. Supported values are deny and fail.
+- stateDir (string, optional): ACPX state directory. Defaults to a Paperclip-managed company/agent scoped location.
+- instructionsFilePath (string, optional): absolute path to a markdown instructions file used by Paperclip prompt construction.
+- promptTemplate (string, optional): run prompt template.
+- bootstrapPromptTemplate (string, optional): first-run bootstrap prompt template.
+- timeoutSec (number, optional): run timeout in seconds. Defaults to 0, meaning no adapter timeout.
+- env (object, optional): KEY=VALUE environment variables or secret bindings.
+
+Dependency decision:
+- acpx_local declares direct dependencies on acpx, @agentclientprotocol/claude-agent-acp, and @zed-industries/codex-acp so the built-in adapter has deterministic package resolution instead of relying on globally installed ACP commands.
+- ACPX currently requires Node >=22.12.0. Paperclip keeps the repo-wide Node >=20 engine and surfaces the stricter runtime prerequisite through acpx_local diagnostics.
+`;
diff --git a/packages/adapters/acpx-local/src/server/config-schema.ts b/packages/adapters/acpx-local/src/server/config-schema.ts
new file mode 100644
index 0000000000..871009178d
--- /dev/null
+++ b/packages/adapters/acpx-local/src/server/config-schema.ts
@@ -0,0 +1,102 @@
+import type { AdapterConfigSchema } from "@paperclipai/adapter-utils";
+import {
+ DEFAULT_ACPX_LOCAL_AGENT,
+ DEFAULT_ACPX_LOCAL_MODE,
+ DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS,
+ DEFAULT_ACPX_LOCAL_PERMISSION_MODE,
+ DEFAULT_ACPX_LOCAL_TIMEOUT_SEC,
+ acpxAgentOptions,
+} from "../index.js";
+
+export function getConfigSchema(): AdapterConfigSchema {
+ return {
+ fields: [
+ {
+ key: "agent",
+ label: "ACP agent",
+ type: "select",
+ default: DEFAULT_ACPX_LOCAL_AGENT,
+ required: true,
+ options: acpxAgentOptions.map((agent) => ({ value: agent.id, label: agent.label })),
+ hint: "Choose the ACP agent launched through ACPX.",
+ },
+ {
+ key: "agentCommand",
+ label: "Agent command",
+ type: "text",
+ hint: "Required for custom agents; optional override for built-in Claude or Codex ACP commands.",
+ },
+ {
+ key: "mode",
+ label: "Session mode",
+ type: "select",
+ default: DEFAULT_ACPX_LOCAL_MODE,
+ options: [
+ { value: "persistent", label: "Persistent" },
+ { value: "oneshot", label: "One shot" },
+ ],
+ },
+ {
+ key: "permissionMode",
+ label: "Permission mode",
+ type: "select",
+ default: DEFAULT_ACPX_LOCAL_PERMISSION_MODE,
+ options: [
+ { value: "approve-all", label: "Approve all" },
+ { value: "default", label: "Approve reads" },
+ ],
+ hint: "Defaults to maximum permissions. Approve reads grants read-only requests and asks for approval on writes.",
+ },
+ {
+ key: "nonInteractivePermissions",
+ label: "Non-interactive permissions",
+ type: "select",
+ default: DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS,
+ options: [
+ { value: "deny", label: "Deny" },
+ { value: "fail", label: "Fail" },
+ ],
+ },
+ {
+ key: "cwd",
+ label: "Working directory",
+ type: "text",
+ hint: "Absolute fallback directory. Paperclip execution workspaces can override this at runtime.",
+ },
+ {
+ key: "stateDir",
+ label: "State directory",
+ type: "text",
+ hint: "Optional ACPX session state directory. Defaults to Paperclip-managed company/agent scoped storage.",
+ },
+ {
+ key: "instructionsFilePath",
+ label: "Instructions file",
+ type: "text",
+ hint: "Optional absolute path to markdown instructions injected into the run prompt.",
+ },
+ {
+ key: "promptTemplate",
+ label: "Prompt template",
+ type: "textarea",
+ },
+ {
+ key: "bootstrapPromptTemplate",
+ label: "Bootstrap prompt template",
+ type: "textarea",
+ },
+ {
+ key: "timeoutSec",
+ label: "Timeout seconds",
+ type: "number",
+ default: DEFAULT_ACPX_LOCAL_TIMEOUT_SEC,
+ },
+ {
+ key: "env",
+ label: "Environment JSON",
+ type: "textarea",
+ hint: "Optional JSON object of environment values or secret bindings.",
+ },
+ ],
+ };
+}
diff --git a/packages/adapters/acpx-local/src/server/execute.test.ts b/packages/adapters/acpx-local/src/server/execute.test.ts
new file mode 100644
index 0000000000..ccdea01372
--- /dev/null
+++ b/packages/adapters/acpx-local/src/server/execute.test.ts
@@ -0,0 +1,362 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { createAcpxLocalExecutor } from "./execute.js";
+
+const tempRoots: string[] = [];
+
+async function makeTempRoot() {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-skills-"));
+ tempRoots.push(root);
+ return root;
+}
+
+afterEach(async () => {
+ await Promise.all(tempRoots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
+});
+
+async function pathExists(candidate: string): Promise<boolean> {
+ return fs.access(candidate).then(() => true).catch(() => false);
+}
+
+async function onlyChildDir(parent: string): Promise<string> {
+ const entries = await fs.readdir(parent);
+ expect(entries).toHaveLength(1);
+ return path.join(parent, entries[0]!);
+}
+
+async function createSkill(root: string, name: string, body = `---\nrequired: false\n---\n# ${name}\n`) {
+ const skillDir = path.join(root, name);
+ await fs.mkdir(skillDir, { recursive: true });
+ await fs.writeFile(path.join(skillDir, "SKILL.md"), body, "utf8");
+ return {
+ key: `paperclipai/test/${name}`,
+ runtimeName: name,
+ source: skillDir,
+ required: false,
+ };
+}
+
+function buildRuntime() {
+ return {
+ ensureSession: async () => ({
+ backendSessionId: "backend-session",
+ agentSessionId: "agent-session",
+ runtimeSessionName: "runtime-session",
+ }),
+ startTurn: () => ({
+ events: (async function* () {
+ yield { type: "done", stopReason: "end_turn" };
+ })(),
+ result: Promise.resolve({ status: "completed", stopReason: "end_turn" }),
+ cancel: async () => {},
+ }),
+ close: async () => {},
+ };
+}
+
+async function runExecutor(config: Record<string, unknown>) {
+ const runtimeOptions: Record<string, unknown>[] = [];
+ const meta: Record<string, unknown>[] = [];
+ const logs: Array<{ stream: string; text: string }> = [];
+ const execute = createAcpxLocalExecutor({
+ createRuntime: (options) => {
+ runtimeOptions.push(options as unknown as Record<string, unknown>);
+ return buildRuntime() as never;
+ },
+ });
+
+ const result = await execute({
+ runId: "run-1",
+ agent: {
+ id: "agent-1",
+ companyId: "company-1",
+ },
+ runtime: {},
+ config,
+ context: {},
+ onLog: async (stream: "stdout" | "stderr", text: string) => {
+ logs.push({ stream, text });
+ },
+ onMeta: async (payload: unknown) => {
+ meta.push(payload as Record<string, unknown>);
+ },
+ } as never);
+
+ expect(result.exitCode).toBe(0);
+ return { logs, meta, runtimeOptions, result };
+}
+
+describe("acpx_local runtime skill isolation", () => {
+ it.skipIf(process.platform === "win32")("materializes ACPX Claude skills without symlinked descendants", async () => {
+ const root = await makeTempRoot();
+ const skillRoot = path.join(root, "skills");
+ const outsideRoot = path.join(root, "outside");
+ await fs.mkdir(outsideRoot, { recursive: true });
+ await fs.writeFile(path.join(outsideRoot, "secret.txt"), "do not expose", "utf8");
+ const skill = await createSkill(skillRoot, "danger");
+ await fs.symlink(path.join(outsideRoot, "secret.txt"), path.join(skill.source, "leak.txt"));
+ await fs.symlink(outsideRoot, path.join(skill.source, "leak-dir"));
+
+ const stateDir = path.join(root, "state");
+ const { meta } = await runExecutor({
+ agent: "claude",
+ stateDir,
+ paperclipRuntimeSkills: [skill],
+ paperclipSkillSync: { desiredSkills: [skill.key] },
+ });
+
+ const mountedRoot = await onlyChildDir(path.join(stateDir, "runtime-skills", "claude"));
+ const skillsHome = path.join(mountedRoot, ".claude", "skills");
+ const materializedSkill = path.join(skillsHome, skill.runtimeName);
+ expect(await fs.readFile(path.join(materializedSkill, "SKILL.md"), "utf8")).toContain("# danger");
+ expect(await pathExists(path.join(materializedSkill, "leak.txt"))).toBe(false);
+ expect(await pathExists(path.join(materializedSkill, "leak-dir"))).toBe(false);
+ expect(String(meta[0]?.prompt ?? "")).toContain(`Skill root: ${skillsHome}`);
+ });
+
+ it.skipIf(process.platform === "win32")("revokes removed ACPX Codex skills and skips symlinked descendants", async () => {
+ const root = await makeTempRoot();
+ const skillRoot = path.join(root, "skills");
+ const outsideRoot = path.join(root, "outside");
+ const codexHome = path.join(root, "codex-home");
+ await fs.mkdir(outsideRoot, { recursive: true });
+ await fs.writeFile(path.join(outsideRoot, "secret.txt"), "do not expose", "utf8");
+ const keep = await createSkill(skillRoot, "keep");
+ const remove = await createSkill(skillRoot, "remove");
+ await fs.symlink(path.join(outsideRoot, "secret.txt"), path.join(keep.source, "leak.txt"));
+ await fs.symlink(outsideRoot, path.join(keep.source, "leak-dir"));
+
+ const baseConfig = {
+ agent: "codex",
+ stateDir: path.join(root, "state"),
+ env: { CODEX_HOME: codexHome },
+ paperclipRuntimeSkills: [keep, remove],
+ };
+
+ await runExecutor({
+ ...baseConfig,
+ paperclipSkillSync: { desiredSkills: [keep.key, remove.key] },
+ });
+ expect(await pathExists(path.join(codexHome, "skills", remove.runtimeName, "SKILL.md"))).toBe(true);
+
+ await runExecutor({
+ ...baseConfig,
+ paperclipSkillSync: { desiredSkills: [keep.key] },
+ });
+
+ expect(await pathExists(path.join(codexHome, "skills", keep.runtimeName, "SKILL.md"))).toBe(true);
+ expect(await pathExists(path.join(codexHome, "skills", keep.runtimeName, "leak.txt"))).toBe(false);
+ expect(await pathExists(path.join(codexHome, "skills", keep.runtimeName, "leak-dir"))).toBe(false);
+ expect(await pathExists(path.join(codexHome, "skills", remove.runtimeName))).toBe(false);
+ });
+
+ it.skipIf(process.platform === "win32")("removes legacy ACPX Codex skill symlinks when a skill is no longer desired", async () => {
+ const root = await makeTempRoot();
+ const skillRoot = path.join(root, "skills");
+ const codexHome = path.join(root, "codex-home");
+ const legacy = await createSkill(skillRoot, "legacy");
+ const skillsHome = path.join(codexHome, "skills");
+ await fs.mkdir(skillsHome, { recursive: true });
+ await fs.symlink(legacy.source, path.join(skillsHome, legacy.runtimeName));
+
+ await runExecutor({
+ agent: "codex",
+ stateDir: path.join(root, "state"),
+ env: { CODEX_HOME: codexHome },
+ paperclipRuntimeSkills: [legacy],
+ paperclipSkillSync: { desiredSkills: [] },
+ });
+
+ expect(await pathExists(path.join(skillsHome, legacy.runtimeName))).toBe(false);
+ });
+
+ it.skipIf(process.platform === "win32")("replaces stale managed Codex auth files with source symlinks", async () => {
+ const root = await makeTempRoot();
+ const sourceCodexHome = path.join(root, "source-codex-home");
+ const paperclipHome = path.join(root, "paperclip-home");
+ const managedCodexHome = path.join(
+ paperclipHome,
+ "instances",
+ "default",
+ "companies",
+ "company-1",
+ "codex-home",
+ );
+ await fs.mkdir(sourceCodexHome, { recursive: true });
+ await fs.mkdir(managedCodexHome, { recursive: true });
+ const sourceAuth = path.join(sourceCodexHome, "auth.json");
+ const managedAuth = path.join(managedCodexHome, "auth.json");
+ await fs.writeFile(sourceAuth, "{\"source\":true}", "utf8");
+ await fs.writeFile(managedAuth, "{\"stale\":true}", "utf8");
+
+ const previousCodexHome = process.env.CODEX_HOME;
+ const previousPaperclipHome = process.env.PAPERCLIP_HOME;
+ try {
+ process.env.CODEX_HOME = sourceCodexHome;
+ process.env.PAPERCLIP_HOME = paperclipHome;
+ await runExecutor({
+ agent: "codex",
+ stateDir: path.join(root, "state"),
+ paperclipRuntimeSkills: [],
+ paperclipSkillSync: { desiredSkills: [] },
+ });
+ } finally {
+ if (previousCodexHome === undefined) delete process.env.CODEX_HOME;
+ else process.env.CODEX_HOME = previousCodexHome;
+ if (previousPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;
+ else process.env.PAPERCLIP_HOME = previousPaperclipHome;
+ }
+
+ const authStat = await fs.lstat(managedAuth);
+ expect(authStat.isSymbolicLink()).toBe(true);
+ expect(path.resolve(path.dirname(managedAuth), await fs.readlink(managedAuth))).toBe(sourceAuth);
+ });
+
+ it("keeps fresh credential wrapper scripts across ACPX agent changes", async () => {
+ const root = await makeTempRoot();
+ const stateDir = path.join(root, "state");
+ const baseConfig = {
+ agentCommand: "node ./fake-acp.js",
+ stateDir,
+ };
+
+ await runExecutor({
+ ...baseConfig,
+ agent: "custom-a",
+ env: { PAPERCLIP_API_KEY: "old-key" },
+ });
+ await runExecutor({
+ ...baseConfig,
+ agent: "custom-b",
+ env: { PAPERCLIP_API_KEY: "new-key" },
+ });
+
+ const wrappers = await fs.readdir(path.join(stateDir, "wrappers"));
+ expect(wrappers.filter((name) => name.endsWith(".sh"))).toHaveLength(2);
+ expect(wrappers.filter((name) => name.endsWith(".env"))).toHaveLength(2);
+ expect(wrappers.some((name) => name.startsWith("custom-a-"))).toBe(true);
+ expect(wrappers.some((name) => name.startsWith("custom-b-"))).toBe(true);
+ const wrapperPath = path.join(stateDir, "wrappers", wrappers.find((name) => name.startsWith("custom-b-") && name.endsWith(".sh"))!);
+ const envPath = path.join(stateDir, "wrappers", wrappers.find((name) => name.startsWith("custom-b-") && name.endsWith(".env"))!);
+ const wrapper = await fs.readFile(wrapperPath, "utf8");
+ const env = await fs.readFile(envPath, "utf8");
+ expect((await fs.stat(envPath)).mode & 0o777).toBe(0o600);
+ expect((await fs.stat(wrapperPath)).mode & 0o777).toBe(0o700);
+ expect(wrapper).toContain("node ./fake-acp.js");
+ expect(wrapper).not.toContain("PAPERCLIP_API_KEY");
+ expect(wrapper).not.toContain("new-key");
+ expect(wrapper).not.toContain("old-key");
+ expect(env).toContain("PAPERCLIP_API_KEY='new-key'");
+ expect(env).not.toContain("old-key");
+ });
+
+ it("cleans aged credential wrapper scripts across ACPX agent changes", async () => {
+ const root = await makeTempRoot();
+ const stateDir = path.join(root, "state");
+ const wrappersDir = path.join(stateDir, "wrappers");
+ const baseConfig = {
+ agentCommand: "node ./fake-acp.js",
+ stateDir,
+ };
+
+ await runExecutor({
+ ...baseConfig,
+ agent: "custom-a",
+ env: { PAPERCLIP_API_KEY: "old-key" },
+ });
+ const oldDate = new Date(Date.now() - 16 * 60 * 1000);
+ await Promise.all(
+ (await fs.readdir(wrappersDir))
+ .filter((name) => name.startsWith("custom-a-"))
+ .map((name) => fs.utimes(path.join(wrappersDir, name), oldDate, oldDate)),
+ );
+
+ await runExecutor({
+ ...baseConfig,
+ agent: "custom-b",
+ env: { PAPERCLIP_API_KEY: "new-key" },
+ });
+
+ const wrappers = await fs.readdir(wrappersDir);
+ expect(wrappers.filter((name) => name.endsWith(".sh"))).toHaveLength(1);
+ expect(wrappers.filter((name) => name.endsWith(".env"))).toHaveLength(1);
+ expect(wrappers.some((name) => name.startsWith("custom-a-"))).toBe(false);
+ expect(wrappers.some((name) => name.startsWith("custom-b-"))).toBe(true);
+ });
+
+ it("keeps distinct wrapper env files for concurrent runs with different credentials", async () => {
+ const root = await makeTempRoot();
+ const stateDir = path.join(root, "state");
+ const baseConfig = {
+ agent: "custom-a",
+ agentCommand: "node ./fake-acp.js",
+ stateDir,
+ };
+
+ await runExecutor({
+ ...baseConfig,
+ env: { PAPERCLIP_API_KEY: "first-key" },
+ });
+ await runExecutor({
+ ...baseConfig,
+ env: { PAPERCLIP_API_KEY: "second-key" },
+ });
+
+ const envFileNames = (await fs.readdir(path.join(stateDir, "wrappers"))).filter((name) => name.endsWith(".env"));
+ expect(envFileNames).toHaveLength(2);
+ const envFiles = await Promise.all(
+ envFileNames.map(async (name) => fs.readFile(path.join(stateDir, "wrappers", name), "utf8")),
+ );
+ expect(envFiles.filter((contents) => contents.includes("PAPERCLIP_API_KEY='first-key'"))).toHaveLength(1);
+ expect(envFiles.filter((contents) => contents.includes("PAPERCLIP_API_KEY='second-key'"))).toHaveLength(1);
+ });
+
+ it("passes Paperclip env through the ACP agent wrapper instead of process.env", async () => {
+ let observedApiKeyDuringStream: string | undefined;
+ const execute = createAcpxLocalExecutor({
+ createRuntime: () => ({
+ ensureSession: async () => ({
+ backendSessionId: "backend-session",
+ agentSessionId: "agent-session",
+ runtimeSessionName: "runtime-session",
+ }),
+ startTurn: () => ({
+ events: (async function* () {
+ await Promise.resolve();
+ observedApiKeyDuringStream = process.env.PAPERCLIP_API_KEY;
+ yield { type: "done", stopReason: "end_turn" };
+ })(),
+ result: Promise.resolve({ status: "completed", stopReason: "end_turn" }),
+ cancel: async () => {},
+ }),
+ close: async () => {},
+ }) as never,
+ });
+
+ const previousApiKey = process.env.PAPERCLIP_API_KEY;
+ try {
+ delete process.env.PAPERCLIP_API_KEY;
+ const result = await execute({
+ runId: "run-1",
+ agent: {
+ id: "agent-1",
+ companyId: "company-1",
+ },
+ runtime: {},
+ config: { agent: "custom", agentCommand: "node ./fake-acp.js" },
+ context: {},
+ authToken: "runtime-key",
+ onLog: async () => {},
+ onMeta: async () => {},
+ } as never);
+
+ expect(result.exitCode).toBe(0);
+ expect(observedApiKeyDuringStream).toBeUndefined();
+ } finally {
+ if (previousApiKey === undefined) delete process.env.PAPERCLIP_API_KEY;
+ else process.env.PAPERCLIP_API_KEY = previousApiKey;
+ }
+ });
+});
diff --git a/packages/adapters/acpx-local/src/server/execute.ts b/packages/adapters/acpx-local/src/server/execute.ts
new file mode 100644
index 0000000000..6c2840e02d
--- /dev/null
+++ b/packages/adapters/acpx-local/src/server/execute.ts
@@ -0,0 +1,1212 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import { readAdapterExecutionTarget, adapterExecutionTargetSessionIdentity } from "@paperclipai/adapter-utils/execution-target";
+import {
+ DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
+ applyPaperclipWorkspaceEnv,
+ asNumber,
+ asString,
+ buildInvocationEnvForLogs,
+ buildPaperclipEnv,
+ ensureAbsoluteDirectory,
+ ensurePathInEnv,
+ joinPromptSections,
+ materializePaperclipSkillCopy,
+ parseObject,
+ readPaperclipRuntimeSkillEntries,
+ renderPaperclipWakePrompt,
+ renderTemplate,
+ resolvePaperclipDesiredSkillNames,
+ stringifyPaperclipWakePayload,
+ type PaperclipSkillEntry,
+} from "@paperclipai/adapter-utils/server-utils";
+import { shellQuote } from "@paperclipai/adapter-utils/ssh";
+import {
+ createAcpRuntime,
+ createAgentRegistry,
+ createRuntimeStore,
+ isAcpRuntimeError,
+ type AcpAgentRegistry,
+ type AcpRuntime,
+ type AcpRuntimeEvent,
+ type AcpRuntimeHandle,
+ type AcpRuntimeOptions,
+ type AcpRuntimeTurn,
+ type AcpRuntimeTurnResult,
+} from "acpx/runtime";
+import {
+ DEFAULT_ACPX_LOCAL_AGENT,
+ DEFAULT_ACPX_LOCAL_MODE,
+ DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS,
+ DEFAULT_ACPX_LOCAL_PERMISSION_MODE,
+ DEFAULT_ACPX_LOCAL_TIMEOUT_SEC,
+} from "../index.js";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_WARM_HANDLE_IDLE_MS = 15 * 60 * 1000;
+const WRAPPER_CLEANUP_RETENTION_MS = 15 * 60 * 1000;
+const PAPERCLIP_MANAGED_CODEX_SKILLS_MANIFEST = ".paperclip-managed-skills.json";
+
+type AcpxRuntimeFactory = (options: AcpRuntimeOptions) => AcpRuntime;
+
+interface RuntimeCacheEntry {
+ runtime: AcpRuntime;
+ handle: AcpRuntimeHandle;
+ fingerprint: string;
+ lastUsedAt: number;
+}
+
+interface ExecuteDeps {
+ createRuntime?: AcpxRuntimeFactory;
+ now?: () => number;
+ warmHandles?: Map<string, RuntimeCacheEntry>;
+}
+
+interface AcpxPreparedRuntime {
+ acpxAgent: string;
+ mode: "persistent" | "oneshot";
+ cwd: string;
+ workspaceId: string;
+ workspaceRepoUrl: string;
+ workspaceRepoRef: string;
+ env: Record<string, string>;
+ loggedEnv: Record<string, string>;
+ stateDir: string;
+ permissionMode: "approve-all" | "approve-reads" | "deny-all";
+ nonInteractivePermissions: "deny" | "fail";
+ timeoutSec: number;
+ sessionKey: string;
+ fingerprint: string;
+ agentCommand: string | null;
+ agentRegistry: AcpAgentRegistry;
+ remoteExecutionIdentity: Record<string, unknown> | null;
+ skillPromptInstructions: string;
+ skillsIdentity: Record<string, unknown>;
+}
+
+const defaultWarmHandles = new Map<string, RuntimeCacheEntry>();
+
+function stableJson(value: unknown): string {
+ if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+ if (value && typeof value === "object") {
+ return `{${Object.entries(value as Record<string, unknown>)
+ .sort(([a], [b]) => a.localeCompare(b))
+ .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+ .join(",")}}`;
+ }
+ return JSON.stringify(value);
+}
+
+function shortHash(value: unknown): string {
+ return createHash("sha256").update(stableJson(value)).digest("hex").slice(0, 16);
+}
+
+function defaultPaperclipInstanceDir(): string {
+ const home = process.env.PAPERCLIP_HOME?.trim() || path.join(os.homedir(), ".paperclip");
+ const instanceId = process.env.PAPERCLIP_INSTANCE_ID?.trim() || "default";
+ return path.join(home, "instances", instanceId);
+}
+
+function defaultStateDir(companyId: string, agentId: string): string {
+ return path.join(defaultPaperclipInstanceDir(), "companies", companyId, "acpx-local", "agents", agentId);
+}
+
+function resolveManagedCodexHomeDir(companyId: string): string {
+ return path.join(defaultPaperclipInstanceDir(), "companies", companyId, "codex-home");
+}
+
+function packageRootDir(): string {
+ return path.resolve(__moduleDir, "../..");
+}
+
+function resolveBuiltInAgentCommand(agent: string): string | null {
+ const binName =
+ agent === "claude"
+ ? "claude-agent-acp"
+ : agent === "codex"
+ ? "codex-acp"
+ : null;
+ if (!binName) return null;
+ return path.join(packageRootDir(), "node_modules", ".bin", binName);
+}
+
+function normalizeAgent(config: Record<string, unknown>): string {
+ const agent = asString(config.agent, DEFAULT_ACPX_LOCAL_AGENT).trim();
+ return agent || DEFAULT_ACPX_LOCAL_AGENT;
+}
+
+async function pathExists(candidate: string): Promise<boolean> {
+ return fs.access(candidate).then(() => true).catch(() => false);
+}
+
+async function ensureParentDir(target: string): Promise<void> {
+ await fs.mkdir(path.dirname(target), { recursive: true });
+}
+
+async function writeFileAtomically(input: {
+ target: string;
+ contents: string;
+ mode: number;
+}): Promise<void> {
+ await ensureParentDir(input.target);
+ const tempPath = `${input.target}.tmp-${process.pid}-${randomUUID()}`;
+ const handle = await fs.open(tempPath, "wx", input.mode);
+ try {
+ await handle.writeFile(input.contents, "utf8");
+ await handle.close();
+ await fs.rename(tempPath, input.target);
+ await fs.chmod(input.target, input.mode).catch(() => {});
+ } catch (err) {
+ await handle.close().catch(() => {});
+ await fs.rm(tempPath, { force: true }).catch(() => {});
+ throw err;
+ }
+}
+
+async function ensureSymlink(target: string, source: string): Promise<void> {
+ const resolvedSource = path.resolve(source);
+ const existing = await fs.lstat(target).catch(() => null);
+ if (!existing) {
+ await ensureParentDir(target);
+ await fs.symlink(resolvedSource, target);
+ return;
+ }
+
+ if (!existing.isSymbolicLink()) {
+ await fs.rm(target, { recursive: true, force: true });
+ await fs.symlink(resolvedSource, target);
+ return;
+ }
+
+ const linkedPath = await fs.readlink(target).catch(() => null);
+ if (!linkedPath) return;
+
+ const resolvedLinkedPath = path.resolve(path.dirname(target), linkedPath);
+ if (resolvedLinkedPath === resolvedSource) return;
+
+ await fs.unlink(target);
+ await fs.symlink(resolvedSource, target);
+}
+
+async function ensureCopiedFile(target: string, source: string): Promise<void> {
+ if (await pathExists(target)) return;
+ await ensureParentDir(target);
+ await fs.copyFile(source, target);
+}
+
+async function prepareManagedCodexHome(input: {
+ companyId: string;
+ sourceHome: string;
+ targetHome: string;
+ onLog: AdapterExecutionContext["onLog"];
+}): Promise<string> {
+ const { sourceHome, targetHome, onLog } = input;
+ if (path.resolve(sourceHome) === path.resolve(targetHome)) return targetHome;
+
+ await fs.mkdir(targetHome, { recursive: true });
+
+ const authJson = path.join(sourceHome, "auth.json");
+ if (await pathExists(authJson)) await ensureSymlink(path.join(targetHome, "auth.json"), authJson);
+
+ for (const name of ["config.json", "config.toml", "instructions.md"]) {
+ const source = path.join(sourceHome, name);
+ if (await pathExists(source)) await ensureCopiedFile(path.join(targetHome, name), source);
+ }
+
+ await onLog(
+ "stdout",
+ `[paperclip] Using Paperclip-managed ACPX Codex home "${targetHome}" (seeded from "${sourceHome}").\n`,
+ );
+ return targetHome;
+}
+
+async function hashPathContents(
+ candidate: string,
+ hash: ReturnType<typeof createHash>,
+ relativePath: string,
+ seenDirectories: Set<string>,
+): Promise<void> {
+ const stat = await fs.lstat(candidate);
+
+ if (stat.isSymbolicLink()) {
+ hash.update(`symlink-skipped:${relativePath}\n`);
+ return;
+ }
+
+ if (stat.isDirectory()) {
+ const realDir = await fs.realpath(candidate).catch(() => candidate);
+ hash.update(`dir:${relativePath}\n`);
+ if (seenDirectories.has(realDir)) {
+ hash.update("loop\n");
+ return;
+ }
+ seenDirectories.add(realDir);
+ const entries = await fs.readdir(candidate, { withFileTypes: true });
+ entries.sort((left, right) => left.name.localeCompare(right.name));
+ for (const entry of entries) {
+ const childRelativePath = relativePath.length > 0 ? `${relativePath}/${entry.name}` : entry.name;
+ await hashPathContents(path.join(candidate, entry.name), hash, childRelativePath, seenDirectories);
+ }
+ return;
+ }
+
+ if (stat.isFile()) {
+ hash.update(`file:${relativePath}\n`);
+ hash.update(await fs.readFile(candidate));
+ hash.update("\n");
+ return;
+ }
+
+ hash.update(`other:${relativePath}:${stat.mode}\n`);
+}
+
+async function buildSkillSetKey(input: {
+ skills: PaperclipSkillEntry[];
+ label: string;
+}): Promise<string> {
+ const hash = createHash("sha256");
+ hash.update(`paperclip-acpx-${input.label}-skills:v1\n`);
+ const sorted = [...input.skills].sort((left, right) => left.runtimeName.localeCompare(right.runtimeName));
+ for (const entry of sorted) {
+ hash.update(`skill:${entry.key}:${entry.runtimeName}\n`);
+ await hashPathContents(entry.source, hash, entry.runtimeName, new Set<string>());
+ }
+ return hash.digest("hex");
+}
+
+async function resolveSelectedRuntimeSkills(
+ config: Record<string, unknown>,
+): Promise<{ allSkills: PaperclipSkillEntry[]; selectedSkills: PaperclipSkillEntry[]; desiredSkillNames: string[] }> {
+ const allSkills = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+ const desiredSkillNames = resolvePaperclipDesiredSkillNames(config, allSkills);
+ const desiredSet = new Set(desiredSkillNames);
+ return {
+ allSkills,
+ selectedSkills: allSkills.filter((entry) => desiredSet.has(entry.key)),
+ desiredSkillNames,
+ };
+}
+
+async function prepareClaudeSkillRuntime(input: {
+ stateDir: string;
+ config: Record<string, unknown>;
+ onLog: AdapterExecutionContext["onLog"];
+}): Promise<{
+ identity: Record<string, unknown>;
+ promptInstructions: string;
+ commandNotes: string[];
+}> {
+ const { selectedSkills, desiredSkillNames } = await resolveSelectedRuntimeSkills(input.config);
+ const skillSetKey = await buildSkillSetKey({ skills: selectedSkills, label: "claude" });
+ const bundleRoot = path.join(input.stateDir, "runtime-skills", "claude", skillSetKey);
+ const skillsHome = path.join(bundleRoot, ".claude", "skills");
+ await fs.mkdir(skillsHome, { recursive: true });
+
+ for (const entry of selectedSkills) {
+ const target = path.join(skillsHome, entry.runtimeName);
+ try {
+ const result = await materializePaperclipSkillCopy(entry.source, target);
+ if (result.skippedSymlinks.length > 0) {
+ await input.onLog(
+ "stdout",
+ `[paperclip] Materialized ACPX Claude skill "${entry.runtimeName}" into ${skillsHome} and skipped ${result.skippedSymlinks.length} symlink(s).\n`,
+ );
+ }
+ } catch (err) {
+ await input.onLog(
+ "stderr",
+ `[paperclip] Failed to materialize ACPX Claude skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
+ );
+ }
+ }
+
+ const selectedNames = selectedSkills.map((entry) => entry.runtimeName).sort();
+ const promptInstructions = selectedSkills.length > 0
+ ? [
+ "Paperclip has materialized selected runtime skills for this ACPX Claude session.",
+ `Skill root: ${skillsHome}`,
+ selectedNames.length > 0 ? `Selected skills: ${selectedNames.join(", ")}` : "",
+ "When a task calls for one of these skills, read its SKILL.md from that root and follow it.",
+ ].filter(Boolean).join("\n")
+ : "";
+
+ return {
+ identity: {
+ mode: "claude",
+ skillSetKey,
+ desiredSkillNames,
+ selectedSkills: selectedNames,
+ skillRoot: selectedSkills.length > 0 ? skillsHome : null,
+ },
+ promptInstructions,
+ commandNotes: selectedSkills.length > 0
+ ? [`Materialized ${selectedSkills.length} Paperclip skill(s) for ACPX Claude at ${skillsHome}.`]
+ : [],
+ };
+}
+
+async function readManagedCodexSkillsManifest(skillsHome: string): Promise<Set<string>> {
+ const manifestPath = path.join(skillsHome, PAPERCLIP_MANAGED_CODEX_SKILLS_MANIFEST);
+ try {
+ const raw = JSON.parse(await fs.readFile(manifestPath, "utf8")) as unknown;
+ const parsed = parseObject(raw);
+ const skills = Array.isArray(parsed.managedSkillNames)
+ ? parsed.managedSkillNames.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+ : [];
+ return new Set(skills);
+ } catch {
+ return new Set();
+ }
+}
+
+async function writeManagedCodexSkillsManifest(skillsHome: string, skillNames: Iterable<string>): Promise<void> {
+ const managedSkillNames = Array.from(new Set(skillNames)).sort();
+ await fs.writeFile(
+ path.join(skillsHome, PAPERCLIP_MANAGED_CODEX_SKILLS_MANIFEST),
+ `${JSON.stringify({ version: 1, managedSkillNames }, null, 2)}\n`,
+ "utf8",
+ );
+}
+
+async function removeSkillTarget(target: string): Promise<boolean> {
+ const existing = await fs.lstat(target).catch(() => null);
+ if (!existing) return false;
+ await fs.rm(target, { recursive: true, force: true });
+ return true;
+}
+
+async function reconcileManagedCodexSkills(input: {
+ skillsHome: string;
+ allSkills: PaperclipSkillEntry[];
+ selectedSkills: PaperclipSkillEntry[];
+ onLog: AdapterExecutionContext["onLog"];
+}): Promise<void> {
+ const desired = new Set(input.selectedSkills.map((entry) => entry.runtimeName));
+ const managed = await readManagedCodexSkillsManifest(input.skillsHome);
+ const availableByRuntimeName = new Map(input.allSkills.map((entry) => [entry.runtimeName, entry]));
+
+ for (const name of managed) {
+ if (desired.has(name)) continue;
+ if (await removeSkillTarget(path.join(input.skillsHome, name))) {
+ await input.onLog("stdout", `[paperclip] Revoked ACPX Codex skill "${name}" from ${input.skillsHome}\n`);
+ }
+ }
+
+ for (const entry of input.allSkills) {
+ if (desired.has(entry.runtimeName) || managed.has(entry.runtimeName)) continue;
+ const target = path.join(input.skillsHome, entry.runtimeName);
+ const existing = await fs.lstat(target).catch(() => null);
+ if (!existing?.isSymbolicLink()) continue;
+ const linkedPath = await fs.readlink(target).catch(() => null);
+ if (!linkedPath) continue;
+ const resolvedLinkedPath = path.resolve(path.dirname(target), linkedPath);
+ if (resolvedLinkedPath !== path.resolve(entry.source)) continue;
+ if (await removeSkillTarget(target)) {
+ await input.onLog("stdout", `[paperclip] Revoked legacy ACPX Codex skill "${entry.runtimeName}" from ${input.skillsHome}\n`);
+ }
+ }
+
+ for (const name of managed) {
+ if (desired.has(name) || availableByRuntimeName.has(name)) continue;
+ if (await removeSkillTarget(path.join(input.skillsHome, name))) {
+ await input.onLog("stdout", `[paperclip] Revoked unavailable ACPX Codex skill "${name}" from ${input.skillsHome}\n`);
+ }
+ }
+}
+
+async function prepareCodexSkillRuntime(input: {
+ companyId: string;
+ config: Record<string, unknown>;
+ env: Record<string, string>;
+ onLog: AdapterExecutionContext["onLog"];
+}): Promise<{ identity: Record<string, unknown>; commandNotes: string[] }> {
+ const envConfig = parseObject(input.config.env);
+ const configuredCodexHome =
+ typeof envConfig.CODEX_HOME === "string" && envConfig.CODEX_HOME.trim().length > 0
+ ? path.resolve(envConfig.CODEX_HOME.trim())
+ : null;
+ const sourceCodexHome =
+ typeof process.env.CODEX_HOME === "string" && process.env.CODEX_HOME.trim().length > 0
+ ? path.resolve(process.env.CODEX_HOME.trim())
+ : path.join(os.homedir(), ".codex");
+ const managedCodexHome = resolveManagedCodexHomeDir(input.companyId);
+ const effectiveCodexHome = configuredCodexHome ??
+ await prepareManagedCodexHome({
+ companyId: input.companyId,
+ sourceHome: sourceCodexHome,
+ targetHome: managedCodexHome,
+ onLog: input.onLog,
+ });
+ const { allSkills, selectedSkills, desiredSkillNames } = await resolveSelectedRuntimeSkills(input.config);
+ const skillSetKey = await buildSkillSetKey({ skills: selectedSkills, label: "codex" });
+ const skillsHome = path.join(effectiveCodexHome, "skills");
+ await fs.mkdir(skillsHome, { recursive: true });
+ await reconcileManagedCodexSkills({
+ skillsHome,
+ allSkills,
+ selectedSkills,
+ onLog: input.onLog,
+ });
+
+ for (const entry of selectedSkills) {
+ const target = path.join(skillsHome, entry.runtimeName);
+ try {
+ const result = await materializePaperclipSkillCopy(entry.source, target);
+ if (result.skippedSymlinks.length > 0) {
+ await input.onLog(
+ "stdout",
+ `[paperclip] Materialized ACPX Codex skill "${entry.runtimeName}" into ${skillsHome} and skipped ${result.skippedSymlinks.length} symlink(s).\n`,
+ );
+ }
+ } catch (err) {
+ await input.onLog(
+ "stderr",
+ `[paperclip] Failed to inject ACPX Codex skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
+ );
+ }
+ }
+ await writeManagedCodexSkillsManifest(skillsHome, selectedSkills.map((entry) => entry.runtimeName));
+
+ input.env.CODEX_HOME = effectiveCodexHome;
+
+ return {
+ identity: {
+ mode: "codex",
+ skillSetKey,
+ desiredSkillNames,
+ selectedSkills: selectedSkills.map((entry) => entry.runtimeName).sort(),
+ codexHome: effectiveCodexHome,
+ skillsHome,
+ },
+ commandNotes: [`Prepared ACPX Codex skill home at ${skillsHome}.`],
+ };
+}
+
+function normalizeMode(config: Record<string, unknown>): "persistent" | "oneshot" {
+ return asString(config.mode, DEFAULT_ACPX_LOCAL_MODE) === "oneshot" ? "oneshot" : "persistent";
+}
+
+function normalizePermissionMode(config: Record<string, unknown>): "approve-all" | "approve-reads" | "deny-all" {
+ const value = asString(config.permissionMode, DEFAULT_ACPX_LOCAL_PERMISSION_MODE).trim();
+ if (value === "approve-reads" || value === "deny-all") return value;
+ if (value === "default") return "approve-reads";
+ return "approve-all";
+}
+
+function normalizeNonInteractivePermissions(config: Record<string, unknown>): "deny" | "fail" {
+ return asString(config.nonInteractivePermissions, DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS) === "fail"
+ ? "fail"
+ : "deny";
+}
+
+function isCompatibleSession(
+ params: Record<string, unknown>,
+ runtime: Pick<AcpxPreparedRuntime, "fingerprint" | "sessionKey" | "cwd" | "mode" | "acpxAgent" | "remoteExecutionIdentity">,
+): boolean {
+ if (asString(params.configFingerprint, "") !== runtime.fingerprint) return false;
+ if (asString(params.sessionKey, "") !== runtime.sessionKey) return false;
+ if (asString(params.agent, "") !== runtime.acpxAgent) return false;
+ if (asString(params.mode, "") !== runtime.mode) return false;
+ const savedCwd = asString(params.cwd, "");
+ if (!savedCwd || path.resolve(savedCwd) !== path.resolve(runtime.cwd)) return false;
+ const savedRemote = parseObject(params.remoteExecution);
+ return stableJson(savedRemote) === stableJson(runtime.remoteExecutionIdentity ?? {});
+}
+
+function buildSessionParams(input: {
+ prepared: AcpxPreparedRuntime;
+ handle: AcpRuntimeHandle;
+}): Record<string, unknown> {
+ const { prepared, handle } = input;
+ return {
+ sessionKey: prepared.sessionKey,
+ runtimeSessionName: handle.runtimeSessionName,
+ acpxRecordId: handle.acpxRecordId,
+ acpSessionId: handle.backendSessionId,
+ agentSessionId: handle.agentSessionId,
+ agent: prepared.acpxAgent,
+ cwd: prepared.cwd,
+ mode: prepared.mode,
+ stateDir: prepared.stateDir,
+ configFingerprint: prepared.fingerprint,
+ skills: prepared.skillsIdentity,
+ ...(prepared.workspaceId ? { workspaceId: prepared.workspaceId } : {}),
+ ...(prepared.workspaceRepoUrl ? { repoUrl: prepared.workspaceRepoUrl } : {}),
+ ...(prepared.workspaceRepoRef ? { repoRef: prepared.workspaceRepoRef } : {}),
+ ...(prepared.remoteExecutionIdentity ? { remoteExecution: prepared.remoteExecutionIdentity } : {}),
+ };
+}
+
+async function writeAgentWrapper(input: {
+ stateDir: string;
+ acpxAgent: string;
+ agentCommandShell: string;
+ env: Record<string, string>;
+}): Promise<{ wrapperPath: string; envFilePath: string }> {
+ const wrappersDir = path.join(input.stateDir, "wrappers");
+ await fs.mkdir(wrappersDir, { recursive: true });
+ const envLines = Object.entries(input.env)
+ .filter(([key]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+ .sort(([left], [right]) => left.localeCompare(right))
+ .map(([key, value]) => `${key}=${shellQuote(value)}`);
+ const wrapperHash = shortHash({
+ agent: input.acpxAgent,
+ command: input.agentCommandShell,
+ env: envLines,
+ });
+ const wrapperPath = path.join(wrappersDir, `${input.acpxAgent}-${wrapperHash}.sh`);
+ const envFilePath = path.join(wrappersDir, `${input.acpxAgent}-${wrapperHash}.env`);
+ const script = [
+ "#!/usr/bin/env bash",
+ "set -euo pipefail",
+ `env_file=${shellQuote(envFilePath)}`,
+ "if [[ -f \"$env_file\" ]]; then",
+ " set -a",
+ " source \"$env_file\"",
+ " set +a",
+ "fi",
+ `exec ${input.agentCommandShell} "$@"`,
+ "",
+ ].join("\n");
+ await writeFileAtomically({
+ target: envFilePath,
+ contents: `${envLines.join("\n")}\n`,
+ mode: 0o600,
+ });
+ await writeFileAtomically({
+ target: wrapperPath,
+ contents: script,
+ mode: 0o700,
+ });
+ await cleanupStaleAgentWrappers({
+ wrappersDir,
+ currentFileNames: new Set([path.basename(wrapperPath), path.basename(envFilePath)]),
+ });
+ return { wrapperPath, envFilePath };
+}
+
+async function cleanupStaleAgentWrappers(input: { wrappersDir: string; currentFileNames: Set<string> }) {
+ const wrappers = await fs.readdir(input.wrappersDir).catch(() => []);
+ const now = Date.now();
+ await Promise.all(
+ wrappers.map(async (name) => {
+ const isManagedWrapperFile = name.endsWith(".sh") || name.endsWith(".env");
+ if (!isManagedWrapperFile || input.currentFileNames.has(name)) return;
+ const wrapperPath = path.join(input.wrappersDir, name);
+ const stats = await fs.stat(wrapperPath).catch(() => null);
+ if (!stats || now - stats.mtimeMs < WRAPPER_CLEANUP_RETENTION_MS) return;
+ await fs.rm(wrapperPath, { force: true });
+ }),
+ );
+}
+
+async function buildRuntime(input: {
+ ctx: AdapterExecutionContext;
+}): Promise<AcpxPreparedRuntime> {
+ const { runId, agent, config, context, authToken } = input.ctx;
+ const workspaceContext = parseObject(context.paperclipWorkspace);
+ const workspaceCwd = asString(workspaceContext.cwd, "");
+ const workspaceSource = asString(workspaceContext.source, "");
+ const workspaceStrategy = asString(workspaceContext.strategy, "");
+ const workspaceId = asString(workspaceContext.workspaceId, "");
+ const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
+ const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+ const workspaceBranch = asString(workspaceContext.branchName, "");
+ const workspaceWorktreePath = asString(workspaceContext.worktreePath, "");
+ const agentHome = asString(workspaceContext.agentHome, "");
+ const configuredCwd = asString(config.cwd, "");
+ const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
+ const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
+ const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
+ await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+
+ const acpxAgent = normalizeAgent(config);
+ const mode = normalizeMode(config);
+ const permissionMode = normalizePermissionMode(config);
+ const nonInteractivePermissions = normalizeNonInteractivePermissions(config);
+ const timeoutSec = asNumber(config.timeoutSec, DEFAULT_ACPX_LOCAL_TIMEOUT_SEC);
+ const stateDir = path.resolve(asString(config.stateDir, "") || defaultStateDir(agent.companyId, agent.id));
+ await fs.mkdir(stateDir, { recursive: true });
+
+ const envConfig = parseObject(config.env);
+ const hasExplicitApiKey =
+ typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;
+ const env: Record<string, string> = { ...buildPaperclipEnv(agent), PAPERCLIP_RUN_ID: runId };
+ const wakeTaskId =
+ (typeof context.taskId === "string" && context.taskId.trim()) ||
+ (typeof context.issueId === "string" && context.issueId.trim()) ||
+ "";
+ const wakeReason = typeof context.wakeReason === "string" ? context.wakeReason.trim() : "";
+ const wakeCommentId =
+ (typeof context.wakeCommentId === "string" && context.wakeCommentId.trim()) ||
+ (typeof context.commentId === "string" && context.commentId.trim()) ||
+ "";
+ const approvalId = typeof context.approvalId === "string" ? context.approvalId.trim() : "";
+ const approvalStatus = typeof context.approvalStatus === "string" ? context.approvalStatus.trim() : "";
+ const linkedIssueIds = Array.isArray(context.issueIds)
+ ? context.issueIds.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+ : [];
+ const wakePayloadJson = stringifyPaperclipWakePayload(context.paperclipWake);
+ if (wakeTaskId) env.PAPERCLIP_TASK_ID = wakeTaskId;
+ if (wakeReason) env.PAPERCLIP_WAKE_REASON = wakeReason;
+ if (wakeCommentId) env.PAPERCLIP_WAKE_COMMENT_ID = wakeCommentId;
+ if (approvalId) env.PAPERCLIP_APPROVAL_ID = approvalId;
+ if (approvalStatus) env.PAPERCLIP_APPROVAL_STATUS = approvalStatus;
+ if (linkedIssueIds.length > 0) env.PAPERCLIP_LINKED_ISSUE_IDS = linkedIssueIds.join(",");
+ if (wakePayloadJson) env.PAPERCLIP_WAKE_PAYLOAD_JSON = wakePayloadJson;
+ applyPaperclipWorkspaceEnv(env, {
+ workspaceCwd: effectiveWorkspaceCwd,
+ workspaceSource,
+ workspaceStrategy,
+ workspaceId,
+ workspaceRepoUrl,
+ workspaceRepoRef,
+ workspaceBranch,
+ workspaceWorktreePath,
+ agentHome,
+ });
+ for (const [key, value] of Object.entries(envConfig)) {
+ if (typeof value === "string") env[key] = value;
+ }
+ if (!hasExplicitApiKey && authToken) env.PAPERCLIP_API_KEY = authToken;
+
+ let skillPromptInstructions = "";
+ let skillsIdentity: Record<string, unknown> = { mode: "unsupported" };
+ const skillCommandNotes: string[] = [];
+ if (acpxAgent === "claude") {
+ const preparedSkills = await prepareClaudeSkillRuntime({
+ stateDir,
+ config,
+ onLog: input.ctx.onLog,
+ });
+ skillPromptInstructions = preparedSkills.promptInstructions;
+ skillsIdentity = preparedSkills.identity;
+ skillCommandNotes.push(...preparedSkills.commandNotes);
+ } else if (acpxAgent === "codex") {
+ const preparedSkills = await prepareCodexSkillRuntime({
+ companyId: agent.companyId,
+ config,
+ env,
+ onLog: input.ctx.onLog,
+ });
+ skillsIdentity = preparedSkills.identity;
+ skillCommandNotes.push(...preparedSkills.commandNotes);
+ } else {
+ const desired = resolvePaperclipDesiredSkillNames(config, await readPaperclipRuntimeSkillEntries(config, __moduleDir));
+ skillsIdentity = { mode: "custom_unsupported", desiredSkillNames: desired };
+ if (desired.length > 0) {
+ skillCommandNotes.push("Selected Paperclip skills are tracked only; ACPX custom commands do not expose a runtime skill contract yet.");
+ }
+ }
+
+ const configuredCommand = asString(config.agentCommand, "").trim();
+ const builtInCommand = resolveBuiltInAgentCommand(acpxAgent);
+ const agentCommand = configuredCommand || builtInCommand || null;
+ const agentCommandShell = configuredCommand || (builtInCommand ? shellQuote(builtInCommand) : "");
+ const wrapper = agentCommand
+ ? await writeAgentWrapper({
+ stateDir,
+ acpxAgent,
+ agentCommandShell,
+ env,
+ })
+ : null;
+ const wrapperPath = wrapper?.wrapperPath ?? null;
+ const overrides = wrapperPath ? { [acpxAgent]: wrapperPath } : undefined;
+ const agentRegistry = createAgentRegistry({ overrides });
+ const executionTarget = readAdapterExecutionTarget({
+ executionTarget: input.ctx.executionTarget,
+ legacyRemoteExecution: input.ctx.executionTransport?.remoteExecution,
+ });
+ const remoteExecutionIdentity = adapterExecutionTargetSessionIdentity(executionTarget);
+ const fingerprint = shortHash({
+ acpxAgent,
+ agentCommand: agentCommand ?? acpxAgent,
+ cwd: path.resolve(cwd),
+ mode,
+ permissionMode,
+ nonInteractivePermissions,
+ remoteExecutionIdentity,
+ skillsIdentity,
+ skillPromptInstructions,
+ });
+ const taskKey = asString(input.ctx.runtime.taskKey, "") || wakeTaskId || workspaceId || "default";
+ const sessionKey = `paperclip:${agent.companyId}:${agent.id}:${taskKey}:${fingerprint}`;
+ const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
+ const loggedEnv = buildInvocationEnvForLogs(env, {
+ runtimeEnv,
+ includeRuntimeKeys: ["HOME"],
+ resolvedCommand: wrapperPath ?? agentCommand ?? acpxAgent,
+ });
+
+ return {
+ acpxAgent,
+ mode,
+ cwd,
+ workspaceId,
+ workspaceRepoUrl,
+ workspaceRepoRef,
+ env,
+ loggedEnv,
+ stateDir,
+ permissionMode,
+ nonInteractivePermissions,
+ timeoutSec,
+ sessionKey,
+ fingerprint,
+ agentCommand,
+ agentRegistry,
+ remoteExecutionIdentity,
+ skillPromptInstructions,
+ skillsIdentity: {
+ ...skillsIdentity,
+ commandNotes: skillCommandNotes,
+ },
+ };
+}
+
+async function buildPrompt(ctx: AdapterExecutionContext, resumedSession: boolean): Promise<{
+ prompt: string;
+ promptMetrics: Record<string, number>;
+ commandNotes: string[];
+}> {
+ const { agent, runId, config, context, onLog } = ctx;
+ const promptTemplate = asString(config.promptTemplate, DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE);
+ const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
+ const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
+ let instructionsPrefix = "";
+ const commandNotes: string[] = [];
+ if (instructionsFilePath) {
+ try {
+ const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
+ instructionsPrefix =
+ `${instructionsContents}\n\n` +
+ `The above agent instructions were loaded from ${instructionsFilePath}. ` +
+ `Resolve any relative file references from ${instructionsDir}.\n\n`;
+ commandNotes.push(
+ `Loaded agent instructions from ${instructionsFilePath}`,
+ `Prepended instructions + path directive to the ACPX prompt (relative references from ${instructionsDir}).`,
+ );
+ } catch (err) {
+ const reason = err instanceof Error ? err.message : String(err);
+ await onLog(
+ "stderr",
+ `[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
+ );
+ commandNotes.push(`Configured instructionsFilePath ${instructionsFilePath}, but file could not be read.`);
+ }
+ }
+
+ const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+ const templateData = {
+ agentId: agent.id,
+ companyId: agent.companyId,
+ runId,
+ company: { id: agent.companyId },
+ agent,
+ run: { id: runId, source: "on_demand" },
+ context,
+ };
+ const renderedBootstrapPrompt =
+ !resumedSession && bootstrapPromptTemplate.trim().length > 0
+ ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+ : "";
+ const wakePrompt = renderPaperclipWakePrompt(context.paperclipWake, { resumedSession });
+ const shouldUseResumeDeltaPrompt = resumedSession && wakePrompt.length > 0;
+ const promptInstructionsPrefix = shouldUseResumeDeltaPrompt ? "" : instructionsPrefix;
+ const renderedPrompt = shouldUseResumeDeltaPrompt ? "" : renderTemplate(promptTemplate, templateData);
+ const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+ const taskContextNote = asString(context.paperclipTaskMarkdown, "").trim();
+ const prompt = joinPromptSections([
+ promptInstructionsPrefix,
+ renderedBootstrapPrompt,
+ wakePrompt,
+ sessionHandoffNote,
+ taskContextNote,
+ renderedPrompt,
+ ]);
+
+ return {
+ prompt,
+ commandNotes,
+ promptMetrics: {
+ promptChars: prompt.length,
+ instructionsChars: promptInstructionsPrefix.length,
+ bootstrapPromptChars: renderedBootstrapPrompt.length,
+ wakePromptChars: wakePrompt.length,
+ sessionHandoffChars: sessionHandoffNote.length,
+ taskContextChars: taskContextNote.length,
+ heartbeatPromptChars: renderedPrompt.length,
+ },
+ };
+}
+
+async function emitAcpxLog(ctx: AdapterExecutionContext, payload: Record<string, unknown>) {
+ await ctx.onLog("stdout", `${JSON.stringify(payload)}\n`);
+}
+
+async function emitRuntimeEvent(ctx: AdapterExecutionContext, event: AcpRuntimeEvent) {
+ if (event.type === "text_delta") {
+ await emitAcpxLog(ctx, {
+ type: "acpx.text_delta",
+ text: event.text,
+ channel: event.stream === "thought" ? "thought" : "output",
+ tag: event.tag,
+ });
+ return;
+ }
+ if (event.type === "tool_call") {
+ await emitAcpxLog(ctx, {
+ type: "acpx.tool_call",
+ name: event.title ?? "acp_tool",
+ toolCallId: event.toolCallId,
+ status: event.status,
+ text: event.text,
+ tag: event.tag,
+ });
+ return;
+ }
+ if (event.type === "status") {
+ await emitAcpxLog(ctx, {
+ type: "acpx.status",
+ text: event.text,
+ tag: event.tag,
+ used: event.used,
+ size: event.size,
+ });
+ return;
+ }
+ if (event.type === "done") {
+ await emitAcpxLog(ctx, {
+ type: "acpx.result",
+ summary: event.stopReason ?? "completed",
+ stopReason: event.stopReason,
+ });
+ return;
+ }
+ if (event.type === "error") {
+ await emitAcpxLog(ctx, {
+ type: "acpx.error",
+ message: event.message,
+ code: event.code,
+ retryable: event.retryable,
+ });
+ }
+}
+
+function resultErrorMessage(result: AcpRuntimeTurnResult): string | null {
+ if (result.status !== "failed") return null;
+ return result.error.message;
+}
+
+function classifyError(err: unknown): Pick<AdapterExecutionResult, "errorCode" | "errorMeta"> {
+ const message = err instanceof Error ? err.message : String(err);
+ const maybeCode =
+ err && typeof err === "object" && typeof (err as { code?: unknown }).code === "string"
+ ? (err as { code: string }).code
+ : null;
+ const acpCode = isAcpRuntimeError(err) || (maybeCode?.startsWith("ACP_") ?? false) ? maybeCode : null;
+ const lower = message.toLowerCase();
+ const authLike = lower.includes("auth") || lower.includes("login") || lower.includes("credential");
+ if (authLike) {
+ return {
+ errorCode: "acpx_auth_required",
+ errorMeta: { category: "auth", ...(acpCode ? { acpCode } : {}) },
+ };
+ }
+ if (acpCode) {
+ return {
+ errorCode: "acpx_protocol_error",
+ errorMeta: { category: "protocol", acpCode },
+ };
+ }
+ return {
+ errorCode: "acpx_runtime_error",
+ errorMeta: { category: "runtime" },
+ };
+}
+
+function isResumeFailure(err: unknown): boolean {
+ const message = err instanceof Error ? err.message : String(err);
+ return /resume|load|not found|no session|unknown session|conversation/i.test(message);
+}
+
+async function cleanupIdleHandles(input: {
+ handles: Map<string, RuntimeCacheEntry>;
+ now: number;
+ idleMs: number;
+}) {
+ const stale: Array<[string, RuntimeCacheEntry]> = [];
+ for (const entry of input.handles.entries()) {
+ if (input.now - entry[1].lastUsedAt >= input.idleMs) stale.push(entry);
+ }
+ for (const [key, entry] of stale) {
+ input.handles.delete(key);
+ await entry.runtime.close({
+ handle: entry.handle,
+ reason: "paperclip idle cleanup",
+ discardPersistentState: false,
+ }).catch(() => {});
+ }
+}
+
+function warmHandleMatches(
+ entry: RuntimeCacheEntry | undefined,
+ runtime: AcpRuntime,
+ handle: AcpRuntimeHandle,
+): boolean {
+ return entry?.runtime === runtime && entry.handle === handle;
+}
+
+export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
+ const createRuntime = deps.createRuntime ?? createAcpRuntime;
+ const now = deps.now ?? (() => Date.now());
+ const warmHandles = deps.warmHandles ?? defaultWarmHandles;
+
+ return async function executeAcpxLocal(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
+ const prepared = await buildRuntime({ ctx });
+ const warmIdleMs = asNumber(ctx.config.warmHandleIdleMs, DEFAULT_WARM_HANDLE_IDLE_MS);
+ await cleanupIdleHandles({ handles: warmHandles, now: now(), idleMs: warmIdleMs });
+
+ const previousParams = parseObject(ctx.runtime.sessionParams);
+ const canResume = isCompatibleSession(previousParams, prepared);
+ const resumeSessionId = canResume ? asString(previousParams.acpSessionId, "") || undefined : undefined;
+ const cached = canResume ? warmHandles.get(prepared.sessionKey) : undefined;
+ const runtimeOptions: AcpRuntimeOptions = {
+ cwd: prepared.cwd,
+ sessionStore: createRuntimeStore({ stateDir: prepared.stateDir }),
+ agentRegistry: prepared.agentRegistry,
+ permissionMode: prepared.permissionMode,
+ nonInteractivePermissions: prepared.nonInteractivePermissions,
+ timeoutMs: prepared.timeoutSec > 0 ? prepared.timeoutSec * 1000 : undefined,
+ };
+ const runtime = cached?.runtime ?? createRuntime(runtimeOptions);
+ if (!canResume && asString(previousParams.runtimeSessionName, "")) {
+ await ctx.onLog(
+ "stdout",
+ `[paperclip] ACPX session "${asString(previousParams.runtimeSessionName, "")}" does not match the current agent/cwd/mode/runtime identity; starting fresh in "${prepared.cwd}".\n`,
+ );
+ }
+
+ let handle = cached?.handle ?? null;
+ let resumedSession = Boolean(handle ?? resumeSessionId);
+ let clearSession = false;
+
+ try {
+ if (!handle) {
+ try {
+ handle = await runtime.ensureSession({
+ sessionKey: prepared.sessionKey,
+ agent: prepared.acpxAgent,
+ mode: prepared.mode,
+ cwd: prepared.cwd,
+ resumeSessionId,
+ });
+ } catch (err) {
+ if (!resumeSessionId || !isResumeFailure(err)) throw err;
+ clearSession = true;
+ resumedSession = false;
+ await ctx.onLog(
+ "stdout",
+ `[paperclip] ACPX resume session "${resumeSessionId}" is unavailable; retrying with a fresh session.\n`,
+ );
+ handle = await runtime.ensureSession({
+ sessionKey: prepared.sessionKey,
+ agent: prepared.acpxAgent,
+ mode: prepared.mode,
+ cwd: prepared.cwd,
+ });
+ }
+ }
+ } catch (err) {
+ const classified = classifyError(err);
+ const message = err instanceof Error ? err.message : String(err);
+ await emitAcpxLog(ctx, { type: "acpx.error", message, ...classified.errorMeta });
+ return {
+ exitCode: 1,
+ signal: null,
+ timedOut: false,
+ errorMessage: message,
+ ...classified,
+ provider: "acpx",
+ model: null,
+ clearSession,
+ resultJson: { phase: "ensure_session" },
+ summary: message,
+ };
+ }
+
+ if (!handle) {
+ return {
+ exitCode: 1,
+ signal: null,
+ timedOut: false,
+ errorMessage: "ACPX did not return a runtime session handle.",
+ errorCode: "acpx_runtime_error",
+ provider: "acpx",
+ model: null,
+ resultJson: { phase: "ensure_session" },
+ summary: "ACPX did not return a runtime session handle.",
+ };
+ }
+ const sessionHandle = handle;
+ const { prompt, promptMetrics, commandNotes } = await buildPrompt(ctx, resumedSession);
+ const runPrompt = joinPromptSections([prepared.skillPromptInstructions, prompt]);
+ await emitAcpxLog(ctx, {
+ type: "acpx.session",
+ agent: prepared.acpxAgent,
+ sessionId: sessionHandle.backendSessionId,
+ acpSessionId: sessionHandle.backendSessionId,
+ agentSessionId: sessionHandle.agentSessionId,
+ runtimeSessionName: sessionHandle.runtimeSessionName,
+ mode: prepared.mode,
+ permissionMode: prepared.permissionMode,
+ });
+ if (ctx.onMeta) {
+ await ctx.onMeta({
+ adapterType: "acpx_local",
+ command: prepared.agentCommand ?? prepared.acpxAgent,
+ cwd: prepared.cwd,
+ commandNotes: [
+ `ACPX runtime embedded in Paperclip with ${prepared.mode} session mode.`,
+ `Effective ACPX permission mode: ${prepared.permissionMode}.`,
+ ...(Array.isArray(prepared.skillsIdentity.commandNotes)
+ ? prepared.skillsIdentity.commandNotes.filter((note): note is string => typeof note === "string")
+ : []),
+ ...commandNotes,
+ ],
+ env: prepared.loggedEnv,
+ prompt: runPrompt,
+ promptMetrics,
+ context: ctx.context,
+ });
+ }
+
+ let cancelActiveTurn: ((reason: string) => Promise<void>) | null = null;
+ let controller: AbortController | null = null;
+ let timeout: NodeJS.Timeout | null = null;
+ let timedOut = false;
+ const textParts: string[] = [];
+ try {
+ const timeoutMs = prepared.timeoutSec > 0 ? prepared.timeoutSec * 1000 : undefined;
+ controller = new AbortController();
+ if (timeoutMs) {
+ timeout = setTimeout(() => {
+ timedOut = true;
+ controller?.abort();
+ void cancelActiveTurn?.(`Timed out after ${prepared.timeoutSec}s`).catch(() => {});
+ }, timeoutMs);
+ }
+ const turn = runtime.startTurn({
+ handle: sessionHandle,
+ text: runPrompt,
+ mode: "prompt",
+ requestId: ctx.runId,
+ timeoutMs,
+ signal: controller?.signal,
+ });
+ cancelActiveTurn = async (reason: string) => {
+ await turn.cancel({ reason });
+ };
+ for await (const event of turn.events) {
+ if (event.type === "text_delta") textParts.push(event.text);
+ await emitRuntimeEvent(ctx, event);
+ }
+ const terminal = await turn.result;
+ if (timeout) clearTimeout(timeout);
+ if (terminal.status === "failed" || terminal.status === "cancelled" || timedOut) {
+ if (warmHandleMatches(warmHandles.get(prepared.sessionKey), runtime, sessionHandle)) {
+ warmHandles.delete(prepared.sessionKey);
+ }
+ await runtime.close({
+ handle: sessionHandle,
+ reason: timedOut ? "paperclip timeout cleanup" : `paperclip turn ${terminal.status}`,
+ discardPersistentState: terminal.status === "cancelled" || timedOut,
+ }).catch(() => {});
+ } else if (prepared.mode === "persistent") {
+ const existing = warmHandles.get(prepared.sessionKey);
+ if (existing && !warmHandleMatches(existing, runtime, sessionHandle)) {
+ await runtime.close({
+ handle: sessionHandle,
+ reason: "paperclip duplicate warm handle cleanup",
+ discardPersistentState: false,
+ }).catch(() => {});
+ } else {
+ warmHandles.set(prepared.sessionKey, {
+ runtime,
+ handle: sessionHandle,
+ fingerprint: prepared.fingerprint,
+ lastUsedAt: now(),
+ });
+ }
+ }
+
+ const errorMessage = timedOut
+ ? `Timed out after ${prepared.timeoutSec}s`
+ : resultErrorMessage(terminal);
+ const terminalStopReason = terminal.status === "failed" ? terminal.error.message : terminal.stopReason;
+ await emitAcpxLog(ctx, {
+ type: terminal.status === "completed" ? "acpx.result" : "acpx.error",
+ summary: terminal.status,
+ stopReason: terminalStopReason,
+ message: errorMessage,
+ });
+ return {
+ exitCode: terminal.status === "completed" ? 0 : 1,
+ signal: timedOut ? "SIGTERM" : null,
+ timedOut,
+ errorMessage,
+ errorCode: terminal.status === "failed" ? "acpx_turn_failed" : timedOut ? "acpx_timeout" : null,
+ sessionId: sessionHandle.backendSessionId ?? sessionHandle.runtimeSessionName,
+ sessionParams: buildSessionParams({ prepared, handle: sessionHandle }),
+ sessionDisplayId: sessionHandle.agentSessionId ?? sessionHandle.backendSessionId ?? sessionHandle.runtimeSessionName,
+ provider: "acpx",
+ model: null,
+ billingType: "unknown",
+ costUsd: null,
+ resultJson: {
+ status: terminal.status,
+ stopReason: terminalStopReason,
+ permissionMode: prepared.permissionMode,
+ mode: prepared.mode,
+ },
+ summary: textParts.join("").trim() || terminalStopReason || terminal.status,
+ clearSession,
+ };
+ } catch (err) {
+ if (timeout) clearTimeout(timeout);
+ const classified = classifyError(err);
+ const message = timedOut ? `Timed out after ${prepared.timeoutSec}s` : err instanceof Error ? err.message : String(err);
+ const cancel = cancelActiveTurn as ((reason: string) => Promise<void>) | null;
+ if (cancel) await cancel(message).catch(() => {});
+ await runtime.close({
+ handle: sessionHandle,
+ reason: timedOut ? "paperclip timeout cleanup" : "paperclip error cleanup",
+ discardPersistentState: timedOut,
+ }).catch(() => {});
+ if (warmHandleMatches(warmHandles.get(prepared.sessionKey), runtime, sessionHandle)) {
+ warmHandles.delete(prepared.sessionKey);
+ }
+ await emitAcpxLog(ctx, { type: "acpx.error", message, ...classified.errorMeta });
+ return {
+ exitCode: 1,
+ signal: timedOut ? "SIGTERM" : null,
+ timedOut,
+ errorMessage: message,
+ errorCode: timedOut ? "acpx_timeout" : classified.errorCode,
+ errorMeta: classified.errorMeta,
+ provider: "acpx",
+ model: null,
+ clearSession: clearSession || timedOut,
+ resultJson: { phase: "turn" },
+ summary: message,
+ };
+ }
+ };
+}
+
+export const execute = createAcpxLocalExecutor();
diff --git a/packages/adapters/acpx-local/src/server/index.ts b/packages/adapters/acpx-local/src/server/index.ts
new file mode 100644
index 0000000000..7463c9526a
--- /dev/null
+++ b/packages/adapters/acpx-local/src/server/index.ts
@@ -0,0 +1,5 @@
+export { execute, createAcpxLocalExecutor } from "./execute.js";
+export { testEnvironment } from "./test.js";
+export { getConfigSchema } from "./config-schema.js";
+export { sessionCodec } from "./session-codec.js";
+export { listAcpxSkills, syncAcpxSkills } from "./skills.js";
diff --git a/packages/adapters/acpx-local/src/server/session-codec.ts b/packages/adapters/acpx-local/src/server/session-codec.ts
new file mode 100644
index 0000000000..2045adcd1b
--- /dev/null
+++ b/packages/adapters/acpx-local/src/server/session-codec.ts
@@ -0,0 +1,50 @@
+import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
+
+function readString(value: unknown): string | null {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+ return typeof value === "object" && value !== null && !Array.isArray(value) ? { ...(value as Record<string, unknown>) } : null;
+}
+
+export const sessionCodec: AdapterSessionCodec = {
+ deserialize(raw: unknown) {
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+ const record = raw as Record<string, unknown>;
+ const runtimeSessionName = readString(record.runtimeSessionName);
+ const acpSessionId = readString(record.acpSessionId);
+ const agentSessionId = readString(record.agentSessionId);
+ const remoteExecution = readRecord(record.remoteExecution);
+ if (!runtimeSessionName && !acpSessionId && !agentSessionId) return null;
+
+ return {
+ ...(runtimeSessionName ? { runtimeSessionName } : {}),
+ ...(readString(record.sessionKey) ? { sessionKey: readString(record.sessionKey) } : {}),
+ ...(readString(record.acpxRecordId) ? { acpxRecordId: readString(record.acpxRecordId) } : {}),
+ ...(acpSessionId ? { acpSessionId } : {}),
+ ...(agentSessionId ? { agentSessionId } : {}),
+ ...(readString(record.agent) ? { agent: readString(record.agent) } : {}),
+ ...(readString(record.cwd) ? { cwd: readString(record.cwd) } : {}),
+ ...(readString(record.mode) ? { mode: readString(record.mode) } : {}),
+ ...(readString(record.stateDir) ? { stateDir: readString(record.stateDir) } : {}),
+ ...(readString(record.configFingerprint) ? { configFingerprint: readString(record.configFingerprint) } : {}),
+ ...(readString(record.workspaceId) ? { workspaceId: readString(record.workspaceId) } : {}),
+ ...(readString(record.repoUrl) ? { repoUrl: readString(record.repoUrl) } : {}),
+ ...(readString(record.repoRef) ? { repoRef: readString(record.repoRef) } : {}),
+ ...(remoteExecution ? { remoteExecution } : {}),
+ };
+ },
+ serialize(params: Record<string, unknown> | null) {
+ if (!params) return null;
+ return this.deserialize(params);
+ },
+ getDisplayId(params: Record<string, unknown> | null) {
+ if (!params) return null;
+ return (
+ readString(params.runtimeSessionName) ??
+ readString(params.acpSessionId) ??
+ readString(params.agentSessionId)
+ );
+ },
+};
diff --git a/packages/adapters/acpx-local/src/server/skills.ts b/packages/adapters/acpx-local/src/server/skills.ts
new file mode 100644
index 0000000000..16065b3623
--- /dev/null
+++ b/packages/adapters/acpx-local/src/server/skills.ts
@@ -0,0 +1,106 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+ AdapterSkillContext,
+ AdapterSkillEntry,
+ AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
+} from "@paperclipai/adapter-utils/server-utils";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+type AcpxSkillAgent = "claude" | "codex" | "custom";
+
+function normalizeAcpxSkillAgent(config: Record<string, unknown>): AcpxSkillAgent {
+ const configured = typeof config.agent === "string" ? config.agent.trim() : "";
+ if (configured === "codex" || configured === "custom") return configured;
+ if (configured === "claude" || configured === "") return "claude";
+ return "claude";
+}
+
+function configuredDetail(agent: AcpxSkillAgent): string {
+ if (agent === "codex") {
+ return "Will be linked into the effective CODEX_HOME/skills/ directory for the next ACPX Codex session.";
+ }
+ return "Will be mounted into the next ACPX Claude session.";
+}
+
+function unsupportedDetail(): string {
+ return "Desired state is stored in Paperclip only; custom ACP commands need an explicit skill integration contract before runtime sync is available.";
+}
+
+async function buildAcpxSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
+ const acpxAgent = normalizeAcpxSkillAgent(config);
+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+ const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
+ const desiredSet = new Set(desiredSkills);
+ const supported = acpxAgent !== "custom";
+ const warnings: string[] = supported
+ ? []
+ : [
+ "Custom ACP commands do not expose a Paperclip skill integration contract yet; selected skills are tracked only.",
+ ];
+
+ const entries: AdapterSkillEntry[] = availableEntries.map((entry) => {
+ const desired = desiredSet.has(entry.key);
+ return {
+ key: entry.key,
+ runtimeName: entry.runtimeName,
+ desired,
+ managed: true,
+ state: desired ? "configured" : "available",
+ origin: entry.required ? "paperclip_required" : "company_managed",
+ originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
+ readOnly: false,
+ sourcePath: entry.source,
+ targetPath: null,
+ detail: desired ? (supported ? configuredDetail(acpxAgent) : unsupportedDetail()) : null,
+ required: Boolean(entry.required),
+ requiredReason: entry.requiredReason ?? null,
+ };
+ });
+
+ for (const desiredSkill of desiredSkills) {
+ if (availableByKey.has(desiredSkill)) continue;
+ warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+ entries.push({
+ key: desiredSkill,
+ runtimeName: null,
+ desired: true,
+ managed: true,
+ state: "missing",
+ origin: "external_unknown",
+ originLabel: "External or unavailable",
+ readOnly: false,
+ sourcePath: null,
+ targetPath: null,
+ detail: "Paperclip cannot find this skill in the local runtime skills directory.",
+ });
+ }
+
+ entries.sort((left, right) => left.key.localeCompare(right.key));
+
+ return {
+ adapterType: "acpx_local",
+ supported,
+ mode: supported ? "ephemeral" : "unsupported",
+ desiredSkills,
+ entries,
+ warnings,
+ };
+}
+
+export async function listAcpxSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+ return buildAcpxSkillSnapshot(ctx.config);
+}
+
+export async function syncAcpxSkills(
+ ctx: AdapterSkillContext,
+ _desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+ return buildAcpxSkillSnapshot(ctx.config);
+}
diff --git a/packages/adapters/acpx-local/src/server/test.test.ts b/packages/adapters/acpx-local/src/server/test.test.ts
new file mode 100644
index 0000000000..f5744f5408
--- /dev/null
+++ b/packages/adapters/acpx-local/src/server/test.test.ts
@@ -0,0 +1,49 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { testEnvironment } from "./test.js";
+
+const originalNodeVersion = process.version;
+
+function setNodeVersion(version: string): void {
+ Object.defineProperty(process, "version", {
+ configurable: true,
+ enumerable: true,
+ value: version,
+ });
+}
+
+afterEach(() => {
+ setNodeVersion(originalNodeVersion);
+});
+
+describe("acpx_local environment diagnostics", () => {
+ it("does not force healthy default Claude diagnostics to warn", async () => {
+ setNodeVersion("v22.12.0");
+
+ const result = await testEnvironment({
+ adapterType: "acpx_local",
+ companyId: "test-company",
+ config: { agent: "claude" },
+ });
+
+ expect(result.status).toBe("pass");
+ expect(result.checks).toContainEqual(
+ expect.objectContaining({
+ code: "acpx_agent_selected",
+ level: "info",
+ message: "ACP agent selected: claude",
+ }),
+ );
+ expect(result.checks).toContainEqual(
+ expect.objectContaining({
+ code: "acpx_runtime_scaffold",
+ level: "info",
+ }),
+ );
+ expect(result.checks).not.toContainEqual(
+ expect.objectContaining({
+ code: "acpx_runtime_scaffold",
+ level: "warn",
+ }),
+ );
+ });
+});
diff --git a/packages/adapters/acpx-local/src/server/test.ts b/packages/adapters/acpx-local/src/server/test.ts
new file mode 100644
index 0000000000..f19304e8d6
--- /dev/null
+++ b/packages/adapters/acpx-local/src/server/test.ts
@@ -0,0 +1,295 @@
+import { createRequire } from "node:module";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type {
+ AdapterEnvironmentCheck,
+ AdapterEnvironmentTestContext,
+ AdapterEnvironmentTestResult,
+} from "@paperclipai/adapter-utils";
+import {
+ asString,
+ parseObject,
+} from "@paperclipai/adapter-utils/server-utils";
+
+const require = createRequire(import.meta.url);
+const MIN_NODE_MAJOR = 22;
+const MIN_NODE_MINOR = 12;
+const MIN_NODE_PATCH = 0;
+
+function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
+ if (checks.some((check) => check.level === "error")) return "fail";
+ if (checks.some((check) => check.level === "warn")) return "warn";
+ return "pass";
+}
+
+function nodeVersionMeetsMinimum(version: string): boolean {
+ const [major = 0, minor = 0, patch = 0] = version
+ .replace(/^v/, "")
+ .split(".")
+ .map((part) => Number.parseInt(part, 10));
+ if (major > MIN_NODE_MAJOR) return true;
+ if (major < MIN_NODE_MAJOR) return false;
+ if (minor > MIN_NODE_MINOR) return true;
+ if (minor < MIN_NODE_MINOR) return false;
+ return patch >= MIN_NODE_PATCH;
+}
+
+function isNonEmpty(value: unknown): value is string {
+ return typeof value === "string" && value.trim().length > 0;
+}
+
+function getStringEnv(configEnv: Record<string, string>, key: string): string | undefined {
+ const configured = configEnv[key];
+ if (typeof configured === "string") return configured;
+ return process.env[key];
+}
+
+function credentialSource(configEnv: Record<string, string>, key: string): string {
+ return typeof configEnv[key] === "string" ? "adapter config env" : "server environment";
+}
+
+async function readJsonObject(filePath: string): Promise<Record<string, unknown> | null> {
+ try {
+ const parsed = JSON.parse(await fs.readFile(filePath, "utf8")) as unknown;
+ return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+ ? parsed as Record<string, unknown>
+ : null;
+ } catch {
+ return null;
+ }
+}
+
+function readNestedString(record: Record<string, unknown>, pathSegments: string[]): string | null {
+ let current: unknown = record;
+ for (const segment of pathSegments) {
+ if (typeof current !== "object" || current === null || Array.isArray(current)) return null;
+ current = (current as Record<string, unknown>)[segment];
+ }
+ return isNonEmpty(current) ? current.trim() : null;
+}
+
+async function hasClaudeSubscriptionCredentials(configDir: string): Promise<boolean> {
+ for (const filename of [".credentials.json", "credentials.json"]) {
+ const credentials = await readJsonObject(path.join(configDir, filename));
+ if (!credentials) continue;
+ if (readNestedString(credentials, ["claudeAiOauth", "accessToken"])) return true;
+ }
+ return false;
+}
+
+async function hasCodexNativeCredentials(codexHome: string): Promise<boolean> {
+ const auth = await readJsonObject(path.join(codexHome, "auth.json"));
+ if (!auth) return false;
+ return Boolean(
+ readNestedString(auth, ["accessToken"]) ||
+ readNestedString(auth, ["tokens", "access_token"]) ||
+ readNestedString(auth, ["OPENAI_API_KEY"]),
+ );
+}
+
+async function buildCredentialHintChecks(
+ agent: string,
+ configEnv: Record<string, string>,
+): Promise<AdapterEnvironmentCheck[]> {
+ if (agent === "claude") {
+ const bedrockFlag = getStringEnv(configEnv, "CLAUDE_CODE_USE_BEDROCK");
+ const bedrockBaseUrl = getStringEnv(configEnv, "ANTHROPIC_BEDROCK_BASE_URL");
+ const hasBedrock =
+ bedrockFlag === "1" ||
+ /^true$/i.test(bedrockFlag ?? "") ||
+ isNonEmpty(bedrockBaseUrl);
+ const bedrockSourceKey = isNonEmpty(bedrockFlag)
+ ? "CLAUDE_CODE_USE_BEDROCK"
+ : "ANTHROPIC_BEDROCK_BASE_URL";
+ const anthropicApiKey = getStringEnv(configEnv, "ANTHROPIC_API_KEY");
+ const claudeConfigDir = isNonEmpty(getStringEnv(configEnv, "CLAUDE_CONFIG_DIR"))
+ ? path.resolve(getStringEnv(configEnv, "CLAUDE_CONFIG_DIR") as string)
+ : path.join(os.homedir(), ".claude");
+
+ if (hasBedrock) {
+ return [{
+ code: "acpx_claude_bedrock_auth_detected",
+ level: "info",
+ message: "Claude credential hint: Bedrock auth indicators are configured.",
+ detail: `Detected in ${credentialSource(configEnv, bedrockSourceKey)}.`,
+ hint: "Ensure AWS credentials and AWS_REGION are available to the ACPX-launched Claude agent.",
+ }];
+ }
+
+ if (isNonEmpty(anthropicApiKey)) {
+ return [{
+ code: "acpx_claude_anthropic_api_key_detected",
+ level: "info",
+ message: "Claude credential hint: ANTHROPIC_API_KEY is set.",
+ detail: `Detected in ${credentialSource(configEnv, "ANTHROPIC_API_KEY")}.`,
+ }];
+ }
+
+ if (await hasClaudeSubscriptionCredentials(claudeConfigDir)) {
+ return [{
+ code: "acpx_claude_subscription_auth_detected",
+ level: "info",
+ message: "Claude credential hint: local Claude subscription credentials were found.",
+ detail: `Credentials found in ${claudeConfigDir}.`,
+ }];
+ }
+
+ return [{
+ code: "acpx_claude_credentials_missing",
+ level: "info",
+ message: "Claude credential hint: no Claude API, Bedrock, or local subscription credentials were detected.",
+ hint: "Set ANTHROPIC_API_KEY, configure Bedrock, or run `claude login` before starting an ACPX Claude agent.",
+ }];
+ }
+
+ if (agent === "codex") {
+ const openAiApiKey = getStringEnv(configEnv, "OPENAI_API_KEY");
+ const codexHome = isNonEmpty(getStringEnv(configEnv, "CODEX_HOME"))
+ ? path.resolve(getStringEnv(configEnv, "CODEX_HOME") as string)
+ : path.join(os.homedir(), ".codex");
+
+ if (isNonEmpty(openAiApiKey)) {
+ return [{
+ code: "acpx_codex_openai_api_key_detected",
+ level: "info",
+ message: "Codex credential hint: OPENAI_API_KEY is set.",
+ detail: `Detected in ${credentialSource(configEnv, "OPENAI_API_KEY")}.`,
+ }];
+ }
+
+ if (await hasCodexNativeCredentials(codexHome)) {
+ return [{
+ code: "acpx_codex_native_auth_detected",
+ level: "info",
+ message: "Codex credential hint: local Codex auth configuration was found.",
+ detail: `Credentials found in ${path.join(codexHome, "auth.json")}.`,
+ }];
+ }
+
+ return [{
+ code: "acpx_codex_credentials_missing",
+ level: "info",
+ message: "Codex credential hint: no OpenAI API key or local Codex auth configuration was detected.",
+ hint: "Set OPENAI_API_KEY or run `codex login` before starting an ACPX Codex agent.",
+ }];
+ }
+
+ return [];
+}
+
+function resolvePackage(name: string): AdapterEnvironmentCheck {
+ try {
+ const resolved = require.resolve(`${name}/package.json`);
+ return {
+ code: `acpx_package_${name.replace(/[^a-z0-9]+/gi, "_").toLowerCase()}_present`,
+ level: "info",
+ message: `${name} is resolvable.`,
+ detail: resolved,
+ };
+ } catch {
+ return {
+ code: `acpx_package_${name.replace(/[^a-z0-9]+/gi, "_").toLowerCase()}_missing`,
+ level: "error",
+ message: `${name} is not resolvable from the acpx_local adapter package.`,
+ hint: "Run pnpm install so the ACPX adapter dependencies are installed.",
+ };
+ }
+}
+
+async function checkDirectory(pathValue: string, code: string, label: string): Promise<AdapterEnvironmentCheck | null> {
+ const dir = pathValue.trim();
+ if (!dir) return null;
+ try {
+ await fs.mkdir(dir, { recursive: true });
+ await fs.access(dir);
+ return {
+ code,
+ level: "info",
+ message: `${label} is writable: ${dir}`,
+ };
+ } catch (err) {
+ return {
+ code: `${code}_invalid`,
+ level: "error",
+ message: err instanceof Error ? err.message : `${label} is not writable.`,
+ detail: dir,
+ };
+ }
+}
+
+export async function testEnvironment(
+ ctx: AdapterEnvironmentTestContext,
+): Promise<AdapterEnvironmentTestResult> {
+ const config = parseObject(ctx.config);
+ const envConfig = parseObject(config.env);
+ const configEnv: Record<string, string> = {};
+ for (const [key, value] of Object.entries(envConfig)) {
+ if (typeof value === "string") configEnv[key] = value;
+ }
+ const checks: AdapterEnvironmentCheck[] = [];
+ const nodeVersion = process.version;
+
+ checks.push({
+ code: nodeVersionMeetsMinimum(nodeVersion) ? "acpx_node_supported" : "acpx_node_unsupported",
+ level: nodeVersionMeetsMinimum(nodeVersion) ? "info" : "error",
+ message: nodeVersionMeetsMinimum(nodeVersion)
+ ? `Node ${nodeVersion} satisfies ACPX's >=22.12.0 requirement.`
+ : `Node ${nodeVersion} does not satisfy ACPX's >=22.12.0 requirement.`,
+ hint: nodeVersionMeetsMinimum(nodeVersion)
+ ? undefined
+ : "Run acpx_local agents with Node >=22.12.0 or use claude_local/codex_local on Node 20.",
+ });
+
+ checks.push(resolvePackage("acpx"));
+ checks.push(resolvePackage("@agentclientprotocol/claude-agent-acp"));
+ checks.push(resolvePackage("@zed-industries/codex-acp"));
+
+ const agent = asString(config.agent, "claude");
+ if (!["claude", "codex", "custom"].includes(agent)) {
+ checks.push({
+ code: "acpx_agent_invalid",
+ level: "error",
+ message: `Unsupported ACP agent: ${agent}`,
+ hint: "Use agent=claude, agent=codex, or agent=custom.",
+ });
+ } else {
+ checks.push({
+ code: "acpx_agent_selected",
+ level: "info",
+ message: `ACP agent selected: ${agent}`,
+ });
+ checks.push(...await buildCredentialHintChecks(agent, configEnv));
+ }
+
+ if (agent === "custom" && !asString(config.agentCommand, "")) {
+ checks.push({
+ code: "acpx_custom_command_missing",
+ level: "error",
+ message: "agentCommand is required when agent=custom.",
+ });
+ }
+
+ const stateDirCheck = await checkDirectory(asString(config.stateDir, ""), "acpx_state_dir_writable", "ACPX state directory");
+ if (stateDirCheck) checks.push(stateDirCheck);
+
+ const permissionMode = asString(config.permissionMode, "approve-all");
+ checks.push({
+ code: "acpx_permission_mode",
+ level: "info",
+ message: `Effective permission mode: ${permissionMode || "approve-all"}`,
+ });
+
+ checks.push({
+ code: "acpx_runtime_scaffold",
+ level: "info",
+ message: "acpx_local runtime execution is available through the bundled ACPX runtime.",
+ });
+
+ return {
+ adapterType: ctx.adapterType,
+ status: summarizeStatus(checks),
+ checks,
+ testedAt: new Date().toISOString(),
+ };
+}
diff --git a/packages/adapters/acpx-local/src/ui/build-config.ts b/packages/adapters/acpx-local/src/ui/build-config.ts
new file mode 100644
index 0000000000..445686dc30
--- /dev/null
+++ b/packages/adapters/acpx-local/src/ui/build-config.ts
@@ -0,0 +1,139 @@
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+import {
+ DEFAULT_ACPX_LOCAL_AGENT,
+ DEFAULT_ACPX_LOCAL_MODE,
+ DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS,
+ DEFAULT_ACPX_LOCAL_PERMISSION_MODE,
+ DEFAULT_ACPX_LOCAL_TIMEOUT_SEC,
+} from "../index.js";
+
+function parseCommaArgs(value: string): string[] {
+ return value
+ .split(",")
+ .map((item) => item.trim())
+ .filter(Boolean);
+}
+
+function parseEnvVars(text: string): Record<string, string> {
+ const env: Record<string, string> = {};
+ for (const line of text.split(/\r?\n/)) {
+ const trimmed = line.trim();
+ if (!trimmed || trimmed.startsWith("#")) continue;
+ const eq = trimmed.indexOf("=");
+ if (eq <= 0) continue;
+ const key = trimmed.slice(0, eq).trim();
+ const value = trimmed.slice(eq + 1);
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+ env[key] = value;
+ }
+ return env;
+}
+
+function parseEnvBindings(bindings: unknown): Record<string, unknown> {
+ if (typeof bindings !== "object" || bindings === null || Array.isArray(bindings)) return {};
+ const env: Record<string, unknown> = {};
+ for (const [key, raw] of Object.entries(bindings)) {
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+ if (typeof raw === "string") {
+ env[key] = { type: "plain", value: raw };
+ continue;
+ }
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) continue;
+ const rec = raw as Record<string, unknown>;
+ if (rec.type === "plain" && typeof rec.value === "string") {
+ env[key] = { type: "plain", value: rec.value };
+ continue;
+ }
+ if (rec.type === "secret_ref" && typeof rec.secretId === "string") {
+ env[key] = {
+ type: "secret_ref",
+ secretId: rec.secretId,
+ ...(typeof rec.version === "number" || rec.version === "latest"
+ ? { version: rec.version }
+ : {}),
+ };
+ }
+ }
+ return env;
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | null {
+ const trimmed = text.trim();
+ if (!trimmed) return null;
+ try {
+ const parsed = JSON.parse(trimmed);
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+ return parsed as Record<string, unknown>;
+ } catch {
+ return null;
+ }
+}
+
+function readNumber(value: unknown, fallback: number): number {
+ if (typeof value === "number" && Number.isFinite(value)) return value;
+ if (typeof value === "string" && value.trim()) {
+ const parsed = Number(value);
+ if (Number.isFinite(parsed)) return parsed;
+ }
+ return fallback;
+}
+
+export function buildAcpxLocalConfig(v: CreateConfigValues): Record<string, unknown> {
+ const schemaValues = v.adapterSchemaValues ?? {};
+ const ac: Record<string, unknown> = {
+ agent: schemaValues.agent || DEFAULT_ACPX_LOCAL_AGENT,
+ mode: schemaValues.mode || DEFAULT_ACPX_LOCAL_MODE,
+ permissionMode: schemaValues.permissionMode || DEFAULT_ACPX_LOCAL_PERMISSION_MODE,
+ nonInteractivePermissions:
+ schemaValues.nonInteractivePermissions || DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS,
+ timeoutSec: readNumber(schemaValues.timeoutSec, DEFAULT_ACPX_LOCAL_TIMEOUT_SEC),
+ };
+
+ for (const key of [
+ "agentCommand",
+ "cwd",
+ "stateDir",
+ "instructionsFilePath",
+ "promptTemplate",
+ "bootstrapPromptTemplate",
+ ]) {
+ const value = schemaValues[key];
+ if (typeof value === "string" && value.trim()) ac[key] = value.trim();
+ }
+
+ if (!ac.cwd && v.cwd) ac.cwd = v.cwd;
+ if (!ac.instructionsFilePath && v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
+ if (!ac.promptTemplate && v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+ if (!ac.bootstrapPromptTemplate && v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
+
+ const env = parseEnvBindings(v.envBindings);
+ const legacy = parseEnvVars(v.envVars);
+ for (const [key, value] of Object.entries(legacy)) {
+ if (!Object.prototype.hasOwnProperty.call(env, key)) {
+ env[key] = { type: "plain", value };
+ }
+ }
+ if (typeof schemaValues.env === "string") {
+ const schemaEnv = parseJsonObject(schemaValues.env);
+ if (schemaEnv) Object.assign(env, schemaEnv);
+ } else if (typeof schemaValues.env === "object" && schemaValues.env !== null && !Array.isArray(schemaValues.env)) {
+ Object.assign(env, schemaValues.env as Record<string, unknown>);
+ }
+ if (Object.keys(env).length > 0) ac.env = env;
+
+ if (v.workspaceStrategyType === "git_worktree") {
+ ac.workspaceStrategy = {
+ type: "git_worktree",
+ ...(v.workspaceBaseRef ? { baseRef: v.workspaceBaseRef } : {}),
+ ...(v.workspaceBranchTemplate ? { branchTemplate: v.workspaceBranchTemplate } : {}),
+ ...(v.worktreeParentDir ? { worktreeParentDir: v.worktreeParentDir } : {}),
+ };
+ }
+ const runtimeServices = parseJsonObject(v.runtimeServicesJson ?? "");
+ if (runtimeServices && Array.isArray(runtimeServices.services)) {
+ ac.workspaceRuntime = runtimeServices;
+ }
+ if (v.command) ac.command = v.command;
+ if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
+ return ac;
+}
diff --git a/packages/adapters/acpx-local/src/ui/index.ts b/packages/adapters/acpx-local/src/ui/index.ts
new file mode 100644
index 0000000000..629baaad40
--- /dev/null
+++ b/packages/adapters/acpx-local/src/ui/index.ts
@@ -0,0 +1,2 @@
+export { parseAcpxStdoutLine } from "./parse-stdout.js";
+export { buildAcpxLocalConfig } from "./build-config.js";
diff --git a/packages/adapters/acpx-local/src/ui/parse-stdout.test.ts b/packages/adapters/acpx-local/src/ui/parse-stdout.test.ts
new file mode 100644
index 0000000000..80fb267160
--- /dev/null
+++ b/packages/adapters/acpx-local/src/ui/parse-stdout.test.ts
@@ -0,0 +1,160 @@
+import { describe, expect, it } from "vitest";
+import { parseAcpxStdoutLine } from "./parse-stdout.js";
+
+const TS = "2026-04-30T00:00:00.000Z";
+
+function emit(payload: Record<string, unknown>): string {
+ return JSON.stringify(payload);
+}
+
+describe("parseAcpxStdoutLine", () => {
+ it("renders an init entry from acpx.session", () => {
+ const entries = parseAcpxStdoutLine(
+ emit({
+ type: "acpx.session",
+ agent: "claude",
+ acpSessionId: "acp-1",
+ runtimeSessionName: "runtime-1",
+ mode: "persistent",
+ permissionMode: "approve-all",
+ }),
+ TS,
+ );
+ expect(entries).toEqual([
+ {
+ kind: "init",
+ ts: TS,
+ model: "claude (persistent / approve-all)",
+ sessionId: "acp-1",
+ },
+ ]);
+ });
+
+ it("routes output text_delta to the assistant transcript", () => {
+ const entries = parseAcpxStdoutLine(
+ emit({ type: "acpx.text_delta", text: "hello", channel: "output", tag: "agent_message_chunk" }),
+ TS,
+ );
+ expect(entries).toEqual([
+ { kind: "assistant", ts: TS, text: "hello", delta: true },
+ ]);
+ });
+
+ it("routes thought text_delta to the thinking transcript", () => {
+ const entries = parseAcpxStdoutLine(
+ emit({ type: "acpx.text_delta", text: "thinking…", channel: "thought" }),
+ TS,
+ );
+ expect(entries).toEqual([
+ { kind: "thinking", ts: TS, text: "thinking…", delta: true },
+ ]);
+ });
+
+ it("falls back to stream when channel is missing", () => {
+ const entries = parseAcpxStdoutLine(
+ emit({ type: "acpx.text_delta", text: "thinking…", stream: "thought" }),
+ TS,
+ );
+ expect(entries[0]).toMatchObject({ kind: "thinking" });
+ });
+
+ it("renders status events as system text with optional ctx usage", () => {
+ expect(
+ parseAcpxStdoutLine(
+ emit({ type: "acpx.status", text: "thinking", tag: "agent_thought_chunk" }),
+ TS,
+ ),
+ ).toEqual([{ kind: "system", ts: TS, text: "thinking" }]);
+
+ expect(
+ parseAcpxStdoutLine(
+ emit({ type: "acpx.status", tag: "context_window", used: 12000, size: 200000 }),
+ TS,
+ ),
+ ).toEqual([{ kind: "system", ts: TS, text: "context_window (12000/200000 ctx)" }]);
+ });
+
+ it("emits a tool_call entry that preserves toolCallId, status, and input", () => {
+ const entries = parseAcpxStdoutLine(
+ emit({
+ type: "acpx.tool_call",
+ name: "read",
+ toolCallId: "tool-1",
+ status: "running",
+ text: "read README.md",
+ }),
+ TS,
+ );
+ expect(entries).toEqual([
+ {
+ kind: "tool_call",
+ ts: TS,
+ name: "read",
+ toolUseId: "tool-1",
+ input: { text: "read README.md", status: "running" },
+ },
+ ]);
+ });
+
+ it("emits a paired tool_result entry when a tool_call reports terminal status", () => {
+ const completed = parseAcpxStdoutLine(
+ emit({
+ type: "acpx.tool_call",
+ name: "read",
+ toolCallId: "tool-1",
+ status: "completed",
+ text: "ok",
+ }),
+ TS,
+ );
+ expect(completed[1]).toEqual({
+ kind: "tool_result",
+ ts: TS,
+ toolUseId: "tool-1",
+ toolName: "read",
+ content: "ok",
+ isError: false,
+ });
+
+ const failed = parseAcpxStdoutLine(
+ emit({
+ type: "acpx.tool_call",
+ name: "edit",
+ toolCallId: "tool-2",
+ status: "failed",
+ text: "permission denied",
+ }),
+ TS,
+ );
+ expect(failed[1]).toMatchObject({ kind: "tool_result", isError: true, content: "permission denied" });
+ });
+
+ it("renders acpx.result with summary fallback to stopReason", () => {
+ const entries = parseAcpxStdoutLine(
+ emit({ type: "acpx.result", summary: "completed", stopReason: "end_turn" }),
+ TS,
+ );
+ expect(entries[0]).toMatchObject({ kind: "result", text: "completed", subtype: "end_turn", isError: false });
+ });
+
+ it("treats acpx.error as a stderr entry", () => {
+ const entries = parseAcpxStdoutLine(
+ emit({ type: "acpx.error", message: "auth required", code: "ACP_AUTH" }),
+ TS,
+ );
+ expect(entries).toEqual([{ kind: "stderr", ts: TS, text: "auth required" }]);
+ });
+
+ it("renders unknown acpx.* events as system entries", () => {
+ const entries = parseAcpxStdoutLine(
+ emit({ type: "acpx.misc", message: "unhandled" }),
+ TS,
+ );
+ expect(entries).toEqual([{ kind: "system", ts: TS, text: "unhandled" }]);
+ });
+
+ it("falls back to a stdout entry for non-JSON lines", () => {
+ const entries = parseAcpxStdoutLine("not json", TS);
+ expect(entries).toEqual([{ kind: "stdout", ts: TS, text: "not json" }]);
+ });
+});
diff --git a/packages/adapters/acpx-local/src/ui/parse-stdout.ts b/packages/adapters/acpx-local/src/ui/parse-stdout.ts
new file mode 100644
index 0000000000..019e8f3322
--- /dev/null
+++ b/packages/adapters/acpx-local/src/ui/parse-stdout.ts
@@ -0,0 +1,158 @@
+import type { TranscriptEntry } from "@paperclipai/adapter-utils";
+
+function parseJson(line: string): Record<string, unknown> | null {
+ try {
+ const parsed = JSON.parse(line);
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+ return parsed as Record<string, unknown>;
+ } catch {
+ return null;
+ }
+}
+
+function asString(value: unknown, fallback = ""): string {
+ return typeof value === "string" ? value : fallback;
+}
+
+function asNumber(value: unknown, fallback = 0): number {
+ return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function stringify(value: unknown): string {
+ if (typeof value === "string") return value;
+ if (value === null || value === undefined) return "";
+ try {
+ return JSON.stringify(value, null, 2);
+ } catch {
+ return String(value);
+ }
+}
+
+function pickToolUseId(parsed: Record<string, unknown>): string {
+ return (
+ asString(parsed.toolCallId) ||
+ asString(parsed.toolUseId) ||
+ asString(parsed.id)
+ );
+}
+
+function statusText(parsed: Record<string, unknown>): string {
+ const text = asString(parsed.text).trim();
+ const tag = asString(parsed.tag).trim();
+ const used = asNumber(parsed.used, -1);
+ const size = asNumber(parsed.size, -1);
+ const parts: string[] = [];
+ if (text) parts.push(text);
+ if (tag && !text) parts.push(tag);
+ if (used >= 0 && size > 0) parts.push(`(${used}/${size} ctx)`);
+ return parts.join(" ") || tag || "status";
+}
+
+export function parseAcpxStdoutLine(line: string, ts: string): TranscriptEntry[] {
+ const parsed = parseJson(line);
+ if (!parsed) return [{ kind: "stdout", ts, text: line }];
+
+ const type = asString(parsed.type);
+ if (type === "acpx.session") {
+ const agent = asString(parsed.agent, "acpx");
+ const mode = asString(parsed.mode);
+ const permissionMode = asString(parsed.permissionMode);
+ const tail = [mode, permissionMode].filter(Boolean).join(" / ");
+ return [{
+ kind: "init",
+ ts,
+ model: tail ? `${agent} (${tail})` : agent,
+ sessionId:
+ asString(parsed.acpSessionId) ||
+ asString(parsed.sessionId) ||
+ asString(parsed.runtimeSessionName),
+ }];
+ }
+
+ if (type === "acpx.text_delta") {
+ const text = asString(parsed.text);
+ if (!text) return [];
+ const channel = asString(parsed.channel) || asString(parsed.stream);
+ return [{
+ kind: channel === "thought" || channel === "thinking" ? "thinking" : "assistant",
+ ts,
+ text,
+ delta: true,
+ }];
+ }
+
+ if (type === "acpx.tool_call") {
+ const status = asString(parsed.status);
+ const text = asString(parsed.text);
+ const name = asString(parsed.name, "acp_tool");
+ const toolUseId = pickToolUseId(parsed);
+ const input =
+ parsed.input !== undefined
+ ? parsed.input
+ : text || status
+ ? { ...(text ? { text } : {}), ...(status ? { status } : {}) }
+ : {};
+ const entries: TranscriptEntry[] = [
+ {
+ kind: "tool_call",
+ ts,
+ name,
+ toolUseId: toolUseId || undefined,
+ input,
+ },
+ ];
+ if (status === "completed" || status === "failed" || status === "cancelled") {
+ entries.push({
+ kind: "tool_result",
+ ts,
+ toolUseId: toolUseId || name,
+ toolName: name,
+ content: text || status,
+ isError: status !== "completed",
+ });
+ }
+ return entries;
+ }
+
+ if (type === "acpx.tool_result") {
+ return [{
+ kind: "tool_result",
+ ts,
+ toolUseId: pickToolUseId(parsed) || asString(parsed.name, "acp_tool"),
+ toolName: asString(parsed.name) || undefined,
+ content: stringify(parsed.content ?? parsed.output ?? parsed.error),
+ isError: parsed.isError === true || parsed.error !== undefined,
+ }];
+ }
+
+ if (type === "acpx.status") {
+ return [{ kind: "system", ts, text: statusText(parsed) }];
+ }
+
+ if (type === "acpx.result") {
+ return [{
+ kind: "result",
+ ts,
+ text: asString(parsed.summary, asString(parsed.stopReason, asString(parsed.text))),
+ inputTokens: asNumber(parsed.inputTokens),
+ outputTokens: asNumber(parsed.outputTokens),
+ cachedTokens: asNumber(parsed.cachedTokens),
+ costUsd: asNumber(parsed.costUsd),
+ subtype: asString(parsed.subtype, asString(parsed.stopReason, "acpx.result")),
+ isError: parsed.isError === true,
+ errors: Array.isArray(parsed.errors)
+ ? parsed.errors.map((error) => stringify(error)).filter(Boolean)
+ : [],
+ }];
+ }
+
+ if (type === "acpx.error") {
+ return [{ kind: "stderr", ts, text: asString(parsed.message, line) }];
+ }
+
+ if (type.startsWith("acpx.")) {
+ return [{ kind: "system", ts, text: asString(parsed.message, type) }];
+ }
+
+ return [{ kind: "stdout", ts, text: line }];
+}
diff --git a/packages/adapters/acpx-local/tsconfig.json b/packages/adapters/acpx-local/tsconfig.json
new file mode 100644
index 0000000000..e1b71318a6
--- /dev/null
+++ b/packages/adapters/acpx-local/tsconfig.json
@@ -0,0 +1,8 @@
+{
+ "extends": "../../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "dist",
+ "rootDir": "src"
+ },
+ "include": ["src"]
+}
diff --git a/packages/adapters/acpx-local/vitest.config.ts b/packages/adapters/acpx-local/vitest.config.ts
new file mode 100644
index 0000000000..f624398e8d
--- /dev/null
+++ b/packages/adapters/acpx-local/vitest.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+ test: {
+ environment: "node",
+ },
+});
diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.ts
index 16211b38e4..8b196e9352 100644
--- a/packages/shared/src/constants.ts
+++ b/packages/shared/src/constants.ts
@@ -30,6 +30,7 @@ export type AgentStatus = (typeof AGENT_STATUSES)[number];
export const AGENT_ADAPTER_TYPES = [
"process",
"http",
+ "acpx_local",
"claude_local",
"codex_local",
"gemini_local",
diff --git a/packages/shared/src/environment-support.ts b/packages/shared/src/environment-support.ts
index 0ebb3ff938..f63ad70790 100644
--- a/packages/shared/src/environment-support.ts
+++ b/packages/shared/src/environment-support.ts
@@ -31,6 +31,7 @@ export interface EnvironmentCapabilities {
}
const REMOTE_MANAGED_ADAPTERS = new Set<AgentAdapterType>([
+ "acpx_local",
"claude_local",
"codex_local",
"cursor",
diff --git a/scripts/capture-acpx-skills-screenshots.mjs b/scripts/capture-acpx-skills-screenshots.mjs
new file mode 100644
index 0000000000..ee184c6614
--- /dev/null
+++ b/scripts/capture-acpx-skills-screenshots.mjs
@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import path from "node:path";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const playwrightPkgRoot = path.join(repoRoot, "node_modules/.pnpm/[email protected]/node_modules/playwright");
+const { chromium } = await import(path.join(playwrightPkgRoot, "index.mjs"));
+
+const baseUrl = process.env.STORYBOOK_BASE_URL ?? "http://127.0.0.1:6007";
+const outDir = process.env.OUT_DIR ?? path.join(repoRoot, "screenshots/pap-2999");
+await fs.mkdir(outDir, { recursive: true });
+
+const stories = [
+ { id: "adapters-acpx-local--skills-tab-claude", slug: "skills-claude" },
+ { id: "adapters-acpx-local--skills-tab-codex", slug: "skills-codex" },
+ { id: "adapters-acpx-local--skills-tab-custom", slug: "skills-custom" },
+ { id: "adapters-acpx-local--skills-tab-loading", slug: "skills-loading" },
+ { id: "adapters-acpx-local--skills-tab-empty-library", slug: "skills-empty-library" },
+];
+
+const themes = [
+ { name: "light", apply: false },
+ { name: "dark", apply: true },
+];
+
+const browser = await chromium.launch();
+try {
+ const context = await browser.newContext({ viewport: { width: 1280, height: 1100 } });
+ const page = await context.newPage();
+ for (const story of stories) {
+ for (const theme of themes) {
+ const url = `${baseUrl}/iframe.html?args=&id=${story.id}&viewMode=story&globals=theme:${theme.name}`;
+ await page.goto(url, { waitUntil: "load" });
+ await page.waitForTimeout(1500);
+ const target = path.join(outDir, `${story.slug}-${theme.name}.png`);
+ await page.screenshot({ path: target, fullPage: true });
+ console.log(`captured ${target}`);
+ }
+ }
+} finally {
+ await browser.close();
+}
diff --git a/scripts/run-vitest-stable.mjs b/scripts/run-vitest-stable.mjs
index b9473434a6..e016719f0d 100644
--- a/scripts/run-vitest-stable.mjs
+++ b/scripts/run-vitest-stable.mjs
@@ -11,6 +11,7 @@ const nonServerProjects = [
"@paperclipai/shared",
"@paperclipai/db",
"@paperclipai/adapter-utils",
+ "@paperclipai/adapter-acpx-local",
"@paperclipai/adapter-codex-local",
"@paperclipai/adapter-opencode-local",
"@paperclipai/ui",
diff --git a/server/package.json b/server/package.json
index ab81280ea3..bd19e53fcf 100644
--- a/server/package.json
+++ b/server/package.json
@@ -44,6 +44,7 @@
},
"dependencies": {
"@aws-sdk/client-s3": "^3.888.0",
+ "@paperclipai/adapter-acpx-local": "workspace:*",
"@paperclipai/adapter-claude-local": "workspace:*",
"@paperclipai/adapter-codex-local": "workspace:*",
"@paperclipai/adapter-cursor-local": "workspace:*",
diff --git a/server/src/__tests__/acpx-local-adapter-environment.test.ts b/server/src/__tests__/acpx-local-adapter-environment.test.ts
new file mode 100644
index 0000000000..0883fae0b6
--- /dev/null
+++ b/server/src/__tests__/acpx-local-adapter-environment.test.ts
@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { testEnvironment } from "@paperclipai/adapter-acpx-local/server";
+import type { AdapterEnvironmentCheck } from "@paperclipai/adapter-utils";
+
+function credentialChecks(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentCheck[] {
+ return checks.filter((check) => check.code.startsWith("acpx_claude_") || check.code.startsWith("acpx_codex_"));
+}
+
+describe("acpx_local environment credential diagnostics", () => {
+ beforeEach(() => {
+ vi.stubEnv("ANTHROPIC_API_KEY", "");
+ vi.stubEnv("ANTHROPIC_BEDROCK_BASE_URL", "");
+ vi.stubEnv("CLAUDE_CODE_USE_BEDROCK", "");
+ vi.stubEnv("CLAUDE_CONFIG_DIR", "");
+ vi.stubEnv("OPENAI_API_KEY", "");
+ vi.stubEnv("CODEX_HOME", "");
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ });
+
+ it("emits an info-level Claude credential hint when ANTHROPIC_API_KEY is present", async () => {
+ const result = await testEnvironment({
+ companyId: "company-1",
+ adapterType: "acpx_local",
+ config: {
+ agent: "claude",
+ env: {
+ ANTHROPIC_API_KEY: "sk-ant-test",
+ },
+ },
+ });
+
+ expect(result.checks).toContainEqual(expect.objectContaining({
+ code: "acpx_claude_anthropic_api_key_detected",
+ level: "info",
+ }));
+ expect(result.checks.some((check) => check.code.startsWith("acpx_codex_"))).toBe(false);
+ });
+
+ it("emits an info-level Claude missing credential hint without changing diagnostic health", async () => {
+ const root = path.join(os.tmpdir(), `paperclip-acpx-claude-noauth-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+ const claudeConfigDir = path.join(root, ".claude");
+
+ try {
+ await fs.mkdir(claudeConfigDir, { recursive: true });
+
+ const result = await testEnvironment({
+ companyId: "company-1",
+ adapterType: "acpx_local",
+ config: {
+ agent: "claude",
+ env: {
+ CLAUDE_CONFIG_DIR: claudeConfigDir,
+ },
+ },
+ });
+
+ expect(result.checks).toContainEqual(expect.objectContaining({
+ code: "acpx_claude_credentials_missing",
+ level: "info",
+ }));
+ expect(credentialChecks(result.checks).every((check) => check.level === "info")).toBe(true);
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("emits an info-level Codex credential hint when native auth is present", async () => {
+ const root = path.join(os.tmpdir(), `paperclip-acpx-codex-auth-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+ const codexHome = path.join(root, ".codex");
+
+ try {
+ await fs.mkdir(codexHome, { recursive: true });
+ await fs.writeFile(path.join(codexHome, "auth.json"), JSON.stringify({ accessToken: "token" }), "utf8");
+
+ const result = await testEnvironment({
+ companyId: "company-1",
+ adapterType: "acpx_local",
+ config: {
+ agent: "codex",
+ env: {
+ CODEX_HOME: codexHome,
+ },
+ },
+ });
+
+ expect(result.checks).toContainEqual(expect.objectContaining({
+ code: "acpx_codex_native_auth_detected",
+ level: "info",
+ }));
+ expect(result.checks.some((check) => check.code.startsWith("acpx_claude_"))).toBe(false);
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("emits an info-level Codex missing credential hint without changing diagnostic health", async () => {
+ const root = path.join(os.tmpdir(), `paperclip-acpx-codex-noauth-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+ const codexHome = path.join(root, ".codex");
+
+ try {
+ await fs.mkdir(codexHome, { recursive: true });
+
+ const result = await testEnvironment({
+ companyId: "company-1",
+ adapterType: "acpx_local",
+ config: {
+ agent: "codex",
+ env: {
+ CODEX_HOME: codexHome,
+ },
+ },
+ });
+
+ expect(result.checks).toContainEqual(expect.objectContaining({
+ code: "acpx_codex_credentials_missing",
+ level: "info",
+ }));
+ expect(credentialChecks(result.checks).every((check) => check.level === "info")).toBe(true);
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/server/src/__tests__/acpx-local-execute.test.ts b/server/src/__tests__/acpx-local-execute.test.ts
new file mode 100644
index 0000000000..ff9c46cbab
--- /dev/null
+++ b/server/src/__tests__/acpx-local-execute.test.ts
@@ -0,0 +1,603 @@
+import { describe, expect, it } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+import { createAcpxLocalExecutor } from "@paperclipai/adapter-acpx-local/server";
+import type {
+ AcpRuntime,
+ AcpRuntimeEvent,
+ AcpRuntimeHandle,
+ AcpRuntimeOptions,
+ AcpRuntimeTurn,
+ AcpRuntimeTurnResult,
+} from "acpx/runtime";
+
+type LogEntry = { stream: "stdout" | "stderr"; chunk: string };
+type TestAcpRuntimeOptions = AcpRuntimeOptions & {
+ sessionOptions?: {
+ systemPrompt?: string | { append: string };
+ additionalRoots?: string[];
+ };
+};
+
+class FakeRuntime implements AcpRuntime {
+ ensureInputs: Array<{ sessionKey: string; agent: string; mode: "persistent" | "oneshot"; cwd?: string; resumeSessionId?: string }> = [];
+ startInputs: Array<{ handle: AcpRuntimeHandle; text: string; requestId: string; timeoutMs?: number }> = [];
+ closeInputs: Array<{ handle: AcpRuntimeHandle; reason: string; discardPersistentState?: boolean }> = [];
+ cancelInputs: Array<{ handle: AcpRuntimeHandle; reason?: string }> = [];
+ setModeInputs: Array<{ handle: AcpRuntimeHandle; mode: string }> = [];
+ setConfigInputs: Array<{ handle: AcpRuntimeHandle; key: string; value: string }> = [];
+ ensureCount = 0;
+ turnCount = 0;
+ nextEnsureError: Error | null = null;
+
+ constructor(
+ readonly options: TestAcpRuntimeOptions,
+ readonly events: AcpRuntimeEvent[] = [
+ { type: "status", text: "thinking", tag: "agent_thought_chunk" },
+ { type: "text_delta", text: "hello ", stream: "output", tag: "agent_message_chunk" },
+ { type: "tool_call", text: "read README.md", title: "read", status: "running", toolCallId: "tool-1" },
+ { type: "text_delta", text: "world", stream: "output", tag: "agent_message_chunk" },
+ ],
+ readonly terminal: AcpRuntimeTurnResult = { status: "completed", stopReason: "end_turn" },
+ ) {}
+
+ async ensureSession(input: { sessionKey: string; agent: string; mode: "persistent" | "oneshot"; cwd?: string; resumeSessionId?: string }): Promise<AcpRuntimeHandle> {
+ this.ensureInputs.push(input);
+ this.ensureCount += 1;
+ if (this.nextEnsureError) {
+ const err = this.nextEnsureError;
+ this.nextEnsureError = null;
+ throw err;
+ }
+ return {
+ sessionKey: input.sessionKey,
+ backend: "acpx",
+ runtimeSessionName: `runtime-${this.ensureCount}`,
+ cwd: input.cwd,
+ acpxRecordId: `record-${this.ensureCount}`,
+ backendSessionId: `acp-${this.ensureCount}`,
+ agentSessionId: `agent-${this.ensureCount}`,
+ };
+ }
+
+ startTurn(input: { handle: AcpRuntimeHandle; text: string; requestId: string; timeoutMs?: number }): AcpRuntimeTurn {
+ this.startInputs.push(input);
+ this.turnCount += 1;
+ let closed = false;
+ const events = this.events;
+ const terminal = this.terminal;
+ const cancelInputs = this.cancelInputs;
+ return {
+ requestId: input.requestId,
+ events: {
+ [Symbol.asyncIterator]: async function* () {
+ for (const event of events) {
+ if (closed) return;
+ yield event;
+ }
+ },
+ },
+ result: Promise.resolve(terminal),
+ cancel: async (args?: { reason?: string }) => {
+ cancelInputs.push({ handle: input.handle, reason: args?.reason });
+ closed = true;
+ },
+ closeStream: async () => {
+ closed = true;
+ },
+ };
+ }
+
+ runTurn(): AsyncIterable<AcpRuntimeEvent> {
+ throw new Error("not used");
+ }
+
+ getCapabilities() {
+ return { controls: [] };
+ }
+
+ getStatus() {
+ return Promise.resolve({});
+ }
+
+ async setMode(input: { handle: AcpRuntimeHandle; mode: string }) {
+ this.setModeInputs.push(input);
+ }
+
+ async setConfigOption(input: { handle: AcpRuntimeHandle; key: string; value: string }) {
+ this.setConfigInputs.push(input);
+ }
+
+ async cancel(input: { handle: AcpRuntimeHandle; reason?: string }) {
+ this.cancelInputs.push(input);
+ }
+
+ async close(input: { handle: AcpRuntimeHandle; reason: string; discardPersistentState?: boolean }) {
+ this.closeInputs.push(input);
+ }
+}
+
+async function createRuntimeSkill(root: string, input: {
+ key?: string;
+ runtimeName?: string;
+ body?: string;
+}) {
+ const runtimeName = input.runtimeName ?? "paperclip-test-skill";
+ const key = input.key ?? `company/${runtimeName}`;
+ const source = path.join(root, "skills", runtimeName);
+ await fs.mkdir(source, { recursive: true });
+ await fs.writeFile(path.join(source, "SKILL.md"), input.body ?? "---\nrequired: false\n---\nUse the test skill.\n", "utf8");
+ return {
+ key,
+ runtimeName,
+ source,
+ required: false,
+ };
+}
+
+function parseStdoutLogs(logs: LogEntry[]) {
+ return logs
+ .filter((entry) => entry.stream === "stdout")
+ .flatMap((entry) => entry.chunk.trim().split(/\n+/).filter(Boolean))
+ .map((line) => JSON.parse(line) as Record<string, unknown>);
+}
+
+function buildContext(root: string, overrides: Partial<AdapterExecutionContext> = {}): AdapterExecutionContext {
+ return {
+ runId: "run-1",
+ agent: {
+ id: "agent-1",
+ companyId: "company-1",
+ name: "ACPX Coder",
+ adapterType: "acpx_local",
+ adapterConfig: {},
+ },
+ runtime: {
+ sessionId: null,
+ sessionParams: null,
+ sessionDisplayId: null,
+ taskKey: "PAP-1",
+ },
+ config: {
+ agent: "claude",
+ cwd: root,
+ stateDir: path.join(root, "state"),
+ promptTemplate: "Do the assigned work.",
+ },
+ context: {
+ issueId: "issue-1",
+ paperclipTaskMarkdown: "Task context",
+ },
+ onLog: async () => {},
+ ...overrides,
+ };
+}
+
+describe("acpx_local execute", () => {
+ it("streams ACPX session, status, text, and tool events before returning success", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-success-"));
+ try {
+ const runtime = new FakeRuntime({} as AcpRuntimeOptions);
+ const logs: LogEntry[] = [];
+ let metaPermissionNote = "";
+ const execute = createAcpxLocalExecutor({
+ createRuntime: () => runtime,
+ });
+ const result = await execute(buildContext(root, {
+ onLog: async (stream, chunk) => logs.push({ stream, chunk }),
+ onMeta: async (meta) => {
+ metaPermissionNote = meta.commandNotes?.join("\n") ?? "";
+ },
+ }));
+
+ expect(result.exitCode).toBe(0);
+ expect(result.summary).toBe("hello world");
+ expect(result.sessionParams).toMatchObject({
+ agent: "claude",
+ cwd: root,
+ mode: "persistent",
+ acpSessionId: "acp-1",
+ });
+ expect(metaPermissionNote).toContain("Effective ACPX permission mode: approve-all");
+ const parsed = parseStdoutLogs(logs);
+ expect(parsed.map((event) => event.type)).toEqual([
+ "acpx.session",
+ "acpx.status",
+ "acpx.text_delta",
+ "acpx.tool_call",
+ "acpx.text_delta",
+ "acpx.result",
+ ]);
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("reuses a compatible warm session and starts fresh when cwd changes", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-reuse-"));
+ const other = path.join(root, "other");
+ await fs.mkdir(other);
+ try {
+ const runtimes: FakeRuntime[] = [];
+ const execute = createAcpxLocalExecutor({
+ createRuntime: (options) => {
+ const runtime = new FakeRuntime(options);
+ runtimes.push(runtime);
+ return runtime;
+ },
+ });
+
+ const first = await execute(buildContext(root));
+ const second = await execute(buildContext(root, {
+ runtime: {
+ sessionId: first.sessionId ?? null,
+ sessionParams: first.sessionParams ?? null,
+ sessionDisplayId: first.sessionDisplayId ?? null,
+ taskKey: "PAP-1",
+ },
+ }));
+ const third = await execute(buildContext(root, {
+ runtime: {
+ sessionId: first.sessionId ?? null,
+ sessionParams: first.sessionParams ?? null,
+ sessionDisplayId: first.sessionDisplayId ?? null,
+ taskKey: "PAP-1",
+ },
+ config: {
+ agent: "claude",
+ cwd: other,
+ stateDir: path.join(root, "state"),
+ promptTemplate: "Do the assigned work.",
+ },
+ }));
+
+ expect(runtimes).toHaveLength(2);
+ expect(runtimes[0].ensureCount).toBe(1);
+ expect(runtimes[0].turnCount).toBe(2);
+ expect(runtimes[1].ensureCount).toBe(1);
+ expect(second.sessionParams?.acpSessionId).toBe("acp-1");
+ expect(third.sessionParams?.cwd).toBe(other);
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("closes duplicate warm handles from concurrent runs for the same session key", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-concurrent-"));
+ try {
+ const runtimes: FakeRuntime[] = [];
+ const warmHandles = new Map();
+ const execute = createAcpxLocalExecutor({
+ warmHandles,
+ createRuntime: (options) => {
+ const runtime = new FakeRuntime(options);
+ runtimes.push(runtime);
+ return runtime;
+ },
+ });
+
+ const [first, second] = await Promise.all([
+ execute(buildContext(root, { runId: "run-1" })),
+ execute(buildContext(root, { runId: "run-2" })),
+ ]);
+
+ expect(first.exitCode).toBe(0);
+ expect(second.exitCode).toBe(0);
+ expect(runtimes).toHaveLength(2);
+ expect(warmHandles.size).toBe(1);
+ expect(runtimes.flatMap((runtime) => runtime.closeInputs).filter((input) =>
+ input.reason === "paperclip duplicate warm handle cleanup"
+ )).toHaveLength(1);
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("retries with a fresh session when ACPX cannot resume the saved backend session", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-resume-"));
+ try {
+ const runtime = new FakeRuntime({} as AcpRuntimeOptions);
+ const firstExecute = createAcpxLocalExecutor({
+ createRuntime: () => runtime,
+ warmHandles: new Map(),
+ });
+ const initial = await firstExecute(buildContext(root));
+ const compatibleParams = {
+ ...initial.sessionParams,
+ runtimeSessionName: "runtime-old",
+ acpSessionId: "acp-old",
+ };
+ runtime.nextEnsureError = new Error("session/load failed: no session acp-old");
+ const logs: LogEntry[] = [];
+ const execute = createAcpxLocalExecutor({
+ createRuntime: () => runtime,
+ warmHandles: new Map(),
+ });
+ const result = await execute(buildContext(root, {
+ runtime: {
+ sessionId: "acp-old",
+ sessionParams: compatibleParams,
+ sessionDisplayId: "acp-old",
+ taskKey: "PAP-1",
+ },
+ onLog: async (stream, chunk) => logs.push({ stream, chunk }),
+ }));
+
+ expect(result.exitCode).toBe(0);
+ expect(result.clearSession).toBe(true);
+ expect(runtime.ensureInputs.at(-2)?.resumeSessionId).toBe("acp-old");
+ expect(runtime.ensureInputs.at(-1)?.resumeSessionId).toBeUndefined();
+ expect(logs.some((entry) => entry.chunk.includes("retrying with a fresh session"))).toBe(true);
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("cancels and closes stale handles on timeout", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-timeout-"));
+ try {
+ const neverFinishes = new FakeRuntime(
+ {} as AcpRuntimeOptions,
+ [],
+ { status: "cancelled", stopReason: "cancelled" },
+ );
+ neverFinishes.startTurn = function (input): AcpRuntimeTurn {
+ this.startInputs.push(input);
+ let resolveResult!: (value: AcpRuntimeTurnResult) => void;
+ const result = new Promise<AcpRuntimeTurnResult>((resolve) => {
+ resolveResult = resolve;
+ });
+ return {
+ requestId: input.requestId,
+ events: {
+ [Symbol.asyncIterator]: async function* () {
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ },
+ },
+ result,
+ cancel: async (args?: { reason?: string }) => {
+ this.cancelInputs.push({ handle: input.handle, reason: args?.reason });
+ resolveResult({ status: "cancelled", stopReason: args?.reason });
+ },
+ closeStream: async () => {},
+ };
+ };
+ const execute = createAcpxLocalExecutor({ createRuntime: () => neverFinishes });
+ const result = await execute(buildContext(root, {
+ config: {
+ agent: "claude",
+ cwd: root,
+ stateDir: path.join(root, "state"),
+ promptTemplate: "Do the assigned work.",
+ timeoutSec: 0.01,
+ },
+ }));
+
+ expect(result.timedOut).toBe(true);
+ expect(result.errorCode).toBe("acpx_timeout");
+ expect(neverFinishes.cancelInputs.length).toBeGreaterThan(0);
+ expect(neverFinishes.closeInputs.at(-1)?.discardPersistentState).toBe(true);
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("returns structured auth errors", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-error-"));
+ try {
+ const runtime = new FakeRuntime({} as AcpRuntimeOptions);
+ runtime.nextEnsureError = new Error("authentication required: login first");
+ const execute = createAcpxLocalExecutor({ createRuntime: () => runtime });
+ const result = await execute(buildContext(root));
+ expect(result.exitCode).toBe(1);
+ expect(result.errorCode).toBe("acpx_auth_required");
+ expect(result.errorMeta).toMatchObject({ category: "auth" });
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("returns structured ACP protocol errors", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-protocol-"));
+ try {
+ const runtime = new FakeRuntime({} as AcpRuntimeOptions);
+ runtime.nextEnsureError = Object.assign(new Error("protocol init failed"), {
+ code: "ACP_SESSION_INIT_FAILED",
+ });
+ const execute = createAcpxLocalExecutor({ createRuntime: () => runtime });
+ const result = await execute(buildContext(root));
+ expect(result.exitCode).toBe(1);
+ expect(result.errorCode).toBe("acpx_protocol_error");
+ expect(result.errorMeta).toMatchObject({
+ category: "protocol",
+ acpCode: "ACP_SESSION_INIT_FAILED",
+ });
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("materializes selected skills for ACPX Claude and passes public session metadata", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-claude-skills-"));
+ try {
+ const skill = await createRuntimeSkill(root, {});
+ let runtime: FakeRuntime | null = null;
+ let meta: Record<string, unknown> | null = null;
+ const execute = createAcpxLocalExecutor({
+ createRuntime: (options) => {
+ runtime = new FakeRuntime(options);
+ return runtime;
+ },
+ });
+
+ const result = await execute(buildContext(root, {
+ config: {
+ agent: "claude",
+ cwd: root,
+ stateDir: path.join(root, "state"),
+ promptTemplate: "Do the assigned work.",
+ paperclipRuntimeSkills: [skill],
+ paperclipSkillSync: {
+ desiredSkills: [skill.key],
+ },
+ },
+ onMeta: async (payload) => {
+ meta = payload as Record<string, unknown>;
+ },
+ }));
+
+ expect(result.exitCode).toBe(0);
+ expect(runtime?.options).not.toHaveProperty("sessionOptions");
+ const skillRoot = result.sessionParams?.skills && typeof result.sessionParams.skills === "object"
+ ? (result.sessionParams.skills as { skillRoot?: string | null }).skillRoot
+ : null;
+ expect(skillRoot).toContain(path.join("state", "runtime-skills", "claude"));
+ await expect(fs.lstat(path.join(skillRoot!, skill.runtimeName))).resolves.toMatchObject({});
+ expect(result.sessionParams?.skills).toMatchObject({
+ mode: "claude",
+ selectedSkills: [skill.runtimeName],
+ });
+ expect(String(meta?.prompt ?? "")).toContain(`Skill root: ${skillRoot}`);
+ expect((meta?.commandNotes as string[]).join("\n")).toContain("Materialized 1 Paperclip skill");
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("includes skill content in the ACPX Claude session fingerprint", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-claude-fingerprint-"));
+ try {
+ const skill = await createRuntimeSkill(root, { body: "---\nrequired: false\n---\nFirst version.\n" });
+ const runtimes: FakeRuntime[] = [];
+ const execute = createAcpxLocalExecutor({
+ createRuntime: (options) => {
+ const runtime = new FakeRuntime(options);
+ runtimes.push(runtime);
+ return runtime;
+ },
+ });
+ const context = buildContext(root, {
+ config: {
+ agent: "claude",
+ cwd: root,
+ stateDir: path.join(root, "state"),
+ promptTemplate: "Do the assigned work.",
+ paperclipRuntimeSkills: [skill],
+ paperclipSkillSync: {
+ desiredSkills: [skill.key],
+ },
+ },
+ });
+
+ const first = await execute(context);
+ await fs.writeFile(path.join(skill.source, "SKILL.md"), "---\nrequired: false\n---\nSecond version.\n", "utf8");
+ const second = await execute({
+ ...context,
+ runtime: {
+ sessionId: first.sessionId ?? null,
+ sessionParams: first.sessionParams ?? null,
+ sessionDisplayId: first.sessionDisplayId ?? null,
+ taskKey: "PAP-1",
+ },
+ });
+
+ expect(second.sessionParams?.configFingerprint).not.toBe(first.sessionParams?.configFingerprint);
+ expect(runtimes.at(-1)?.ensureInputs.at(-1)?.resumeSessionId).toBeUndefined();
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("materializes selected skills into the effective ACPX Codex CODEX_HOME", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-codex-skills-"));
+ try {
+ const skill = await createRuntimeSkill(root, {});
+ const codexHome = path.join(root, "codex-home");
+ let runtime: FakeRuntime | null = null;
+ let meta: Record<string, unknown> | null = null;
+ const execute = createAcpxLocalExecutor({
+ createRuntime: (options) => {
+ runtime = new FakeRuntime(options);
+ return runtime;
+ },
+ });
+
+ const result = await execute(buildContext(root, {
+ config: {
+ agent: "codex",
+ cwd: root,
+ stateDir: path.join(root, "state"),
+ promptTemplate: "Do the assigned work.",
+ env: { CODEX_HOME: codexHome },
+ paperclipRuntimeSkills: [skill],
+ paperclipSkillSync: {
+ desiredSkills: [skill.key],
+ },
+ },
+ onMeta: async (payload) => {
+ meta = payload as Record<string, unknown>;
+ },
+ }));
+
+ expect(result.exitCode).toBe(0);
+ await expect(fs.lstat(path.join(codexHome, "skills", skill.runtimeName))).resolves.toMatchObject({});
+ const wrapperPath = runtime?.options.agentRegistry.resolve("codex");
+ const wrapper = await fs.readFile(wrapperPath!, "utf8");
+ expect(wrapper).not.toContain("CODEX_HOME");
+ expect(wrapper).not.toContain(codexHome);
+ expect((meta?.env as Record<string, string>).CODEX_HOME).toBe(codexHome);
+ expect(result.sessionParams?.skills).toMatchObject({
+ mode: "codex",
+ codexHome,
+ selectedSkills: [skill.runtimeName],
+ });
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ it("keeps ACPX custom skill selection tracked without runtime materialization", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-custom-skills-"));
+ try {
+ const skill = await createRuntimeSkill(root, {});
+ let runtime: FakeRuntime | null = null;
+ let meta: Record<string, unknown> | null = null;
+ const execute = createAcpxLocalExecutor({
+ createRuntime: (options) => {
+ runtime = new FakeRuntime(options);
+ return runtime;
+ },
+ });
+
+ const result = await execute(buildContext(root, {
+ config: {
+ agent: "custom",
+ agentCommand: "custom-acp",
+ cwd: root,
+ stateDir: path.join(root, "state"),
+ promptTemplate: "Do the assigned work.",
+ paperclipRuntimeSkills: [skill],
+ paperclipSkillSync: {
+ desiredSkills: [skill.key],
+ },
+ },
+ onMeta: async (payload) => {
+ meta = payload as Record<string, unknown>;
+ },
+ }));
+
+ expect(result.exitCode).toBe(0);
+ expect(runtime?.options.sessionOptions).toBeUndefined();
+ await expect(fs.lstat(path.join(root, "state", "runtime-skills"))).rejects.toMatchObject({ code: "ENOENT" });
+ expect(result.sessionParams?.skills).toMatchObject({
+ mode: "custom_unsupported",
+ desiredSkillNames: [skill.key],
+ });
+ expect((meta?.commandNotes as string[]).join("\n")).toContain("tracked only");
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/server/src/__tests__/acpx-local-skill-sync.test.ts b/server/src/__tests__/acpx-local-skill-sync.test.ts
new file mode 100644
index 0000000000..5da02709a6
--- /dev/null
+++ b/server/src/__tests__/acpx-local-skill-sync.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import {
+ listAcpxSkills,
+ syncAcpxSkills,
+} from "@paperclipai/adapter-acpx-local/server";
+
+describe("acpx local skill sync", () => {
+ const paperclipKey = "paperclipai/paperclip/paperclip";
+ const createAgentKey = "paperclipai/paperclip/paperclip-create-agent";
+
+ it("reports ACPX Claude skills as supported runtime-mounted state", async () => {
+ const snapshot = await listAcpxSkills({
+ agentId: "agent-1",
+ companyId: "company-1",
+ adapterType: "acpx_local",
+ config: {
+ agent: "claude",
+ paperclipSkillSync: {
+ desiredSkills: [paperclipKey],
+ },
+ },
+ });
+
+ expect(snapshot.adapterType).toBe("acpx_local");
+ expect(snapshot.supported).toBe(true);
+ expect(snapshot.mode).toBe("ephemeral");
+ expect(snapshot.desiredSkills).toContain(paperclipKey);
+ expect(snapshot.desiredSkills).toContain(createAgentKey);
+ expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("configured");
+ expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.detail).toContain("ACPX Claude session");
+ expect(snapshot.warnings).toEqual([]);
+ });
+
+ it("reports ACPX Codex skills with Codex home runtime detail", async () => {
+ const snapshot = await syncAcpxSkills({
+ agentId: "agent-2",
+ companyId: "company-1",
+ adapterType: "acpx_local",
+ config: {
+ agent: "codex",
+ paperclipSkillSync: {
+ desiredSkills: ["paperclip"],
+ },
+ },
+ }, ["paperclip"]);
+
+ expect(snapshot.supported).toBe(true);
+ expect(snapshot.mode).toBe("ephemeral");
+ expect(snapshot.desiredSkills).toContain(paperclipKey);
+ expect(snapshot.desiredSkills).not.toContain("paperclip");
+ expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("configured");
+ expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.detail).toContain("CODEX_HOME/skills/");
+ expect(snapshot.warnings).toEqual([]);
+ });
+
+ it("keeps ACPX custom skill selection tracked but unsupported", async () => {
+ const snapshot = await listAcpxSkills({
+ agentId: "agent-3",
+ companyId: "company-1",
+ adapterType: "acpx_local",
+ config: {
+ agent: "custom",
+ paperclipSkillSync: {
+ desiredSkills: [paperclipKey],
+ },
+ },
+ });
+
+ expect(snapshot.supported).toBe(false);
+ expect(snapshot.mode).toBe("unsupported");
+ expect(snapshot.desiredSkills).toContain(paperclipKey);
+ expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.desired).toBe(true);
+ expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.detail).toContain("stored in Paperclip only");
+ expect(snapshot.warnings).toContain(
+ "Custom ACP commands do not expose a Paperclip skill integration contract yet; selected skills are tracked only.",
+ );
+ });
+});
diff --git a/server/src/__tests__/adapter-routes.test.ts b/server/src/__tests__/adapter-routes.test.ts
index eede2af23c..6fa67915a9 100644
--- a/server/src/__tests__/adapter-routes.test.ts
+++ b/server/src/__tests__/adapter-routes.test.ts
@@ -202,6 +202,11 @@ describe("adapter routes", () => {
const codexLocal = res.body.find((a: any) => a.type === "codex_local");
expect(codexLocal).toBeDefined();
expect(codexLocal.capabilities.supportsSkills).toBe(true);
+
+ // acpx_local exposes runtime-aware skill snapshots for Claude/Codex/custom ACP agents
+ const acpxLocal = res.body.find((a: any) => a.type === "acpx_local");
+ expect(acpxLocal).toBeDefined();
+ expect(acpxLocal.capabilities.supportsSkills).toBe(true);
});
it("uses the active adapter when resolving config schema for a paused builtin override", async () => {
@@ -225,6 +230,31 @@ describe("adapter routes", () => {
});
});
+ it("serves the built-in acpx_local config schema", async () => {
+ const app = createApp();
+
+ const res = await request(app).get("/api/adapters/acpx_local/config-schema");
+
+ expect(res.status, JSON.stringify(res.body)).toBe(200);
+ expect(res.body.fields).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ key: "agent",
+ default: "claude",
+ options: expect.arrayContaining([
+ expect.objectContaining({ value: "claude" }),
+ expect.objectContaining({ value: "codex" }),
+ expect.objectContaining({ value: "custom" }),
+ ]),
+ }),
+ expect.objectContaining({
+ key: "permissionMode",
+ default: "approve-all",
+ }),
+ ]),
+ );
+ });
+
it("rejects signed-in users without org access", async () => {
const app = createApp({
userId: "outsider-1",
diff --git a/server/src/__tests__/adapter-session-codecs.test.ts b/server/src/__tests__/adapter-session-codecs.test.ts
index 27efe287ba..10905e5193 100644
--- a/server/src/__tests__/adapter-session-codecs.test.ts
+++ b/server/src/__tests__/adapter-session-codecs.test.ts
@@ -13,6 +13,7 @@ import {
sessionCodec as opencodeSessionCodec,
isOpenCodeUnknownSessionError,
} from "@paperclipai/adapter-opencode-local/server";
+import { sessionCodec as acpxSessionCodec } from "@paperclipai/adapter-acpx-local/server";
describe("adapter session codecs", () => {
it("normalizes claude session params with cwd", () => {
@@ -107,6 +108,50 @@ describe("adapter session codecs", () => {
});
expect(geminiSessionCodec.getDisplayId?.(serialized ?? null)).toBe("gemini-session-1");
});
+
+ it("preserves acpx session params required for compatibility checks", () => {
+ const parsed = acpxSessionCodec.deserialize({
+ sessionKey: "paperclip:company:agent:task:fingerprint",
+ runtimeSessionName: "runtime-session-1",
+ acpxRecordId: "record-1",
+ acpSessionId: "acp-session-1",
+ agentSessionId: "agent-session-1",
+ agent: "claude",
+ cwd: "/tmp/acpx",
+ mode: "persistent",
+ stateDir: "/tmp/acpx-state",
+ configFingerprint: "fingerprint",
+ workspaceId: "workspace-1",
+ repoUrl: "https://example.com/repo.git",
+ repoRef: "main",
+ remoteExecution: {
+ environmentId: "environment-1",
+ leaseId: "lease-1",
+ },
+ });
+
+ expect(parsed).toMatchObject({
+ sessionKey: "paperclip:company:agent:task:fingerprint",
+ runtimeSessionName: "runtime-session-1",
+ acpxRecordId: "record-1",
+ acpSessionId: "acp-session-1",
+ agentSessionId: "agent-session-1",
+ agent: "claude",
+ cwd: "/tmp/acpx",
+ mode: "persistent",
+ stateDir: "/tmp/acpx-state",
+ configFingerprint: "fingerprint",
+ workspaceId: "workspace-1",
+ repoUrl: "https://example.com/repo.git",
+ repoRef: "main",
+ remoteExecution: {
+ environmentId: "environment-1",
+ leaseId: "lease-1",
+ },
+ });
+ expect(acpxSessionCodec.serialize(parsed)).toEqual(parsed);
+ expect(acpxSessionCodec.getDisplayId?.(parsed)).toBe("runtime-session-1");
+ });
});
describe("codex resume recovery detection", () => {
diff --git a/server/src/__tests__/agent-skills-routes.test.ts b/server/src/__tests__/agent-skills-routes.test.ts
index 4dd60ce861..84537a9b10 100644
--- a/server/src/__tests__/agent-skills-routes.test.ts
+++ b/server/src/__tests__/agent-skills-routes.test.ts
@@ -362,6 +362,99 @@ describe.sequential("agent skill routes", () => {
expect(res.status, JSON.stringify(res.body)).toBe(200);
});
+ it("passes ACPX Claude config through the agent skill listing route", async () => {
+ mockAgentService.getById.mockResolvedValue({
+ ...makeAgent("acpx_local"),
+ adapterConfig: { agent: "claude" },
+ });
+ mockSecretService.resolveAdapterConfigForRuntime.mockResolvedValueOnce({
+ config: { agent: "claude" },
+ });
+ mockAdapter.listSkills.mockResolvedValue({
+ adapterType: "acpx_local",
+ supported: true,
+ mode: "ephemeral",
+ desiredSkills: ["paperclipai/paperclip/paperclip"],
+ entries: [],
+ warnings: [],
+ });
+
+ const res = await requestApp(
+ await createApp(),
+ (baseUrl) => request(baseUrl)
+ .get("/api/agents/11111111-1111-4111-8111-111111111111/skills?companyId=company-1"),
+ );
+
+ expect(res.status, JSON.stringify(res.body)).toBe(200);
+ expect(mockCompanySkillService.listRuntimeSkillEntries).toHaveBeenCalledWith("company-1", {
+ materializeMissing: false,
+ });
+ expect(mockAdapter.listSkills).toHaveBeenCalledWith(
+ expect.objectContaining({
+ adapterType: "acpx_local",
+ config: expect.objectContaining({
+ agent: "claude",
+ paperclipRuntimeSkills: expect.any(Array),
+ }),
+ }),
+ );
+ });
+
+ it("persists ACPX Codex desired skills through the agent skill sync route", async () => {
+ mockAgentService.getById.mockResolvedValue({
+ ...makeAgent("acpx_local"),
+ adapterConfig: { agent: "codex" },
+ });
+ mockAgentService.update.mockImplementationOnce(async (_id: string, patch: Record<string, unknown>) => ({
+ ...makeAgent("acpx_local"),
+ adapterConfig: patch.adapterConfig ?? {},
+ }));
+ mockSecretService.resolveAdapterConfigForRuntime.mockResolvedValueOnce({
+ config: {
+ agent: "codex",
+ paperclipSkillSync: {
+ desiredSkills: ["paperclipai/paperclip/paperclip"],
+ },
+ },
+ });
+ mockAdapter.syncSkills.mockResolvedValue({
+ adapterType: "acpx_local",
+ supported: true,
+ mode: "ephemeral",
+ desiredSkills: ["paperclipai/paperclip/paperclip"],
+ entries: [],
+ warnings: [],
+ });
+
+ const res = await requestApp(await createApp(), (baseUrl) => request(baseUrl)
+ .post("/api/agents/11111111-1111-4111-8111-111111111111/skills/sync?companyId=company-1")
+ .send({ desiredSkills: ["paperclip"] }));
+
+ expect(res.status, JSON.stringify(res.body)).toBe(200);
+ expect(mockAgentService.update).toHaveBeenCalledWith(
+ expect.any(String),
+ expect.objectContaining({
+ adapterConfig: expect.objectContaining({
+ agent: "codex",
+ paperclipSkillSync: expect.objectContaining({
+ desiredSkills: ["paperclipai/paperclip/paperclip"],
+ }),
+ }),
+ }),
+ expect.any(Object),
+ );
+ expect(mockAdapter.syncSkills).toHaveBeenCalledWith(
+ expect.objectContaining({
+ adapterType: "acpx_local",
+ config: expect.objectContaining({
+ agent: "codex",
+ paperclipRuntimeSkills: expect.any(Array),
+ }),
+ }),
+ ["paperclipai/paperclip/paperclip"],
+ );
+ });
+
it("keeps runtime materialization for persistent skill adapters", async () => {
mockAgentService.getById.mockResolvedValue(makeAgent("cursor"));
mockAdapter.listSkills.mockResolvedValue({
diff --git a/server/src/__tests__/redaction.test.ts b/server/src/__tests__/redaction.test.ts
index e22eb597ab..e5b00cff25 100644
--- a/server/src/__tests__/redaction.test.ts
+++ b/server/src/__tests__/redaction.test.ts
@@ -84,4 +84,51 @@ describe("redaction", () => {
expect(result).not.toContain(githubToken);
expect(result).not.toContain(jwt);
});
+
+ it("redacts inline secrets from command metadata without hiding safe command text", () => {
+ const input = {
+ command: "custom-acp --token ghp_example_secret env OPENAI_API_KEY=sk-live-example custom-acp",
+ commandArgs: ["--safe", "ok", "--token", "ghp_arg_secret", "--api-key=sk-inline-example"],
+ env: {
+ PAPERCLIP_RESOLVED_COMMAND: "env OPENAI_API_KEY=sk-live-example custom-acp --token ghp_example_secret",
+ SAFE_VALUE: "visible",
+ },
+ };
+
+ const result = redactEventPayload(input);
+
+ expect(result?.command).toBe(
+ `custom-acp --token ${REDACTED_EVENT_VALUE} env OPENAI_API_KEY=${REDACTED_EVENT_VALUE} custom-acp`,
+ );
+ expect(result?.commandArgs).toEqual([
+ "--safe",
+ "ok",
+ "--token",
+ REDACTED_EVENT_VALUE,
+ `--api-key=${REDACTED_EVENT_VALUE}`,
+ ]);
+ expect(result?.env).toEqual({
+ PAPERCLIP_RESOLVED_COMMAND:
+ `env OPENAI_API_KEY=${REDACTED_EVENT_VALUE} custom-acp --token ${REDACTED_EVENT_VALUE}`,
+ SAFE_VALUE: "visible",
+ });
+ });
+
+ it("redacts non-string command args after secret flags", () => {
+ const result = redactEventPayload({
+ commandArgs: ["--api-key", { nested: "secret-value" }, "safe-next"],
+ });
+
+ expect(result?.commandArgs).toEqual(["--api-key", REDACTED_EVENT_VALUE, "safe-next"]);
+ });
+
+ it("does not treat bare args payloads as command args", () => {
+ const result = redactEventPayload({
+ args: ["--api-key", "not-a-command-secret"],
+ argv: ["--api-key", "command-secret"],
+ });
+
+ expect(result?.args).toEqual(["--api-key", "not-a-command-secret"]);
+ expect(result?.argv).toEqual(["--api-key", REDACTED_EVENT_VALUE]);
+ });
});
diff --git a/server/src/adapters/builtin-adapter-types.ts b/server/src/adapters/builtin-adapter-types.ts
index 463a56945f..3028ae0c09 100644
--- a/server/src/adapters/builtin-adapter-types.ts
+++ b/server/src/adapters/builtin-adapter-types.ts
@@ -2,6 +2,7 @@
* Adapter types shipped with Paperclip. External plugins must not replace these.
*/
export const BUILTIN_ADAPTER_TYPES = new Set([
+ "acpx_local",
"claude_local",
"codex_local",
"cursor",
diff --git a/server/src/adapters/registry.ts b/server/src/adapters/registry.ts
index 94c38e2952..359aecd4bd 100644
--- a/server/src/adapters/registry.ts
+++ b/server/src/adapters/registry.ts
@@ -1,5 +1,14 @@
import type { AdapterModelProfileDefinition, ServerAdapterModule } from "./types.js";
import { getAdapterSessionManagement } from "@paperclipai/adapter-utils";
+import {
+ execute as acpxExecute,
+ testEnvironment as acpxTestEnvironment,
+ sessionCodec as acpxSessionCodec,
+ getConfigSchema as getAcpxConfigSchema,
+ listAcpxSkills,
+ syncAcpxSkills,
+} from "@paperclipai/adapter-acpx-local/server";
+import { agentConfigurationDoc as acpxAgentConfigurationDoc } from "@paperclipai/adapter-acpx-local";
import {
execute as claudeExecute,
listClaudeSkills,
@@ -154,6 +163,22 @@ const claudeLocalAdapter: ServerAdapterModule = {
getQuotaWindows: claudeGetQuotaWindows,
};
+const acpxLocalAdapter: ServerAdapterModule = {
+ type: "acpx_local",
+ execute: acpxExecute,
+ testEnvironment: acpxTestEnvironment,
+ listSkills: listAcpxSkills,
+ syncSkills: syncAcpxSkills,
+ sessionCodec: acpxSessionCodec,
+ sessionManagement: getAdapterSessionManagement("acpx_local") ?? undefined,
+ supportsLocalAgentJwt: true,
+ supportsInstructionsBundle: true,
+ instructionsPathKey: "instructionsFilePath",
+ requiresMaterializedRuntimeSkills: false,
+ agentConfigurationDoc: acpxAgentConfigurationDoc,
+ getConfigSchema: getAcpxConfigSchema,
+};
+
const codexLocalAdapter: ServerAdapterModule = {
type: "codex_local",
execute: codexExecute,
@@ -335,6 +360,7 @@ const pausedOverrides = new Set<string>();
function registerBuiltInAdapters() {
for (const adapter of [
+ acpxLocalAdapter,
claudeLocalAdapter,
codexLocalAdapter,
openCodeLocalAdapter,
diff --git a/server/src/adapters/utils.ts b/server/src/adapters/utils.ts
index da3767dd27..a2682f235c 100644
--- a/server/src/adapters/utils.ts
+++ b/server/src/adapters/utils.ts
@@ -64,7 +64,8 @@ export function buildInvocationEnvForLogs(
const resolvedCommand = options.resolvedCommand?.trim();
if (resolvedCommand) {
- merged[options.resolvedCommandEnvKey ?? "PAPERCLIP_RESOLVED_COMMAND"] = resolvedCommand;
+ merged[options.resolvedCommandEnvKey ?? "PAPERCLIP_RESOLVED_COMMAND"] =
+ serverUtils.redactCommandTextForLogs(resolvedCommand);
}
return redactEnvForLogs(merged);
diff --git a/server/src/redaction.ts b/server/src/redaction.ts
index 75ebd56e3e..f3877a8b0b 100644
--- a/server/src/redaction.ts
+++ b/server/src/redaction.ts
@@ -1,12 +1,13 @@
+import { redactCommandText } from "@paperclipai/adapter-utils";
+
const SECRET_PAYLOAD_KEY_RE =
/(api[-_]?key|access[-_]?token|auth(?:_?token)?|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)/i;
+const COMMAND_PAYLOAD_KEY_RE =
+ /(^command$|^cmd$|command[-_]?line|resolved[-_]?command|PAPERCLIP_RESOLVED_COMMAND)/i;
+const COMMAND_ARGS_PAYLOAD_KEY_RE = /^(commandArgs|command_?args|argv)$/i;
const JWT_VALUE_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)?$/;
-const JWT_TEXT_RE = /\b[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}(?:\.[A-Za-z0-9_-]{8,})?\b/g;
-const OPENAI_KEY_TEXT_RE = /\bsk-[A-Za-z0-9_-]{12,}\b/g;
-const GITHUB_TOKEN_TEXT_RE = /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g;
-const AUTHORIZATION_BEARER_TEXT_RE = /(\bAuthorization\s*:\s*Bearer\s+)[^\s"'`]+/gi;
-const ENV_SECRET_ASSIGNMENT_TEXT_RE =
- /(\b[A-Za-z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD|PASSWD|AUTHORIZATION|JWT)[A-Za-z0-9_]*\s*=\s*)[^\s"'`]+/gi;
+const CLI_SECRET_FLAG_RE =
+ /^-{1,2}(?:api[-_]?key|(?:access[-_]?|auth[-_]?)?token|token|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)$/i;
const JSON_SECRET_FIELD_TEXT_RE =
/((?:"|')?(?:api[-_]?key|access[-_]?token|auth(?:_?token)?|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)(?:"|')?\s*:\s*(?:"|'))[^"'`\r\n]+((?:"|'))/gi;
const ESCAPED_JSON_SECRET_FIELD_TEXT_RE =
@@ -38,9 +39,33 @@ function isPlainBinding(value: unknown): value is { type: "plain"; value: unknow
return value.type === "plain" && "value" in value;
}
+function sanitizeCommandArgs(args: unknown[]): unknown[] {
+ let redactNext = false;
+ return args.map((arg) => {
+ if (redactNext) {
+ redactNext = false;
+ return REDACTED_EVENT_VALUE;
+ }
+ if (typeof arg !== "string") return sanitizeValue(arg);
+ if (CLI_SECRET_FLAG_RE.test(arg.trim())) {
+ redactNext = true;
+ return arg;
+ }
+ return redactSensitiveText(arg);
+ });
+}
+
export function sanitizeRecord(record: Record<string, unknown>): Record<string, unknown> {
const redacted: Record<string, unknown> = {};
for (const [key, value] of Object.entries(record)) {
+ if (COMMAND_ARGS_PAYLOAD_KEY_RE.test(key) && Array.isArray(value)) {
+ redacted[key] = sanitizeCommandArgs(value);
+ continue;
+ }
+ if (COMMAND_PAYLOAD_KEY_RE.test(key) && typeof value === "string") {
+ redacted[key] = redactSensitiveText(value);
+ continue;
+ }
if (SECRET_PAYLOAD_KEY_RE.test(key)) {
if (isSecretRefBinding(value)) {
redacted[key] = sanitizeValue(value);
@@ -69,12 +94,10 @@ export function redactEventPayload(payload: Record<string, unknown> | null): Rec
}
export function redactSensitiveText(input: string): string {
- return input
- .replace(AUTHORIZATION_BEARER_TEXT_RE, `$1${REDACTED_EVENT_VALUE}`)
- .replace(JSON_SECRET_FIELD_TEXT_RE, `$1${REDACTED_EVENT_VALUE}$2`)
- .replace(ESCAPED_JSON_SECRET_FIELD_TEXT_RE, `$1${REDACTED_EVENT_VALUE}$2`)
- .replace(ENV_SECRET_ASSIGNMENT_TEXT_RE, `$1${REDACTED_EVENT_VALUE}`)
- .replace(OPENAI_KEY_TEXT_RE, REDACTED_EVENT_VALUE)
- .replace(GITHUB_TOKEN_TEXT_RE, REDACTED_EVENT_VALUE)
- .replace(JWT_TEXT_RE, REDACTED_EVENT_VALUE);
+ return redactCommandText(
+ input
+ .replace(JSON_SECRET_FIELD_TEXT_RE, `$1${REDACTED_EVENT_VALUE}$2`)
+ .replace(ESCAPED_JSON_SECRET_FIELD_TEXT_RE, `$1${REDACTED_EVENT_VALUE}$2`),
+ REDACTED_EVENT_VALUE,
+ );
}
diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.ts
index 2dbe8ad825..6b663a85f5 100644
--- a/server/src/routes/agents.ts
+++ b/server/src/routes/agents.ts
@@ -72,6 +72,12 @@ import { redactCurrentUserValue } from "../log-redaction.js";
import { renderOrgChartSvg, renderOrgChartPng, type OrgNode, type OrgChartStyle, ORG_CHART_STYLES } from "./org-chart-svg.js";
import { instanceSettingsService } from "../services/instance-settings.js";
import { runClaudeLogin } from "@paperclipai/adapter-claude-local/server";
+import {
+ DEFAULT_ACPX_LOCAL_AGENT,
+ DEFAULT_ACPX_LOCAL_MODE,
+ DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS,
+ DEFAULT_ACPX_LOCAL_PERMISSION_MODE,
+} from "@paperclipai/adapter-acpx-local";
import {
DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX,
DEFAULT_CODEX_LOCAL_MODEL,
@@ -110,6 +116,7 @@ export function agentRoutes(
// Legacy hardcoded maps — used as fallback when adapter module does not
// declare capability flags explicitly.
const DEFAULT_INSTRUCTIONS_PATH_KEYS: Record<string, string> = {
+ acpx_local: "instructionsFilePath",
claude_local: "instructionsFilePath",
codex_local: "instructionsFilePath",
droid_local: "instructionsFilePath",
@@ -826,6 +833,21 @@ export function agentRoutes(
adapterConfig: Record<string, unknown>,
): Record<string, unknown> {
const next = { ...adapterConfig };
+ if (adapterType === "acpx_local") {
+ if (!asNonEmptyString(next.agent)) {
+ next.agent = DEFAULT_ACPX_LOCAL_AGENT;
+ }
+ if (!asNonEmptyString(next.mode)) {
+ next.mode = DEFAULT_ACPX_LOCAL_MODE;
+ }
+ if (!asNonEmptyString(next.permissionMode)) {
+ next.permissionMode = DEFAULT_ACPX_LOCAL_PERMISSION_MODE;
+ }
+ if (!asNonEmptyString(next.nonInteractivePermissions)) {
+ next.nonInteractivePermissions = DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS;
+ }
+ return ensureGatewayDeviceKey(adapterType, next);
+ }
if (adapterType === "codex_local") {
if (!asNonEmptyString(next.model)) {
next.model = DEFAULT_CODEX_LOCAL_MODEL;
diff --git a/server/src/services/environment-execution-target.ts b/server/src/services/environment-execution-target.ts
index 49ceac60d2..0f2f70db53 100644
--- a/server/src/services/environment-execution-target.ts
+++ b/server/src/services/environment-execution-target.ts
@@ -34,6 +34,7 @@ export async function resolveEnvironmentExecutionTarget(input: {
if (input.environment.driver === "sandbox") {
if (
+ input.adapterType !== "acpx_local" &&
input.adapterType !== "codex_local" &&
input.adapterType !== "claude_local" &&
input.adapterType !== "gemini_local" &&
@@ -106,6 +107,7 @@ export async function resolveEnvironmentExecutionTarget(input: {
if (
(
input.adapterType !== "codex_local" &&
+ input.adapterType !== "acpx_local" &&
input.adapterType !== "claude_local" &&
input.adapterType !== "gemini_local" &&
input.adapterType !== "opencode_local" &&
diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts
index a76b15a814..f7c0a220bd 100644
--- a/server/src/services/heartbeat.ts
+++ b/server/src/services/heartbeat.ts
@@ -121,6 +121,7 @@ import { recoveryService } from "./recovery/service.js";
import { productivityReviewService } from "./productivity-review.js";
import { withAgentStartLock } from "./agent-start-lock.js";
import { redactCurrentUserText, redactCurrentUserValue } from "../log-redaction.js";
+import { redactEventPayload } from "../redaction.js";
import {
hasSessionCompactionThresholds,
resolveSessionCompactionPolicy,
@@ -3118,9 +3119,10 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
const boundedPayload = event.payload
? boundHeartbeatRunEventPayloadForStorage(event.payload)
: event.payload;
- const sanitizedPayload = boundedPayload
- ? redactCurrentUserValue(boundedPayload, currentUserRedactionOptions)
- : boundedPayload;
+ const secretSanitizedPayload = boundedPayload ? redactEventPayload(boundedPayload) : boundedPayload;
+ const sanitizedPayload = secretSanitizedPayload
+ ? redactCurrentUserValue(secretSanitizedPayload, currentUserRedactionOptions)
+ : secretSanitizedPayload;
await db.insert(heartbeatRunEvents).values({
companyId: run.companyId,
diff --git a/ui/package.json b/ui/package.json
index dda6e7154b..6160df07d9 100644
--- a/ui/package.json
+++ b/ui/package.json
@@ -34,6 +34,7 @@
"@dnd-kit/utilities": "^3.2.2",
"@lexical/link": "0.35.0",
"@mdxeditor/editor": "^3.52.4",
+ "@paperclipai/adapter-acpx-local": "workspace:*",
"@paperclipai/adapter-claude-local": "workspace:*",
"@paperclipai/adapter-codex-local": "workspace:*",
"@paperclipai/adapter-cursor-local": "workspace:*",
diff --git a/ui/src/adapters/acpx-local/index.ts b/ui/src/adapters/acpx-local/index.ts
new file mode 100644
index 0000000000..d8ae9675e0
--- /dev/null
+++ b/ui/src/adapters/acpx-local/index.ts
@@ -0,0 +1,11 @@
+import type { UIAdapterModule } from "../types";
+import { parseAcpxStdoutLine, buildAcpxLocalConfig } from "@paperclipai/adapter-acpx-local/ui";
+import { SchemaConfigFields } from "../schema-config-fields";
+
+export const acpxLocalUIAdapter: UIAdapterModule = {
+ type: "acpx_local",
+ label: "ACPX (local)",
+ parseStdoutLine: parseAcpxStdoutLine,
+ ConfigFields: SchemaConfigFields,
+ buildAdapterConfig: buildAcpxLocalConfig,
+};
diff --git a/ui/src/adapters/adapter-display-registry.ts b/ui/src/adapters/adapter-display-registry.ts
index fe80927396..d75da55724 100644
--- a/ui/src/adapters/adapter-display-registry.ts
+++ b/ui/src/adapters/adapter-display-registry.ts
@@ -49,9 +49,18 @@ export interface AdapterDisplayInfo {
recommended?: boolean;
comingSoon?: boolean;
disabledLabel?: string;
+ experimental?: boolean;
+ hideFromVisualSelection?: boolean;
}
const adapterDisplayMap: Record<string, AdapterDisplayInfo> = {
+ acpx_local: {
+ label: "ACPX",
+ description: "Experimental local ACPX multi-agent adapter",
+ icon: Bot,
+ experimental: true,
+ hideFromVisualSelection: true,
+ },
claude_local: {
label: "Claude Code",
description: "Local Claude agent",
diff --git a/ui/src/adapters/metadata.test.ts b/ui/src/adapters/metadata.test.ts
index 70b7ef3c96..c08c2f2142 100644
--- a/ui/src/adapters/metadata.test.ts
+++ b/ui/src/adapters/metadata.test.ts
@@ -1,5 +1,10 @@
import { describe, expect, it } from "vitest";
-import { isEnabledAdapterType, listAdapterOptions } from "./metadata";
+import {
+ isEnabledAdapterType,
+ isValidAdapterType,
+ isVisualAdapterChoice,
+ listAdapterOptions,
+} from "./metadata";
import type { UIAdapterModule } from "./types";
const externalAdapter: UIAdapterModule = {
@@ -22,6 +27,7 @@ describe("adapter metadata", () => {
label: "external_test",
comingSoon: false,
hidden: false,
+ experimental: false,
},
]);
});
@@ -30,4 +36,27 @@ describe("adapter metadata", () => {
expect(isEnabledAdapterType("process")).toBe(false);
expect(isEnabledAdapterType("http")).toBe(false);
});
-});
\ No newline at end of file
+
+ it("keeps ACPX selectable from explicit configuration but out of visual pickers", () => {
+ expect(isEnabledAdapterType("acpx_local")).toBe(true);
+ expect(isValidAdapterType("acpx_local")).toBe(true);
+ expect(isVisualAdapterChoice("acpx_local")).toBe(false);
+
+ expect(
+ listAdapterOptions((type) => type, [
+ {
+ ...externalAdapter,
+ type: "acpx_local",
+ },
+ ]),
+ ).toEqual([
+ {
+ value: "acpx_local",
+ label: "acpx_local",
+ comingSoon: false,
+ hidden: false,
+ experimental: true,
+ },
+ ]);
+ });
+});
diff --git a/ui/src/adapters/metadata.ts b/ui/src/adapters/metadata.ts
index 297a7237c3..d19d0093ac 100644
--- a/ui/src/adapters/metadata.ts
+++ b/ui/src/adapters/metadata.ts
@@ -15,6 +15,7 @@ export interface AdapterOptionMetadata {
label: string;
comingSoon: boolean;
hidden: boolean;
+ experimental: boolean;
}
export function listKnownAdapterTypes(): string[] {
@@ -43,6 +44,15 @@ export function isValidAdapterType(type: string): boolean {
return true;
}
+/**
+ * Check whether an adapter should appear in card-style visual pickers.
+ * Experimental adapters can remain selectable from explicit configuration
+ * dropdowns without being recommended during onboarding or setup flows.
+ */
+export function isVisualAdapterChoice(type: string): boolean {
+ return !getAdapterDisplay(type).hideFromVisualSelection;
+}
+
/**
* Build option metadata for a list of adapters (for dropdowns).
* `labelFor` callback allows callers to override labels; defaults to display registry.
@@ -57,6 +67,7 @@ export function listAdapterOptions(
label: getLabel(adapter.type),
comingSoon: !!getAdapterDisplay(adapter.type).comingSoon,
hidden: isAdapterTypeHidden(adapter.type),
+ experimental: !!getAdapterDisplay(adapter.type).experimental,
}));
}
diff --git a/ui/src/adapters/registry.ts b/ui/src/adapters/registry.ts
index e8e24eafed..d53eaaaea2 100644
--- a/ui/src/adapters/registry.ts
+++ b/ui/src/adapters/registry.ts
@@ -1,4 +1,5 @@
import type { UIAdapterModule } from "./types";
+import { acpxLocalUIAdapter } from "./acpx-local";
import { claudeLocalUIAdapter } from "./claude-local";
import { codexLocalUIAdapter } from "./codex-local";
import { cursorLocalUIAdapter } from "./cursor";
@@ -49,6 +50,7 @@ setDynamicParserResultNotifier(notifyAdapterChange);
function registerBuiltInUIAdapters() {
for (const adapter of [
+ acpxLocalUIAdapter,
claudeLocalUIAdapter,
codexLocalUIAdapter,
geminiLocalUIAdapter,
diff --git a/ui/src/adapters/use-adapter-capabilities.ts b/ui/src/adapters/use-adapter-capabilities.ts
index 631c01f3d9..786776fe75 100644
--- a/ui/src/adapters/use-adapter-capabilities.ts
+++ b/ui/src/adapters/use-adapter-capabilities.ts
@@ -16,6 +16,7 @@ const ALL_FALSE: AdapterCapabilities = {
* return correct values on first render before the /api/adapters call resolves.
*/
const KNOWN_DEFAULTS: Record<string, AdapterCapabilities> = {
+ acpx_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: false, supportsModelProfiles: false },
claude_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: false, supportsModelProfiles: true },
codex_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: false, supportsModelProfiles: true },
cursor: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: true },
diff --git a/ui/src/components/AgentConfigForm.tsx b/ui/src/components/AgentConfigForm.tsx
index f1af84a6eb..c36463ab9f 100644
--- a/ui/src/components/AgentConfigForm.tsx
+++ b/ui/src/components/AgentConfigForm.tsx
@@ -52,7 +52,7 @@ import { ReportsToPicker } from "./ReportsToPicker";
import { EnvVarEditor } from "./EnvVarEditor";
import { shouldShowLegacyWorkingDirectoryField } from "../lib/legacy-agent-config";
import { listAdapterOptions, listVisibleAdapterTypes } from "../adapters/metadata";
-import { getAdapterLabel } from "../adapters/adapter-display-registry";
+import { getAdapterDisplay, getAdapterLabel } from "../adapters/adapter-display-registry";
import { useDisabledAdaptersSync } from "../adapters/use-disabled-adapters";
import { buildAgentUpdatePatch, type AgentConfigOverlay } from "../lib/agent-config-patch";
import { useAdapterCapabilities } from "../adapters/use-adapter-capabilities";
@@ -1239,6 +1239,7 @@ function AdapterTypeDropdown({
disabledTypes: Set<string>;
}) {
const [open, setOpen] = useState(false);
+ const selectedDisplay = getAdapterDisplay(value);
const adapterList = useMemo(
() =>
listAdapterOptions((type) => adapterLabels[type] ?? getAdapterLabel(type)).filter(
@@ -1251,9 +1252,10 @@ function AdapterTypeDropdown({
<Popover open={open} onOpenChange={setOpen}>
<PopoverTrigger asChild>
<button className="inline-flex items-center gap-1.5 rounded-md border border-border px-2.5 py-1.5 text-sm hover:bg-accent/50 transition-colors w-full justify-between">
- <span className="inline-flex items-center gap-1.5">
+ <span className="inline-flex min-w-0 items-center gap-1.5">
{value === "opencode_local" ? <OpenCodeLogoIcon className="h-3.5 w-3.5" /> : null}
- <span>{adapterLabels[value] ?? getAdapterLabel(value)}</span>
+ <span className="truncate">{adapterLabels[value] ?? getAdapterLabel(value)}</span>
+ {selectedDisplay.experimental && <ExperimentalBadge />}
</span>
<ChevronDown className="h-3 w-3 text-muted-foreground" />
</button>
@@ -1280,6 +1282,7 @@ function AdapterTypeDropdown({
<span className="inline-flex items-center gap-1.5">
{item.value === "opencode_local" ? <OpenCodeLogoIcon className="h-3.5 w-3.5" /> : null}
<span>{item.label}</span>
+ {item.experimental && <ExperimentalBadge />}
</span>
{item.comingSoon && (
<span className="text-[10px] text-muted-foreground">Coming soon</span>
@@ -1291,6 +1294,14 @@ function AdapterTypeDropdown({
);
}
+function ExperimentalBadge() {
+ return (
+ <span className="shrink-0 rounded border border-amber-500/30 bg-amber-500/10 px-1.5 py-0.5 text-[10px] font-medium leading-none text-amber-700 dark:text-amber-200">
+ Experimental
+ </span>
+ );
+}
+
function ModelDropdown({
models,
value,
diff --git a/ui/src/components/NewAgentDialog.tsx b/ui/src/components/NewAgentDialog.tsx
index 4ff672c660..6400038de0 100644
--- a/ui/src/components/NewAgentDialog.tsx
+++ b/ui/src/components/NewAgentDialog.tsx
@@ -17,6 +17,7 @@ import {
} from "lucide-react";
import { cn } from "@/lib/utils";
import { listUIAdapters } from "../adapters";
+import { isVisualAdapterChoice } from "../adapters/metadata";
import { getAdapterDisplay } from "../adapters/adapter-display-registry";
import { useDisabledAdaptersSync } from "../adapters/use-disabled-adapters";
@@ -57,7 +58,11 @@ export function NewAgentDialog() {
// This automatically includes external/plugin adapters.
const adapterGrid = useMemo(() => {
const registered = listUIAdapters()
- .filter((a) => isAgentAdapterType(a.type) && !disabledTypes.has(a.type));
+ .filter((a) =>
+ isAgentAdapterType(a.type) &&
+ !disabledTypes.has(a.type) &&
+ isVisualAdapterChoice(a.type)
+ );
// Sort: recommended first, then alphabetical
return registered
diff --git a/ui/src/components/OnboardingWizard.tsx b/ui/src/components/OnboardingWizard.tsx
index 9ec608f337..5000d759d3 100644
--- a/ui/src/components/OnboardingWizard.tsx
+++ b/ui/src/components/OnboardingWizard.tsx
@@ -25,6 +25,7 @@ import {
} from "../lib/model-utils";
import { getUIAdapter } from "../adapters";
import { listUIAdapters } from "../adapters";
+import { isVisualAdapterChoice } from "../adapters/metadata";
import { useDisabledAdaptersSync } from "../adapters/use-disabled-adapters";
import { useAdapterCapabilities } from "../adapters/use-adapter-capabilities";
import { getAdapterDisplay } from "../adapters/adapter-display-registry";
@@ -209,7 +210,11 @@ export function OnboardingWizard() {
const { recommendedAdapters, moreAdapters } = useMemo(() => {
const SYSTEM_ADAPTER_TYPES = new Set(["process", "http"]);
const all = listUIAdapters()
- .filter((a) => !SYSTEM_ADAPTER_TYPES.has(a.type) && !disabledTypes.has(a.type))
+ .filter((a) =>
+ !SYSTEM_ADAPTER_TYPES.has(a.type) &&
+ !disabledTypes.has(a.type) &&
+ isVisualAdapterChoice(a.type)
+ )
.map((a) => ({ ...getAdapterDisplay(a.type), type: a.type }));
return {
diff --git a/ui/src/pages/AgentDetail.tsx b/ui/src/pages/AgentDetail.tsx
index 0eca94412b..d1dddfedd3 100644
--- a/ui/src/pages/AgentDetail.tsx
+++ b/ui/src/pages/AgentDetail.tsx
@@ -27,6 +27,7 @@ import { PageTabBar } from "../components/PageTabBar";
import { adapterLabels, roleLabels, help } from "../components/agent-config-primitives";
import { ToggleSwitch } from "@/components/ui/toggle-switch";
import { useAdapterCapabilities } from "@/adapters/use-adapter-capabilities";
+import { redactCommandText as redactCommandSecretText } from "@paperclipai/adapter-utils";
import { MarkdownEditor } from "../components/MarkdownEditor";
import { assetsApi } from "../api/assets";
import { getUIAdapter, buildTranscript, onAdapterChange } from "../adapters";
@@ -115,6 +116,7 @@ const RUN_LOG_PAGE_BYTES = 256_000;
const REDACTED_ENV_VALUE = "***REDACTED***";
const SECRET_ENV_KEY_RE =
/(api[-_]?key|access[-_]?token|auth(?:_?token)?|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)/i;
+const COMMAND_ENV_KEY_RE = /(^command$|^cmd$|command[-_]?line|resolved[-_]?command|PAPERCLIP_RESOLVED_COMMAND)/i;
const JWT_VALUE_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)?$/;
function redactPathText(value: string, censorUsernameInLogs: boolean) {
@@ -125,6 +127,10 @@ function redactPathValue<T>(value: T, censorUsernameInLogs: boolean): T {
return redactHomePathUserSegmentsInValue(value, { enabled: censorUsernameInLogs });
}
+function redactCommandText(value: string, censorUsernameInLogs: boolean): string {
+ return redactPathText(redactCommandSecretText(value, REDACTED_ENV_VALUE), censorUsernameInLogs);
+}
+
function shouldRedactSecretValue(key: string, value: unknown): boolean {
if (SECRET_ENV_KEY_RE.test(key)) return true;
if (typeof value !== "string") return false;
@@ -142,6 +148,7 @@ function redactEnvValue(key: string, value: unknown, censorUsernameInLogs: boole
}
if (shouldRedactSecretValue(key, value)) return REDACTED_ENV_VALUE;
if (value === null || value === undefined) return "";
+ if (typeof value === "string" && COMMAND_ENV_KEY_RE.test(key)) return redactCommandText(value, censorUsernameInLogs);
if (typeof value === "string") return redactPathText(value, censorUsernameInLogs);
try {
return JSON.stringify(redactPathValue(value, censorUsernameInLogs));
@@ -302,7 +309,7 @@ export function RunInvocationCard({
payload: Record<string, unknown>;
censorUsernameInLogs: boolean;
}) {
- const commandLine = [
+ const rawCommandLine = [
typeof payload.command === "string" ? payload.command : null,
...(Array.isArray(payload.commandArgs)
? payload.commandArgs.filter((value): value is string => typeof value === "string")
@@ -310,6 +317,7 @@ export function RunInvocationCard({
]
.filter((value): value is string => Boolean(value))
.join(" ");
+ const commandLine = rawCommandLine ? redactCommandText(rawCommandLine, censorUsernameInLogs) : "";
const hasAdvancedDetails =
commandLine.length > 0
@@ -2466,7 +2474,7 @@ function PromptEditorSkeleton() {
);
}
-function AgentSkillsTab({
+export function AgentSkillsTab({
agent,
companyId,
}: {
@@ -2649,11 +2657,18 @@ function AgentSkillsTab({
}, [skillSnapshot?.mode]);
const unsupportedSkillMessage = useMemo(() => {
if (skillSnapshot?.mode !== "unsupported") return null;
+ if (
+ agent.adapterType === "acpx_local" &&
+ typeof agent.adapterConfig.agent === "string" &&
+ agent.adapterConfig.agent === "custom"
+ ) {
+ return "Paperclip cannot manage skills for custom ACP commands yet.";
+ }
if (agent.adapterType === "openclaw_gateway") {
return "Paperclip cannot manage OpenClaw skills here. Visit your OpenClaw instance to manage this agent's skills.";
}
return "Paperclip cannot manage skills for this adapter yet. Manage them in the adapter directly.";
- }, [agent.adapterType, skillSnapshot?.mode]);
+ }, [agent.adapterConfig.agent, agent.adapterType, skillSnapshot?.mode]);
const hasUnsavedChanges = !arraysEqual(skillDraft, lastSavedSkills);
const saveStatusLabel = syncSkills.isPending
? "Saving changes..."
diff --git a/ui/storybook/.storybook/preview.tsx b/ui/storybook/.storybook/preview.tsx
index 3d0397d203..8871f5362e 100644
--- a/ui/storybook/.storybook/preview.tsx
+++ b/ui/storybook/.storybook/preview.tsx
@@ -26,6 +26,12 @@ import "@mdxeditor/editor/style.css";
import "./tailwind-entry.css";
import "./styles.css";
+// Install fetch monkeypatch eagerly so any module-load-time fetches (e.g. schema
+// caches in adapter config renderers) hit our fixtures before they reach the
+// network. Some renderers issue a fetch from useEffect on first paint, which
+// can otherwise race the StorybookProviders mount.
+installStorybookApiFixtures();
+
function installStorybookApiFixtures() {
if (typeof window === "undefined") return;
const currentWindow = window as typeof window & {
@@ -148,6 +154,16 @@ function installStorybookApiFixtures() {
return Response.json([]);
}
+ const adapterSchemaMatch = url.pathname.match(/^\/api\/adapters\/([^/]+)\/config-schema$/);
+ if (adapterSchemaMatch) {
+ const [, adapterType] = adapterSchemaMatch;
+ const schemas = (window as typeof window & {
+ __paperclipStorybookAdapterSchemas?: Record<string, unknown>;
+ }).__paperclipStorybookAdapterSchemas;
+ const schema = schemas?.[adapterType];
+ if (schema) return Response.json(schema);
+ }
+
const companyResourceMatch = url.pathname.match(/^\/api\/companies\/([^/]+)\/([^/]+)$/);
if (companyResourceMatch) {
const [, companyId, resource] = companyResourceMatch;
@@ -233,7 +249,6 @@ function StorybookProviders({
useEffect(() => {
applyStorybookTheme(theme);
- installStorybookApiFixtures();
}, [theme]);
return (
diff --git a/ui/storybook/stories/acpx-local.stories.tsx b/ui/storybook/stories/acpx-local.stories.tsx
new file mode 100644
index 0000000000..93d30ed23f
--- /dev/null
+++ b/ui/storybook/stories/acpx-local.stories.tsx
@@ -0,0 +1,896 @@
+import { useMemo, useState, type ReactNode } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useQueryClient } from "@tanstack/react-query";
+import type { AdapterConfigSchema, CreateConfigValues } from "@paperclipai/adapter-utils";
+import { parseAcpxStdoutLine } from "@paperclipai/adapter-acpx-local/ui";
+import type {
+ Agent,
+ AgentSkillSnapshot,
+ CompanySkillListItem,
+} from "@paperclipai/shared";
+import { SchemaConfigFields } from "@/adapters/schema-config-fields";
+import type { TranscriptEntry } from "@/adapters";
+import { RunTranscriptView } from "@/components/transcript/RunTranscriptView";
+import { AgentSkillsTab } from "@/pages/AgentDetail";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+import { queryKeys } from "@/lib/queryKeys";
+
+type SchemaWindow = typeof window & {
+ __paperclipStorybookAdapterSchemas?: Record<string, unknown>;
+};
+
+// Mirrors packages/adapters/acpx-local/src/server/config-schema.ts. Inlined so the
+// storybook bundle does not pull node-only imports from the adapter server entry.
+const acpxLocalConfigSchema: AdapterConfigSchema = {
+ fields: [
+ {
+ key: "agent",
+ label: "ACP agent",
+ type: "select",
+ default: "claude",
+ required: true,
+ options: [
+ { value: "claude", label: "Claude via ACPX" },
+ { value: "codex", label: "Codex via ACPX" },
+ { value: "custom", label: "Custom ACP command" },
+ ],
+ hint: "Choose the ACP agent launched through ACPX.",
+ },
+ {
+ key: "agentCommand",
+ label: "Agent command",
+ type: "text",
+ hint: "Required for custom agents; optional override for built-in Claude or Codex ACP commands.",
+ },
+ {
+ key: "mode",
+ label: "Session mode",
+ type: "select",
+ default: "persistent",
+ options: [
+ { value: "persistent", label: "Persistent" },
+ { value: "oneshot", label: "One shot" },
+ ],
+ },
+ {
+ key: "permissionMode",
+ label: "Permission mode",
+ type: "select",
+ default: "approve-all",
+ options: [
+ { value: "approve-all", label: "Approve all" },
+ { value: "default", label: "ACP default" },
+ ],
+ hint: "Defaults to maximum permissions: ACPX permission requests are auto-approved.",
+ },
+ {
+ key: "nonInteractivePermissions",
+ label: "Non-interactive permissions",
+ type: "select",
+ default: "deny",
+ options: [
+ { value: "deny", label: "Deny" },
+ { value: "fail", label: "Fail" },
+ ],
+ },
+ {
+ key: "cwd",
+ label: "Working directory",
+ type: "text",
+ hint: "Absolute fallback directory. Paperclip execution workspaces can override this at runtime.",
+ },
+ {
+ key: "stateDir",
+ label: "State directory",
+ type: "text",
+ hint: "Optional ACPX session state directory. Defaults to Paperclip-managed company/agent scoped storage.",
+ },
+ {
+ key: "instructionsFilePath",
+ label: "Instructions file",
+ type: "text",
+ hint: "Optional absolute path to markdown instructions injected into the run prompt.",
+ },
+ { key: "promptTemplate", label: "Prompt template", type: "textarea" },
+ { key: "bootstrapPromptTemplate", label: "Bootstrap prompt template", type: "textarea" },
+ { key: "timeoutSec", label: "Timeout seconds", type: "number", default: 0 },
+ {
+ key: "env",
+ label: "Environment JSON",
+ type: "textarea",
+ hint: "Optional JSON object of environment values or secret bindings.",
+ },
+ ],
+};
+
+function installAcpxSchemaMock(): void {
+ if (typeof window === "undefined") return;
+ const win = window as SchemaWindow;
+ win.__paperclipStorybookAdapterSchemas = {
+ ...(win.__paperclipStorybookAdapterSchemas ?? {}),
+ acpx_local: acpxLocalConfigSchema,
+ };
+}
+
+function ConfigSection({ title, description, children }: { title: string; description?: string; children: ReactNode }) {
+ return (
+ <Card className="shadow-none border-border">
+ <CardHeader>
+ <CardTitle className="text-base font-semibold">{title}</CardTitle>
+ {description && (
+ <p className="text-sm text-muted-foreground">{description}</p>
+ )}
+ </CardHeader>
+ <CardContent>
+ <div className="space-y-3">{children}</div>
+ </CardContent>
+ </Card>
+ );
+}
+
+function AcpxLocalConfigStory() {
+ installAcpxSchemaMock();
+
+ const [values, setValues] = useState<CreateConfigValues>(() => ({
+ name: "",
+ role: "",
+ title: "",
+ capabilities: "",
+ icon: "code",
+ adapterType: "acpx_local",
+ command: "",
+ promptTemplate: "",
+ bootstrapPromptTemplate: "",
+ instructionsFilePath: "",
+ extraArgs: "",
+ envVars: "",
+ envBindings: {},
+ runtimeServicesJson: "",
+ runtimeDesiredState: "manual",
+ runtimeServiceStates: {},
+ heartbeatEnabled: false,
+ intervalSec: 900,
+ wakeOnDemand: true,
+ cooldownSec: 60,
+ maxConcurrentRuns: 1,
+ pauseOnIdle: false,
+ idleTimeoutSec: 0,
+ runtimeMaxStuckHeartbeats: 0,
+ adapterSchemaValues: {},
+ } as unknown as CreateConfigValues));
+
+ return (
+ <div className="mx-auto max-w-3xl space-y-5 p-6">
+ <header className="space-y-2">
+ <Badge variant="outline" className="rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.18em]">
+ UX preview
+ </Badge>
+ <h1 className="text-2xl font-semibold tracking-tight">Agent config — acpx_local</h1>
+ <p className="text-sm text-muted-foreground">
+ Renders the schema-driven adapter config block exactly as the operator sees it inside the agent edit form.
+ Defaults reflect Phase 3 of PAP-2944: maximum-permission auto-approve, persistent session mode, Claude as the
+ default ACP agent.
+ </p>
+ </header>
+
+ <ConfigSection
+ title="Adapter configuration"
+ description="Schema fields rendered through the generic SchemaConfigFields component."
+ >
+ <SchemaConfigFields
+ mode="create"
+ isCreate
+ adapterType="acpx_local"
+ values={values}
+ set={(patch) => setValues((current) => ({ ...current, ...patch }))}
+ config={{}}
+ eff={(_group, _field, original) => original}
+ mark={() => {}}
+ models={[]}
+ />
+ </ConfigSection>
+
+ <ConfigSection title="Resolved values (debug)">
+ <pre className="whitespace-pre-wrap text-xs font-mono text-muted-foreground">
+ {JSON.stringify(values.adapterSchemaValues ?? {}, null, 2)}
+ </pre>
+ </ConfigSection>
+ </div>
+ );
+}
+
+const ACPX_TS_BASE = new Date("2026-04-30T15:30:00.000Z").getTime();
+
+function ts(offsetMs: number): string {
+ return new Date(ACPX_TS_BASE + offsetMs).toISOString();
+}
+
+function flattenLines(lines: Array<{ payload: Record<string, unknown>; offsetMs: number }>): TranscriptEntry[] {
+ const entries: TranscriptEntry[] = [];
+ for (const { payload, offsetMs } of lines) {
+ const parsed = parseAcpxStdoutLine(JSON.stringify(payload), ts(offsetMs));
+ entries.push(...parsed);
+ }
+ return entries;
+}
+
+function useAcpxTranscript(): TranscriptEntry[] {
+ return useMemo(
+ () =>
+ flattenLines([
+ {
+ offsetMs: 0,
+ payload: {
+ type: "acpx.session",
+ agent: "claude",
+ mode: "persistent",
+ permissionMode: "approve-all",
+ acpSessionId: "acp_session_42a8c1",
+ runtimeSessionName: "acpx-claude-PAP-1812",
+ },
+ },
+ {
+ offsetMs: 800,
+ payload: {
+ type: "acpx.status",
+ tag: "context_window",
+ used: 12000,
+ size: 200000,
+ },
+ },
+ {
+ offsetMs: 1200,
+ payload: {
+ type: "acpx.text_delta",
+ text: "Looking at the failing test in `runtime-state.test.ts` — ",
+ channel: "thought",
+ },
+ },
+ {
+ offsetMs: 1500,
+ payload: {
+ type: "acpx.text_delta",
+ text: "the assertion expects `pendingRestart` but the new state machine uses `restartScheduled`.\n",
+ channel: "thought",
+ },
+ },
+ {
+ offsetMs: 1900,
+ payload: {
+ type: "acpx.text_delta",
+ text: "I'll inspect the test file to confirm the change.\n\n",
+ channel: "output",
+ tag: "agent_message_chunk",
+ },
+ },
+ {
+ offsetMs: 2200,
+ payload: {
+ type: "acpx.tool_call",
+ name: "read",
+ toolCallId: "tool_read_01",
+ status: "running",
+ text: "server/src/runtime-state.test.ts",
+ input: { path: "server/src/runtime-state.test.ts" },
+ },
+ },
+ {
+ offsetMs: 3500,
+ payload: {
+ type: "acpx.tool_call",
+ name: "read",
+ toolCallId: "tool_read_01",
+ status: "completed",
+ text: "Read 142 lines",
+ },
+ },
+ {
+ offsetMs: 3700,
+ payload: {
+ type: "acpx.text_delta",
+ text:
+ "The test still references the old `pendingRestart` field. I'll update the assertion to use the renamed `restartScheduled` flag.\n\n",
+ channel: "output",
+ },
+ },
+ {
+ offsetMs: 4200,
+ payload: {
+ type: "acpx.tool_call",
+ name: "edit",
+ toolCallId: "tool_edit_02",
+ status: "running",
+ input: {
+ path: "server/src/runtime-state.test.ts",
+ find: "expect(state.pendingRestart).toBe(true)",
+ replace: "expect(state.restartScheduled).toBe(true)",
+ },
+ },
+ },
+ {
+ offsetMs: 5400,
+ payload: {
+ type: "acpx.tool_call",
+ name: "edit",
+ toolCallId: "tool_edit_02",
+ status: "completed",
+ text: "1 replacement",
+ },
+ },
+ {
+ offsetMs: 5800,
+ payload: {
+ type: "acpx.status",
+ text: "Running vitest for runtime-state.test.ts",
+ },
+ },
+ {
+ offsetMs: 6100,
+ payload: {
+ type: "acpx.tool_call",
+ name: "command",
+ toolCallId: "tool_run_03",
+ status: "running",
+ input: { command: "pnpm exec vitest run server/src/runtime-state.test.ts" },
+ },
+ },
+ {
+ offsetMs: 9100,
+ payload: {
+ type: "acpx.tool_call",
+ name: "command",
+ toolCallId: "tool_run_03",
+ status: "completed",
+ text:
+ "Test Files 1 passed (1)\nTests 6 passed (6)\nDuration 2.31s",
+ },
+ },
+ {
+ offsetMs: 9400,
+ payload: {
+ type: "acpx.text_delta",
+ text:
+ "**Test passes.** Updated `runtime-state.test.ts` to assert against `restartScheduled` instead of the renamed `pendingRestart` field.\n\n",
+ channel: "output",
+ },
+ },
+ {
+ offsetMs: 9600,
+ payload: {
+ type: "acpx.text_delta",
+ text:
+ "Next I'll update the issue with a summary and hand it back to QA for verification.",
+ channel: "output",
+ },
+ },
+ {
+ offsetMs: 9800,
+ payload: {
+ type: "acpx.status",
+ tag: "context_window",
+ used: 18450,
+ size: 200000,
+ },
+ },
+ {
+ offsetMs: 10000,
+ payload: {
+ type: "acpx.result",
+ summary: "completed",
+ stopReason: "end_turn",
+ inputTokens: 18450,
+ outputTokens: 412,
+ cachedTokens: 12000,
+ costUsd: 0.024,
+ subtype: "end_turn",
+ },
+ },
+ ]),
+ [],
+ );
+}
+
+function AcpxLocalTranscriptStory() {
+ const entries = useAcpxTranscript();
+
+ return (
+ <div className="mx-auto max-w-4xl space-y-5 p-6">
+ <header className="space-y-2">
+ <Badge variant="outline" className="rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.18em]">
+ UX preview
+ </Badge>
+ <h1 className="text-2xl font-semibold tracking-tight">Run transcript — acpx_local streamed events</h1>
+ <p className="text-sm text-muted-foreground">
+ Demonstrates how a streamed acpx_local run renders through the existing transcript pipeline. Events flow
+ through <code>parseAcpxStdoutLine</code> (session init, thought delta, assistant delta, tool call/result
+ pairs, context window status, final result) and into <code>RunTranscriptView</code> in nice mode.
+ </p>
+ </header>
+
+ <Card className="shadow-none border-border overflow-hidden">
+ <CardHeader>
+ <CardTitle className="text-base font-semibold">Run Transcript (nice mode)</CardTitle>
+ <p className="text-xs text-muted-foreground">
+ Streaming, comfortable density. Mirrors the agent detail page transcript surface.
+ </p>
+ </CardHeader>
+ <CardContent>
+ <RunTranscriptView entries={entries} mode="nice" density="comfortable" streaming />
+ </CardContent>
+ </Card>
+
+ <Card className="shadow-none border-border overflow-hidden">
+ <CardHeader>
+ <CardTitle className="text-base font-semibold">Run Transcript (compact density)</CardTitle>
+ <p className="text-xs text-muted-foreground">
+ Same parsed events, compact density — matches the live-run widget on the issue thread.
+ </p>
+ </CardHeader>
+ <CardContent>
+ <RunTranscriptView entries={entries} mode="nice" density="compact" streaming={false} />
+ </CardContent>
+ </Card>
+ </div>
+ );
+}
+
+const SKILLS_COMPANY_ID = "company-storybook";
+
+const acpxSkillsCompanyLibrary: CompanySkillListItem[] = [
+ {
+ id: "skill-paperclip",
+ companyId: SKILLS_COMPANY_ID,
+ key: "paperclip",
+ slug: "paperclip",
+ name: "Paperclip",
+ description:
+ "Coordination skill: heartbeats, checkout, comments, and routine API patterns for Paperclip agents.",
+ sourceType: "local_path",
+ sourceLocator: "skills/paperclip",
+ sourceRef: null,
+ trustLevel: "scripts_executables",
+ compatibility: "compatible",
+ fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+ createdAt: new Date("2026-04-12T09:00:00.000Z"),
+ updatedAt: new Date("2026-04-22T15:30:00.000Z"),
+ attachedAgentCount: 4,
+ editable: false,
+ editableReason: "Required by Paperclip",
+ sourceLabel: "Paperclip",
+ sourceBadge: "paperclip",
+ sourcePath: "skills/paperclip",
+ },
+ {
+ id: "skill-design-guide",
+ companyId: SKILLS_COMPANY_ID,
+ key: "design-guide",
+ slug: "design-guide",
+ name: "Design guide",
+ description:
+ "Paperclip UI design system reference: tokens, typography, status colors, and reusable component patterns.",
+ sourceType: "local_path",
+ sourceLocator: "skills/design-guide",
+ sourceRef: null,
+ trustLevel: "markdown_only",
+ compatibility: "compatible",
+ fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+ createdAt: new Date("2026-04-15T10:00:00.000Z"),
+ updatedAt: new Date("2026-04-25T12:00:00.000Z"),
+ attachedAgentCount: 2,
+ editable: true,
+ editableReason: null,
+ sourceLabel: "Local",
+ sourceBadge: "local",
+ sourcePath: "skills/design-guide",
+ },
+ {
+ id: "skill-mobile-qa",
+ companyId: SKILLS_COMPANY_ID,
+ key: "mobile-app-qa",
+ slug: "mobile-app-qa",
+ name: "Mobile app QA",
+ description:
+ "Exploratory QA flows for mobile/web apps using Chrome automation. Captures bugs and writes a final report.",
+ sourceType: "local_path",
+ sourceLocator: "skills/mobile-app-qa",
+ sourceRef: null,
+ trustLevel: "assets",
+ compatibility: "compatible",
+ fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+ createdAt: new Date("2026-04-18T11:00:00.000Z"),
+ updatedAt: new Date("2026-04-26T09:30:00.000Z"),
+ attachedAgentCount: 1,
+ editable: true,
+ editableReason: null,
+ sourceLabel: "Local",
+ sourceBadge: "local",
+ sourcePath: "skills/mobile-app-qa",
+ },
+];
+
+function buildAcpxAgent({
+ agentId,
+ acpAgent,
+ desiredSkills,
+}: {
+ agentId: string;
+ acpAgent: "claude" | "codex" | "custom";
+ desiredSkills: string[];
+}): Agent {
+ return {
+ id: agentId,
+ companyId: SKILLS_COMPANY_ID,
+ name: `ACPX ${acpAgent === "custom" ? "Custom" : acpAgent === "codex" ? "Codex" : "Claude"}`,
+ urlKey: `acpx-${acpAgent}`,
+ role: "engineer",
+ title: `ACPX ${acpAgent} agent`,
+ icon: "code",
+ status: "idle",
+ reportsTo: null,
+ capabilities: "Routes work through the ACPX adapter for skill-tagged agent flows.",
+ adapterType: "acpx_local",
+ adapterConfig: {
+ agent: acpAgent,
+ mode: "persistent",
+ permissionMode: "approve-all",
+ paperclipSkillSync: {
+ desiredSkills,
+ },
+ },
+ runtimeConfig: {},
+ budgetMonthlyCents: 100_000,
+ spentMonthlyCents: 0,
+ pauseReason: null,
+ pausedAt: null,
+ permissions: { canCreateAgents: false },
+ lastHeartbeatAt: null,
+ metadata: null,
+ createdAt: new Date("2026-04-30T12:00:00.000Z"),
+ updatedAt: new Date("2026-04-30T12:00:00.000Z"),
+ } as Agent;
+}
+
+function buildAcpxClaudeSnapshot(): AgentSkillSnapshot {
+ return {
+ adapterType: "acpx_local",
+ supported: true,
+ mode: "ephemeral",
+ desiredSkills: ["paperclip", "design-guide"],
+ warnings: [],
+ entries: [
+ {
+ key: "paperclip",
+ runtimeName: "paperclip",
+ desired: true,
+ managed: true,
+ required: true,
+ requiredReason: "Paperclip coordination skill is mandatory for control-plane agents.",
+ state: "configured",
+ origin: "paperclip_required",
+ originLabel: "Required by Paperclip",
+ readOnly: false,
+ sourcePath: "skills/paperclip",
+ targetPath: null,
+ detail: "Will be mounted into the next ACPX Claude session.",
+ },
+ {
+ key: "design-guide",
+ runtimeName: "design-guide",
+ desired: true,
+ managed: true,
+ required: false,
+ state: "configured",
+ origin: "company_managed",
+ originLabel: "Managed by Paperclip",
+ readOnly: false,
+ sourcePath: "skills/design-guide",
+ targetPath: null,
+ detail: "Will be mounted into the next ACPX Claude session.",
+ },
+ {
+ key: "mobile-app-qa",
+ runtimeName: "mobile-app-qa",
+ desired: false,
+ managed: true,
+ required: false,
+ state: "available",
+ origin: "company_managed",
+ originLabel: "Managed by Paperclip",
+ readOnly: false,
+ sourcePath: "skills/mobile-app-qa",
+ targetPath: null,
+ detail: null,
+ },
+ ],
+ };
+}
+
+function buildAcpxCodexSnapshot(): AgentSkillSnapshot {
+ return {
+ adapterType: "acpx_local",
+ supported: true,
+ mode: "ephemeral",
+ desiredSkills: ["paperclip"],
+ warnings: [],
+ entries: [
+ {
+ key: "paperclip",
+ runtimeName: "paperclip",
+ desired: true,
+ managed: true,
+ required: true,
+ requiredReason: "Paperclip coordination skill is mandatory for control-plane agents.",
+ state: "configured",
+ origin: "paperclip_required",
+ originLabel: "Required by Paperclip",
+ readOnly: false,
+ sourcePath: "skills/paperclip",
+ targetPath: null,
+ detail: "Will be linked into the effective CODEX_HOME/skills/ directory for the next ACPX Codex session.",
+ },
+ {
+ key: "design-guide",
+ runtimeName: "design-guide",
+ desired: false,
+ managed: true,
+ required: false,
+ state: "available",
+ origin: "company_managed",
+ originLabel: "Managed by Paperclip",
+ readOnly: false,
+ sourcePath: "skills/design-guide",
+ targetPath: null,
+ detail: null,
+ },
+ {
+ key: "mobile-app-qa",
+ runtimeName: "mobile-app-qa",
+ desired: false,
+ managed: true,
+ required: false,
+ state: "available",
+ origin: "company_managed",
+ originLabel: "Managed by Paperclip",
+ readOnly: false,
+ sourcePath: "skills/mobile-app-qa",
+ targetPath: null,
+ detail: null,
+ },
+ ],
+ };
+}
+
+function buildAcpxCustomSnapshot(): AgentSkillSnapshot {
+ return {
+ adapterType: "acpx_local",
+ supported: false,
+ mode: "unsupported",
+ desiredSkills: ["design-guide"],
+ warnings: [
+ "Custom ACP commands do not expose a Paperclip skill integration contract yet; selected skills are tracked only.",
+ ],
+ entries: [
+ {
+ key: "paperclip",
+ runtimeName: "paperclip",
+ desired: false,
+ managed: true,
+ required: true,
+ requiredReason: "Paperclip coordination skill is mandatory for control-plane agents.",
+ state: "available",
+ origin: "paperclip_required",
+ originLabel: "Required by Paperclip",
+ readOnly: false,
+ sourcePath: "skills/paperclip",
+ targetPath: null,
+ detail: null,
+ },
+ {
+ key: "design-guide",
+ runtimeName: "design-guide",
+ desired: true,
+ managed: true,
+ required: false,
+ state: "configured",
+ origin: "company_managed",
+ originLabel: "Managed by Paperclip",
+ readOnly: false,
+ sourcePath: "skills/design-guide",
+ targetPath: null,
+ detail:
+ "Desired state is stored in Paperclip only; custom ACP commands need an explicit skill integration contract before runtime sync is available.",
+ },
+ {
+ key: "mobile-app-qa",
+ runtimeName: "mobile-app-qa",
+ desired: false,
+ managed: true,
+ required: false,
+ state: "available",
+ origin: "company_managed",
+ originLabel: "Managed by Paperclip",
+ readOnly: false,
+ sourcePath: "skills/mobile-app-qa",
+ targetPath: null,
+ detail: null,
+ },
+ ],
+ };
+}
+
+function StoryFrame({
+ title,
+ subtitle,
+ children,
+}: {
+ title: string;
+ subtitle: string;
+ children: ReactNode;
+}) {
+ return (
+ <div className="mx-auto max-w-3xl space-y-5 p-6">
+ <header className="space-y-2">
+ <Badge variant="outline" className="rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.18em]">
+ UX preview
+ </Badge>
+ <h1 className="text-2xl font-semibold tracking-tight">{title}</h1>
+ <p className="text-sm text-muted-foreground">{subtitle}</p>
+ </header>
+
+ <Card className="shadow-none border-border">
+ <CardHeader>
+ <CardTitle className="text-base font-semibold">Agent detail — Skills tab</CardTitle>
+ </CardHeader>
+ <CardContent>{children}</CardContent>
+ </Card>
+ </div>
+ );
+}
+
+function AcpxSkillsState({
+ agent,
+ snapshot,
+ library,
+}: {
+ agent: Agent;
+ snapshot: AgentSkillSnapshot;
+ library: CompanySkillListItem[];
+}) {
+ const queryClient = useQueryClient();
+ queryClient.setQueryData(queryKeys.companySkills.list(SKILLS_COMPANY_ID), library);
+ queryClient.setQueryData(queryKeys.agents.skills(agent.id), snapshot);
+ return <AgentSkillsTab agent={agent} companyId={SKILLS_COMPANY_ID} />;
+}
+
+function AcpxClaudeSkillsStory() {
+ const agent = buildAcpxAgent({
+ agentId: "agent-acpx-claude",
+ acpAgent: "claude",
+ desiredSkills: ["paperclip", "design-guide"],
+ });
+ return (
+ <StoryFrame
+ title="ACPX Claude — Skills tab"
+ subtitle="Runtime-synced state. Selected skills are mounted into the next ACPX Claude session via the Paperclip skills directory."
+ >
+ <AcpxSkillsState agent={agent} snapshot={buildAcpxClaudeSnapshot()} library={acpxSkillsCompanyLibrary} />
+ </StoryFrame>
+ );
+}
+
+function AcpxCodexSkillsStory() {
+ const agent = buildAcpxAgent({
+ agentId: "agent-acpx-codex",
+ acpAgent: "codex",
+ desiredSkills: ["paperclip"],
+ });
+ return (
+ <StoryFrame
+ title="ACPX Codex — Skills tab"
+ subtitle="Runtime-synced state. Selected skills are linked into the effective CODEX_HOME/skills/ directory for the next ACPX Codex session."
+ >
+ <AcpxSkillsState agent={agent} snapshot={buildAcpxCodexSnapshot()} library={acpxSkillsCompanyLibrary} />
+ </StoryFrame>
+ );
+}
+
+function AcpxCustomSkillsStory() {
+ const agent = buildAcpxAgent({
+ agentId: "agent-acpx-custom",
+ acpAgent: "custom",
+ desiredSkills: ["design-guide"],
+ });
+ return (
+ <StoryFrame
+ title="ACPX custom — Skills tab"
+ subtitle="Unsupported runtime sync. Desired skills are tracked in Paperclip only until a custom ACP command declares a skill integration contract."
+ >
+ <AcpxSkillsState agent={agent} snapshot={buildAcpxCustomSnapshot()} library={acpxSkillsCompanyLibrary} />
+ </StoryFrame>
+ );
+}
+
+function AcpxClaudeSkillsLoadingStory() {
+ const agent = buildAcpxAgent({
+ agentId: "agent-acpx-claude-loading",
+ acpAgent: "claude",
+ desiredSkills: [],
+ });
+ return (
+ <StoryFrame
+ title="ACPX Claude — Skills tab (loading)"
+ subtitle="Initial render before /api/agents/{id}/skills resolves. Uses the shared list skeleton."
+ >
+ <AgentSkillsTab agent={agent} companyId={SKILLS_COMPANY_ID} />
+ </StoryFrame>
+ );
+}
+
+function AcpxClaudeSkillsEmptyLibraryStory() {
+ const agent = buildAcpxAgent({
+ agentId: "agent-acpx-claude-empty",
+ acpAgent: "claude",
+ desiredSkills: [],
+ });
+ const emptySnapshot: AgentSkillSnapshot = {
+ adapterType: "acpx_local",
+ supported: true,
+ mode: "ephemeral",
+ desiredSkills: [],
+ warnings: [],
+ entries: [],
+ };
+ return (
+ <StoryFrame
+ title="ACPX Claude — Skills tab (empty company library)"
+ subtitle="Runtime supports skills, but the company library has no skills imported yet. Operator is prompted to import skills first."
+ >
+ <AcpxSkillsState agent={agent} snapshot={emptySnapshot} library={[]} />
+ </StoryFrame>
+ );
+}
+
+const meta: Meta = {
+ title: "Adapters / acpx_local",
+ parameters: {
+ layout: "fullscreen",
+ },
+};
+
+export default meta;
+
+export const ConfigForm: StoryObj = {
+ name: "Agent config form",
+ render: () => <AcpxLocalConfigStory />,
+};
+
+export const Transcript: StoryObj = {
+ name: "Streamed run transcript",
+ render: () => <AcpxLocalTranscriptStory />,
+};
+
+export const SkillsTabClaude: StoryObj = {
+ name: "Skills tab — ACPX Claude",
+ render: () => <AcpxClaudeSkillsStory />,
+};
+
+export const SkillsTabCodex: StoryObj = {
+ name: "Skills tab — ACPX Codex",
+ render: () => <AcpxCodexSkillsStory />,
+};
+
+export const SkillsTabCustom: StoryObj = {
+ name: "Skills tab — ACPX custom (unsupported)",
+ render: () => <AcpxCustomSkillsStory />,
+};
+
+export const SkillsTabLoading: StoryObj = {
+ name: "Skills tab — loading",
+ render: () => <AcpxClaudeSkillsLoadingStory />,
+};
+
+export const SkillsTabEmptyLibrary: StoryObj = {
+ name: "Skills tab — empty company library",
+ render: () => <AcpxClaudeSkillsEmptyLibraryStory />,
+};
diff --git a/vitest.config.ts b/vitest.config.ts
index c886095dad..85fd42d437 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -6,6 +6,7 @@ export default defineConfig({
"packages/shared",
"packages/db",
"packages/adapter-utils",
+ "packages/adapters/acpx-local",
"packages/adapters/claude-local",
"packages/adapters/codex-local",
"packages/adapters/cursor-local",