acpx 0.1.7 → 0.1.9

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;
+    agentSessionId?: string;
     agentCommand: string;
     cwd: string;
     name?: string;

package/dist/cli.js

@@ -1715,6 +1715,35 @@ function classifyPermissionDecision(params, response) {
   return "denied";
 }
 
+// src/agent-session-id.ts
+var AGENT_SESSION_ID_META_KEYS = ["agentSessionId", "sessionId"];
+function normalizeAgentSessionId(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 extractAgentSessionId(meta) {
+  const record = asMetaRecord(meta);
+  if (!record) {
+    return void 0;
+  }
+  for (const key of AGENT_SESSION_ID_META_KEYS) {
+    const normalized = normalizeAgentSessionId(record[key]);
+    if (normalized) {
+      return normalized;
+    }
+  }
+  return void 0;
+}
+
 // src/terminal.ts
 import { spawn } from "child_process";
 import { randomUUID } from "crypto";
@@ -2373,18 +2402,22 @@ var AcpClient = class {
       cwd: asAbsoluteCwd(cwd),
       mcpServers: []
     });
-    return result.sessionId;
+    return {
+      sessionId: result.sessionId,
+      agentSessionId: extractAgentSessionId(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 +2429,9 @@ var AcpClient = class {
     } finally {
       this.suppressSessionUpdates = previousSuppression;
     }
+    return {
+      agentSessionId: extractAgentSessionId(response?._meta)
+    };
   }
   async prompt(sessionId, text) {
     const connection = this.getConnection();
@@ -4203,6 +4239,7 @@ function parseSessionRecord(raw) {
     return null;
   }
   const record = raw;
+  const agentSessionId = normalizeAgentSessionId(record.agentSessionId);
   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 +4262,7 @@ function parseSessionRecord(raw) {
     ...record,
     id: record.id,
     sessionId: record.sessionId,
+    agentSessionId,
     agentCommand: record.agentCommand,
     cwd: record.cwd,
     name,
@@ -4617,6 +4655,13 @@ function applyLifecycleSnapshotToRecord(record, snapshot) {
   record.lastAgentExitAt = void 0;
   record.lastAgentDisconnectReason = void 0;
 }
+function reconcileAgentSessionId(record, agentSessionId) {
+  const normalized = normalizeAgentSessionId(agentSessionId);
+  if (!normalized) {
+    return;
+  }
+  record.agentSessionId = normalized;
+}
 function shouldFallbackToNewSession(error) {
   if (error instanceof TimeoutError || error instanceof InterruptedError) {
     return false;
@@ -4653,31 +4698,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
       );
+      reconcileAgentSessionId(record, loadResult.agentSessionId);
       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;
+      reconcileAgentSessionId(record, createdSession.agentSessionId);
     }
   } 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;
+    reconcileAgentSessionId(record, createdSession.agentSessionId);
   }
   options.onSessionIdResolved?.(sessionId);
   return {
     sessionId,
+    agentSessionId: record.agentSessionId,
     resumed,
     loadError
   };
@@ -5030,10 +5084,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 +5124,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,
+          agentSessionId: createdSession.agentSessionId,
           agentCommand: options.agentCommand,
           cwd: absolutePath(options.cwd),
           name: normalizeName(options.name),
@@ -5655,8 +5712,22 @@ function resolveAgentInvocation(explicitAgentName, globalFlags, config) {
 }
 function printSessionsByFormat(sessions, format) {
   if (format === "json") {
-    process.stdout.write(`${JSON.stringify(sessions)}
-`);
+    process.stdout.write(
+      `${JSON.stringify(
+        sessions.map((session) => {
+          const { id, sessionId, agentSessionId, ...rest } = session;
+          return {
+            ...rest,
+            ...canonicalSessionIdentity({
+              id,
+              sessionId,
+              agentSessionId
+            })
+          };
+        })
+      )}
+`
+    );
     return;
   }
   if (format === "quiet") {
@@ -5684,8 +5755,7 @@ function printClosedSessionByFormat(record, format) {
     process.stdout.write(
       `${JSON.stringify({
         type: "session_closed",
-        id: record.id,
-        sessionId: record.sessionId,
+        ...canonicalSessionIdentity(record),
         name: record.name
       })}
 `
@@ -5698,15 +5768,22 @@ function printClosedSessionByFormat(record, format) {
   process.stdout.write(`${record.id}
 `);
 }
+function canonicalSessionIdentity(record) {
+  const normalizedAgentSessionId = normalizeAgentSessionId(record.agentSessionId);
+  return {
+    acpxRecordId: record.id,
+    acpxSessionId: record.sessionId,
+    ...normalizedAgentSessionId ? { agentSessionId: normalizedAgentSessionId } : {}
+  };
+}
 function printNewSessionByFormat(record, replaced, format) {
   if (format === "json") {
     process.stdout.write(
       `${JSON.stringify({
         type: "session_created",
-        id: record.id,
-        sessionId: record.sessionId,
+        ...canonicalSessionIdentity(record),
         name: record.name,
-        replacedSessionId: replaced?.id
+        ...replaced ? { replacedAcpxRecordId: replaced.id } : {}
       })}
 `
     );
@@ -5730,8 +5807,7 @@ function printEnsuredSessionByFormat(record, created, format) {
     process.stdout.write(
       `${JSON.stringify({
         type: "session_ensured",
-        id: record.id,
-        sessionId: record.sessionId,
+        ...canonicalSessionIdentity(record),
         name: record.name,
         created
       })}
@@ -5753,7 +5829,7 @@ function printQueuedPromptByFormat(result, format) {
     process.stdout.write(
       `${JSON.stringify({
         type: "queued",
-        sessionId: result.sessionId,
+        acpxRecordId: result.sessionId,
         requestId: result.requestId
       })}
 `
@@ -5910,8 +5986,13 @@ async function handleExec(explicitAgentName, promptParts, flags, command, config
 }
 function printCancelResultByFormat(result, format) {
   if (format === "json") {
-    process.stdout.write(`${JSON.stringify(result)}
-`);
+    process.stdout.write(
+      `${JSON.stringify({
+        acpxRecordId: result.sessionId || null,
+        cancelled: result.cancelled
+      })}
+`
+    );
     return;
   }
   if (result.cancelled) {
@@ -5924,7 +6005,7 @@ function printSetModeResultByFormat(modeId, result, format) {
   if (format === "json") {
     process.stdout.write(
       `${JSON.stringify({
-        sessionId: result.record.id,
+        ...canonicalSessionIdentity(result.record),
         modeId,
         resumed: result.resumed
       })}
@@ -5944,7 +6025,7 @@ function printSetConfigOptionResultByFormat(configId, value, result, format) {
   if (format === "json") {
     process.stdout.write(
       `${JSON.stringify({
-        sessionId: result.record.id,
+        ...canonicalSessionIdentity(result.record),
         configId,
         value,
         resumed: result.resumed,
@@ -6136,8 +6217,18 @@ async function handleSessionsEnsure(explicitAgentName, flags, command, config) {
 }
 function printSessionDetailsByFormat(record, format) {
   if (format === "json") {
-    process.stdout.write(`${JSON.stringify(record)}
-`);
+    const { id, sessionId, agentSessionId, ...rest } = record;
+    process.stdout.write(
+      `${JSON.stringify({
+        ...rest,
+        ...canonicalSessionIdentity({
+          id,
+          sessionId,
+          agentSessionId
+        })
+      })}
+`
+    );
     return;
   }
   if (format === "quiet") {
@@ -6145,9 +6236,11 @@ function printSessionDetailsByFormat(record, format) {
 `);
     return;
   }
-  process.stdout.write(`id: ${record.id}
+  process.stdout.write(`acpxRecordId: ${record.id}
+`);
+  process.stdout.write(`acpxSessionId: ${record.sessionId}
 `);
-  process.stdout.write(`sessionId: ${record.sessionId}
+  process.stdout.write(`agentSessionId: ${record.agentSessionId ?? "-"}
 `);
   process.stdout.write(`agent: ${record.agentCommand}
 `);
@@ -6188,8 +6281,7 @@ function printSessionHistoryByFormat(record, limit, format) {
   if (format === "json") {
     process.stdout.write(
       `${JSON.stringify({
-        id: record.id,
-        sessionId: record.sessionId,
+        ...canonicalSessionIdentity(record),
         limit,
         count: visible.length,
         entries: visible
@@ -6275,7 +6367,9 @@ async function handleStatus(explicitAgentName, flags, command, config) {
   });
   if (!record) {
     const payload2 = {
-      sessionId: null,
+      acpxRecordId: null,
+      acpxSessionId: null,
+      agentSessionId: null,
       agentCommand: agent.agentCommand,
       pid: null,
       status: "no-session",
@@ -6309,7 +6403,7 @@ async function handleStatus(explicitAgentName, flags, command, config) {
   }
   const running = isProcessAlive(record.pid);
   const payload = {
-    sessionId: record.id,
+    ...canonicalSessionIdentity(record),
     agentCommand: record.agentCommand,
     pid: record.pid ?? null,
     status: running ? "running" : "dead",
@@ -6328,7 +6422,11 @@ async function handleStatus(explicitAgentName, flags, command, config) {
 `);
     return;
   }
-  process.stdout.write(`session: ${payload.sessionId}
+  process.stdout.write(`acpxRecordId: ${payload.acpxRecordId}
+`);
+  process.stdout.write(`acpxSessionId: ${payload.acpxSessionId}
+`);
+  process.stdout.write(`agentSessionId: ${payload.agentSessionId ?? "-"}
 `);
   process.stdout.write(`agent: ${payload.agentCommand}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acpx",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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"