@ganglion/xacpx 0.19.2 → 0.20.0-beta.0

package/README.md

@@ -31,7 +31,7 @@ Chat isn't the only entry point: xacpx also ships a self-hostable **[relay hub](
 
 ### Prerequisites
 
-- Node.js 22.12+ or Bun
+- Node.js 22.13+ or Bun
 - A working agent CLI you intend to use, such as Codex / Claude Code / Gemini / OpenCode
 - A phone with WeChat, Feishu, or Yuanbao installed
 

package/dist/adapters/adapter-catalog.d.ts

@@ -2,24 +2,71 @@ export declare const MANAGED_ADAPTERS: {
     readonly codex: {
         readonly packageName: "@agentclientprotocol/codex-acp";
         readonly binName: "codex-acp";
-        readonly defaultVersion: "1.1.4";
+        readonly defaultVersion: "1.1.9";
     };
     readonly claude: {
         readonly packageName: "@agentclientprotocol/claude-agent-acp";
         readonly binName: "claude-agent-acp";
-        readonly defaultVersion: "0.59.0";
+        readonly defaultVersion: "0.64.2";
     };
 };
 export type ManagedAdapterId = keyof typeof MANAGED_ADAPTERS;
 export type AdapterVersionOverrides = Partial<Record<ManagedAdapterId, string>>;
+export interface ManagedNpxCommand {
+    kind: "npx";
+    id: ManagedAdapterId;
+    version: string;
+    registry?: string;
+}
+export interface ManagedPreinstalledCommand {
+    kind: "preinstalled";
+    id: ManagedAdapterId;
+    releaseId: string;
+    nodeExecutable: string;
+    entryPath: string;
+}
+export type DecodedManagedAdapterCommand = ManagedNpxCommand | ManagedPreinstalledCommand;
 export declare function isManagedAdapterId(value: string): value is ManagedAdapterId;
 export declare function listManagedAdapterIds(): ManagedAdapterId[];
 export declare function isExactAdapterVersion(value: string): boolean;
 export declare function effectiveAdapterVersion(id: ManagedAdapterId, overrides: AdapterVersionOverrides | undefined): string;
+export declare function buildManagedAdapterArgv(id: ManagedAdapterId, version: string, registry?: string): string[];
 export declare function buildManagedAdapterCommand(id: ManagedAdapterId, version: string, registry?: string): string;
+export declare function resolveManagedAdapterArgv(driver: string, overrides?: AdapterVersionOverrides, registry?: string): string[] | undefined;
 export declare function resolveManagedAdapterCommand(driver: string, overrides?: AdapterVersionOverrides, registry?: string): string | undefined;
 export declare function isManagedAdapterCommand(driver: string, command: string | undefined): boolean;
 export declare function managedAdapterRegistryFromCommand(command: string | undefined): string | undefined;
+export declare function canonicalAdapterRegistry(registry: string): string;
+export declare function adapterRegistryHash8(registry: string): string;
+export declare function createAdapterReleaseId(version: string, registry: string, uuid?: string): string;
+export declare function parseAdapterReleaseId(releaseId: string): {
+    version: string;
+    registryHash8: string;
+    uuid8: string;
+} | null;
+export declare function splitAdapterCommand(command: string): string[] | null;
+/** Structural preinstall classifier used only to decide whether launch fencing is mandatory. */
+export declare function classifyPreinstalledAdapterCommandShape(command: string | undefined): ManagedAdapterId | null;
+export interface ClassifyRecordedPreinstalledAdapterCommandOptions {
+    /** Trusted xacpx runtime root containing the managed adapters directory. */
+    runtimeRoot: string;
+    platform?: NodeJS.Platform;
+}
+/**
+ * Strict structural classifier for persisted session identity. Unlike the broad
+ * fencing classifier above, this only treats a command as derived managed state
+ * when its entry is under the trusted runtime adapter root and has the complete
+ * immutable release/package layout.
+ */
+export declare function classifyRecordedPreinstalledAdapterCommand(command: string | undefined, options: ClassifyRecordedPreinstalledAdapterCommandOptions): ManagedAdapterId | null;
+export interface DecodeManagedAdapterCommandOptions {
+    adaptersRoot?: string;
+    controlledNodeExecutable?: string;
+    platform?: NodeJS.Platform;
+    realpath?: (path: string) => Promise<string>;
+}
+/** The single trust-boundary decoder used by classification and GC. */
+export declare function decodeManagedAdapterCommand(command: string | undefined, options?: DecodeManagedAdapterCommandOptions): Promise<DecodedManagedAdapterCommand | null>;
 /** A recorded generated command is derived state, so a newer configured/default
  * version replaces it. Truly custom commands remain sticky for session identity. */
 export declare function preferCurrentManagedAdapterCommand(driver: string, recorded: string | undefined, current: string | undefined): string | undefined;

package/dist/adapters/adapter-npm.d.ts

@@ -0,0 +1,6 @@
+import { type ManagedAdapterId } from "./adapter-catalog";
+export declare function getAdapterNpmVersion(id: ManagedAdapterId, version: string | undefined, registry: string): Promise<string | null>;
+export declare function resolveNpmCommand(): {
+    command: string;
+    prefixArgs: string[];
+};

package/dist/adapters/adapter-preinstall.d.ts

@@ -0,0 +1,64 @@
+import { type ManagedAdapterId } from "./adapter-catalog";
+export interface InstalledAdapterManifest {
+    schemaVersion: 1;
+    id: ManagedAdapterId;
+    packageName: string;
+    version: string;
+    releaseId: string;
+    registry: string;
+    nodeExecutable: string;
+    entryRelPath: string;
+    installedAt: string;
+}
+export interface ActiveAdapterPointer {
+    version: string;
+    releaseId: string;
+    activatedAt: string;
+}
+export interface ValidateReleaseExpected {
+    id: ManagedAdapterId;
+    version: string;
+    packageName: string;
+    registry: string;
+    releaseId: string;
+}
+export interface ValidateReleaseOptions {
+    probe?: boolean;
+    verify?: (command: string, args: string[]) => Promise<void>;
+    platform?: NodeJS.Platform;
+    staging?: boolean;
+}
+export interface PreinstallAdapterOptions {
+    runtimeRoot: string;
+    id: ManagedAdapterId;
+    version: string;
+    registry: string;
+    nodeExecutable?: string;
+    now?: () => Date;
+    uuid?: () => string;
+    installPackage?: (stagingDir: string, packageSpec: string, registry: string) => Promise<void>;
+    verify?: (command: string, args: string[]) => Promise<void>;
+    fault?: (boundary: string) => void | Promise<void>;
+}
+export declare function validateAdapterRelease(releaseDir: string, expected: ValidateReleaseExpected, options?: ValidateReleaseOptions): Promise<InstalledAdapterManifest>;
+export declare function preinstallAdapter(options: PreinstallAdapterOptions): Promise<{
+    releaseDir: string;
+    manifest: InstalledAdapterManifest;
+    pointer: ActiveAdapterPointer;
+}>;
+export declare function recoverAdapterInstall(runtimeRoot: string, id: ManagedAdapterId): Promise<void>;
+export declare function readActiveAdapterPointer(runtimeRoot: string, id: ManagedAdapterId): Promise<ActiveAdapterPointer | null>;
+export declare function listInstalledAdapterReleases(runtimeRoot: string): Promise<Array<{
+    id: ManagedAdapterId;
+    releaseId: string;
+    active: boolean;
+}>>;
+/** Spawn-time static validation. The initialize probe is intentionally skipped. */
+export declare function resolveActiveAdapterCommandSync(runtimeRoot: string, expected: Omit<ValidateReleaseExpected, "releaseId">): string | null;
+/** Structured-argv variant of the spawn-time resolution for lossless launches. */
+export declare function resolveActiveAdapterArgvSync(runtimeRoot: string, expected: Omit<ValidateReleaseExpected, "releaseId">): string[] | null;
+/** Validate the referenced immutable release, then re-resolve the active pointer. */
+export declare function validateAndReResolveAdapterCommand(runtimeRoot: string, command: string): Promise<{
+    id: ManagedAdapterId;
+    agentCommand: string;
+}>;

package/dist/adapters/adapter-registry.d.ts

@@ -1,4 +1,4 @@
-export declare const DEFAULT_ADAPTER_REGISTRY = "https://registry.npmjs.org/";
+export declare const DEFAULT_ADAPTER_REGISTRY = "https://registry.npmjs.org";
 export declare class AdapterRegistryPackageNotFoundError extends Error {
     readonly registry: string;
     readonly code = "E404";

package/dist/adapters/adapter-verifier.d.ts

@@ -0,0 +1,10 @@
+import { type ManagedAdapterId } from "./adapter-catalog";
+interface VerifyOptions {
+    timeoutMs?: number;
+    adapterRegistry?: string;
+}
+/** Runs a structured ACP initialize probe and tears down the process tree afterward. */
+export declare function verifyAcpInitialize(command: string, args: string[], options?: VerifyOptions): Promise<void>;
+/** Downloads the exact package version through npm's exec cache, then probes ACP. */
+export declare function verifyAdapterVersion(id: ManagedAdapterId, version: string, registry?: string): Promise<void>;
+export {};

package/dist/adapters/hermes-acp-shim.js

@@ -0,0 +1,172 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __promiseAll = (args) => Promise.all(args);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/adapters/hermes-shim.ts
+import { fileURLToPath } from "node:url";
+function isDefaultHermesCommand(command) {
+  return command.trim().replaceAll(/\s+/g, " ") === DEFAULT_HERMES_COMMAND;
+}
+function isHermesShimCommand(command) {
+  return command.includes("/hermes-acp-shim.") || command.includes("\\hermes-acp-shim.");
+}
+function resolveHermesAcpShimEntry(moduleUrl = import.meta.url) {
+  if (moduleUrl.endsWith(".ts")) {
+    return fileURLToPath(new URL("./hermes-acp-shim.ts", moduleUrl));
+  }
+  const idx = moduleUrl.lastIndexOf(DIST_MARKER);
+  if (idx !== -1) {
+    return fileURLToPath(new URL(`${moduleUrl.slice(0, idx + DIST_MARKER.length)}adapters/hermes-acp-shim.js`));
+  }
+  return fileURLToPath(new URL("./hermes-acp-shim.js", moduleUrl));
+}
+function hermesAcpShimArgv(execPath = process.execPath, shimEntry = resolveHermesAcpShimEntry()) {
+  return [execPath, shimEntry, "hermes", "acp"];
+}
+function stripResumeCapability(line) {
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!message || typeof message !== "object")
+    return null;
+  const result = message.result;
+  if (!result || typeof result !== "object")
+    return null;
+  const capabilities = result.agentCapabilities;
+  if (!capabilities || typeof capabilities !== "object")
+    return null;
+  const sessionCapabilities = capabilities.sessionCapabilities;
+  if (!sessionCapabilities || typeof sessionCapabilities !== "object")
+    return null;
+  if (!Object.hasOwn(sessionCapabilities, "resume"))
+    return null;
+  delete sessionCapabilities.resume;
+  return JSON.stringify(message);
+}
+function isInitializeResponse(line) {
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch {
+    return false;
+  }
+  if (!message || typeof message !== "object")
+    return false;
+  const result = message.result;
+  if (!result || typeof result !== "object")
+    return false;
+  const capabilities = result.agentCapabilities;
+  return Boolean(capabilities) && typeof capabilities === "object";
+}
+var DEFAULT_HERMES_COMMAND = "hermes acp", DIST_MARKER = "/dist/";
+var init_hermes_shim = () => {};
+
+// src/adapters/hermes-acp-shim.ts
+init_hermes_shim();
+import { spawn } from "node:child_process";
+import { constants as osConstants } from "node:os";
+var argv = process.argv.slice(2);
+var command = argv.length > 0 ? argv : ["hermes", "acp"];
+var child = spawn(command[0], command.slice(1), {
+  stdio: ["pipe", "pipe", "inherit"],
+  shell: process.platform === "win32"
+});
+child.on("error", (error) => {
+  process.stderr.write(`[hermes-acp-shim] failed to spawn "${command.join(" ")}": ${error.message}
+`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  process.exitCode = signal ? 128 + (osConstants.signals[signal] ?? 0) : code ?? 0;
+});
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => {
+    child.kill(signal);
+  });
+}
+process.stdin.pipe(child.stdin);
+var patched = false;
+var pending = Buffer.alloc(0);
+var NEWLINE = 10;
+var interceptStdout = (chunk) => {
+  pending = pending.length > 0 ? Buffer.concat([pending, chunk]) : chunk;
+  let newlineIndex;
+  while (!patched && (newlineIndex = pending.indexOf(NEWLINE)) !== -1) {
+    const line = pending.subarray(0, newlineIndex + 1);
+    pending = pending.subarray(newlineIndex + 1);
+    const text = line.toString("utf8");
+    const replaced = stripResumeCapability(text);
+    if (replaced !== null) {
+      patched = true;
+      process.stdout.write(`${replaced}
+`);
+    } else {
+      process.stdout.write(line);
+      if (isInitializeResponse(text))
+        patched = true;
+    }
+  }
+  if (patched) {
+    if (pending.length > 0) {
+      process.stdout.write(pending);
+      pending = Buffer.alloc(0);
+    }
+    child.stdout.off("data", interceptStdout);
+    child.stdout.pipe(process.stdout, { end: false });
+  }
+};
+child.stdout.on("data", interceptStdout);
+child.stdout.on("end", () => {
+  if (pending.length > 0) {
+    process.stdout.write(pending);
+    pending = Buffer.alloc(0);
+  }
+});

package/dist/adapters/hermes-shim.d.ts

@@ -0,0 +1,41 @@
+/** The command the 0.19.2 template baked into configs; treated as "no explicit
+ * command" so those configs migrate onto the shim without hand-editing. */
+export declare function isDefaultHermesCommand(command: string): boolean;
+/** A recorded shim command is derived, machine-specific state — the current
+ * install's shim (whose dist path may differ after an upgrade) must replace it.
+ * The leading separator keeps user wrappers like `my-hermes-acp-shim.sh` custom. */
+export declare function isHermesShimCommand(command: string): boolean;
+/**
+ * Path to the shim entry script. Unbundled dev runs (module URL still ends in .ts)
+ * resolve the sibling .ts source, which the dev runtime (bun) executes directly —
+ * checked FIRST so a checkout path that happens to contain `/dist/` cannot
+ * misresolve. Bundled builds (cli.js AND bridge/bridge-main.js both sit under
+ * dist/) anchor on the last `/dist/` segment.
+ */
+export declare function resolveHermesAcpShimEntry(moduleUrl?: string): string;
+/** Quote one token for acpx's `--agent` parser (double quotes; `\` and `"` escaped —
+ * its splitCommandLine treats backslash as an escape inside double quotes). */
+export declare function quoteAgentCommandToken(token: string): string;
+/** Runtime-only agent argv for the hermes driver: never persisted to config.
+ *
+ * Tradeoff: the argv embeds `process.execPath` and this install's dist path,
+ * and acpx keys its backend session records by EXACT agentCommand equality — so a
+ * node upgrade (nvm paths embed the version) or an install relocation re-keys
+ * hermes session identity: acpx starts a fresh backend record and the old queue
+ * owner ages out via TTL. Accepted because the alternative (a stable bin shim)
+ * isn't worth the packaging surface for a workaround slated for removal. */
+export declare function hermesAcpShimArgv(execPath?: string, shimEntry?: string): string[];
+/** Runtime-only agent command for the hermes driver: the quoted-string form of
+ * `hermesAcpShimArgv` for acpx `--agent` (Unix paths only). Only path-bearing
+ * tokens are quoted; `hermes acp` stay bare. */
+export declare function hermesAcpShimCommand(execPath?: string, shimEntry?: string): string;
+/**
+ * If `line` is the initialize response advertising `sessionCapabilities.resume`,
+ * return the same frame re-serialized without it; otherwise null (caller forwards
+ * the original bytes untouched).
+ */
+export declare function stripResumeCapability(line: string): string | null;
+/** Is `line` an initialize response (the only frame carrying agentCapabilities)?
+ * Lets the shim latch to raw passthrough even when hermes stops advertising
+ * `resume` after the upstream fix, instead of parsing every line forever. */
+export declare function isInitializeResponse(line: string): boolean;

package/dist/adapters/resolve-node-exe.d.ts

@@ -0,0 +1,6 @@
+export interface ResolveNodeExecutableOptions {
+    execPath?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+}
+export declare function resolveStableNodeExecutable(options?: ResolveNodeExecutableOptions): Promise<string>;