@ganglion/xacpx 0.19.3 → 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

@@ -65,16 +65,8 @@ function resolveHermesAcpShimEntry(moduleUrl = import.meta.url) {
   }
   return fileURLToPath(new URL("./hermes-acp-shim.js", moduleUrl));
 }
-function quoteAgentCommandToken(token) {
-  return `"${token.replaceAll("\\", "\\\\").replaceAll('"', "\\\"")}"`;
-}
-function hermesAcpShimCommand(execPath = process.execPath, shimEntry = resolveHermesAcpShimEntry()) {
-  return [
-    quoteAgentCommandToken(execPath),
-    quoteAgentCommandToken(shimEntry),
-    "hermes",
-    "acp"
-  ].join(" ");
+function hermesAcpShimArgv(execPath = process.execPath, shimEntry = resolveHermesAcpShimEntry()) {
+  return [execPath, shimEntry, "hermes", "acp"];
 }
 function stripResumeCapability(line) {
   let message;

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

@@ -16,14 +16,18 @@ 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 command for the hermes driver: never persisted to config.
+/** Runtime-only agent argv for the hermes driver: never persisted to config.
  *
- * Tradeoff: the string embeds `process.execPath` and this install's dist path,
+ * 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`,

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>;