@ganglion/xacpx 0.12.1 → 0.14.0

package/README.md

@@ -519,19 +519,27 @@ For more filtering, aliases, and troubleshooting, see [docs/native-sessions.md](
 
 If you run several xacpx instances and want to drive them all from one browser dashboard, you can self-host the **relay hub**. Each instance dials out to the hub over WebSocket and registers; you log in to a multi-tenant web dashboard and manage every instance's sessions — chat, scheduled tasks, and orchestration — from one place. Streaming agent replies render as markdown, and the layout works on mobile.
 
-> Status: the relay packages are built and audited but **not yet published to npm**, so today you deploy from a source checkout. See the full guide for the exact steps.
+The hub ships as an npm package (`@ganglion/xacpx-relay`) with the dashboard **bundled in** — no separate build. It serves everything on a single port (HTTP API + dashboard + the instance WebSocket gateway), and authentication is a single **access token** used for both web login and connector pairing.
 
 ```bash
-# Build the hub server + dashboard from a repo checkout
-git clone https://github.com/gadzan/xacpx && cd xacpx && bun install
-bun run build:relay && bun run build:relay-web
+# 1. On the hub host: install (dashboard is bundled — nothing else to build)
+npm i -g @ganglion/xacpx-relay
 
-# Create the first admin, then start (point --web-root at the built dashboard)
-node packages/relay/dist/cli.js init-admin --username admin --db /var/lib/xacpx-relay/relay.db
-node packages/relay/dist/cli.js start --db /var/lib/xacpx-relay/relay.db \
-  --web-root packages/relay-web/dist --host 0.0.0.0
+# 2. Mint an access token (DB auto-created at ~/.xacpx-relay/relay.db)
+xacpx-relay add token
+#   → prints the token once; use it to log into the dashboard AND to pair connectors
+
+# 3. Start the hub (defaults: --host 0.0.0.0 --http-port 8787, dashboard auto-detected)
+xacpx-relay start
+
+# 4. On each instance host: add the connector channel and point it at the hub
+xacpx plugin add @ganglion/xacpx-channel-relay   # requires xacpx >= 0.11.0
+xacpx channel add relay --url wss://relay.example.com --token <access-token> --name my-box
+xacpx restart
 ```
 
+In production, terminate TLS at a reverse proxy in front of the single port and have instances dial `wss://`. There's no `stop`/`status` subcommand — manage the process with systemd/pm2/Docker (`Ctrl-C`/`SIGTERM` to stop); update with `xacpx-relay update`.
+
 Full walkthrough — pairing instances, TLS/reverse-proxy, systemd, backups, troubleshooting: **[Self-Hosting the Relay Hub](https://gadzan.github.io/xacpx/guide/relay-self-hosting)** (or [docs/relay-deployment.md](./docs/relay-deployment.md) for the terse runbook).
 
 ## Config and runtime files

package/dist/bridge/bridge-main.js

@@ -72,6 +72,10 @@ function encodeBridgePromptUsageEvent(event) {
   return `${JSON.stringify(event)}
 `;
 }
+function encodeBridgePromptCommandsEvent(event) {
+  return `${JSON.stringify(event)}
+`;
+}
 function encodeBridgeSessionProgressEvent(event) {
   return `${JSON.stringify(event)}
 `;
@@ -429,6 +433,7 @@ function createStreamingPromptState(formatToolCalls = false, options) {
   let onThought;
   let onPlan;
   let onUsage;
+  let onCommands;
   let rawStream = false;
   if (options === undefined) {
     toolEventMode = "text";
@@ -441,6 +446,7 @@ function createStreamingPromptState(formatToolCalls = false, options) {
     onThought = options.onThought;
     onPlan = options.onPlan;
     onUsage = options.onUsage;
+    onCommands = options.onCommands;
     rawStream = options.rawStream ?? false;
     toolEventMode = resolveToolEventMode({
       toolEventMode: options.mode,
@@ -460,6 +466,7 @@ function createStreamingPromptState(formatToolCalls = false, options) {
     onThought,
     onPlan,
     onUsage,
+    onCommands,
     finalize() {
       if (this.pendingLine.trim().length > 0) {
         parseStreamingChunks(this, this.pendingLine);
@@ -527,8 +534,17 @@ function parseStreamingChunks(state, line) {
   if (update.sessionUpdate === "usage_update") {
     const used = typeof update.used === "number" && Number.isFinite(update.used) ? update.used : undefined;
     const size = typeof update.size === "number" && Number.isFinite(update.size) ? update.size : undefined;
-    if (used !== undefined && size !== undefined && size > 0)
-      state.onUsage?.({ used, size });
+    if (used !== undefined && size !== undefined && size > 0) {
+      const cost = normalizeUsageCost(update.cost);
+      const breakdown = normalizeUsageBreakdown(update._meta?.usage);
+      state.onUsage?.({ used, size, ...cost ? { cost } : {}, ...breakdown ? { breakdown } : {} });
+    }
+    return;
+  }
+  if (update.sessionUpdate === "available_commands_update") {
+    if (Array.isArray(update.availableCommands)) {
+      state.onCommands?.(normalizeAgentCommands(update.availableCommands));
+    }
     return;
   }
   const isThoughtChunk = update.sessionUpdate === "agent_thought_chunk" && update.content?.type === "text" && typeof update.content.text === "string";
@@ -695,6 +711,52 @@ function readFirstStringArray(record, keys) {
   }
   return;
 }
+function asFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function firstFiniteNumber(record, keys) {
+  for (const key of keys) {
+    const n = asFiniteNumber(record[key]);
+    if (n !== undefined)
+      return n;
+  }
+  return;
+}
+function normalizeUsageBreakdown(value) {
+  if (!isRecord(value))
+    return;
+  const out = {};
+  for (const [key, aliases] of USAGE_BREAKDOWN_FIELDS) {
+    const n = firstFiniteNumber(value, aliases);
+    if (n !== undefined)
+      out[key] = n;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+function normalizeUsageCost(value) {
+  if (!isRecord(value))
+    return;
+  const amount = asFiniteNumber(value.amount);
+  const currency = readString(value, "currency");
+  if (amount === undefined && !currency)
+    return;
+  return { ...amount !== undefined ? { amount } : {}, ...currency ? { currency } : {} };
+}
+function normalizeAgentCommands(value) {
+  if (!Array.isArray(value))
+    return [];
+  const out = [];
+  for (const entry of value) {
+    if (!isRecord(entry))
+      continue;
+    const name = readString(entry, "name");
+    if (!name)
+      continue;
+    const description = readString(entry, "description");
+    out.push({ name, ...description ? { description } : {}, hasInput: entry.input != null });
+  }
+  return out;
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -720,8 +782,17 @@ function isGenericToolTitle(kind, title) {
   }
   return false;
 }
+var USAGE_BREAKDOWN_FIELDS;
 var init_streaming_prompt = __esm(() => {
   init_tool_kind_emoji();
+  USAGE_BREAKDOWN_FIELDS = [
+    ["inputTokens", ["inputTokens", "input_tokens"]],
+    ["outputTokens", ["outputTokens", "output_tokens"]],
+    ["cachedReadTokens", ["cachedReadTokens", "cacheReadInputTokens", "cache_read_input_tokens"]],
+    ["cachedWriteTokens", ["cachedWriteTokens", "cacheCreationInputTokens", "cache_creation_input_tokens"]],
+    ["thoughtTokens", ["thoughtTokens", "thought_tokens"]],
+    ["totalTokens", ["totalTokens", "total_tokens"]]
+  ];
 });
 
 // src/recovery/discover-parent-package-paths.ts
@@ -940,6 +1011,7 @@ ${detail}`,
     sessionBlockedByTasks: (alias, count) => `Session "${alias}" has ${count} unfinished task(s). Cancel or wait for them to complete first.`,
     sessionBlockedByTasksHint: "Use /tasks to list tasks, or /task cancel <id> to cancel one.",
     sessionRemoved: (alias) => `Session "${alias}" removed.`,
+    sessionArchived: (alias) => `Archived session "${alias}". Send a message to restore it.`,
     sessionRemovedWasActive: "This was the active session. Its chat context has been cleared.",
     sessionRemovedWasActivePromoted: (alias) => `This was the active session. Switched back to the previous session "${alias}".`,
     sessionTransportShared: (transportSession, count) => `Note: backend session "${transportSession}" is still referenced by ${count} other session(s) and was not closed.`,
@@ -2035,6 +2107,7 @@ ${detail}`,
     sessionBlockedByTasks: (alias, count) => `会话「${alias}」下还有 ${count} 个未结束的任务，请先取消或等待完成。`,
     sessionBlockedByTasksHint: "使用 /tasks 查看任务列表，或 /task cancel <id> 取消任务。",
     sessionRemoved: (alias) => `已删除会话「${alias}」。`,
+    sessionArchived: (alias) => `已归档会话「${alias}」。发送消息即可恢复。`,
     sessionRemovedWasActive: "该会话是当前活跃会话，已自动清除相关聊天上下文。",
     sessionRemovedWasActivePromoted: (alias) => `该会话是当前活跃会话，已切换回上一个会话「${alias}」。`,
     sessionTransportShared: (transportSession, count) => `提示：后端会话「${transportSession}」仍被其他 ${count} 个会话引用，未关闭。`,
@@ -3424,6 +3497,31 @@ var init_agent_session_list = __esm(() => {
   init_path();
 });
 
+// src/transport/acpx-session-files.ts
+import { readdir, unlink as unlink2 } from "node:fs/promises";
+import { homedir as homedir4 } from "node:os";
+import { join as join3 } from "node:path";
+async function deleteAcpxSessionFiles(options) {
+  const dir = options.sessionsDir ?? join3(homedir4(), ".acpx", "sessions");
+  const safeId = encodeURIComponent(options.acpxRecordId);
+  await unlink2(join3(dir, `${safeId}.json`)).catch(() => {
+    return;
+  });
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return;
+  }
+  const streamFiles = entries.filter((name) => name.startsWith(`${safeId}.stream.`));
+  for (const name of streamFiles) {
+    await unlink2(join3(dir, name)).catch(() => {
+      return;
+    });
+  }
+}
+var init_acpx_session_files = () => {};
+
 // src/bridge/bridge-main.ts
 import { createInterface } from "node:readline";
 
@@ -3496,9 +3594,9 @@ init_terminate_process_tree();
 init_prompt_output();
 init_prompt_media();
 init_streaming_prompt();
-import { copyFile, readdir } from "node:fs/promises";
-import { homedir as homedir4 } from "node:os";
-import { dirname as dirname2, join as join3, win32 } from "node:path";
+import { copyFile, readdir as readdir2 } from "node:fs/promises";
+import { homedir as homedir5 } from "node:os";
+import { dirname as dirname2, join as join4, win32 } from "node:path";
 import { spawn as spawn4 } from "node:child_process";
 
 // src/bridge/parse-missing-optional-dep.ts
@@ -3518,6 +3616,7 @@ function parseMissingOptionalDep(text) {
 init_discover_parent_package_paths();
 init_acpx_queue_owner_launcher();
 init_agent_session_list();
+init_acpx_session_files();
 class EnsureSessionFailedError extends Error {
   kind;
   data;
@@ -3798,7 +3897,7 @@ class BridgeRuntime {
         acpxRecordId = parsed.id;
       }
       const agentSessionId = typeof parsed.agentSessionId === "string" ? parsed.agentSessionId : undefined;
-      if (acpxRecordId) {
+      if (acpxRecordId && /^[\w.:-]+$/.test(acpxRecordId) && acpxRecordId.length >= 8) {
         return { acpxRecordId, agentSessionId };
       }
     } catch {
@@ -3890,6 +3989,17 @@ class BridgeRuntime {
     }
     throw new Error(result.stderr || result.stdout || "sessions close failed");
   }
+  async deleteSession(input) {
+    let acpxRecordId;
+    try {
+      ({ acpxRecordId } = await this.readSessionRecord(input));
+    } catch {
+      return {};
+    }
+    await this.removeSession(input);
+    await deleteAcpxSessionFiles({ acpxRecordId });
+    return {};
+  }
   async shutdown() {
     return {};
   }
@@ -4010,7 +4120,8 @@ async function runStreamingPrompt(command, args, onEvent, options = {}) {
       ...onEvent && (toolEventMode === "structured" || toolEventMode === "both") ? { onToolEvent: (toolEvent) => onEvent({ type: "prompt.tool_event", event: toolEvent }) } : {},
       ...onEvent ? { onThought: (chunk) => onEvent({ type: "prompt.thought", text: chunk }) } : {},
       ...onEvent ? { onPlan: (entries) => onEvent({ type: "prompt.plan", entries }) } : {},
-      ...onEvent ? { onUsage: (usage) => onEvent({ type: "prompt.usage", used: usage.used, size: usage.size }) } : {}
+      ...onEvent ? { onUsage: (usage) => onEvent({ type: "prompt.usage", used: usage.used, size: usage.size, ...usage.cost ? { cost: usage.cost } : {}, ...usage.breakdown ? { breakdown: usage.breakdown } : {} }) } : {},
+      ...onEvent ? { onCommands: (commands) => onEvent({ type: "prompt.commands", commands }) } : {}
     });
     let lastReplyAt = now();
     const flushBuffer = () => {
@@ -4080,14 +4191,14 @@ async function tryRepairAcpxSessionIndex(deps = {}) {
   if (platform !== "win32") {
     return false;
   }
-  const home = deps.home ?? process.env.HOME ?? process.env.USERPROFILE ?? homedir4();
+  const home = deps.home ?? process.env.HOME ?? process.env.USERPROFILE ?? homedir5();
   if (!home) {
     return false;
   }
-  const pathJoin = platform === "win32" ? win32.join : join3;
+  const pathJoin = platform === "win32" ? win32.join : join4;
   const sessionsDir = pathJoin(home, ".acpx", "sessions");
   const indexPath = pathJoin(sessionsDir, "index.json");
-  const readdirFn = deps.readdirFn ?? readdir;
+  const readdirFn = deps.readdirFn ?? readdir2;
   const copyFileFn = deps.copyFileFn ?? copyFile;
   let files;
   try {
@@ -4135,6 +4246,7 @@ var BRIDGE_METHODS = new Set([
   "getSessionModel",
   "cancel",
   "removeSession",
+  "deleteSession",
   "getAgentSessionId"
 ]);
 var SESSION_SCOPED_METHODS = new Set([
@@ -4148,6 +4260,7 @@ var SESSION_SCOPED_METHODS = new Set([
   "getSessionModel",
   "cancel",
   "removeSession",
+  "deleteSession",
   "getAgentSessionId"
 ]);
 
@@ -4306,7 +4419,15 @@ class BridgeServer {
               id: requestId,
               event: "prompt.usage",
               used: event.used,
-              size: event.size
+              size: event.size,
+              ...event.cost ? { cost: event.cost } : {},
+              ...event.breakdown ? { breakdown: event.breakdown } : {}
+            }));
+          } else if (event.type === "prompt.commands") {
+            writeLine?.(encodeBridgePromptCommandsEvent({
+              id: requestId,
+              event: "prompt.commands",
+              commands: event.commands
             }));
           }
         });
@@ -4355,6 +4476,13 @@ class BridgeServer {
           cwd: requireString(params, "cwd"),
           name: requireString(params, "name")
         });
+      case "deleteSession":
+        return await this.runtime.deleteSession({
+          agent: requireString(params, "agent"),
+          agentCommand: asOptionalString(params.agentCommand),
+          cwd: requireString(params, "cwd"),
+          name: requireString(params, "name")
+        });
       case "getAgentSessionId":
         return await this.runtime.getAgentSessionId({
           agent: requireString(params, "agent"),