Add ACPX local adapter runtime (#4893)

## Thinking Path

> - Paperclip orchestrates AI-agent companies through a control plane
that can start, supervise, and recover agent runs.
> - Local adapters are the bridge between Paperclip issues and concrete
agent runtimes such as Claude, Codex, and other ACP-compatible tools.
> - The roadmap calls out broader “bring your own agent” and claw-style
agent support, and ACPX gives Paperclip one path to normalize multiple
ACP agents behind a single adapter.
> - The branch needed to become one reviewable PR against current
`paperclipai/paperclip:master`, without carrying stale base conflicts or
generated lockfile churn.
> - This pull request adds an experimental built-in `acpx_local`
adapter, integrates it through the server/CLI/UI adapter surfaces, and
adds regression coverage for runtime execution, skill sync, stream
parsing, diagnostics, and log redaction.
> - The benefit is that Paperclip can run Claude/Codex/custom ACP agents
through ACPX while keeping operator configuration, skills, logging, and
transcript rendering inside the existing adapter model.

## What Changed

- Added `@paperclipai/adapter-acpx-local` with server execution, config
schema, ACPX session handling, CLI formatting, UI config helpers, and
stdout parsing.
- Registered `acpx_local` across CLI, server, shared constants, UI
adapter metadata, adapter capabilities, and agent creation/editing
surfaces.
- Added ACPX runtime execution support with persistent sessions,
local-agent JWT environment handling, skill snapshots, runtime skill
materialization, and isolation/security regressions.
- Added ACPX adapter diagnostics and marked the adapter experimental in
the UI.
- Added command/env secret redaction for resolved command metadata in
adapter-utils, server event storage, and the Agent Detail invocation UI.
- Added Storybook coverage for ACPX config, transcript rendering, and
skill states, plus PR screenshots under `docs/pr-screenshots/pap-2944/`.
- Rebased the branch onto current `public-gh/master`; `pnpm-lock.yaml`
is intentionally not included and there are no migration/schema changes.

## Verification

- `pnpm exec vitest run
packages/adapters/acpx-local/src/server/execute.test.ts
packages/adapters/acpx-local/src/server/test.test.ts
packages/adapters/acpx-local/src/cli/format-event.test.ts
packages/adapters/acpx-local/src/ui/parse-stdout.test.ts
packages/adapter-utils/src/server-utils.test.ts
server/src/__tests__/redaction.test.ts
server/src/__tests__/acpx-local-execute.test.ts
server/src/__tests__/acpx-local-skill-sync.test.ts
server/src/__tests__/acpx-local-adapter-environment.test.ts
server/src/__tests__/adapter-routes.test.ts
server/src/__tests__/agent-skills-routes.test.ts
ui/src/adapters/metadata.test.ts` — 12 files, 87 tests passed.
- `pnpm --filter @paperclipai/adapter-acpx-local typecheck` — passed.
- `pnpm --filter @paperclipai/server typecheck` — passed.
- `pnpm --filter @paperclipai/ui typecheck` — passed.
- Confirmed PR diff does not include `pnpm-lock.yaml`, database schema
files, or migrations.

Screenshots:

![ACPX Claude skills
light](https://github.com/cryppadotta/paperclip-1/blob/PAP-2944-acpx-make-a-claude_local-adapter-that-uses-acpx-instead/docs/pr-screenshots/pap-2944/skills-claude-light.png?raw=true)
![ACPX Claude skills
dark](https://github.com/cryppadotta/paperclip-1/blob/PAP-2944-acpx-make-a-claude_local-adapter-that-uses-acpx-instead/docs/pr-screenshots/pap-2944/skills-claude-dark.png?raw=true)
![ACPX custom skills
light](https://github.com/cryppadotta/paperclip-1/blob/PAP-2944-acpx-make-a-claude_local-adapter-that-uses-acpx-instead/docs/pr-screenshots/pap-2944/skills-custom-light.png?raw=true)

## Risks

- Medium risk: this introduces a new built-in adapter package and
touches runtime execution, adapter registration, agent config, skills,
and transcript rendering.
- ACPX and ACP agent behavior can vary by installed tool versions; the
adapter is marked experimental to set operator expectations.
- `pnpm-lock.yaml` is excluded per repository PR policy, so dependency
lock refresh must be handled by the repo’s automation or maintainers.
- No database migration risk: no schema or migration files changed.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex coding agent based on GPT-5, with repository tool use,
shell execution, git operations, and local verification. Exact hosted
context window was not exposed in this environment.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

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/

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:*",

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,

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);
+}

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.

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(

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>,

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",

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"
+  }
+}

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");
+  });
+});

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);
+}

packages/adapters/acpx-local/src/cli/index.ts

@@ -0,0 +1 @@
+export { printAcpxStreamEvent } from "./format-event.js";

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.
+`;

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.",
+      },
+    ],
+  };
+}

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;
+    }
+  });
+});

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";

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)
+    );
+  },
+};

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);
+}

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",
+      }),
+    );
+  });
+});

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(),
+  };
+}

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;
+}

packages/adapters/acpx-local/src/ui/index.ts

@@ -0,0 +1,2 @@
+export { parseAcpxStdoutLine } from "./parse-stdout.js";
+export { buildAcpxLocalConfig } from "./build-config.js";

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" }]);
+  });
+});

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 }];
+}

packages/adapters/acpx-local/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

packages/adapters/acpx-local/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+  },
+});

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",

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",

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/playwright@1.58.2/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();
+}

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",

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:*",

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 });
+    }
+  });
+});

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 });
+    }
+  });
+});

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.",
+    );
+  });
+});

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",

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", () => {

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({

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]);
+  });
 });

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",

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,

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);

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 CLI_SECRET_FLAG_RE =
-const OPENAI_KEY_TEXT_RE = /\bsk-[A-Za-z0-9_-]{12,}\b/g;
+  /^-{1,2}(?:api[-_]?key|(?:access[-_]?|auth[-_]?)?token|token|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)$/i;
-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 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
+  return redactCommandText(
-    .replace(AUTHORIZATION_BEARER_TEXT_RE, `$1${REDACTED_EVENT_VALUE}`)
+    input
-    .replace(JSON_SECRET_FIELD_TEXT_RE, `$1${REDACTED_EVENT_VALUE}$2`)
+      .replace(JSON_SECRET_FIELD_TEXT_RE, `$1${REDACTED_EVENT_VALUE}$2`)
-    .replace(ESCAPED_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}`)
+    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);
 }

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;

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" &&

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
+    const secretSanitizedPayload = boundedPayload ? redactEventPayload(boundedPayload) : boundedPayload;
-      ? redactCurrentUserValue(boundedPayload, currentUserRedactionOptions)
+    const sanitizedPayload = secretSanitizedPayload
-      : boundedPayload;
+      ? redactCurrentUserValue(secretSanitizedPayload, currentUserRedactionOptions)
+      : secretSanitizedPayload;
 
     await db.insert(heartbeatRunEvents).values({
       companyId: run.companyId,

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:*",

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,
+};

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",

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);
   });
+
+  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,
+      },
+    ]);
+  });
 });

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,
   }));
 }
 

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,

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 },

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,

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

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 {

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..."

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 (

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 />,
+};

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",