@kodelyth/acpx 2026.5.39 → 2026.5.42

package/dist/setup-api.js

@@ -0,0 +1,16 @@
+import { definePluginEntry } from "klaw/plugin-sdk/plugin-entry";
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+//#region extensions/acpx/setup-api.ts
+var setup_api_default = definePluginEntry({
+	id: "acpx",
+	name: "ACPX Setup",
+	description: "Lightweight ACPX setup hooks",
+	register(api) {
+		api.registerAutoEnableProbe(({ config }) => {
+			const backendRaw = normalizeLowercaseStringOrEmpty(config.acp?.backend);
+			return (config.acp?.enabled === true || config.acp?.dispatch?.enabled === true || backendRaw === "acpx") && (!backendRaw || backendRaw === "acpx") ? "ACP runtime configured" : null;
+		});
+	}
+});
+//#endregion
+export { setup_api_default as default };

package/index.test.ts

@@ -0,0 +1,119 @@
+import type { KlawPluginApi } from "klaw/plugin-sdk/plugin-entry";
+import { createTestPluginApi } from "klaw/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("klaw/plugin-sdk/acp-runtime-backend", () => ({
+  tryDispatchAcpReplyHook: tryDispatchAcpReplyHookMock,
+}));
+
+import plugin from "./index.js";
+
+type AcpxAutoEnableProbe = Parameters<KlawPluginApi["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,19 @@
+import { tryDispatchAcpReplyHook } from "klaw/plugin-sdk/acp-runtime-backend";
+import { createAcpxRuntimeService } from "./register.runtime.js";
+import type { KlawPluginApi } 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: KlawPluginApi) {
+    api.registerService(
+      createAcpxRuntimeService({
+        pluginConfig: api.pluginConfig,
+      }),
+    );
+    api.on("reply_dispatch", tryDispatchAcpReplyHook);
+  },
+};
+
+export default plugin;

package/klaw.plugin.json

@@ -6,9 +6,7 @@
   "enabledByDefault": true,
   "name": "ACPX Runtime",
   "description": "Embedded ACP runtime backend with plugin-owned session and transport management.",
-  "skills": [
-    "./skills"
-  ],
+  "skills": ["./skills"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -27,18 +25,11 @@
       },
       "permissionMode": {
         "type": "string",
-        "enum": [
-          "approve-all",
-          "approve-reads",
-          "deny-all"
-        ]
+        "enum": ["approve-all", "approve-reads", "deny-all"]
       },
       "nonInteractivePermissions": {
         "type": "string",
-        "enum": [
-          "deny",
-          "fail"
-        ]
+        "enum": ["deny", "fail"]
       },
       "pluginToolsMcpBridge": {
         "type": "boolean"
@@ -58,6 +49,10 @@
         "type": "number",
         "minimum": 0
       },
+      "probeAgent": {
+        "type": "string",
+        "minLength": 1
+      },
       "mcpServers": {
         "type": "object",
         "additionalProperties": {
@@ -70,22 +65,16 @@
             },
             "args": {
               "type": "array",
-              "items": {
-                "type": "string"
-              },
+              "items": { "type": "string" },
               "description": "Arguments to pass to the command"
             },
             "env": {
               "type": "object",
-              "additionalProperties": {
-                "type": "string"
-              },
+              "additionalProperties": { "type": "string" },
               "description": "Environment variables for the MCP server"
             }
           },
-          "required": [
-            "command"
-          ]
+          "required": ["command"]
         }
       },
       "agents": {
@@ -99,14 +88,10 @@
             },
             "args": {
               "type": "array",
-              "items": {
-                "type": "string"
-              }
+              "items": { "type": "string" }
             }
           },
-          "required": [
-            "command"
-          ]
+          "required": ["command"]
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodelyth/acpx",
-  "version": "2026.5.39",
+  "version": "2026.5.42",
   "description": "Klaw ACP runtime backend",
   "repository": {
     "type": "git",
@@ -18,7 +18,7 @@
   },
   "klaw": {
     "extensions": [
-      "./index.js"
+      "./index.ts"
     ],
     "install": {
       "npmSpec": "@kodelyth/acpx",

package/register.runtime.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { runtimeRegistry } = vi.hoisted(() => ({
+  runtimeRegistry: new Map<string, { runtime: unknown }>(),
+}));
+
+const { realRuntime, realServiceStartMock, realServiceStopMock, createRealServiceMock } =
+  vi.hoisted(() => {
+    const runtime = { isHealthy: vi.fn(() => true), probeAvailability: vi.fn(async () => {}) };
+    const start = vi.fn(async () => {
+      runtimeRegistry.set("acpx", { runtime });
+    });
+    const stop = vi.fn(async () => {
+      runtimeRegistry.delete("acpx");
+    });
+    return {
+      realRuntime: runtime,
+      realServiceStartMock: start,
+      realServiceStopMock: stop,
+      createRealServiceMock: vi.fn(() => ({ id: "real-acpx-runtime", start, stop })),
+    };
+  });
+
+vi.mock("klaw/plugin-sdk/acp-runtime-backend", () => ({
+  getAcpRuntimeBackend: (id: string) => runtimeRegistry.get(id),
+  unregisterAcpRuntimeBackend: (id: string) => {
+    runtimeRegistry.delete(id);
+  },
+}));
+
+vi.mock("./src/service.js", () => ({
+  createAcpxRuntimeService: createRealServiceMock,
+}));
+
+import { createAcpxRuntimeService } from "./register.runtime.js";
+
+const previousSkipRuntime = process.env.KLAW_SKIP_ACPX_RUNTIME;
+
+function restoreEnv(): void {
+  if (previousSkipRuntime === undefined) {
+    delete process.env.KLAW_SKIP_ACPX_RUNTIME;
+  } else {
+    process.env.KLAW_SKIP_ACPX_RUNTIME = previousSkipRuntime;
+  }
+}
+
+function createServiceContext() {
+  return {
+    workspaceDir: "/tmp/klaw-acpx-register-test",
+    stateDir: "/tmp/klaw-acpx-register-test/state",
+    config: {},
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    },
+  };
+}
+
+describe("acpx register runtime service", () => {
+  afterEach(() => {
+    runtimeRegistry.clear();
+    realServiceStartMock.mockClear();
+    realServiceStopMock.mockClear();
+    createRealServiceMock.mockClear();
+    restoreEnv();
+  });
+
+  it("starts the real service by default while leaving probe policy to the inner service", async () => {
+    delete process.env.KLAW_SKIP_ACPX_RUNTIME;
+    const ctx = createServiceContext();
+    const service = createAcpxRuntimeService({
+      pluginConfig: { timeoutSeconds: 10 },
+    });
+
+    await service.start(ctx as never);
+
+    expect(createRealServiceMock).toHaveBeenCalledWith({
+      pluginConfig: { timeoutSeconds: 10 },
+    });
+    expect(realServiceStartMock).toHaveBeenCalledWith(ctx);
+    expect(runtimeRegistry.get("acpx")?.runtime).toBe(realRuntime);
+
+    await service.stop?.(ctx as never);
+
+    expect(realServiceStopMock).toHaveBeenCalledWith(ctx);
+    expect(runtimeRegistry.get("acpx")).toBeUndefined();
+  });
+
+  it("keeps the explicit runtime skip env as the only outer startup skip", async () => {
+    process.env.KLAW_SKIP_ACPX_RUNTIME = "1";
+    const ctx = createServiceContext();
+    const service = createAcpxRuntimeService();
+
+    await service.start(ctx as never);
+
+    expect(createRealServiceMock).not.toHaveBeenCalled();
+    expect(runtimeRegistry.get("acpx")).toBeUndefined();
+    expect(ctx.logger.info).toHaveBeenCalledWith(
+      "skipping embedded acpx runtime backend (KLAW_SKIP_ACPX_RUNTIME=1)",
+    );
+  });
+});

package/register.runtime.ts

@@ -0,0 +1,86 @@
+import {
+  getAcpRuntimeBackend,
+  unregisterAcpRuntimeBackend,
+  type AcpRuntime,
+} from "klaw/plugin-sdk/acp-runtime-backend";
+import type { KlawPluginService, KlawPluginServiceContext } from "klaw/plugin-sdk/core";
+
+const ACPX_BACKEND_ID = "acpx";
+
+type RealAcpxServiceModule = typeof import("./src/service.js");
+type CreateAcpxRuntimeServiceParams = NonNullable<
+  Parameters<RealAcpxServiceModule["createAcpxRuntimeService"]>[0]
+>;
+
+type DeferredServiceState = {
+  ctx: KlawPluginServiceContext | null;
+  params: CreateAcpxRuntimeServiceParams;
+  realRuntime: AcpRuntime | null;
+  realService: KlawPluginService | null;
+  startPromise: Promise<AcpRuntime> | null;
+};
+
+let serviceModulePromise: Promise<RealAcpxServiceModule> | null = null;
+
+function loadServiceModule(): Promise<RealAcpxServiceModule> {
+  serviceModulePromise ??= import("./src/service.js");
+  return serviceModulePromise;
+}
+
+async function startRealService(state: DeferredServiceState): Promise<AcpRuntime> {
+  if (state.realRuntime) {
+    return state.realRuntime;
+  }
+  if (!state.ctx) {
+    throw new Error("ACPX runtime service is not started");
+  }
+  state.startPromise ??= (async () => {
+    const { createAcpxRuntimeService } = await loadServiceModule();
+    const service = createAcpxRuntimeService(state.params);
+    state.realService = service;
+    await service.start(state.ctx as KlawPluginServiceContext);
+    const backend = getAcpRuntimeBackend(ACPX_BACKEND_ID);
+    if (!backend?.runtime) {
+      throw new Error("ACPX runtime service did not register an ACP backend");
+    }
+    state.realRuntime = backend.runtime;
+    return state.realRuntime;
+  })();
+  return await state.startPromise;
+}
+
+export function createAcpxRuntimeService(
+  params: CreateAcpxRuntimeServiceParams = {},
+): KlawPluginService {
+  const state: DeferredServiceState = {
+    ctx: null,
+    params,
+    realRuntime: null,
+    realService: null,
+    startPromise: null,
+  };
+
+  return {
+    id: "acpx-runtime",
+    async start(ctx) {
+      if (process.env.KLAW_SKIP_ACPX_RUNTIME === "1") {
+        ctx.logger.info("skipping embedded acpx runtime backend (KLAW_SKIP_ACPX_RUNTIME=1)");
+        return;
+      }
+
+      state.ctx = ctx;
+      await startRealService(state);
+    },
+    async stop(ctx) {
+      if (state.realService) {
+        await state.realService.stop?.(ctx);
+      } else {
+        unregisterAcpRuntimeBackend(ACPX_BACKEND_ID);
+      }
+      state.ctx = null;
+      state.realRuntime = null;
+      state.realService = null;
+      state.startPromise = null;
+    },
+  };
+}

package/runtime-api.ts

@@ -0,0 +1,49 @@
+export type { AcpRuntimeErrorCode } from "klaw/plugin-sdk/acp-runtime-backend";
+export {
+  AcpRuntimeError,
+  getAcpRuntimeBackend,
+  tryDispatchAcpReplyHook,
+  registerAcpRuntimeBackend,
+  unregisterAcpRuntimeBackend,
+} from "klaw/plugin-sdk/acp-runtime-backend";
+export type {
+  AcpRuntime,
+  AcpRuntimeCapabilities,
+  AcpRuntimeDoctorReport,
+  AcpRuntimeEnsureInput,
+  AcpRuntimeEvent,
+  AcpRuntimeHandle,
+  AcpRuntimeStatus,
+  AcpRuntimeTurn,
+  AcpRuntimeTurnAttachment,
+  AcpRuntimeTurnInput,
+  AcpRuntimeTurnResult,
+  AcpRuntimeTurnResultError,
+  AcpSessionUpdateTag,
+} from "klaw/plugin-sdk/acp-runtime-backend";
+export type {
+  KlawPluginApi,
+  KlawPluginConfigSchema,
+  KlawPluginService,
+  KlawPluginServiceContext,
+  PluginLogger,
+} from "klaw/plugin-sdk/core";
+export type {
+  PluginHookReplyDispatchContext,
+  PluginHookReplyDispatchEvent,
+  PluginHookReplyDispatchResult,
+} from "klaw/plugin-sdk/core";
+export type {
+  WindowsSpawnProgram,
+  WindowsSpawnProgramCandidate,
+  WindowsSpawnResolution,
+} from "klaw/plugin-sdk/windows-spawn";
+export {
+  applyWindowsSpawnProgramPolicy,
+  materializeWindowsSpawnProgram,
+  resolveWindowsSpawnProgramCandidate,
+} from "klaw/plugin-sdk/windows-spawn";
+export {
+  listKnownProviderAuthEnvVarNames,
+  omitEnvKeysCaseInsensitive,
+} from "klaw/plugin-sdk/provider-env-vars";

package/setup-api.ts

@@ -0,0 +1,18 @@
+import { definePluginEntry } from "klaw/plugin-sdk/plugin-entry";
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+
+export default definePluginEntry({
+  id: "acpx",
+  name: "ACPX Setup",
+  description: "Lightweight ACPX setup hooks",
+  register(api) {
+    api.registerAutoEnableProbe(({ config }) => {
+      const backendRaw = normalizeLowercaseStringOrEmpty(config.acp?.backend);
+      const configured =
+        config.acp?.enabled === true ||
+        config.acp?.dispatch?.enabled === true ||
+        backendRaw === "acpx";
+      return configured && (!backendRaw || backendRaw === "acpx") ? "ACP runtime configured" : null;
+    });
+  },
+});

package/src/acpx-runtime-compat.d.ts

@@ -0,0 +1,65 @@
+declare module "acpx/runtime" {
+  export const ACPX_BACKEND_ID: string;
+
+  export type AcpRuntimeDoctorReport = import("../runtime-api.js").AcpRuntimeDoctorReport;
+  export type AcpRuntimeEnsureInput = import("../runtime-api.js").AcpRuntimeEnsureInput;
+  export type AcpRuntimeEvent = import("../runtime-api.js").AcpRuntimeEvent;
+  export type AcpRuntimeHandle = import("../runtime-api.js").AcpRuntimeHandle;
+  export type AcpRuntimeCapabilities = import("../runtime-api.js").AcpRuntimeCapabilities;
+  export type AcpRuntimeStatus = import("../runtime-api.js").AcpRuntimeStatus;
+  export type AcpRuntimeTurn = import("../runtime-api.js").AcpRuntimeTurn;
+  export type AcpRuntimeTurnInput = import("../runtime-api.js").AcpRuntimeTurnInput;
+  export type AcpRuntimeTurnResult = import("../runtime-api.js").AcpRuntimeTurnResult;
+
+  export type AcpAgentRegistry = {
+    resolve(agent: string): string | undefined;
+    list(): string[];
+  };
+
+  export type AcpSessionRecord = Record<string, unknown>;
+
+  export type AcpSessionStore = {
+    load(sessionId: string): Promise<AcpSessionRecord | undefined>;
+    save(record: AcpSessionRecord): Promise<void>;
+  };
+
+  export type AcpRuntimeOptions = {
+    cwd: string;
+    sessionStore: AcpSessionStore;
+    agentRegistry: AcpAgentRegistry;
+    probeAgent?: string;
+    mcpServers?: unknown;
+    permissionMode?: unknown;
+    nonInteractivePermissions?: unknown;
+    timeoutMs?: number;
+    probeAgent?: string;
+  };
+
+  export class AcpxRuntime {
+    constructor(options: AcpRuntimeOptions, testOptions?: unknown);
+    isHealthy(): boolean;
+    probeAvailability(): Promise<void>;
+    doctor(): Promise<AcpRuntimeDoctorReport>;
+    ensureSession(input: AcpRuntimeEnsureInput): Promise<AcpRuntimeHandle>;
+    startTurn(input: AcpRuntimeTurnInput): AcpRuntimeTurn;
+    runTurn(input: AcpRuntimeTurnInput): AsyncIterable<AcpRuntimeEvent>;
+    getCapabilities(input?: {
+      handle?: AcpRuntimeHandle;
+    }): AcpRuntimeCapabilities | Promise<AcpRuntimeCapabilities>;
+    getStatus(input: { handle: AcpRuntimeHandle; signal?: AbortSignal }): Promise<AcpRuntimeStatus>;
+    setMode(input: { handle: AcpRuntimeHandle; mode: string }): Promise<void>;
+    setConfigOption(input: { handle: AcpRuntimeHandle; key: string; value: string }): Promise<void>;
+    cancel(input: { handle: AcpRuntimeHandle; reason?: string }): Promise<void>;
+    close(input: {
+      handle: AcpRuntimeHandle;
+      reason?: string;
+      discardPersistentState?: boolean;
+    }): Promise<void>;
+  }
+
+  export function createAcpRuntime(...args: unknown[]): AcpxRuntime;
+  export function createAgentRegistry(params: { overrides?: unknown }): AcpAgentRegistry;
+  export function createFileSessionStore(params: { stateDir: string }): AcpSessionStore;
+  export function decodeAcpxRuntimeHandleState(...args: unknown[]): unknown;
+  export function encodeAcpxRuntimeHandleState(...args: unknown[]): unknown;
+}