@kodelyth/acpx 2026.5.42 → 2026.6.2

package/src/service.ts

@@ -1,630 +0,0 @@
-import { randomUUID } from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { inspect } from "node:util";
-import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
-import type {
-  AcpRuntime,
-  AcpRuntimeEvent,
-  KlawPluginService,
-  KlawPluginServiceContext,
-  PluginLogger,
-} from "../runtime-api.js";
-import { registerAcpRuntimeBackend, unregisterAcpRuntimeBackend } from "../runtime-api.js";
-import { prepareAcpxCodexAuthConfig } from "./codex-auth-bridge.js";
-import { DEFAULT_ACPX_TIMEOUT_SECONDS } from "./config-schema.js";
-import {
-  resolveAcpxPluginConfig,
-  toAcpMcpServers,
-  type ResolvedAcpxPluginConfig,
-} from "./config.js";
-import { createAcpxProcessLeaseStore, type AcpxProcessLeaseStore } from "./process-lease.js";
-import {
-  cleanupKlawOwnedAcpxProcessTree,
-  reapStaleKlawOwnedAcpxOrphans,
-  type AcpxProcessCleanupDeps,
-} from "./process-reaper.js";
-
-type AcpxRuntimeLike = AcpRuntime & {
-  probeAvailability(): Promise<void>;
-  isHealthy(): boolean;
-  doctor?(): Promise<{
-    ok: boolean;
-    message: string;
-    details?: string[];
-  }>;
-};
-type AcpRuntimeTurnInput = Parameters<AcpRuntime["runTurn"]>[0];
-type AcpRuntimeTurn = ReturnType<NonNullable<AcpRuntime["startTurn"]>>;
-type AcpRuntimeTurnResult = Awaited<AcpRuntimeTurn["result"]>;
-
-const ENABLE_STARTUP_PROBE_ENV = "KLAW_ACPX_RUNTIME_STARTUP_PROBE";
-const SKIP_RUNTIME_PROBE_ENV = "KLAW_SKIP_ACPX_RUNTIME_PROBE";
-const ACPX_BACKEND_ID = "acpx";
-
-type AcpxRuntimeModule = typeof import("./runtime.js");
-let runtimeModulePromise: Promise<AcpxRuntimeModule> | null = null;
-
-type AcpxRuntimeFactoryParams = {
-  pluginConfig: ResolvedAcpxPluginConfig;
-  gatewayInstanceId: string;
-  processLeaseStore: AcpxProcessLeaseStore;
-  wrapperRoot: string;
-  logger?: PluginLogger;
-};
-
-type CreateAcpxRuntimeServiceParams = {
-  pluginConfig?: unknown;
-  runtimeFactory?: (params: AcpxRuntimeFactoryParams) => AcpxRuntimeLike | Promise<AcpxRuntimeLike>;
-  processCleanupDeps?: AcpxProcessCleanupDeps;
-};
-
-function loadRuntimeModule(): Promise<AcpxRuntimeModule> {
-  runtimeModulePromise ??= import("./runtime.js");
-  return runtimeModulePromise;
-}
-
-function createDeferredResult<T>() {
-  let resolve!: (value: T) => void;
-  let reject!: (error: unknown) => void;
-  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
-    resolve = resolvePromise;
-    reject = rejectPromise;
-  });
-  return { promise, resolve, reject };
-}
-
-class LegacyRunTurnEventQueue {
-  private readonly items: AcpRuntimeEvent[] = [];
-  private readonly waits: Array<{
-    resolve: (value: AcpRuntimeEvent | null) => void;
-    reject: (error: unknown) => void;
-  }> = [];
-  private closed = false;
-  private error: unknown;
-
-  push(item: AcpRuntimeEvent): void {
-    if (this.closed) {
-      return;
-    }
-    const waiter = this.waits.shift();
-    if (waiter) {
-      waiter.resolve(item);
-      return;
-    }
-    this.items.push(item);
-  }
-
-  clear(): void {
-    this.items.length = 0;
-  }
-
-  close(): void {
-    if (this.closed) {
-      return;
-    }
-    this.closed = true;
-    for (const waiter of this.waits.splice(0)) {
-      waiter.resolve(null);
-    }
-  }
-
-  fail(error: unknown): void {
-    if (this.closed) {
-      return;
-    }
-    this.error = error;
-    this.closed = true;
-    for (const waiter of this.waits.splice(0)) {
-      waiter.reject(error);
-    }
-  }
-
-  private async next(): Promise<AcpRuntimeEvent | null> {
-    const item = this.items.shift();
-    if (item) {
-      return item;
-    }
-    if (this.error) {
-      throw this.error;
-    }
-    if (this.closed) {
-      return null;
-    }
-    return await new Promise<AcpRuntimeEvent | null>((resolve, reject) => {
-      this.waits.push({ resolve, reject });
-    });
-  }
-
-  async *iterate(): AsyncIterable<AcpRuntimeEvent> {
-    for (;;) {
-      const item = await this.next();
-      if (!item) {
-        return;
-      }
-      yield item;
-    }
-  }
-}
-
-function legacyRunTurnAsStartTurn(runtime: AcpRuntime, input: AcpRuntimeTurnInput): AcpRuntimeTurn {
-  const result = createDeferredResult<AcpRuntimeTurnResult>();
-  result.promise.catch(() => {});
-  const queue = new LegacyRunTurnEventQueue();
-  let resultSettled = false;
-  const settleResult = (next: AcpRuntimeTurnResult) => {
-    if (resultSettled) {
-      return;
-    }
-    resultSettled = true;
-    result.resolve(next);
-  };
-  void (async () => {
-    try {
-      for await (const event of runtime.runTurn(input)) {
-        if (event.type === "done") {
-          settleResult({
-            status: "completed",
-            ...(event.stopReason ? { stopReason: event.stopReason } : {}),
-          });
-          continue;
-        }
-        if (event.type === "error") {
-          settleResult({
-            status: "failed",
-            error: {
-              message: event.message,
-              ...(event.code ? { code: event.code } : {}),
-              ...(event.detailCode ? { detailCode: event.detailCode } : {}),
-              ...(event.retryable === undefined ? {} : { retryable: event.retryable }),
-            },
-          });
-          continue;
-        }
-        queue.push(event);
-      }
-      settleResult({
-        status: "failed",
-        error: {
-          code: "ACP_TURN_FAILED",
-          message: "ACP turn ended without a terminal done event.",
-        },
-      });
-    } catch (error) {
-      result.reject(error);
-      queue.fail(error);
-      return;
-    }
-    queue.close();
-  })();
-  return {
-    requestId: input.requestId,
-    events: queue.iterate(),
-    result: result.promise,
-    async cancel(inputArgs) {
-      await runtime.cancel({ handle: input.handle, reason: inputArgs?.reason });
-    },
-    async closeStream() {
-      queue.clear();
-      queue.close();
-    },
-  };
-}
-
-function startRuntimeTurn(runtime: AcpRuntime, input: AcpRuntimeTurnInput): AcpRuntimeTurn {
-  return runtime.startTurn?.(input) ?? legacyRunTurnAsStartTurn(runtime, input);
-}
-
-function createLazyDefaultRuntime(params: AcpxRuntimeFactoryParams): AcpxRuntimeLike {
-  let runtime: AcpxRuntimeLike | null = null;
-  let runtimePromise: Promise<AcpxRuntimeLike> | null = null;
-
-  async function resolveRuntime(): Promise<AcpxRuntimeLike> {
-    if (runtime) {
-      return runtime;
-    }
-    runtimePromise ??= loadRuntimeModule().then((module) => {
-      runtime = new module.AcpxRuntime({
-        cwd: params.pluginConfig.cwd,
-        klawGatewayInstanceId: params.gatewayInstanceId,
-        klawProcessLeaseStore: params.processLeaseStore,
-        klawWrapperRoot: params.wrapperRoot,
-        sessionStore: module.createFileSessionStore({
-          stateDir: params.pluginConfig.stateDir,
-        }),
-        agentRegistry: module.createAgentRegistry({
-          overrides: params.pluginConfig.agents,
-        }),
-        probeAgent: params.pluginConfig.probeAgent,
-        mcpServers: toAcpMcpServers(params.pluginConfig.mcpServers),
-        permissionMode: params.pluginConfig.permissionMode,
-        nonInteractivePermissions: params.pluginConfig.nonInteractivePermissions,
-        timeoutMs:
-          params.pluginConfig.timeoutSeconds != null
-            ? params.pluginConfig.timeoutSeconds * 1_000
-            : undefined,
-      }) as AcpxRuntimeLike;
-      return runtime;
-    });
-    return await runtimePromise;
-  }
-
-  return {
-    async ensureSession(input) {
-      return await (await resolveRuntime()).ensureSession(input);
-    },
-    startTurn(input) {
-      const turnPromise = resolveRuntime().then((resolved) => startRuntimeTurn(resolved, input));
-      return {
-        requestId: input.requestId,
-        events: {
-          async *[Symbol.asyncIterator]() {
-            yield* (await turnPromise).events;
-          },
-        },
-        result: turnPromise.then((turn) => turn.result),
-        cancel(inputArgs) {
-          return turnPromise.then((turn) => turn.cancel(inputArgs));
-        },
-        closeStream(inputArgs) {
-          return turnPromise.then((turn) => turn.closeStream(inputArgs));
-        },
-      };
-    },
-    async *runTurn(input) {
-      yield* (await resolveRuntime()).runTurn(input);
-    },
-    async getCapabilities(input) {
-      return (await (await resolveRuntime()).getCapabilities?.(input)) ?? { controls: [] };
-    },
-    async getStatus(input) {
-      return (await (await resolveRuntime()).getStatus?.(input)) ?? {};
-    },
-    async setMode(input) {
-      await (await resolveRuntime()).setMode?.(input);
-    },
-    async setConfigOption(input) {
-      await (await resolveRuntime()).setConfigOption?.(input);
-    },
-    async doctor() {
-      return (await (await resolveRuntime()).doctor?.()) ?? { ok: true, message: "ok" };
-    },
-    async prepareFreshSession(input) {
-      await (await resolveRuntime()).prepareFreshSession?.(input);
-    },
-    async cancel(input) {
-      await (await resolveRuntime()).cancel(input);
-    },
-    async close(input) {
-      await (await resolveRuntime()).close(input);
-    },
-    async probeAvailability() {
-      await (await resolveRuntime()).probeAvailability();
-    },
-    isHealthy() {
-      return runtime?.isHealthy() ?? false;
-    },
-  };
-}
-
-function warnOnIgnoredLegacyCompatibilityConfig(params: {
-  pluginConfig: ResolvedAcpxPluginConfig;
-  logger?: PluginLogger;
-}): void {
-  const ignoredFields: string[] = [];
-  if (params.pluginConfig.legacyCompatibilityConfig.queueOwnerTtlSeconds != null) {
-    ignoredFields.push("queueOwnerTtlSeconds");
-  }
-  if (params.pluginConfig.legacyCompatibilityConfig.strictWindowsCmdWrapper === false) {
-    ignoredFields.push("strictWindowsCmdWrapper=false");
-  }
-  if (ignoredFields.length === 0) {
-    return;
-  }
-  params.logger?.warn(
-    `embedded acpx runtime ignores legacy compatibility config: ${ignoredFields.join(", ")}`,
-  );
-}
-
-function formatDoctorDetail(detail: unknown): string | null {
-  if (!detail) {
-    return null;
-  }
-  if (typeof detail === "string") {
-    return detail.trim() || null;
-  }
-  if (detail instanceof Error) {
-    return formatErrorMessage(detail);
-  }
-  if (typeof detail === "object") {
-    try {
-      return JSON.stringify(detail) ?? inspect(detail, { breakLength: Infinity, depth: 3 });
-    } catch {
-      return inspect(detail, { breakLength: Infinity, depth: 3 });
-    }
-  }
-  if (
-    typeof detail === "number" ||
-    typeof detail === "boolean" ||
-    typeof detail === "bigint" ||
-    typeof detail === "symbol"
-  ) {
-    return detail.toString();
-  }
-  return inspect(detail, { breakLength: Infinity, depth: 3 });
-}
-
-function formatDoctorFailureMessage(report: { message: string; details?: unknown[] }): string {
-  const detailText = report.details?.map(formatDoctorDetail).filter(Boolean).join("; ").trim();
-  return detailText ? `${report.message} (${detailText})` : report.message;
-}
-
-function normalizeProbeAgent(value: string | undefined): string | undefined {
-  const normalized = value?.trim().toLowerCase();
-  return normalized ? normalized : undefined;
-}
-
-function resolveAllowedAgentsProbeAgent(ctx: KlawPluginServiceContext): string | undefined {
-  for (const agent of ctx.config.acp?.allowedAgents ?? []) {
-    const normalized = normalizeProbeAgent(agent);
-    if (normalized) {
-      return normalized;
-    }
-  }
-  return undefined;
-}
-
-async function measureAcpxStartup<T>(
-  ctx: KlawPluginServiceContext,
-  name: string,
-  run: () => T | Promise<T>,
-): Promise<T> {
-  return ctx.startupTrace ? await ctx.startupTrace.measure(name, run) : await run();
-}
-
-function detailAcpxStartup(
-  ctx: KlawPluginServiceContext,
-  name: string,
-  metrics: ReadonlyArray<readonly [string, number | string]>,
-): void {
-  ctx.startupTrace?.detail?.(name, metrics);
-}
-
-function shouldRunStartupProbe(env: NodeJS.ProcessEnv = process.env): boolean {
-  return env[ENABLE_STARTUP_PROBE_ENV] !== "0";
-}
-
-function shouldProbeRuntimeAtStartup(env: NodeJS.ProcessEnv = process.env): boolean {
-  return shouldRunStartupProbe(env) && env[SKIP_RUNTIME_PROBE_ENV] !== "1";
-}
-
-async function withStartupProbeTimeout<T>(params: {
-  promise: Promise<T>;
-  timeoutSeconds: number;
-}): Promise<T> {
-  let timeout: ReturnType<typeof setTimeout> | undefined;
-  const timeoutMs = Math.max(1, params.timeoutSeconds * 1_000);
-  try {
-    return await Promise.race([
-      params.promise,
-      new Promise<never>((_, reject) => {
-        timeout = setTimeout(() => {
-          reject(
-            new Error(
-              `embedded acpx runtime backend startup probe timed out after ${params.timeoutSeconds}s`,
-            ),
-          );
-        }, timeoutMs);
-        (timeout as { unref?: () => void }).unref?.();
-      }),
-    ]);
-  } finally {
-    if (timeout) {
-      clearTimeout(timeout);
-    }
-  }
-}
-
-async function resolveGatewayInstanceId(stateDir: string): Promise<string> {
-  const filePath = path.join(stateDir, "gateway-instance-id");
-  try {
-    const existing = (await fs.readFile(filePath, "utf8")).trim();
-    if (existing) {
-      return existing;
-    }
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
-      throw error;
-    }
-  }
-  const next = randomUUID();
-  await fs.mkdir(stateDir, { recursive: true });
-  await fs.writeFile(filePath, `${next}\n`, { mode: 0o600 });
-  return next;
-}
-
-async function reapOpenAcpxProcessLeases(params: {
-  gatewayInstanceId: string;
-  leaseStore: AcpxProcessLeaseStore;
-  deps?: AcpxProcessCleanupDeps;
-}): Promise<{ inspectedPids: number[]; terminatedPids: number[] }> {
-  const leases = await params.leaseStore.listOpen(params.gatewayInstanceId);
-  const inspectedPids: number[] = [];
-  const terminatedPids: number[] = [];
-  const pendingLeaseRootResults = new Map<
-    string,
-    { inspectedPids: number[]; terminatedPids: number[] }
-  >();
-  for (const lease of leases) {
-    if (lease.rootPid <= 0) {
-      await params.leaseStore.markState(lease.leaseId, "closing");
-      let result = pendingLeaseRootResults.get(lease.wrapperRoot);
-      if (!result) {
-        result = await reapStaleKlawOwnedAcpxOrphans({
-          wrapperRoot: lease.wrapperRoot,
-          deps: params.deps,
-        });
-        pendingLeaseRootResults.set(lease.wrapperRoot, result);
-        inspectedPids.push(...result.inspectedPids);
-        terminatedPids.push(...result.terminatedPids);
-      }
-      await params.leaseStore.markState(
-        lease.leaseId,
-        result.terminatedPids.length > 0 ? "closed" : "lost",
-      );
-      continue;
-    }
-    await params.leaseStore.markState(lease.leaseId, "closing");
-    const result = await cleanupKlawOwnedAcpxProcessTree({
-      rootPid: lease.rootPid,
-      expectedLeaseId: lease.leaseId,
-      expectedGatewayInstanceId: lease.gatewayInstanceId,
-      wrapperRoot: lease.wrapperRoot,
-      deps: params.deps,
-    });
-    inspectedPids.push(...result.inspectedPids);
-    terminatedPids.push(...result.terminatedPids);
-    await params.leaseStore.markState(
-      lease.leaseId,
-      result.terminatedPids.length > 0 ? "closed" : "lost",
-    );
-  }
-  return { inspectedPids, terminatedPids };
-}
-
-export function createAcpxRuntimeService(
-  params: CreateAcpxRuntimeServiceParams = {},
-): KlawPluginService {
-  let runtime: AcpxRuntimeLike | null = null;
-  let lifecycleRevision = 0;
-
-  return {
-    id: "acpx-runtime",
-    async start(ctx: KlawPluginServiceContext): Promise<void> {
-      if (process.env.KLAW_SKIP_ACPX_RUNTIME === "1") {
-        ctx.logger.info("skipping embedded acpx runtime backend (KLAW_SKIP_ACPX_RUNTIME=1)");
-        return;
-      }
-
-      const basePluginConfig = await measureAcpxStartup(ctx, "config.resolve", () =>
-        resolveAcpxPluginConfig({
-          rawConfig: params.pluginConfig,
-          workspaceDir: ctx.workspaceDir,
-        }),
-      );
-      const effectiveBasePluginConfig: ResolvedAcpxPluginConfig = {
-        ...basePluginConfig,
-        probeAgent: basePluginConfig.probeAgent ?? resolveAllowedAgentsProbeAgent(ctx),
-      };
-      const pluginConfig = await measureAcpxStartup(ctx, "config.prepare-codex-auth", () =>
-        prepareAcpxCodexAuthConfig({
-          pluginConfig: effectiveBasePluginConfig,
-          stateDir: ctx.stateDir,
-          logger: ctx.logger,
-        }),
-      );
-      const wrapperRoot = path.join(ctx.stateDir, "acpx");
-      await measureAcpxStartup(ctx, "filesystem.prepare", async () => {
-        await fs.mkdir(pluginConfig.stateDir, { recursive: true });
-        await fs.mkdir(wrapperRoot, { recursive: true });
-      });
-      const gatewayInstanceId = await measureAcpxStartup(ctx, "gateway-instance-id", () =>
-        resolveGatewayInstanceId(ctx.stateDir),
-      );
-      const processLeaseStore = createAcpxProcessLeaseStore({ stateDir: wrapperRoot });
-      const startupReap = await measureAcpxStartup(ctx, "process-leases.reap", () =>
-        reapOpenAcpxProcessLeases({
-          gatewayInstanceId,
-          leaseStore: processLeaseStore,
-          deps: params.processCleanupDeps,
-        }),
-      );
-      if (startupReap.terminatedPids.length > 0) {
-        ctx.logger.info(
-          `reaped ${startupReap.terminatedPids.length} stale Klaw-owned ACPX process${startupReap.terminatedPids.length === 1 ? "" : "es"}`,
-        );
-      }
-      warnOnIgnoredLegacyCompatibilityConfig({
-        pluginConfig,
-        logger: ctx.logger,
-      });
-
-      const startedRuntime = await measureAcpxStartup(ctx, "runtime.create", () =>
-        params.runtimeFactory
-          ? params.runtimeFactory({
-              pluginConfig,
-              gatewayInstanceId,
-              processLeaseStore,
-              wrapperRoot,
-              logger: ctx.logger,
-            })
-          : createLazyDefaultRuntime({
-              pluginConfig,
-              gatewayInstanceId,
-              processLeaseStore,
-              wrapperRoot,
-              logger: ctx.logger,
-            }),
-      );
-      runtime = startedRuntime;
-
-      const shouldProbeRuntime = shouldProbeRuntimeAtStartup();
-      detailAcpxStartup(ctx, "probe-policy", [
-        ["startupProbeEnabledCount", shouldProbeRuntime ? 1 : 0],
-        ["probeAgent", pluginConfig.probeAgent ?? "default"],
-      ]);
-      await measureAcpxStartup(ctx, "backend.register", () => {
-        registerAcpRuntimeBackend({
-          id: ACPX_BACKEND_ID,
-          runtime: startedRuntime,
-          ...(shouldProbeRuntime ? { healthy: () => runtime?.isHealthy() ?? false } : {}),
-        });
-        ctx.logger.info(`embedded acpx runtime backend registered (cwd: ${pluginConfig.cwd})`);
-      });
-
-      if (!shouldProbeRuntime) {
-        return;
-      }
-
-      lifecycleRevision += 1;
-      const currentRevision = lifecycleRevision;
-      try {
-        await measureAcpxStartup(ctx, "probe.availability", () =>
-          withStartupProbeTimeout({
-            promise: startedRuntime.probeAvailability(),
-            timeoutSeconds: pluginConfig.timeoutSeconds ?? DEFAULT_ACPX_TIMEOUT_SECONDS,
-          }),
-        );
-        if (currentRevision !== lifecycleRevision) {
-          return;
-        }
-        if (startedRuntime.isHealthy()) {
-          detailAcpxStartup(ctx, "probe.result", [["healthyCount", 1]]);
-          ctx.logger.info("embedded acpx runtime backend ready");
-          return;
-        }
-        const doctorReport = await measureAcpxStartup(ctx, "probe.doctor", () =>
-          startedRuntime.doctor?.(),
-        );
-        if (currentRevision !== lifecycleRevision) {
-          return;
-        }
-        detailAcpxStartup(ctx, "probe.result", [["healthyCount", 0]]);
-        ctx.logger.warn(
-          `embedded acpx runtime backend probe failed: ${doctorReport ? formatDoctorFailureMessage(doctorReport) : "backend remained unhealthy after probe"}`,
-        );
-      } catch (err) {
-        if (currentRevision !== lifecycleRevision) {
-          return;
-        }
-        detailAcpxStartup(ctx, "probe.result", [["healthyCount", 0]]);
-        ctx.logger.warn(`embedded acpx runtime setup failed: ${formatErrorMessage(err)}`);
-      }
-    },
-    async stop(_ctx: KlawPluginServiceContext): Promise<void> {
-      lifecycleRevision += 1;
-      unregisterAcpRuntimeBackend(ACPX_BACKEND_ID);
-      runtime = null;
-    },
-  };
-}

package/tsconfig.json

@@ -1,16 +0,0 @@
-{
-  "extends": "../tsconfig.package-boundary.base.json",
-  "compilerOptions": {
-    "rootDir": "."
-  },
-  "include": ["./*.ts", "./src/**/*.ts"],
-  "exclude": [
-    "./**/*.test.ts",
-    "./dist/**",
-    "./node_modules/**",
-    "./src/test-support/**",
-    "./src/**/*test-helpers.ts",
-    "./src/**/*test-harness.ts",
-    "./src/**/*test-support.ts"
-  ]
-}