@actagent/acpx 2026.6.2

package/AGENTS.md

@@ -0,0 +1,54 @@
+# ACPX Extension Notes
+
+This file applies to work under `extensions/acpx/`.
+
+## Purpose
+
+The ACPX extension is a thin ACTAgent wrapper around the published `acpx` package. Keep reusable ACP runtime logic in `actagent/acpx`, not in this extension.
+
+## Default Version Policy
+
+- `extensions/acpx/package.json` should point at a published npm release by default.
+- Do not leave the extension pinned to a temporary GitHub commit or local checkout once the ACPX release exists.
+- Do not leave temporary pnpm build-script allowlist exceptions behind after switching back to a published ACPX package.
+
+## Unreleased ACPX Development Flow
+
+Use this flow when ACTAgent needs unreleased ACPX changes before the ACPX version is published.
+
+1. Make the ACPX code change in the `actagent/acpx` repo first.
+2. In ACTAgent, temporarily point `extensions/acpx/package.json` at the ACPX GitHub commit you need.
+3. If pnpm blocks ACPX lifecycle/build scripts for that temporary GitHub-sourced package, temporarily add `acpx: true` to `allowBuilds` in `pnpm-workspace.yaml`.
+4. Refresh the root workspace lock:
+   - `pnpm install --lockfile-only --filter ./extensions/acpx`
+5. Refresh the extension-local npm lock for install metadata:
+   - `cd extensions/acpx && npm install --package-lock-only --ignore-scripts`
+6. Rebuild ACTAgent and restart the gateway before doing live ACP validation.
+7. Once ACPX is released, switch `extensions/acpx/package.json` back to the published npm version and refresh the same lockfiles again.
+8. Remove any temporary `acpx` build-script allowlist entry that was only needed for the GitHub-sourced development pin.
+
+## Lockfile Notes
+
+- `pnpm-lock.yaml` is the tracked workspace lockfile and must match the ACPX version referenced by `extensions/acpx/package.json`.
+- `extensions/acpx/package-lock.json` is useful local install metadata for the plugin package.
+- If `extensions/acpx/package-lock.json` is gitignored in this repo state, regenerating it is still useful for local verification, but it will not appear in `git status`.
+
+## Local Runtime Validation
+
+When ACPX integration changes here, prefer this sequence:
+
+1. `pnpm install --filter ./extensions/acpx`
+2. `pnpm test:extension acpx`
+3. `pnpm build`
+4. Restart the local gateway if ACP runtime behavior or bundled plugin wiring changed.
+5. If the change affects direct ACP behavior in chat, run a real ACP smoke after restart.
+
+## Direct ACPX Binary Policy
+
+- Prefer the plugin-local ACPX binary under `extensions/acpx/node_modules/.bin/acpx`.
+- Do not rely on a globally installed `acpx` binary for ACTAgent ACP validation.
+- If the plugin-local ACPX binary is missing or on the wrong version, reinstall it from the version pinned in `extensions/acpx/package.json`.
+
+## Boundary Rule
+
+If a change feels like shared ACP runtime behavior instead of ACTAgent-specific glue, move it to `actagent/acpx` and consume it from here instead of re-implementing it inside `extensions/acpx`.

package/README.md

@@ -0,0 +1,33 @@
+# @actagent/acpx
+
+Official ACP runtime backend for ACTAgent.
+
+ACPx lets ACTAgent run external coding harnesses through the Agent Client Protocol while ACTAgent still owns sessions, channels, delivery, permissions, and Gateway state.
+
+## Install
+
+```bash
+actagent plugins install @actagent/acpx
+```
+
+Restart the Gateway after installing or updating the plugin.
+
+## What it provides
+
+- ACP-backed agent runtime sessions.
+- Plugin-owned session and transport management.
+- MCP bridge helpers for ACTAgent tools and plugin tools.
+- Static runtime assets used by the ACP process bridge.
+
+## Configure
+
+Use the ACP docs for harness-specific setup, permission modes, and model/runtime selection:
+
+- https://docs.actagent.ai/tools/acp-agents-setup
+- https://docs.actagent.ai/tools/acp-agents
+
+## Package
+
+- Plugin id: `acpx`
+- Package: `@actagent/acpx`
+- Minimum ACTAgent host: `2026.4.25`

package/actagent.plugin.json

@@ -0,0 +1,174 @@
+{
+  "id": "acpx",
+  "activation": {
+    "onStartup": true
+  },
+  "enabledByDefault": true,
+  "name": "ACPX Runtime",
+  "description": "ACTAgent ACP runtime backend with plugin-owned session and transport management.",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "cwd": {
+        "type": "string",
+        "minLength": 1
+      },
+      "stateDir": {
+        "type": "string",
+        "minLength": 1
+      },
+      "probeAgent": {
+        "type": "string",
+        "minLength": 1
+      },
+      "permissionMode": {
+        "type": "string",
+        "enum": ["approve-all", "approve-reads", "deny-all"]
+      },
+      "nonInteractivePermissions": {
+        "type": "string",
+        "enum": ["deny", "fail"]
+      },
+      "pluginToolsMcpBridge": {
+        "type": "boolean"
+      },
+      "actAgentToolsMcpBridge": {
+        "type": "boolean"
+      },
+      "strictWindowsCmdWrapper": {
+        "type": "boolean"
+      },
+      "timeoutSeconds": {
+        "type": "number",
+        "minimum": 0.001,
+        "default": 120
+      },
+      "queueOwnerTtlSeconds": {
+        "type": "number",
+        "minimum": 0
+      },
+      "probeAgent": {
+        "type": "string",
+        "minLength": 1
+      },
+      "mcpServers": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "command": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Command to run the MCP server"
+            },
+            "args": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Arguments to pass to the command"
+            },
+            "env": {
+              "type": "object",
+              "additionalProperties": { "type": "string" },
+              "description": "Environment variables for the MCP server"
+            }
+          },
+          "required": ["command"]
+        }
+      },
+      "agents": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "command": {
+              "type": "string",
+              "minLength": 1
+            },
+            "args": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          },
+          "required": ["command"]
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "cwd": {
+      "label": "Default Working Directory",
+      "help": "Default working directory for embedded ACP session operations when not set per session."
+    },
+    "stateDir": {
+      "label": "State Directory",
+      "help": "Directory used for embedded ACP session state and persistence."
+    },
+    "permissionMode": {
+      "label": "Permission Mode",
+      "help": "Default permission policy for embedded ACP runtime prompts."
+    },
+    "nonInteractivePermissions": {
+      "label": "Non-Interactive Permission Policy",
+      "help": "Policy when interactive permission prompts are unavailable."
+    },
+    "pluginToolsMcpBridge": {
+      "label": "Plugin Tools MCP Bridge",
+      "help": "Default off. When enabled, inject the built-in ACTAgent plugin-tools MCP server into embedded ACP sessions so ACP agents can call plugin-registered tools.",
+      "advanced": true
+    },
+    "actAgentToolsMcpBridge": {
+      "label": "ACTAgent Tools MCP Bridge",
+      "help": "Default off. When enabled, inject the built-in ACTAgent core-tools MCP server into embedded ACP sessions so ACP agents can call selected built-in tools such as cron.",
+      "advanced": true
+    },
+    "strictWindowsCmdWrapper": {
+      "label": "Strict Windows cmd Wrapper",
+      "help": "Legacy compatibility field. The current embedded acpx/runtime package uses its own Windows command resolution behavior. Setting this to false is accepted for compatibility and logged as ignored.",
+      "advanced": true
+    },
+    "timeoutSeconds": {
+      "label": "Runtime Operation Timeout Seconds",
+      "help": "Timeout for embedded ACP runtime startup and control operations. ACP turns use ACTAgent agent/run timeouts.",
+      "advanced": true
+    },
+    "queueOwnerTtlSeconds": {
+      "label": "Queue Owner TTL Seconds",
+      "help": "Reserved compatibility field for the older embedded ACPX queue-owner path. Accepted for compatibility and logged as ignored.",
+      "advanced": true
+    },
+    "probeAgent": {
+      "label": "Health Probe Agent",
+      "help": "Agent id used for the embedded ACP runtime health probe. Defaults to the first `acp.allowedAgents` entry when that allowlist is set, otherwise to the runtime built-in probe agent (codex). Set this explicitly (for example `opencode` or `claude`) when the default probe agent is not installed or not authenticated, so the whole embedded ACP backend does not get marked unavailable.",
+      "advanced": true
+    },
+    "mcpServers": {
+      "label": "MCP Servers",
+      "help": "Named MCP server definitions to inject into embedded ACP session bootstrap. Each entry needs a command and can include args and env.",
+      "advanced": true
+    },
+    "agents": {
+      "label": "Agent Commands",
+      "help": "Optional per-agent command overrides for the embedded ACP runtime.",
+      "advanced": true
+    }
+  },
+  "configContracts": {
+    "dangerousFlags": [
+      {
+        "path": "permissionMode",
+        "equals": "approve-all"
+      }
+    ],
+    "secretInputs": {
+      "bundledDefaultEnabled": false,
+      "paths": [
+        {
+          "path": "mcpServers.*.env.*",
+          "expected": "string"
+        }
+      ]
+    }
+  }
+}

package/index.test.ts

@@ -0,0 +1,120 @@
+// ACPX tests cover index plugin behavior.
+import type { ACTAgentPluginApi } from "actagent/plugin-sdk/plugin-entry";
+import { createTestPluginApi } from "actagent/plugin-sdk/plugin-test-api";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import setupPlugin from "./setup-api.js";
+
+const { createAcpxRuntimeServiceMock, tryDispatchAcpReplyHookMock } = vi.hoisted(() => ({
+  createAcpxRuntimeServiceMock: vi.fn(),
+  tryDispatchAcpReplyHookMock: vi.fn(),
+}));
+
+vi.mock("./register.runtime.js", () => ({
+  createAcpxRuntimeService: createAcpxRuntimeServiceMock,
+}));
+
+vi.mock("actagent/plugin-sdk/acp-runtime-backend", () => ({
+  tryDispatchAcpReplyHook: tryDispatchAcpReplyHookMock,
+}));
+
+import plugin from "./index.js";
+
+type AcpxAutoEnableProbe = Parameters<ACTAgentPluginApi["registerAutoEnableProbe"]>[0];
+
+function registerAcpxAutoEnableProbe(): AcpxAutoEnableProbe {
+  const probes: AcpxAutoEnableProbe[] = [];
+  setupPlugin.register(
+    createTestPluginApi({
+      registerAutoEnableProbe(probe) {
+        probes.push(probe);
+      },
+    }),
+  );
+  const probe = probes[0];
+  if (!probe) {
+    throw new Error("expected ACPX setup plugin to register an auto-enable probe");
+  }
+  return probe;
+}
+
+describe("acpx plugin", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("registers the runtime service and reply_dispatch hook", () => {
+    const service = { id: "acpx-service", start: vi.fn() };
+    createAcpxRuntimeServiceMock.mockReturnValue(service);
+
+    const api = {
+      pluginConfig: { stateDir: "/tmp/acpx" },
+      registerService: vi.fn(),
+      on: vi.fn(),
+    };
+
+    plugin.register(api as never);
+
+    expect(createAcpxRuntimeServiceMock).toHaveBeenCalledWith({
+      pluginConfig: api.pluginConfig,
+    });
+    expect(api.registerService).toHaveBeenCalledWith(service);
+    expect(api.on).toHaveBeenCalledWith("reply_dispatch", tryDispatchAcpReplyHookMock);
+  });
+
+  it("preserves the ACP reply_dispatch runtime path through the registered hook", async () => {
+    const service = { id: "acpx-service", start: vi.fn() };
+    createAcpxRuntimeServiceMock.mockReturnValue(service);
+    tryDispatchAcpReplyHookMock.mockResolvedValue({
+      handled: true,
+      queuedFinal: true,
+      counts: { tool: 1, block: 0, final: 1 },
+    });
+
+    const on = vi.fn();
+    const api = createTestPluginApi({
+      pluginConfig: { stateDir: "/tmp/acpx" },
+      registerService: vi.fn(),
+      on,
+    });
+
+    plugin.register(api);
+
+    const hook = on.mock.calls.find(([hookName]) => hookName === "reply_dispatch")?.[1];
+    if (!hook) {
+      throw new Error("expected reply_dispatch hook to be registered");
+    }
+
+    const event = {
+      ctx: { raw: "reply ctx" },
+      runId: "run-1",
+      sessionKey: "agent:test:session",
+      inboundAudio: false,
+      shouldRouteToOriginating: false,
+      shouldSendToolSummaries: true,
+      sendPolicy: "allow",
+    };
+    const ctx = {
+      cfg: {},
+      dispatcher: { dispatch: vi.fn(), getQueuedCounts: vi.fn(), getFailedCounts: vi.fn() },
+      recordProcessed: vi.fn(),
+      markIdle: vi.fn(),
+    };
+
+    await expect(hook(event, ctx)).resolves.toEqual({
+      handled: true,
+      queuedFinal: true,
+      counts: { tool: 1, block: 0, final: 1 },
+    });
+    expect(tryDispatchAcpReplyHookMock).toHaveBeenCalledWith(event, ctx);
+  });
+
+  it("declares setup auto-enable reasons for ACPX-owned ACP config", () => {
+    const probe = registerAcpxAutoEnableProbe();
+
+    expect(probe({ config: { acp: { enabled: true } }, env: {} })).toBe("ACP runtime configured");
+    expect(probe({ config: { acp: { backend: "acpx" } }, env: {} })).toBe("ACP runtime configured");
+    expect(probe({ config: { acp: { enabled: true, backend: "custom-runtime" } }, env: {} })).toBe(
+      null,
+    );
+  });
+});

package/index.ts

@@ -0,0 +1,23 @@
+/**
+ * ACPX runtime plugin entry. It registers the embedded ACP backend service and
+ * wires reply-dispatch hooks into the plugin SDK runtime.
+ */
+import { tryDispatchAcpReplyHook } from "actagent/plugin-sdk/acp-runtime-backend";
+import { createAcpxRuntimeService } from "./register.runtime.js";
+import type { ACTAgentPluginApi } from "./runtime-api.js";
+
+const plugin = {
+  id: "acpx",
+  name: "ACPX Runtime",
+  description: "Embedded ACP runtime backend with plugin-owned session and transport management.",
+  register(api: ACTAgentPluginApi) {
+    api.registerService(
+      createAcpxRuntimeService({
+        pluginConfig: api.pluginConfig,
+      }),
+    );
+    api.on("reply_dispatch", tryDispatchAcpReplyHook);
+  },
+};
+
+export default plugin;