@actagent/acpx 2026.6.2

package/src/runtime-internals/mcp-proxy.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+/**
+ * Stdio MCP proxy used by ACPX wrappers. It injects ACTAgent-provided MCP
+ * servers into session creation/load/fork requests before forwarding to target.
+ */
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
+import { splitCommandLine } from "./mcp-command-line.mjs";
+
+function formatErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message || error.name || "Error";
+  }
+  return String(error);
+}
+
+function decodePayload(argv) {
+  const payloadIndex = argv.indexOf("--payload");
+  if (payloadIndex < 0) {
+    throw new Error("Missing --payload");
+  }
+  const encoded = argv[payloadIndex + 1];
+  if (!encoded) {
+    throw new Error("Missing MCP proxy payload value");
+  }
+  const parsed = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Invalid MCP proxy payload");
+  }
+  if (typeof parsed.targetCommand !== "string" || parsed.targetCommand.trim() === "") {
+    throw new Error("MCP proxy payload missing targetCommand");
+  }
+  const mcpServers = Array.isArray(parsed.mcpServers) ? parsed.mcpServers : [];
+  return {
+    targetCommand: parsed.targetCommand,
+    mcpServers,
+  };
+}
+
+function shouldInject(method) {
+  return method === "session/new" || method === "session/load" || method === "session/fork";
+}
+
+function rewriteLine(line, mcpServers) {
+  if (!line.trim()) {
+    return line;
+  }
+  try {
+    const parsed = JSON.parse(line);
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed) ||
+      !shouldInject(parsed.method) ||
+      !parsed.params ||
+      typeof parsed.params !== "object" ||
+      Array.isArray(parsed.params)
+    ) {
+      return line;
+    }
+    const next = {
+      ...parsed,
+      params: {
+        ...parsed.params,
+        mcpServers,
+      },
+    };
+    return JSON.stringify(next);
+  } catch {
+    return line;
+  }
+}
+
+/** Build spawn options for the proxied MCP target process. */
+export function createTargetSpawnOptions(platform = process.platform) {
+  const options = {
+    stdio: ["pipe", "pipe", "inherit"],
+    env: process.env,
+  };
+  if (platform === "win32") {
+    options.windowsHide = true;
+  }
+  return options;
+}
+
+function isMainModule() {
+  const mainPath = process.argv[1];
+  if (!mainPath) {
+    return false;
+  }
+  return import.meta.url === pathToFileURL(path.resolve(mainPath)).href;
+}
+
+function main() {
+  const { targetCommand, mcpServers } = decodePayload(process.argv.slice(2));
+  const target = splitCommandLine(targetCommand);
+  const child = spawn(target.command, target.args, createTargetSpawnOptions());
+
+  if (!child.stdin || !child.stdout) {
+    throw new Error("Failed to create MCP proxy stdio pipes");
+  }
+
+  const input = createInterface({ input: process.stdin });
+  input.on("line", (line) => {
+    child.stdin.write(`${rewriteLine(line, mcpServers)}\n`);
+  });
+  input.on("close", () => {
+    child.stdin.end();
+  });
+
+  child.stdout.pipe(process.stdout);
+
+  child.on("error", (error) => {
+    process.stderr.write(`${formatErrorMessage(error)}\n`);
+    process.exit(1);
+  });
+
+  child.on("close", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+}
+
+if (isMainModule()) {
+  main();
+}

package/src/runtime-internals/mcp-proxy.test.ts

@@ -0,0 +1,131 @@
+// ACPX tests cover mcp proxy plugin behavior.
+import { spawn } from "node:child_process";
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { bundledPluginFile } from "actagent/plugin-sdk/test-fixtures";
+import { afterEach, describe, expect, it } from "vitest";
+
+const tempDirs: string[] = [];
+const proxyPath = path.resolve(bundledPluginFile("acpx", "src/runtime-internals/mcp-proxy.mjs"));
+
+async function makeTempScript(name: string, content: string): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "actagent-acpx-mcp-proxy-"));
+  tempDirs.push(dir);
+  const scriptPath = path.join(dir, name);
+  await writeFile(scriptPath, content, "utf8");
+  await chmod(scriptPath, 0o755);
+  return scriptPath;
+}
+
+afterEach(async () => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (!dir) {
+      continue;
+    }
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+describe("mcp-proxy", () => {
+  it("hides the target MCP process window on Windows only", async () => {
+    const moduleUrl = pathToFileURL(proxyPath).href;
+    const { createTargetSpawnOptions } = (await import(moduleUrl)) as {
+      createTargetSpawnOptions: (platform?: NodeJS.Platform) => Record<string, unknown>;
+    };
+
+    expect(createTargetSpawnOptions("win32")).toEqual({
+      env: process.env,
+      stdio: ["pipe", "pipe", "inherit"],
+      windowsHide: true,
+    });
+    expect(createTargetSpawnOptions("darwin")).not.toHaveProperty("windowsHide");
+    expect(createTargetSpawnOptions("linux")).not.toHaveProperty("windowsHide");
+  });
+
+  it("injects configured MCP servers into ACP session bootstrap requests", async () => {
+    const echoServerPath = await makeTempScript(
+      "echo-server.cjs",
+      String.raw`#!/usr/bin/env node
+const { createInterface } = require("node:readline");
+const rl = createInterface({ input: process.stdin });
+rl.on("line", (line) => process.stdout.write(line + "\n"));
+`,
+    );
+
+    const payload = Buffer.from(
+      JSON.stringify({
+        targetCommand: `${process.execPath} ${echoServerPath}`,
+        mcpServers: [
+          {
+            name: "canva",
+            command: "npx",
+            args: ["-y", "mcp-remote@latest", "https://mcp.canva.com/mcp"],
+            env: [{ name: "CANVA_TOKEN", value: "secret" }],
+          },
+        ],
+      }),
+      "utf8",
+    ).toString("base64url");
+
+    const child = spawn(process.execPath, [proxyPath, "--payload", payload], {
+      stdio: ["pipe", "pipe", "inherit"],
+      cwd: process.cwd(),
+    });
+
+    let stdout = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+
+    child.stdin.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "session/new",
+        params: { cwd: process.cwd(), mcpServers: [] },
+      })}\n`,
+    );
+    child.stdin.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: 2,
+        method: "session/load",
+        params: { cwd: process.cwd(), sessionId: "sid-1", mcpServers: [] },
+      })}\n`,
+    );
+    child.stdin.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: 3,
+        method: "session/prompt",
+        params: { sessionId: "sid-1", prompt: [{ type: "text", text: "hello" }] },
+      })}\n`,
+    );
+    child.stdin.end();
+
+    const exitCode = await new Promise<number | null>((resolve) => {
+      child.once("close", (code) => resolve(code));
+    });
+
+    expect(exitCode).toBe(0);
+    const lines = stdout
+      .trim()
+      .split(/\r?\n/)
+      .map((line) => JSON.parse(line) as { method: string; params: Record<string, unknown> });
+
+    expect(lines[0].params.mcpServers).toEqual([
+      {
+        name: "canva",
+        command: "npx",
+        args: ["-y", "mcp-remote@latest", "https://mcp.canva.com/mcp"],
+        env: [{ name: "CANVA_TOKEN", value: "secret" }],
+      },
+    ]);
+    expect(lines[1].params.mcpServers).toEqual(lines[0].params.mcpServers);
+    expect(lines[2].method).toBe("session/prompt");
+    expect(lines[2].params.mcpServers).toBeUndefined();
+  });
+});

package/src/runtime-proxy.ts

@@ -0,0 +1,47 @@
+/**
+ * Lazy ACP runtime proxy for ACPX. It defers resolving the real runtime until
+ * the first ACP call while preserving the SDK runtime shape.
+ */
+import type { AcpRuntime } from "../runtime-api.js";
+import { lazyStartRuntimeTurn } from "./runtime-turn.js";
+
+/** Create an ACP runtime facade backed by an async runtime resolver. */
+export function createLazyAcpRuntimeProxy<T extends AcpRuntime>(
+  resolveRuntime: () => Promise<T>,
+): AcpRuntime {
+  return {
+    async ensureSession(input) {
+      return await (await resolveRuntime()).ensureSession(input);
+    },
+    startTurn(input) {
+      return lazyStartRuntimeTurn(resolveRuntime, input);
+    },
+    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);
+    },
+  };
+}

package/src/runtime-turn.ts

@@ -0,0 +1,200 @@
+/**
+ * ACPX turn adapters. Modern runtimes can expose startTurn directly; legacy
+ * runtimes that only stream runTurn events are adapted to the newer contract.
+ */
+import type {
+  AcpRuntime,
+  AcpRuntimeEvent,
+  AcpRuntimeTurn,
+  AcpRuntimeTurnInput,
+  AcpRuntimeTurnResult,
+} from "../runtime-api.js";
+
+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 toLintErrorObject(this.error, "Non-Error thrown");
+    }
+    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();
+    },
+  };
+}
+
+/** Start an ACP turn, adapting legacy runTurn-only runtimes when needed. */
+export function startRuntimeTurn(runtime: AcpRuntime, input: AcpRuntimeTurnInput): AcpRuntimeTurn {
+  return runtime.startTurn?.(input) ?? legacyRunTurnAsStartTurn(runtime, input);
+}
+
+/** Start an ACP turn through a lazy runtime resolver. */
+export function lazyStartRuntimeTurn(
+  resolveRuntime: () => Promise<AcpRuntime>,
+  input: AcpRuntimeTurnInput,
+): AcpRuntimeTurn {
+  const turnPromise = resolveRuntime().then((runtime) => startRuntimeTurn(runtime, 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));
+    },
+  };
+}
+
+function toLintErrorObject(value: unknown, fallbackMessage: string): Error {
+  if (value instanceof Error) {
+    return value;
+  }
+  if (typeof value === "string") {
+    return new Error(value);
+  }
+  const error = new Error(fallbackMessage, { cause: value });
+  if ((typeof value === "object" && value !== null) || typeof value === "function") {
+    Object.assign(error, value);
+  }
+  return error;
+}