acpx 0.1.7 → 0.1.8

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Janitr AI
+Copyright (c) 2025 OpenClaw Team
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -6,10 +6,13 @@
 
 [![npm version](https://img.shields.io/npm/v/acpx.svg)](https://www.npmjs.com/package/acpx)
 [![npm downloads](https://img.shields.io/npm/dm/acpx.svg)](https://www.npmjs.com/package/acpx)
-[![CI](https://github.com/janitrai/acpx/actions/workflows/ci.yml/badge.svg)](https://github.com/janitrai/acpx/actions/workflows/ci.yml)
+[![CI](https://github.com/openclaw/acpx/actions/workflows/ci.yml/badge.svg)](https://github.com/openclaw/acpx/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/node/v/acpx.svg)](https://nodejs.org)
 
+> Alpha notice: `acpx` is in alpha and the CLI/runtime interfaces are likely to change.
+> ACP coverage status: see [ACP Spec Coverage Roadmap](docs/2026-02-19-acp-coverage-roadmap.md).
+
 Your agents love acpx! 🤖❤️ They hate having to scrape characters from a PTY session 😤
 
 `acpx` is a headless CLI client for the [Agent Client Protocol (ACP)](https://agentclientprotocol.com), so AI agents and orchestrators can talk to coding agents over a structured protocol instead of PTY scraping.
@@ -84,10 +87,10 @@ I want you to use acpx to run coding agents over the Agent Client Protocol
 
 3. Read the acpx skill reference so you know every command, flag, and
    workflow pattern:
-   https://raw.githubusercontent.com/janitrai/acpx/main/skills/acpx/SKILL.md
+   https://raw.githubusercontent.com/openclaw/acpx/main/skills/acpx/SKILL.md
 
 4. If you need the full CLI reference with all options and examples:
-   https://raw.githubusercontent.com/janitrai/acpx/main/docs/CLI.md
+   https://raw.githubusercontent.com/openclaw/acpx/main/docs/CLI.md
 
 From now on, when you need to delegate work to a coding agent, use acpx
 instead of spawning raw terminal sessions. For example:
@@ -257,6 +260,9 @@ JSON events include a stable envelope for correlation:
 }
 ```
 
+Session-control JSON payloads (`sessions new|ensure`, `status`) may also include
+`runtimeSessionId` when the adapter exposes a provider-native session ID.
+
 ## Built-in agents and custom servers
 
 Built-ins:

package/dist/cli.d.ts

@@ -10,6 +10,7 @@ type SessionHistoryEntry = {
 type SessionRecord = {
     id: string;
     sessionId: string;
+    runtimeSessionId?: string;
     agentCommand: string;
     cwd: string;
     name?: string;

package/dist/cli.js

@@ -1715,6 +1715,40 @@ function classifyPermissionDecision(params, response) {
   return "denied";
 }
 
+// src/runtime-session-id.ts
+var RUNTIME_SESSION_ID_META_KEYS = [
+  "runtimeSessionId",
+  "providerSessionId",
+  "codexSessionId",
+  "claudeSessionId"
+];
+function normalizeRuntimeSessionId(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function asMetaRecord(meta) {
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+    return void 0;
+  }
+  return meta;
+}
+function extractRuntimeSessionId(meta) {
+  const record = asMetaRecord(meta);
+  if (!record) {
+    return void 0;
+  }
+  for (const key of RUNTIME_SESSION_ID_META_KEYS) {
+    const normalized = normalizeRuntimeSessionId(record[key]);
+    if (normalized) {
+      return normalized;
+    }
+  }
+  return void 0;
+}
+
 // src/terminal.ts
 import { spawn } from "child_process";
 import { randomUUID } from "crypto";
@@ -2373,18 +2407,22 @@ var AcpClient = class {
       cwd: asAbsoluteCwd(cwd),
       mcpServers: []
     });
-    return result.sessionId;
+    return {
+      sessionId: result.sessionId,
+      runtimeSessionId: extractRuntimeSessionId(result._meta)
+    };
   }
   async loadSession(sessionId, cwd = this.options.cwd) {
     this.getConnection();
-    await this.loadSessionWithOptions(sessionId, cwd, {});
+    return await this.loadSessionWithOptions(sessionId, cwd, {});
   }
   async loadSessionWithOptions(sessionId, cwd = this.options.cwd, options = {}) {
     const connection = this.getConnection();
     const previousSuppression = this.suppressSessionUpdates;
     this.suppressSessionUpdates = previousSuppression || Boolean(options.suppressReplayUpdates);
+    let response;
     try {
-      await connection.loadSession({
+      response = await connection.loadSession({
         sessionId,
         cwd: asAbsoluteCwd(cwd),
         mcpServers: []
@@ -2396,6 +2434,9 @@ var AcpClient = class {
     } finally {
       this.suppressSessionUpdates = previousSuppression;
     }
+    return {
+      runtimeSessionId: extractRuntimeSessionId(response?._meta)
+    };
   }
   async prompt(sessionId, text) {
     const connection = this.getConnection();
@@ -4203,6 +4244,7 @@ function parseSessionRecord(raw) {
     return null;
   }
   const record = raw;
+  const runtimeSessionId = normalizeRuntimeSessionId(record.runtimeSessionId);
   const name = record.name == null ? void 0 : typeof record.name === "string" && record.name.trim().length > 0 ? record.name.trim() : null;
   const pid = record.pid == null ? void 0 : Number.isInteger(record.pid) && record.pid > 0 ? record.pid : null;
   const closed = record.closed == null ? false : typeof record.closed === "boolean" ? record.closed : null;
@@ -4225,6 +4267,7 @@ function parseSessionRecord(raw) {
     ...record,
     id: record.id,
     sessionId: record.sessionId,
+    runtimeSessionId,
     agentCommand: record.agentCommand,
     cwd: record.cwd,
     name,
@@ -4617,6 +4660,13 @@ function applyLifecycleSnapshotToRecord(record, snapshot) {
   record.lastAgentExitAt = void 0;
   record.lastAgentDisconnectReason = void 0;
 }
+function reconcileRuntimeSessionId(record, runtimeSessionId) {
+  const normalized = normalizeRuntimeSessionId(runtimeSessionId);
+  if (!normalized) {
+    return;
+  }
+  record.runtimeSessionId = normalized;
+}
 function shouldFallbackToNewSession(error) {
   if (error instanceof TimeoutError || error instanceof InterruptedError) {
     return false;
@@ -4653,31 +4703,40 @@ async function connectAndLoadSession(options) {
   let sessionId = record.sessionId;
   if (client.supportsLoadSession()) {
     try {
-      await withTimeout(
+      const loadResult = await withTimeout(
         client.loadSessionWithOptions(record.sessionId, record.cwd, {
           suppressReplayUpdates: true
         }),
         options.timeoutMs
       );
+      reconcileRuntimeSessionId(record, loadResult.runtimeSessionId);
       resumed = true;
     } catch (error) {
       loadError = formatErrorMessage(error);
       if (!shouldFallbackToNewSession(error)) {
         throw error;
       }
-      sessionId = await withTimeout(
+      const createdSession = await withTimeout(
         client.createSession(record.cwd),
         options.timeoutMs
       );
+      sessionId = createdSession.sessionId;
       record.sessionId = sessionId;
+      reconcileRuntimeSessionId(record, createdSession.runtimeSessionId);
     }
   } else {
-    sessionId = await withTimeout(client.createSession(record.cwd), options.timeoutMs);
+    const createdSession = await withTimeout(
+      client.createSession(record.cwd),
+      options.timeoutMs
+    );
+    sessionId = createdSession.sessionId;
     record.sessionId = sessionId;
+    reconcileRuntimeSessionId(record, createdSession.runtimeSessionId);
   }
   options.onSessionIdResolved?.(sessionId);
   return {
     sessionId,
+    runtimeSessionId: record.runtimeSessionId,
     resumed,
     loadError
   };
@@ -5030,10 +5089,11 @@ async function runOnce(options) {
     return await withInterrupt(
       async () => {
         await withTimeout(client.start(), options.timeoutMs);
-        const sessionId = await withTimeout(
+        const createdSession = await withTimeout(
           client.createSession(absolutePath(options.cwd)),
           options.timeoutMs
         );
+        const sessionId = createdSession.sessionId;
         output.setContext({
           sessionId,
           stream: "prompt"
@@ -5069,15 +5129,17 @@ async function createSession(options) {
     return await withInterrupt(
       async () => {
         await withTimeout(client.start(), options.timeoutMs);
-        const sessionId = await withTimeout(
+        const createdSession = await withTimeout(
           client.createSession(absolutePath(options.cwd)),
           options.timeoutMs
         );
+        const sessionId = createdSession.sessionId;
         const lifecycle = client.getAgentLifecycleSnapshot();
         const now = isoNow2();
         const record = {
           id: sessionId,
           sessionId,
+          runtimeSessionId: createdSession.runtimeSessionId,
           agentCommand: options.agentCommand,
           cwd: absolutePath(options.cwd),
           name: normalizeName(options.name),
@@ -5698,6 +5760,13 @@ function printClosedSessionByFormat(record, format) {
   process.stdout.write(`${record.id}
 `);
 }
+function runtimeSessionIdPayload(runtimeSessionId) {
+  const normalized = normalizeRuntimeSessionId(runtimeSessionId);
+  if (!normalized) {
+    return {};
+  }
+  return { runtimeSessionId: normalized };
+}
 function printNewSessionByFormat(record, replaced, format) {
   if (format === "json") {
     process.stdout.write(
@@ -5706,7 +5775,8 @@ function printNewSessionByFormat(record, replaced, format) {
         id: record.id,
         sessionId: record.sessionId,
         name: record.name,
-        replacedSessionId: replaced?.id
+        replacedSessionId: replaced?.id,
+        ...runtimeSessionIdPayload(record.runtimeSessionId)
       })}
 `
     );
@@ -5733,7 +5803,8 @@ function printEnsuredSessionByFormat(record, created, format) {
         id: record.id,
         sessionId: record.sessionId,
         name: record.name,
-        created
+        created,
+        ...runtimeSessionIdPayload(record.runtimeSessionId)
       })}
 `
     );
@@ -6148,6 +6219,8 @@ function printSessionDetailsByFormat(record, format) {
   process.stdout.write(`id: ${record.id}
 `);
   process.stdout.write(`sessionId: ${record.sessionId}
+`);
+  process.stdout.write(`runtimeSessionId: ${record.runtimeSessionId ?? "-"}
 `);
   process.stdout.write(`agent: ${record.agentCommand}
 `);
@@ -6316,7 +6389,8 @@ async function handleStatus(explicitAgentName, flags, command, config) {
     uptime: running ? formatUptime(record.agentStartedAt) ?? null : null,
     lastPromptTime: record.lastPromptAt ?? null,
     exitCode: running ? null : record.lastAgentExitCode ?? null,
-    signal: running ? null : record.lastAgentExitSignal ?? null
+    signal: running ? null : record.lastAgentExitSignal ?? null,
+    ...runtimeSessionIdPayload(record.runtimeSessionId)
   };
   if (globalFlags.format === "json") {
     process.stdout.write(`${JSON.stringify(payload)}
@@ -6330,6 +6404,10 @@ async function handleStatus(explicitAgentName, flags, command, config) {
   }
   process.stdout.write(`session: ${payload.sessionId}
 `);
+  if ("runtimeSessionId" in payload) {
+    process.stdout.write(`runtimeSessionId: ${payload.runtimeSessionId}
+`);
+  }
   process.stdout.write(`agent: ${payload.agentCommand}
 `);
   process.stdout.write(`pid: ${payload.pid ?? "-"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acpx",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Headless CLI client for the Agent Client Protocol (ACP) — talk to coding agents from the command line",
   "type": "module",
   "files": [
@@ -36,11 +36,11 @@
     "coding-agent",
     "ai"
   ],
-  "author": "Janitr AI",
+  "author": "",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/janitrai/acpx.git"
+    "url": "git+https://github.com/openclaw/acpx.git"
   },
   "engines": {
     "node": ">=18"