@ganglion/xacpx 0.10.1 → 0.12.0

package/README.md

@@ -331,6 +331,7 @@ These templates only write `driver`; the actual launch command is resolved by ac
 | `/use <alias>` | Switch the current session |
 | `/status` | Show the current session status |
 | `/mode` / `/mode <id>` | View or set the underlying `acpx` mode |
+| `/model` / `/model <id>` | View or switch the session's LLM model (also `/session new --model`, `/agent add --model`) |
 | `/replymode` | Show the current reply mode |
 | `/replymode stream` | Streaming replies |
 | `/replymode verbose` | Streaming + tool-call summaries |
@@ -514,6 +515,25 @@ take a look at today's API timeout issue
 
 For more filtering, aliases, and troubleshooting, see [docs/native-sessions.md](./docs/native-sessions.md).
 
+## Self-hosted relay hub (optional)
+
+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.
+
+```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
+
+# 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
+```
+
+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
 
 Default file locations:

package/dist/bridge/bridge-main.js

@@ -64,6 +64,14 @@ function encodeBridgePromptThoughtEvent(event) {
   return `${JSON.stringify(event)}
 `;
 }
+function encodeBridgePromptPlanEvent(event) {
+  return `${JSON.stringify(event)}
+`;
+}
+function encodeBridgePromptUsageEvent(event) {
+  return `${JSON.stringify(event)}
+`;
+}
 function encodeBridgeSessionProgressEvent(event) {
   return `${JSON.stringify(event)}
 `;
@@ -419,6 +427,9 @@ function createStreamingPromptState(formatToolCalls = false, options) {
   let toolEventMode;
   let onToolEvent;
   let onThought;
+  let onPlan;
+  let onUsage;
+  let rawStream = false;
   if (options === undefined) {
     toolEventMode = "text";
     onToolEvent = undefined;
@@ -428,6 +439,9 @@ function createStreamingPromptState(formatToolCalls = false, options) {
   } else {
     onToolEvent = options.onToolEvent;
     onThought = options.onThought;
+    onPlan = options.onPlan;
+    onUsage = options.onUsage;
+    rawStream = options.rawStream ?? false;
     toolEventMode = resolveToolEventMode({
       toolEventMode: options.mode,
       onToolEvent
@@ -441,13 +455,16 @@ function createStreamingPromptState(formatToolCalls = false, options) {
     formatToolCalls,
     emittedToolCallIds: new Set,
     toolEventMode,
+    rawStream,
     onToolEvent,
     onThought,
+    onPlan,
+    onUsage,
     finalize() {
       if (this.pendingLine.trim().length > 0) {
         parseStreamingChunks(this, this.pendingLine);
       }
-      const remaining = this.buffer.trim();
+      const remaining = this.rawStream ? this.buffer : this.buffer.trim();
       this.buffer = "";
       this.pendingLine = "";
       return remaining;
@@ -479,9 +496,9 @@ function parseStreamingChunks(state, line) {
   const update = event.params?.update;
   if (!update)
     return;
-  if (state.formatToolCalls && (update.sessionUpdate === "tool_call" || update.sessionUpdate === "tool_call_update")) {
+  if (update.sessionUpdate === "tool_call" || update.sessionUpdate === "tool_call_update") {
     const wantsStructured = state.toolEventMode === "structured" || state.toolEventMode === "both";
-    const wantsText = state.toolEventMode === "text" || state.toolEventMode === "both";
+    const wantsText = (state.toolEventMode === "text" || state.toolEventMode === "both") && state.formatToolCalls;
     if (wantsStructured && state.onToolEvent) {
       const toolEvent = buildToolUseEvent(update);
       if (toolEvent)
@@ -501,6 +518,19 @@ function parseStreamingChunks(state, line) {
     }
     return;
   }
+  if (update.sessionUpdate === "plan") {
+    const entries = Array.isArray(update.entries) ? update.entries.filter((x) => !!x && typeof x === "object" && typeof x.content === "string" && typeof x.status === "string") : [];
+    if (entries.length > 0)
+      state.onPlan?.(entries);
+    return;
+  }
+  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 });
+    return;
+  }
   const isThoughtChunk = update.sessionUpdate === "agent_thought_chunk" && update.content?.type === "text" && typeof update.content.text === "string";
   if (isThoughtChunk) {
     const chunk2 = update.content.text;
@@ -517,6 +547,8 @@ function parseStreamingChunks(state, line) {
   if (chunk.length === 0)
     return;
   state.buffer += chunk;
+  if (state.rawStream)
+    return;
   let boundary;
   while ((boundary = state.buffer.indexOf(`
 
@@ -882,6 +914,14 @@ var init_session = __esm(() => {
     modeModeLabel: (modeId) => `- mode: ${modeId}`,
     modeNotSet: "not set",
     modeSet: (modeId) => `Current session mode set to: ${modeId}`,
+    modelHeader: "Current model:",
+    modelSessionLabel: (alias) => `- Session: ${alias}`,
+    modelModelLabel: (modelId) => `- model: ${modelId}`,
+    modelNotSet: "not set (using agent default)",
+    modelAvailableLabel: (models) => `- available: ${models}`,
+    modelSet: (modelId) => `Current session model switched to: ${modelId}`,
+    modelSetFailed: (modelId, detail) => `Failed to switch model: ${modelId}
+${detail}`,
     replyModeHeader: "Current reply mode:",
     replyModeSessionLabel: (alias) => `- Session: ${alias}`,
     replyModeGlobalDefault: (value) => `- Global default: ${value}`,
@@ -958,6 +998,11 @@ var init_session = __esm(() => {
     modeHelpCmdShowDesc: "Show the saved mode of the current session",
     modeHelpCmdSet: "/mode <id>",
     modeHelpCmdSetDesc: "Set the current session mode",
+    modelHelpSummary: "View or switch the LLM model for the current session.",
+    modelHelpCmdShow: "/model",
+    modelHelpCmdShowDesc: "Show the current session model and the available ones",
+    modelHelpCmdSet: "/model <id>",
+    modelHelpCmdSetDesc: "Switch the current session model (e.g. gpt-5.2[high])",
     replyModeHelpSummary: "View or set the reply output mode for the current logical session.",
     replyModeHelpCmdShow: "/replymode",
     replyModeHelpCmdShowDesc: "Show global default, current override, and effective value",
@@ -1961,6 +2006,14 @@ var init_session2 = __esm(() => {
     modeModeLabel: (modeId) => `- mode：${modeId}`,
     modeNotSet: "未设置",
     modeSet: (modeId) => `已设置当前会话 mode：${modeId}`,
+    modelHeader: "当前 model：",
+    modelSessionLabel: (alias) => `- 会话：${alias}`,
+    modelModelLabel: (modelId) => `- model：${modelId}`,
+    modelNotSet: "未设置（使用 agent 默认）",
+    modelAvailableLabel: (models) => `- 可选：${models}`,
+    modelSet: (modelId) => `已切换当前会话 model：${modelId}`,
+    modelSetFailed: (modelId, detail) => `切换 model 失败：${modelId}
+${detail}`,
     replyModeHeader: "当前 reply mode：",
     replyModeSessionLabel: (alias) => `- 会话：${alias}`,
     replyModeGlobalDefault: (value) => `- 全局默认：${value}`,
@@ -2037,6 +2090,11 @@ var init_session2 = __esm(() => {
     modeHelpCmdShowDesc: "查看当前会话已保存的 mode",
     modeHelpCmdSet: "/mode <id>",
     modeHelpCmdSetDesc: "设置当前会话 mode",
+    modelHelpSummary: "查看或切换当前会话的 LLM model。",
+    modelHelpCmdShow: "/model",
+    modelHelpCmdShowDesc: "查看当前会话 model 及可选项",
+    modelHelpCmdSet: "/model <id>",
+    modelHelpCmdSetDesc: "切换当前会话 model（如 gpt-5.2[high]）",
     replyModeHelpSummary: "查看或设置当前逻辑会话的回复输出模式。",
     replyModeHelpCmdShow: "/replymode",
     replyModeHelpCmdShowDesc: "查看全局默认、当前覆盖和实际生效值",
@@ -3123,6 +3181,7 @@ class AcpxQueueOwnerLauncher {
       nonInteractivePermissions: input.nonInteractivePermissions,
       ttlMs: this.ttlMs,
       maxQueueDepth: this.maxQueueDepth,
+      ...input.sessionOptions ? { sessionOptions: input.sessionOptions } : {},
       mcpServers: [buildXacpxMcpServerSpec({
         xacpxCommand: this.xacpxCommand,
         coordinatorSession: input.coordinatorSession,
@@ -3473,6 +3532,10 @@ class CommandTimeoutError extends Error {
     this.name = "CommandTimeoutError";
   }
 }
+function modelArgs(model) {
+  const trimmed = model?.trim();
+  return trimmed ? ["--model", trimmed] : [];
+}
 
 class BridgeRuntime {
   command;
@@ -3682,11 +3745,13 @@ class BridgeRuntime {
       ...structuredPrompt ? ["--file", structuredPrompt.filePath] : [input.text]
     ]));
     const formatToolCalls = (input.replyMode ?? "verbose") === "verbose";
+    const rawStream = input.replyMode === "stream";
     const toolEventMode = input.toolEventMode ?? (input.toolEvents === true ? "structured" : "text");
     try {
       const result = onEvent ? await this.runPromptCommand(spawnSpec.command, spawnSpec.args, onEvent, {
         formatToolCalls,
-        toolEventMode
+        toolEventMode,
+        rawStream
       }) : await this.run(spawnSpec.command, spawnSpec.args);
       return { text: getPromptText(result) };
     } finally {
@@ -3755,6 +3820,40 @@ class BridgeRuntime {
     }
     return {};
   }
+  async setModel(input) {
+    const spawnSpec = resolveSpawnCommand(this.command, this.buildSessionArgs({ ...input, model: input.modelId }, [
+      "set",
+      "-s",
+      input.name,
+      "model",
+      input.modelId
+    ]));
+    const result = await this.run(spawnSpec.command, spawnSpec.args);
+    if (result.code !== 0) {
+      throw new Error(result.stderr || result.stdout || "set-model failed");
+    }
+    return {};
+  }
+  async getSessionModel(input) {
+    const spawnSpec = resolveSpawnCommand(this.command, this.buildSessionArgs(input, [
+      "status",
+      "-s",
+      input.name
+    ], { format: "json" }));
+    const result = await this.run(spawnSpec.command, spawnSpec.args);
+    if (result.code !== 0) {
+      throw new Error(result.stderr || result.stdout || "status failed");
+    }
+    try {
+      const json = JSON.parse(result.stdout);
+      return {
+        current: typeof json.model === "string" ? json.model : undefined,
+        available: Array.isArray(json.availableModels) ? json.availableModels.filter((m) => typeof m === "string") : []
+      };
+    } catch {
+      return { available: [] };
+    }
+  }
   async cancel(input) {
     const spawnSpec = resolveSpawnCommand(this.command, this.buildSessionArgs(input, [
       "cancel",
@@ -3794,7 +3893,8 @@ class BridgeRuntime {
       options.format ?? "quiet",
       "--cwd",
       input.cwd,
-      ...this.buildPermissionArgs()
+      ...this.buildPermissionArgs(),
+      ...modelArgs(input.model)
     ];
     if (options.verbose) {
       prefix.push("--verbose");
@@ -3812,6 +3912,7 @@ class BridgeRuntime {
       "--cwd",
       input.cwd,
       ...this.buildPermissionArgs(),
+      ...modelArgs(input.model),
       ...this.buildQueueOwnerTtlArgs()
     ];
     if (input.agentCommand) {
@@ -3888,8 +3989,9 @@ async function runStreamingPrompt(command, args, onEvent, options = {}) {
   const spawnPrompt = options.spawnPrompt ?? ((spawnCommand, spawnArgs) => spawn4(spawnCommand, spawnArgs, { stdio: ["ignore", "pipe", "pipe"] }));
   const setIntervalFn = options.setIntervalFn ?? ((fn, delay) => setInterval(fn, delay));
   const clearIntervalFn = options.clearIntervalFn ?? ((timer) => clearInterval(timer));
-  const maxSegmentWaitMs = options.maxSegmentWaitMs ?? 30000;
-  const flushCheckIntervalMs = options.flushCheckIntervalMs ?? 5000;
+  const rawStream = options.rawStream ?? false;
+  const maxSegmentWaitMs = options.maxSegmentWaitMs ?? (rawStream ? 200 : 30000);
+  const flushCheckIntervalMs = options.flushCheckIntervalMs ?? (rawStream ? 80 : 5000);
   const now = options.now ?? (() => Date.now());
   return await new Promise((resolve, reject) => {
     const child = spawnPrompt(command, args);
@@ -3898,12 +4000,15 @@ async function runStreamingPrompt(command, args, onEvent, options = {}) {
     const toolEventMode = options.toolEventMode ?? "text";
     const state = createStreamingPromptState(options.formatToolCalls ?? false, {
       mode: toolEventMode,
+      rawStream,
       ...onEvent && (toolEventMode === "structured" || toolEventMode === "both") ? { onToolEvent: (toolEvent) => onEvent({ type: "prompt.tool_event", event: toolEvent }) } : {},
-      ...onEvent ? { onThought: (chunk) => onEvent({ type: "prompt.thought", text: chunk }) } : {}
+      ...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 }) } : {}
     });
     let lastReplyAt = now();
     const flushBuffer = () => {
-      const remaining = state.buffer.trim();
+      const remaining = rawStream ? state.buffer : state.buffer.trim();
       if (remaining.length > 0) {
         state.buffer = "";
         onEvent?.({ type: "prompt.segment", text: remaining });
@@ -4020,6 +4125,8 @@ var BRIDGE_METHODS = new Set([
   "resumeAgentSession",
   "prompt",
   "setMode",
+  "setModel",
+  "getSessionModel",
   "cancel",
   "removeSession",
   "getAgentSessionId"
@@ -4031,6 +4138,8 @@ var SESSION_SCOPED_METHODS = new Set([
   "resumeAgentSession",
   "prompt",
   "setMode",
+  "setModel",
+  "getSessionModel",
   "cancel",
   "removeSession",
   "getAgentSessionId"
@@ -4127,6 +4236,7 @@ class BridgeServer {
           agentCommand: asOptionalString(params.agentCommand),
           cwd: requireString(params, "cwd"),
           name: requireString(params, "name"),
+          model: asOptionalString(params.model),
           mcpCoordinatorSession: asOptionalString(params.mcpCoordinatorSession),
           mcpSourceHandle: asOptionalString(params.mcpSourceHandle)
         }, (progress) => {
@@ -4152,6 +4262,7 @@ class BridgeServer {
           agentCommand: asOptionalString(params.agentCommand),
           cwd: requireString(params, "cwd"),
           name: requireString(params, "name"),
+          model: asOptionalString(params.model),
           mcpCoordinatorSession: asOptionalString(params.mcpCoordinatorSession),
           mcpSourceHandle: asOptionalString(params.mcpSourceHandle),
           text: requirePromptText(params, media),
@@ -4178,6 +4289,19 @@ class BridgeServer {
               event: "prompt.thought",
               text: event.text
             }));
+          } else if (event.type === "prompt.plan") {
+            writeLine?.(encodeBridgePromptPlanEvent({
+              id: requestId,
+              event: "prompt.plan",
+              entries: event.entries
+            }));
+          } else if (event.type === "prompt.usage") {
+            writeLine?.(encodeBridgePromptUsageEvent({
+              id: requestId,
+              event: "prompt.usage",
+              used: event.used,
+              size: event.size
+            }));
           }
         });
       case "resumeAgentSession":
@@ -4196,6 +4320,21 @@ class BridgeServer {
           name: requireString(params, "name"),
           modeId: requireString(params, "modeId")
         });
+      case "setModel":
+        return await this.runtime.setModel({
+          agent: requireString(params, "agent"),
+          agentCommand: asOptionalString(params.agentCommand),
+          cwd: requireString(params, "cwd"),
+          name: requireString(params, "name"),
+          modelId: requireString(params, "modelId")
+        });
+      case "getSessionModel":
+        return await this.runtime.getSessionModel({
+          agent: requireString(params, "agent"),
+          agentCommand: asOptionalString(params.agentCommand),
+          cwd: requireString(params, "cwd"),
+          name: requireString(params, "name")
+        });
       case "cancel":
         return await this.runtime.cancel({
           agent: requireString(params, "agent"),

package/dist/channels/types.d.ts

@@ -7,6 +7,7 @@ import type { PerfTracer } from "../perf/perf-tracer.js";
 import type { SessionService } from "../sessions/session-service.js";
 import type { ActiveTurnRegistry } from "../sessions/active-turn-registry.js";
 import type { Locale } from "../i18n/index.js";
+import type { ControlService } from "../control/control-service.js";
 export type { ChatAgent };
 export interface OutboundQuota {
     onInbound(chatKey: string): void;
@@ -44,6 +45,7 @@ export interface ScheduledChannelMessageInput {
     sessionDescriptor?: ScheduledSessionDescriptor;
     accountId?: string;
     replyContextToken?: string;
+    executeAt?: string;
     noticeText: string;
     promptText: string;
     abortSignal?: AbortSignal;
@@ -71,6 +73,12 @@ export interface ChannelStartInput {
      * the active locale via `getLocale()` from `xacpx/plugin-api`.
      */
     locale?: Locale;
+    /**
+     * Structured control facade (sessions / prompt / scheduler / orchestration)
+     * for structured consumers such as the relay connector. Optional: text-only
+     * channels ignore it.
+     */
+    control?: ControlService;
 }
 export interface OrchestrationDeliveryCallbacks {
     markTaskNoticeDelivered: (taskId: string, accountId: string) => Promise<void>;
@@ -140,3 +148,11 @@ export interface ToolUseEvent {
     /** Set when status transitions out of "running". */
     durationMs?: number;
 }
+export type PlanEntryStatus = "pending" | "in_progress" | "completed";
+/** One entry of the agent's ACP `plan` (its live todo list). The agent re-sends the
+ *  WHOLE list on each update, so consumers REPLACE rather than append. */
+export interface PlanEntry {
+    content: string;
+    status: PlanEntryStatus;
+    priority?: "high" | "medium" | "low";
+}