acpx 0.1.8 → 0.1.10

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -11,7 +11,7 @@ import { findSkillsRoot, maybeHandleSkillflag } from "skillflag";
 // src/agent-registry.ts
 var AGENT_REGISTRY = {
   codex: "npx @zed-industries/codex-acp",
-  claude: "npx @zed-industries/claude-agent-acp",
+  claude: "npx -y @zed-industries/claude-agent-acp",
   gemini: "gemini",
   opencode: "npx opencode-ai",
   pi: "npx pi-acp"
@@ -388,6 +388,117 @@ var PermissionPromptUnavailableError = class extends AcpxOperationalError {
   }
 };
 
+// src/acp-error-shapes.ts
+var RESOURCE_NOT_FOUND_ACP_CODES = /* @__PURE__ */ new Set([-32001, -32002]);
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
+function toAcpErrorPayload(value) {
+  const record = asRecord(value);
+  if (!record) {
+    return void 0;
+  }
+  if (typeof record.code !== "number" || !Number.isFinite(record.code)) {
+    return void 0;
+  }
+  if (typeof record.message !== "string" || record.message.length === 0) {
+    return void 0;
+  }
+  return {
+    code: record.code,
+    message: record.message,
+    data: record.data
+  };
+}
+function extractAcpErrorInternal(value, depth) {
+  if (depth > 5) {
+    return void 0;
+  }
+  const direct = toAcpErrorPayload(value);
+  if (direct) {
+    return direct;
+  }
+  const record = asRecord(value);
+  if (!record) {
+    return void 0;
+  }
+  if ("error" in record) {
+    const nested = extractAcpErrorInternal(record.error, depth + 1);
+    if (nested) {
+      return nested;
+    }
+  }
+  if ("cause" in record) {
+    const nested = extractAcpErrorInternal(record.cause, depth + 1);
+    if (nested) {
+      return nested;
+    }
+  }
+  return void 0;
+}
+function formatUnknownErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (error && typeof error === "object") {
+    const maybeMessage = error.message;
+    if (typeof maybeMessage === "string" && maybeMessage.length > 0) {
+      return maybeMessage;
+    }
+    try {
+      return JSON.stringify(error);
+    } catch {
+    }
+  }
+  return String(error);
+}
+function isSessionNotFoundText(value) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const normalized = value.toLowerCase();
+  return normalized.includes("resource_not_found") || normalized.includes("resource not found") || normalized.includes("session not found") || normalized.includes("unknown session");
+}
+function hasSessionNotFoundHint(value, depth = 0) {
+  if (depth > 4) {
+    return false;
+  }
+  if (isSessionNotFoundText(value)) {
+    return true;
+  }
+  if (Array.isArray(value)) {
+    return value.some((entry) => hasSessionNotFoundHint(entry, depth + 1));
+  }
+  const record = asRecord(value);
+  if (!record) {
+    return false;
+  }
+  return Object.values(record).some(
+    (entry) => hasSessionNotFoundHint(entry, depth + 1)
+  );
+}
+function extractAcpError(error) {
+  return extractAcpErrorInternal(error, 0);
+}
+function isAcpResourceNotFoundError(error) {
+  const acp = extractAcpError(error);
+  if (acp && RESOURCE_NOT_FOUND_ACP_CODES.has(acp.code)) {
+    return true;
+  }
+  if (acp) {
+    if (isSessionNotFoundText(acp.message)) {
+      return true;
+    }
+    if (hasSessionNotFoundHint(acp.data)) {
+      return true;
+    }
+  }
+  return isSessionNotFoundText(formatUnknownErrorMessage(error));
+}
+
 // src/types.ts
 var EXIT_CODES = {
   SUCCESS: 0,
@@ -412,9 +523,8 @@ var OUTPUT_ERROR_CODES = [
 var OUTPUT_ERROR_ORIGINS = ["cli", "runtime", "queue", "acp"];
 
 // src/error-normalization.ts
-var RESOURCE_NOT_FOUND_ACP_CODES = /* @__PURE__ */ new Set([-32001, -32002]);
 var AUTH_REQUIRED_ACP_CODES = /* @__PURE__ */ new Set([-32e3]);
-function asRecord(value) {
+function asRecord2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return void 0;
   }
@@ -437,7 +547,7 @@ function isAcpAuthRequiredPayload(acp) {
   if (isAuthRequiredMessage(acp.message)) {
     return true;
   }
-  const data = asRecord(acp.data);
+  const data = asRecord2(acp.data);
   if (!data) {
     return false;
   }
@@ -461,7 +571,7 @@ function isOutputErrorOrigin(value) {
   return typeof value === "string" && OUTPUT_ERROR_ORIGINS.includes(value);
 }
 function readOutputErrorMeta(error) {
-  const record = asRecord(error);
+  const record = asRecord2(error);
   if (!record) {
     return {};
   }
@@ -469,7 +579,7 @@ function readOutputErrorMeta(error) {
   const detailCode = typeof record.detailCode === "string" && record.detailCode.trim().length > 0 ? record.detailCode : void 0;
   const origin = isOutputErrorOrigin(record.origin) ? record.origin : void 0;
   const retryable = typeof record.retryable === "boolean" ? record.retryable : void 0;
-  const acp = toAcpErrorPayload(record.acp);
+  const acp = toAcpErrorPayload2(record.acp);
   return {
     outputCode,
     detailCode,
@@ -478,8 +588,8 @@ function readOutputErrorMeta(error) {
     acp
   };
 }
-function toAcpErrorPayload(value) {
-  const record = asRecord(value);
+function toAcpErrorPayload2(value) {
+  const record = asRecord2(value);
   if (!record) {
     return void 0;
   }
@@ -495,32 +605,6 @@ function toAcpErrorPayload(value) {
     data: record.data
   };
 }
-function extractAcpErrorInternal(value, depth) {
-  if (depth > 5) {
-    return void 0;
-  }
-  const direct = toAcpErrorPayload(value);
-  if (direct) {
-    return direct;
-  }
-  const record = asRecord(value);
-  if (!record) {
-    return void 0;
-  }
-  if ("error" in record) {
-    const nested = extractAcpErrorInternal(record.error, depth + 1);
-    if (nested) {
-      return nested;
-    }
-  }
-  if ("cause" in record) {
-    const nested = extractAcpErrorInternal(record.cause, depth + 1);
-    if (nested) {
-      return nested;
-    }
-  }
-  return void 0;
-}
 function isTimeoutLike(error) {
   return error instanceof Error && error.name === "TimeoutError";
 }
@@ -531,7 +615,7 @@ function isUsageLike(error) {
   if (!(error instanceof Error)) {
     return false;
   }
-  return error.name === "CommanderError" || error.name === "InvalidArgumentError" || asRecord(error)?.code === "commander.invalidArgument";
+  return error.name === "CommanderError" || error.name === "InvalidArgumentError" || asRecord2(error)?.code === "commander.invalidArgument";
 }
 function formatErrorMessage(error) {
   if (error instanceof Error) {
@@ -549,17 +633,6 @@ function formatErrorMessage(error) {
   }
   return String(error);
 }
-function extractAcpError(error) {
-  return extractAcpErrorInternal(error, 0);
-}
-function isAcpResourceNotFoundError(error) {
-  const acp = extractAcpError(error);
-  if (acp && RESOURCE_NOT_FOUND_ACP_CODES.has(acp.code)) {
-    return true;
-  }
-  const message = formatErrorMessage(error).toLowerCase();
-  return message.includes("resource_not_found") || message.includes("resource not found") || message.includes("session not found") || message.includes("unknown session");
-}
 function mapErrorCode(error) {
   if (error instanceof PermissionPromptUnavailableError) {
     return "PERMISSION_PROMPT_UNAVAILABLE";
@@ -658,7 +731,7 @@ function toStatusLabel(status) {
       return "running";
   }
 }
-function asRecord2(value) {
+function asRecord3(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return void 0;
   }
@@ -752,7 +825,7 @@ function summarizeToolInput(rawInput) {
   if (typeof rawInput === "string" || typeof rawInput === "number" || typeof rawInput === "boolean") {
     return toInline(String(rawInput));
   }
-  const record = asRecord2(rawInput);
+  const record = asRecord3(rawInput);
   if (record) {
     const command = readFirstString(record, ["command", "cmd", "program"]);
     const args = readFirstStringArray(record, ["args", "arguments"]);
@@ -886,7 +959,7 @@ function extractOutputText(value, depth = 0, seen = /* @__PURE__ */ new Set()) {
     }
     return dedupeStrings(parts).join("\n");
   }
-  const record = asRecord2(value);
+  const record = asRecord3(value);
   if (!record) {
     return void 0;
   }
@@ -1715,14 +1788,9 @@ function classifyPermissionDecision(params, response) {
   return "denied";
 }
 
-// src/runtime-session-id.ts
-var RUNTIME_SESSION_ID_META_KEYS = [
-  "runtimeSessionId",
-  "providerSessionId",
-  "codexSessionId",
-  "claudeSessionId"
-];
-function normalizeRuntimeSessionId(value) {
+// src/agent-session-id.ts
+var AGENT_SESSION_ID_META_KEYS = ["agentSessionId", "sessionId"];
+function normalizeAgentSessionId(value) {
   if (typeof value !== "string") {
     return void 0;
   }
@@ -1735,13 +1803,13 @@ function asMetaRecord(meta) {
   }
   return meta;
 }
-function extractRuntimeSessionId(meta) {
+function extractAgentSessionId(meta) {
   const record = asMetaRecord(meta);
   if (!record) {
     return void 0;
   }
-  for (const key of RUNTIME_SESSION_ID_META_KEYS) {
-    const normalized = normalizeRuntimeSessionId(record[key]);
+  for (const key of AGENT_SESSION_ID_META_KEYS) {
+    const normalized = normalizeAgentSessionId(record[key]);
     if (normalized) {
       return normalized;
     }
@@ -2091,6 +2159,9 @@ var TerminalManager = class {
 var REPLAY_IDLE_MS = 80;
 var REPLAY_DRAIN_TIMEOUT_MS = 5e3;
 var DRAIN_POLL_INTERVAL_MS = 20;
+var AGENT_CLOSE_AFTER_STDIN_END_MS = 100;
+var AGENT_CLOSE_TERM_GRACE_MS = 1500;
+var AGENT_CLOSE_KILL_GRACE_MS = 1e3;
 function shouldSuppressSdkConsoleError(args) {
   if (args.length === 0) {
     return false;
@@ -2126,6 +2197,38 @@ function waitForSpawn2(child) {
     child.once("error", onError);
   });
 }
+function isChildProcessRunning(child) {
+  return child.exitCode == null && child.signalCode == null;
+}
+function waitForChildExit(child, timeoutMs) {
+  if (!isChildProcessRunning(child)) {
+    return Promise.resolve(true);
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    const timer = setTimeout(
+      () => {
+        finish(false);
+      },
+      Math.max(0, timeoutMs)
+    );
+    const finish = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      child.off("close", onExitLike);
+      child.off("exit", onExitLike);
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const onExitLike = () => {
+      finish(true);
+    };
+    child.once("close", onExitLike);
+    child.once("exit", onExitLike);
+  });
+}
 function splitCommandLine(value) {
   const parts = [];
   let current = "";
@@ -2409,7 +2512,7 @@ var AcpClient = class {
     });
     return {
       sessionId: result.sessionId,
-      runtimeSessionId: extractRuntimeSessionId(result._meta)
+      agentSessionId: extractAgentSessionId(result._meta)
     };
   }
   async loadSession(sessionId, cwd = this.options.cwd) {
@@ -2435,7 +2538,7 @@ var AcpClient = class {
       this.suppressSessionUpdates = previousSuppression;
     }
     return {
-      runtimeSessionId: extractRuntimeSessionId(response?._meta)
+      agentSessionId: extractAgentSessionId(response?._meta)
     };
   }
   async prompt(sessionId, text) {
@@ -2547,8 +2650,8 @@ var AcpClient = class {
   async close() {
     this.closing = true;
     await this.terminalManager.shutdown();
-    if (this.agent && !this.agent.killed) {
-      this.agent.kill();
+    if (this.agent) {
+      await this.terminateAgentProcess(this.agent);
     }
     this.sessionUpdateChain = Promise.resolve();
     this.observedSessionUpdates = 0;
@@ -2560,6 +2663,44 @@ var AcpClient = class {
     this.connection = void 0;
     this.agent = void 0;
   }
+  async terminateAgentProcess(child) {
+    if (!child.stdin.destroyed) {
+      try {
+        child.stdin.end();
+      } catch {
+      }
+    }
+    let exited = await waitForChildExit(child, AGENT_CLOSE_AFTER_STDIN_END_MS);
+    if (!exited && isChildProcessRunning(child)) {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+      }
+      exited = await waitForChildExit(child, AGENT_CLOSE_TERM_GRACE_MS);
+    }
+    if (!exited && isChildProcessRunning(child)) {
+      this.log(
+        `agent did not exit after ${AGENT_CLOSE_TERM_GRACE_MS}ms; forcing SIGKILL`
+      );
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+      exited = await waitForChildExit(child, AGENT_CLOSE_KILL_GRACE_MS);
+    }
+    if (!child.stdin.destroyed) {
+      child.stdin.destroy();
+    }
+    if (!child.stdout.destroyed) {
+      child.stdout.destroy();
+    }
+    if (!child.stderr.destroyed) {
+      child.stderr.destroy();
+    }
+    if (!exited) {
+      child.unref();
+    }
+  }
   getConnection() {
     if (!this.connection) {
       throw new Error("ACP client not started");
@@ -2884,7 +3025,7 @@ import os2 from "os";
 import path4 from "path";
 
 // src/queue-messages.ts
-function asRecord3(value) {
+function asRecord4(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return void 0;
   }
@@ -2903,7 +3044,7 @@ function isOutputErrorOrigin2(value) {
   return typeof value === "string" && OUTPUT_ERROR_ORIGINS.includes(value);
 }
 function parseAcpError(value) {
-  const record = asRecord3(value);
+  const record = asRecord4(value);
   if (!record) {
     return void 0;
   }
@@ -2920,7 +3061,7 @@ function parseAcpError(value) {
   };
 }
 function parseQueueRequest(raw) {
-  const request = asRecord3(raw);
+  const request = asRecord4(raw);
   if (!request) {
     return null;
   }
@@ -2978,15 +3119,15 @@ function parseQueueRequest(raw) {
   return null;
 }
 function parseSessionSendResult(raw) {
-  const result = asRecord3(raw);
+  const result = asRecord4(raw);
   if (!result) {
     return null;
   }
   if (typeof result.stopReason !== "string" || typeof result.sessionId !== "string" || typeof result.resumed !== "boolean") {
     return null;
   }
-  const permissionStats = asRecord3(result.permissionStats);
-  const record = asRecord3(result.record);
+  const permissionStats = asRecord4(result.permissionStats);
+  const record = asRecord4(result.record);
   if (!permissionStats || !record) {
     return null;
   }
@@ -3001,7 +3142,7 @@ function parseSessionSendResult(raw) {
   return result;
 }
 function parseQueueOwnerMessage(raw) {
-  const message = asRecord3(raw);
+  const message = asRecord4(raw);
   if (!message || typeof message.type !== "string") {
     return null;
   }
@@ -3026,7 +3167,7 @@ function parseQueueOwnerMessage(raw) {
     };
   }
   if (message.type === "client_operation") {
-    const operation = asRecord3(message.operation);
+    const operation = asRecord4(message.operation);
     if (!operation || typeof operation.method !== "string" || typeof operation.status !== "string" || typeof operation.summary !== "string" || typeof operation.timestamp !== "string") {
       return null;
     }
@@ -3081,7 +3222,7 @@ function parseQueueOwnerMessage(raw) {
     };
   }
   if (message.type === "set_config_option_result") {
-    const response = asRecord3(message.response);
+    const response = asRecord4(message.response);
     if (!response || !Array.isArray(response.configOptions)) {
       return null;
     }
@@ -4244,7 +4385,7 @@ function parseSessionRecord(raw) {
     return null;
   }
   const record = raw;
-  const runtimeSessionId = normalizeRuntimeSessionId(record.runtimeSessionId);
+  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;
@@ -4267,7 +4408,7 @@ function parseSessionRecord(raw) {
     ...record,
     id: record.id,
     sessionId: record.sessionId,
-    runtimeSessionId,
+    agentSessionId,
     agentCommand: record.agentCommand,
     cwd: record.cwd,
     name,
@@ -4445,11 +4586,196 @@ async function findSessionByDirectoryWalk(options) {
   }
 }
 
+// src/session-runtime-history.ts
+var SESSION_HISTORY_MAX_ENTRIES = 500;
+var SESSION_HISTORY_PREVIEW_CHARS = 220;
+function collapseWhitespace2(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function toPreviewText(value) {
+  const collapsed = collapseWhitespace2(value);
+  if (collapsed.length <= SESSION_HISTORY_PREVIEW_CHARS) {
+    return collapsed;
+  }
+  if (SESSION_HISTORY_PREVIEW_CHARS <= 3) {
+    return collapsed.slice(0, SESSION_HISTORY_PREVIEW_CHARS);
+  }
+  return `${collapsed.slice(0, SESSION_HISTORY_PREVIEW_CHARS - 3)}...`;
+}
+function textFromContent(content) {
+  if (content.type === "text") {
+    return content.text;
+  }
+  if (content.type === "resource_link") {
+    return content.title ?? content.name ?? content.uri;
+  }
+  if (content.type === "resource") {
+    if ("text" in content.resource && typeof content.resource.text === "string") {
+      return content.resource.text;
+    }
+    return content.resource.uri;
+  }
+  return void 0;
+}
+function toHistoryEntryFromUpdate(notification) {
+  const update = notification.update;
+  if (update.sessionUpdate !== "user_message_chunk" && update.sessionUpdate !== "agent_message_chunk") {
+    return void 0;
+  }
+  const text = textFromContent(update.content);
+  if (!text) {
+    return void 0;
+  }
+  const textPreview = toPreviewText(text);
+  if (!textPreview) {
+    return void 0;
+  }
+  return {
+    role: update.sessionUpdate === "user_message_chunk" ? "user" : "assistant",
+    timestamp: isoNow2(),
+    textPreview
+  };
+}
+function appendHistoryEntries(current, entries) {
+  const base = current ? [...current] : [];
+  for (const entry of entries) {
+    if (!entry.textPreview.trim()) {
+      continue;
+    }
+    base.push(entry);
+  }
+  if (base.length <= SESSION_HISTORY_MAX_ENTRIES) {
+    return base;
+  }
+  return base.slice(base.length - SESSION_HISTORY_MAX_ENTRIES);
+}
+
+// src/session-runtime-lifecycle.ts
+function applyLifecycleSnapshotToRecord(record, snapshot) {
+  record.pid = snapshot.pid;
+  record.agentStartedAt = snapshot.startedAt;
+  if (snapshot.lastExit) {
+    record.lastAgentExitCode = snapshot.lastExit.exitCode;
+    record.lastAgentExitSignal = snapshot.lastExit.signal;
+    record.lastAgentExitAt = snapshot.lastExit.exitedAt;
+    record.lastAgentDisconnectReason = snapshot.lastExit.reason;
+    return;
+  }
+  record.lastAgentExitCode = void 0;
+  record.lastAgentExitSignal = void 0;
+  record.lastAgentExitAt = void 0;
+  record.lastAgentDisconnectReason = void 0;
+}
+function reconcileAgentSessionId(record, agentSessionId) {
+  const normalized = normalizeAgentSessionId(agentSessionId);
+  if (!normalized) {
+    return;
+  }
+  record.agentSessionId = normalized;
+}
+
+// src/session-runtime-reconnect.ts
+function loadSessionCandidates(record) {
+  const candidates = [normalizeAgentSessionId(record.agentSessionId), record.sessionId];
+  const unique = [];
+  for (const candidate of candidates) {
+    if (!candidate || unique.includes(candidate)) {
+      continue;
+    }
+    unique.push(candidate);
+  }
+  return unique;
+}
+async function connectAndLoadSession(options) {
+  const record = options.record;
+  const client = options.client;
+  const storedProcessAlive = isProcessAlive(record.pid);
+  const shouldReconnect = Boolean(record.pid) && !storedProcessAlive;
+  if (options.verbose) {
+    if (storedProcessAlive) {
+      process.stderr.write(
+        `[acpx] saved session pid ${record.pid} is running; reconnecting with loadSession
+`
+      );
+    } else if (shouldReconnect) {
+      process.stderr.write(
+        `[acpx] saved session pid ${record.pid} is dead; respawning agent and attempting session/load
+`
+      );
+    }
+  }
+  await options.withTimeout(client.start(), options.timeoutMs);
+  options.onClientAvailable?.(options.activeController);
+  applyLifecycleSnapshotToRecord(record, client.getAgentLifecycleSnapshot());
+  record.closed = false;
+  record.closedAt = void 0;
+  options.onConnectedRecord?.(record);
+  await writeSessionRecord(record);
+  let resumed = false;
+  let loadError;
+  let sessionId = record.sessionId;
+  if (client.supportsLoadSession()) {
+    const candidates = loadSessionCandidates(record);
+    for (const candidate of candidates) {
+      if (options.verbose && candidates.length > 1) {
+        process.stderr.write(`[acpx] attempting session/load with ${candidate}
+`);
+      }
+      try {
+        const loadResult = await options.withTimeout(
+          client.loadSessionWithOptions(candidate, record.cwd, {
+            suppressReplayUpdates: true
+          }),
+          options.timeoutMs
+        );
+        reconcileAgentSessionId(record, loadResult.agentSessionId);
+        resumed = true;
+        sessionId = candidate;
+        loadError = void 0;
+        break;
+      } catch (error) {
+        loadError = formatErrorMessage(error);
+        if (!options.shouldFallbackToNewSession(error)) {
+          throw error;
+        }
+        if (options.verbose) {
+          process.stderr.write(
+            `[acpx] session/load failed for ${candidate}: ${loadError}
+`
+          );
+        }
+      }
+    }
+    if (!resumed) {
+      const createdSession = await options.withTimeout(
+        client.createSession(record.cwd),
+        options.timeoutMs
+      );
+      sessionId = createdSession.sessionId;
+      record.sessionId = sessionId;
+      reconcileAgentSessionId(record, createdSession.agentSessionId);
+    }
+  } else {
+    const createdSession = await options.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
+  };
+}
+
 // src/session-runtime.ts
 var DEFAULT_QUEUE_OWNER_TTL_MS = 3e5;
 var INTERRUPT_CANCEL_WAIT_MS = 2500;
-var SESSION_HISTORY_MAX_ENTRIES = 500;
-var SESSION_HISTORY_PREVIEW_CHARS = 220;
 var TimeoutError = class extends Error {
   constructor(timeoutMs) {
     super(`Timed out after ${timeoutMs}ms`);
@@ -4585,162 +4911,12 @@ function normalizeQueueOwnerTtlMs(ttlMs) {
   }
   return Math.round(ttlMs);
 }
-function collapseWhitespace2(value) {
-  return value.replace(/\s+/g, " ").trim();
-}
-function toPreviewText(value) {
-  const collapsed = collapseWhitespace2(value);
-  if (collapsed.length <= SESSION_HISTORY_PREVIEW_CHARS) {
-    return collapsed;
-  }
-  if (SESSION_HISTORY_PREVIEW_CHARS <= 3) {
-    return collapsed.slice(0, SESSION_HISTORY_PREVIEW_CHARS);
-  }
-  return `${collapsed.slice(0, SESSION_HISTORY_PREVIEW_CHARS - 3)}...`;
-}
-function textFromContent(content) {
-  if (content.type === "text") {
-    return content.text;
-  }
-  if (content.type === "resource_link") {
-    return content.title ?? content.name ?? content.uri;
-  }
-  if (content.type === "resource") {
-    if ("text" in content.resource && typeof content.resource.text === "string") {
-      return content.resource.text;
-    }
-    return content.resource.uri;
-  }
-  return void 0;
-}
-function toHistoryEntryFromUpdate(notification) {
-  const update = notification.update;
-  if (update.sessionUpdate !== "user_message_chunk" && update.sessionUpdate !== "agent_message_chunk") {
-    return void 0;
-  }
-  const text = textFromContent(update.content);
-  if (!text) {
-    return void 0;
-  }
-  const textPreview = toPreviewText(text);
-  if (!textPreview) {
-    return void 0;
-  }
-  return {
-    role: update.sessionUpdate === "user_message_chunk" ? "user" : "assistant",
-    timestamp: isoNow2(),
-    textPreview
-  };
-}
-function appendHistoryEntries(current, entries) {
-  const base = current ? [...current] : [];
-  for (const entry of entries) {
-    if (!entry.textPreview.trim()) {
-      continue;
-    }
-    base.push(entry);
-  }
-  if (base.length <= SESSION_HISTORY_MAX_ENTRIES) {
-    return base;
-  }
-  return base.slice(base.length - SESSION_HISTORY_MAX_ENTRIES);
-}
-function applyLifecycleSnapshotToRecord(record, snapshot) {
-  record.pid = snapshot.pid;
-  record.agentStartedAt = snapshot.startedAt;
-  if (snapshot.lastExit) {
-    record.lastAgentExitCode = snapshot.lastExit.exitCode;
-    record.lastAgentExitSignal = snapshot.lastExit.signal;
-    record.lastAgentExitAt = snapshot.lastExit.exitedAt;
-    record.lastAgentDisconnectReason = snapshot.lastExit.reason;
-    return;
-  }
-  record.lastAgentExitCode = void 0;
-  record.lastAgentExitSignal = void 0;
-  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;
   }
   return isAcpResourceNotFoundError(error);
 }
-async function connectAndLoadSession(options) {
-  const record = options.record;
-  const client = options.client;
-  const storedProcessAlive = isProcessAlive(record.pid);
-  const shouldReconnect = Boolean(record.pid) && !storedProcessAlive;
-  if (options.verbose) {
-    if (storedProcessAlive) {
-      process.stderr.write(
-        `[acpx] saved session pid ${record.pid} is running; reconnecting with loadSession
-`
-      );
-    } else if (shouldReconnect) {
-      process.stderr.write(
-        `[acpx] saved session pid ${record.pid} is dead; respawning agent and attempting session/load
-`
-      );
-    }
-  }
-  await withTimeout(client.start(), options.timeoutMs);
-  options.onClientAvailable?.(options.activeController);
-  applyLifecycleSnapshotToRecord(record, client.getAgentLifecycleSnapshot());
-  record.closed = false;
-  record.closedAt = void 0;
-  options.onConnectedRecord?.(record);
-  await writeSessionRecord(record);
-  let resumed = false;
-  let loadError;
-  let sessionId = record.sessionId;
-  if (client.supportsLoadSession()) {
-    try {
-      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;
-      }
-      const createdSession = await withTimeout(
-        client.createSession(record.cwd),
-        options.timeoutMs
-      );
-      sessionId = createdSession.sessionId;
-      record.sessionId = sessionId;
-      reconcileRuntimeSessionId(record, createdSession.runtimeSessionId);
-    }
-  } else {
-    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
-  };
-}
 async function runQueuedTask(sessionRecordId, task, options) {
   const outputFormatter = task.waitForCompletion ? new QueueTaskOutputFormatter(task) : DISCARD_OUTPUT_FORMATTER;
   try {
@@ -4847,6 +5023,8 @@ async function runSessionPrompt(options) {
           timeoutMs: options.timeoutMs,
           verbose: options.verbose,
           activeController,
+          withTimeout,
+          shouldFallbackToNewSession,
           onClientAvailable: (controller) => {
             options.onClientAvailable?.(controller);
             notifiedClientAvailable = true;
@@ -4981,6 +5159,8 @@ async function withConnectedSession(options) {
           timeoutMs: options.timeoutMs,
           verbose: options.verbose,
           activeController,
+          withTimeout,
+          shouldFallbackToNewSession,
           onClientAvailable: (controller) => {
             options.onClientAvailable?.(controller);
             notifiedClientAvailable = true;
@@ -5139,7 +5319,7 @@ async function createSession(options) {
         const record = {
           id: sessionId,
           sessionId,
-          runtimeSessionId: createdSession.runtimeSessionId,
+          agentSessionId: createdSession.agentSessionId,
           agentCommand: options.agentCommand,
           cwd: absolutePath(options.cwd),
           name: normalizeName(options.name),
@@ -5717,8 +5897,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") {
@@ -5746,8 +5940,7 @@ function printClosedSessionByFormat(record, format) {
     process.stdout.write(
       `${JSON.stringify({
         type: "session_closed",
-        id: record.id,
-        sessionId: record.sessionId,
+        ...canonicalSessionIdentity(record),
         name: record.name
       })}
 `
@@ -5760,23 +5953,22 @@ function printClosedSessionByFormat(record, format) {
   process.stdout.write(`${record.id}
 `);
 }
-function runtimeSessionIdPayload(runtimeSessionId) {
-  const normalized = normalizeRuntimeSessionId(runtimeSessionId);
-  if (!normalized) {
-    return {};
-  }
-  return { runtimeSessionId: normalized };
+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,
-        ...runtimeSessionIdPayload(record.runtimeSessionId)
+        ...replaced ? { replacedAcpxRecordId: replaced.id } : {}
       })}
 `
     );
@@ -5800,11 +5992,9 @@ 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,
-        ...runtimeSessionIdPayload(record.runtimeSessionId)
+        created
       })}
 `
     );
@@ -5824,7 +6014,7 @@ function printQueuedPromptByFormat(result, format) {
     process.stdout.write(
       `${JSON.stringify({
         type: "queued",
-        sessionId: result.sessionId,
+        acpxRecordId: result.sessionId,
         requestId: result.requestId
       })}
 `
@@ -5981,8 +6171,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) {
@@ -5995,7 +6190,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
       })}
@@ -6015,7 +6210,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,
@@ -6207,8 +6402,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") {
@@ -6216,11 +6421,11 @@ function printSessionDetailsByFormat(record, format) {
 `);
     return;
   }
-  process.stdout.write(`id: ${record.id}
+  process.stdout.write(`acpxRecordId: ${record.id}
 `);
-  process.stdout.write(`sessionId: ${record.sessionId}
+  process.stdout.write(`acpxSessionId: ${record.sessionId}
 `);
-  process.stdout.write(`runtimeSessionId: ${record.runtimeSessionId ?? "-"}
+  process.stdout.write(`agentSessionId: ${record.agentSessionId ?? "-"}
 `);
   process.stdout.write(`agent: ${record.agentCommand}
 `);
@@ -6261,8 +6466,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
@@ -6348,7 +6552,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",
@@ -6382,15 +6588,14 @@ 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",
     uptime: running ? formatUptime(record.agentStartedAt) ?? null : null,
     lastPromptTime: record.lastPromptAt ?? null,
     exitCode: running ? null : record.lastAgentExitCode ?? null,
-    signal: running ? null : record.lastAgentExitSignal ?? null,
-    ...runtimeSessionIdPayload(record.runtimeSessionId)
+    signal: running ? null : record.lastAgentExitSignal ?? null
   };
   if (globalFlags.format === "json") {
     process.stdout.write(`${JSON.stringify(payload)}
@@ -6402,12 +6607,12 @@ async function handleStatus(explicitAgentName, flags, command, config) {
 `);
     return;
   }
-  process.stdout.write(`session: ${payload.sessionId}
+  process.stdout.write(`acpxRecordId: ${payload.acpxRecordId}
 `);
-  if ("runtimeSessionId" in payload) {
-    process.stdout.write(`runtimeSessionId: ${payload.runtimeSessionId}
+  process.stdout.write(`acpxSessionId: ${payload.acpxSessionId}
+`);
+  process.stdout.write(`agentSessionId: ${payload.agentSessionId ?? "-"}
 `);
-  }
   process.stdout.write(`agent: ${payload.agentCommand}
 `);
   process.stdout.write(`pid: ${payload.pid ?? "-"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acpx",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Headless CLI client for the Agent Client Protocol (ACP) — talk to coding agents from the command line",
   "type": "module",
   "files": [