@ganglion/xacpx 0.13.0 → 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
@@ -4049,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 = () => {
@@ -4347,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
             }));
           }
         });

package/dist/cli.js

@@ -22377,7 +22377,7 @@ async function handleSessionArchive(context, chatKey, alias, archive) {
   await archive(internalAlias);
   return { text: t().session.sessionArchived(alias) };
 }
-async function promptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage) {
+async function promptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage, onCommands) {
   if (session3.archived) {
     await context.sessions.setArchived(session3.alias, false);
   }
@@ -22412,7 +22412,7 @@ async function promptWithSession(context, session3, chatKey, text, reply, replyC
   const { promptText, taskIds, groupIds, claimHumanReply } = await preparePromptWithFallback(context, session3, chatKey, text, replyContextToken, accountId);
   try {
     const replyContext = transportReply && context.quota && getChannelIdFromChatKey(chatKey) === "weixin" ? { chatKey, quota: context.quota } : undefined;
-    const result = await context.interaction.promptTransportSession(session3, promptText, transportReply, replyContext, media, abortSignal, onToolEvent, onThought, perfSpan, onPlan, onUsage);
+    const result = await context.interaction.promptTransportSession(session3, promptText, transportReply, replyContext, media, abortSignal, onToolEvent, onThought, perfSpan, onPlan, onUsage, onCommands);
     if (claimHumanReply) {
       try {
         await context.orchestration?.claimActiveHumanReply?.(claimHumanReply);
@@ -22432,23 +22432,23 @@ async function promptWithSession(context, session3, chatKey, text, reply, replyC
     throw error2;
   }
 }
-async function handlePromptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage) {
+async function handlePromptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage, onCommands) {
   try {
-    return await promptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage);
+    return await promptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage, onCommands);
   } catch (error2) {
     const recovered = await context.recovery.tryRecoverMissingSession(session3, error2);
     if (recovered) {
-      return await promptWithSession(context, recovered, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage);
+      return await promptWithSession(context, recovered, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage, onCommands);
     }
     return context.recovery.renderTransportError(session3, error2);
   }
 }
-async function handlePrompt(context, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage) {
+async function handlePrompt(context, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage, onCommands) {
   const session3 = metadata?.boundSessionAlias ? context.sessions.getResolvedSessionByInternalAlias(metadata.boundSessionAlias) : await context.sessions.getCurrentSession(chatKey);
   if (!session3) {
     return { text: t().session.noCurrent };
   }
-  return await handlePromptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage);
+  return await handlePromptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage, onCommands);
 }
 function toCoordinatorRouteChatMetadata(metadata) {
   if (!metadata) {
@@ -24707,7 +24707,7 @@ class CommandRouter {
     this.logger = logger2 ?? createNoopAppLogger();
     this.activeTurns = activeTurns;
   }
-  async handle(chatKey, input, reply, replyContextToken, accountId, media, metadata, abortSignal, onToolEvent, onThought, perfSpan, onPlan, onUsage) {
+  async handle(chatKey, input, reply, replyContextToken, accountId, media, metadata, abortSignal, onToolEvent, onThought, perfSpan, onPlan, onUsage, onCommands) {
     const startedAt = Date.now();
     let command = parseCommand(input);
     if (metadata?.channel === "control" && command.kind !== "prompt") {
@@ -24869,16 +24869,16 @@ class CommandRouter {
               ...this.sessions.resolveSession(descriptor.alias, descriptor.agent, descriptor.workspace, descriptor.transportSession),
               transient: true
             };
-            return await handlePromptWithSession(sessionContext, transientSession, chatKey, command.text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage);
+            return await handlePromptWithSession(sessionContext, transientSession, chatKey, command.text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage, onCommands);
           }
           if (metadata?.scheduledSessionAlias) {
             const scheduledSession = await this.sessions.getSession(metadata.scheduledSessionAlias);
             if (!scheduledSession) {
               throw new Error(`session "${metadata.scheduledSessionAlias}" not found for scheduled prompt`);
             }
-            return await handlePromptWithSession(sessionContext, scheduledSession, chatKey, command.text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage);
+            return await handlePromptWithSession(sessionContext, scheduledSession, chatKey, command.text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage, onCommands);
           }
-          return await handlePrompt(sessionContext, chatKey, command.text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage);
+          return await handlePrompt(sessionContext, chatKey, command.text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage, onCommands);
         }
       }
     });
@@ -25102,7 +25102,7 @@ class CommandRouter {
       setModelTransportSession: (session3, modelId) => this.setModelTransportSession(session3, modelId),
       getModelTransportSession: (session3) => this.getModelTransportSession(session3),
       cancelTransportSession: (session3) => this.cancelTransportSession(session3),
-      promptTransportSession: (session3, text, reply, replyContext, media, abortSignal, onToolEvent, onThought, perfSpanOverride, onPlan, onUsage) => this.promptTransportSession(session3, text, reply, replyContext, media, abortSignal, onToolEvent, onThought, perfSpanOverride ?? perfSpan, onPlan, onUsage)
+      promptTransportSession: (session3, text, reply, replyContext, media, abortSignal, onToolEvent, onThought, perfSpanOverride, onPlan, onUsage, onCommands) => this.promptTransportSession(session3, text, reply, replyContext, media, abortSignal, onToolEvent, onThought, perfSpanOverride ?? perfSpan, onPlan, onUsage, onCommands)
     };
   }
   createSessionRenderRecoveryOps() {
@@ -25281,7 +25281,7 @@ class CommandRouter {
   async checkTransportSession(session3) {
     return await this.measureTransportCall("has_session", session3, () => this.transport.hasSession(session3));
   }
-  async promptTransportSession(session3, text, reply, replyContext, media, abortSignal, onToolEvent, onThought, perfSpan, onPlan, onUsage) {
+  async promptTransportSession(session3, text, reply, replyContext, media, abortSignal, onToolEvent, onThought, perfSpan, onPlan, onUsage, onCommands) {
     session3.mcpCoordinatorSession ??= stableCoordinatorSession(session3.transportSession);
     let done = false;
     let abortRequested = false;
@@ -25340,7 +25340,8 @@ class CommandRouter {
         ...onToolEvent ? { onToolEvent } : {},
         ...onThought ? { onThought } : {},
         ...onPlan ? { onPlan } : {},
-        ...onUsage ? { onUsage } : {}
+        ...onUsage ? { onUsage } : {},
+        ...onCommands ? { onCommands } : {}
       }));
     } catch (error2) {
       localOutcome = isAbortError2(error2) || abortRequested ? "aborted" : "error";
@@ -25526,7 +25527,7 @@ class ConsoleAgent {
       ...m.fileName ? { fileName: m.fileName } : {}
     })) : undefined;
     request.perfSpan?.mark("agent.dispatched");
-    return await this.router.handle(request.conversationId, request.text, request.reply, request.replyContextToken, request.accountId, promptMedia, request.metadata, request.abortSignal, request.onToolEvent, request.onThought, request.perfSpan, request.onPlan, request.onUsage);
+    return await this.router.handle(request.conversationId, request.text, request.reply, request.replyContextToken, request.accountId, promptMedia, request.metadata, request.abortSignal, request.onToolEvent, request.onThought, request.perfSpan, request.onPlan, request.onUsage, request.onCommands);
   }
   isKnownCommand(text) {
     return isKnownXacpxCommandText(text);
@@ -30607,6 +30608,10 @@ function encodeBridgePromptUsageEvent(event) {
   return `${JSON.stringify(event)}
 `;
 }
+function encodeBridgePromptCommandsEvent(event) {
+  return `${JSON.stringify(event)}
+`;
+}
 function encodeBridgeSessionProgressEvent(event) {
   return `${JSON.stringify(event)}
 `;
@@ -30913,7 +30918,14 @@ class AcpxBridgeClient {
         pending.onEvent?.({
           type: "prompt.usage",
           used: message.used,
-          size: message.size
+          size: message.size,
+          ...message.cost ? { cost: message.cost } : {},
+          ...message.breakdown ? { breakdown: message.breakdown } : {}
+        });
+      } else if (message.event === "prompt.commands") {
+        pending.onEvent?.({
+          type: "prompt.commands",
+          commands: message.commands
         });
       } else if (message.event === "session.progress") {
         pending.onEvent?.({
@@ -31376,6 +31388,8 @@ class AcpxBridgeTransport {
     let planChain = Promise.resolve();
     let usageError;
     let usageChain = Promise.resolve();
+    let commandsError;
+    let commandsChain = Promise.resolve();
     let toolEventMode = resolveToolEventMode(options);
     if ((toolEventMode === "structured" || toolEventMode === "both") && !options?.onToolEvent) {
       toolEventMode = "text";
@@ -31431,19 +31445,30 @@ class AcpxBridgeTransport {
       if (event.type === "prompt.usage") {
         const onUsage = options?.onUsage;
         if (onUsage) {
-          const usage = { used: event.used, size: event.size };
+          const usage = { used: event.used, size: event.size, ...event.cost ? { cost: event.cost } : {}, ...event.breakdown ? { breakdown: event.breakdown } : {} };
           usageChain = usageChain.then(() => onUsage(usage)).catch((error2) => {
             usageError ??= error2;
           });
         }
         return;
       }
+      if (event.type === "prompt.commands") {
+        const onCommands = options?.onCommands;
+        if (onCommands) {
+          const commands = event.commands;
+          commandsChain = commandsChain.then(() => onCommands(commands)).catch((error2) => {
+            commandsError ??= error2;
+          });
+        }
+        return;
+      }
     });
     await segmentChain;
     await toolEventChain;
     await thoughtChain;
     await planChain;
     await usageChain;
+    await commandsChain;
     if (sink) {
       const { overflowCount } = sink.finalize();
       await sink.drain({ timeoutMs: 30000 });
@@ -31467,6 +31492,9 @@ class AcpxBridgeTransport {
       if (usageError) {
         throw usageError;
       }
+      if (commandsError) {
+        throw commandsError;
+      }
       return { text: summary ? `${summary}
 
 ${result.text}` : "" };
@@ -31486,6 +31514,9 @@ ${result.text}` : "" };
     if (usageError) {
       throw usageError;
     }
+    if (commandsError) {
+      throw commandsError;
+    }
     return result;
   }
   async setMode(session3, modeId) {
@@ -31695,6 +31726,7 @@ function createStreamingPromptState(formatToolCalls = false, options) {
   let onThought;
   let onPlan;
   let onUsage;
+  let onCommands;
   let rawStream = false;
   if (options === undefined) {
     toolEventMode = "text";
@@ -31707,6 +31739,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,
@@ -31726,6 +31759,7 @@ function createStreamingPromptState(formatToolCalls = false, options) {
     onThought,
     onPlan,
     onUsage,
+    onCommands,
     finalize() {
       if (this.pendingLine.trim().length > 0) {
         parseStreamingChunks(this, this.pendingLine);
@@ -31793,8 +31827,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";
@@ -31961,6 +32004,52 @@ function readFirstStringArray(record3, keys) {
   }
   return;
 }
+function asFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function firstFiniteNumber(record3, keys) {
+  for (const key of keys) {
+    const n = asFiniteNumber(record3[key]);
+    if (n !== undefined)
+      return n;
+  }
+  return;
+}
+function normalizeUsageBreakdown(value) {
+  if (!isRecord3(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 (!isRecord3(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 (!isRecord3(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 isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -31986,8 +32075,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/transport/acpx-cli/node-pty-helper.ts
@@ -33497,24 +33595,29 @@ var init_workspace_fs = __esm(() => {
 });
 
 // src/control/control-service.ts
+import path15 from "node:path";
+
 class ControlService {
   deps;
   constructor(deps) {
     this.deps = deps;
   }
   workspaceFs = new WorkspaceFs(() => this.deps.workspaces.list().map((w) => ({ name: w.name, cwd: w.cwd })));
-  listDirectory(workspace3, path15) {
-    return this.workspaceFs.listDirectory(workspace3, path15);
+  listDirectory(workspace3, path16) {
+    return this.workspaceFs.listDirectory(workspace3, path16);
   }
-  readWorkspaceFile(workspace3, path15) {
-    return this.workspaceFs.readFile(workspace3, path15);
+  readWorkspaceFile(workspace3, path16) {
+    return this.workspaceFs.readFile(workspace3, path16);
   }
-  workspaceGitDiff(workspace3, path15) {
-    return this.workspaceFs.gitDiff(workspace3, path15);
+  workspaceGitDiff(workspace3, path16) {
+    return this.workspaceFs.gitDiff(workspace3, path16);
   }
   searchWorkspace(workspace3, query) {
     return this.workspaceFs.search(workspace3, query);
   }
+  async uploadFile(input) {
+    return this.deps.uploadStore.save(input.filename, input.content, input.mimeType);
+  }
   async getSessionModel(chatKey, alias) {
     const session3 = await this.resolveControlSession(chatKey, alias);
     if (!session3)
@@ -33658,7 +33761,8 @@ class ControlService {
       text: input.text,
       senderId: input.senderId,
       ...input.isOwner !== undefined ? { isOwner: input.isOwner } : {},
-      ...input.accountId !== undefined ? { accountId: input.accountId } : {}
+      ...input.accountId !== undefined ? { accountId: input.accountId } : {},
+      ...input.media !== undefined ? { media: input.media } : {}
     });
   }
   async runScheduledTurn(input) {
@@ -33730,6 +33834,32 @@ ${chunk}` : chunk
       });
       emittedChunk = true;
     };
+    const incomingMedia = params.media ?? [];
+    const sandboxedMedia = incomingMedia.length ? (() => {
+      const uploadRoot = path15.resolve(this.deps.uploadStore.root);
+      const kept = incomingMedia.filter((ref) => {
+        const resolved = path15.resolve(ref.filePath);
+        return resolved === uploadRoot || resolved.startsWith(uploadRoot + path15.sep);
+      });
+      const dropped = incomingMedia.length - kept.length;
+      if (dropped > 0) {
+        console.warn(`[control] dropped ${dropped} media ref(s) with filePath outside the upload sandbox`);
+      }
+      return kept;
+    })() : incomingMedia;
+    const chatMedia = sandboxedMedia.map((ref) => ({
+      kind: ref.kind,
+      filePath: ref.filePath,
+      mimeType: ref.mimeType,
+      ...ref.fileName ? { fileName: ref.fileName } : {},
+      sizeBytes: ref.size,
+      source: {
+        channelId: "relay",
+        accountId: params.accountId ?? "control",
+        chatKey: params.chatKey,
+        messageId: ref.id
+      }
+    }));
     try {
       const response = await this.deps.agent.chat({
         accountId: params.accountId ?? "control",
@@ -33737,6 +33867,7 @@ ${chunk}` : chunk
         text: params.text,
         metadata: buildControlMetadata(params.senderId, params.isOwner),
         abortSignal: controller.signal,
+        ...chatMedia.length > 0 ? { media: chatMedia } : {},
         reply: async (chunk) => {
           emitChunk(chunk);
         },
@@ -33770,7 +33901,17 @@ ${chunk}` : chunk
             chatKey: params.chatKey,
             sessionAlias: params.sessionAlias,
             used: usage.used,
-            size: usage.size
+            size: usage.size,
+            ...usage.cost ? { cost: usage.cost } : {},
+            ...usage.breakdown ? { breakdown: usage.breakdown } : {}
+          });
+        },
+        onCommands: (commands) => {
+          this.deps.events.emit({
+            type: "agent-commands",
+            chatKey: params.chatKey,
+            sessionAlias: params.sessionAlias,
+            commands
           });
         }
       });
@@ -33859,13 +34000,92 @@ var init_control_service = __esm(() => {
   init_workspace_fs();
 });
 
+// src/control/upload-store.ts
+import { mkdtemp as mkdtemp2, readdir as readdir5, rm as rm10, stat as stat4, writeFile as writeFile8 } from "node:fs/promises";
+import { homedir as homedir12 } from "node:os";
+import path16 from "node:path";
+function defaultRootDir() {
+  const home = process.env.HOME ?? homedir12();
+  return path16.join(coreHomeDir(home), "runtime", "uploads");
+}
+function sanitizeUploadFilename(raw) {
+  const base = path16.basename(raw).replace(/[/\\]/g, "").replace(/^\.+/, "");
+  const cleaned = base.trim();
+  return cleaned.length > 0 ? cleaned : "file";
+}
+
+class UploadStore {
+  rootDir;
+  maxBytes;
+  ttlMs;
+  now;
+  constructor(opts = {}) {
+    this.rootDir = opts.rootDir ?? defaultRootDir();
+    this.maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+    this.now = opts.now ?? (() => new Date);
+  }
+  get root() {
+    return this.rootDir;
+  }
+  async save(filename, base642, mimeType) {
+    if (base642.length > Math.ceil(this.maxBytes * 4 / 3) + 4)
+      throw new Error("file-too-large");
+    const bytes = Buffer.from(base642, "base64");
+    if (bytes.byteLength === 0)
+      throw new Error("empty-file");
+    if (bytes.byteLength > this.maxBytes)
+      throw new Error("file-too-large");
+    const safeName = sanitizeUploadFilename(filename);
+    const { mkdir: mkdir9 } = await import("node:fs/promises");
+    await mkdir9(this.rootDir, { recursive: true });
+    const dir = await mkdtemp2(path16.join(this.rootDir, "u-"));
+    const filePath = path16.join(dir, safeName);
+    await writeFile8(filePath, bytes);
+    return {
+      id: path16.basename(dir),
+      path: filePath,
+      filename: safeName,
+      mimeType,
+      size: bytes.byteLength
+    };
+  }
+  async cleanup() {
+    let entries;
+    try {
+      entries = await readdir5(this.rootDir);
+    } catch {
+      return 0;
+    }
+    const cutoff = this.now().getTime() - this.ttlMs;
+    let removed = 0;
+    for (const name of entries) {
+      const dir = path16.join(this.rootDir, name);
+      try {
+        const info = await stat4(dir);
+        if (info.mtimeMs < cutoff) {
+          await rm10(dir, { recursive: true, force: true });
+          removed += 1;
+        }
+      } catch {}
+    }
+    return removed;
+  }
+}
+var DEFAULT_MAX_BYTES, DEFAULT_TTL_MS;
+var init_upload_store = __esm(() => {
+  init_core_home();
+  DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+  DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+});
+
 // src/config/agent-catalog.ts
 import { existsSync as existsSync3 } from "node:fs";
 import { delimiter as delimiter2, join as join21 } from "node:path";
 function isBinaryOnPath(binary) {
-  const path15 = process.env.PATH ?? "";
+  const path17 = process.env.PATH ?? "";
   const exts = process.platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
-  for (const dir of path15.split(delimiter2)) {
+  for (const dir of path17.split(delimiter2)) {
     if (!dir)
       continue;
     for (const ext of exts) {
@@ -33910,7 +34130,7 @@ __export(exports_main, {
   buildApp: () => buildApp
 });
 import { randomUUID as randomUUID3 } from "node:crypto";
-import { homedir as homedir12 } from "node:os";
+import { homedir as homedir13 } from "node:os";
 import { dirname as dirname12, join as join22 } from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 function startProgressHeartbeat(orchestration3, config4, logger2, channel) {
@@ -34402,6 +34622,9 @@ async function buildApp(paths, deps = {}) {
   const router3 = new CommandRouter(sessions, transport, config4, configStore, logger2, undefined, orchestration3, quota, scheduledService, deps.channel?.supportsScheduledMessages ? { supportsScheduledMessages: deps.channel.supportsScheduledMessages.bind(deps.channel) } : undefined, deps.channel?.nativeSessionListFormat ? deps.channel.nativeSessionListFormat.bind(deps.channel) : undefined, activeTurns);
   const agent3 = new ConsoleAgent(router3, logger2);
   const controlEvents = createControlEventBus(logger2);
+  const uploadStore = new UploadStore;
+  uploadStore.cleanup();
+  const uploadCleanupInterval = setInterval(() => void uploadStore.cleanup().catch(() => {}), 60 * 60 * 1000);
   const control = new ControlService({
     agent: agent3,
     sessions,
@@ -34444,7 +34667,8 @@ async function buildApp(paths, deps = {}) {
         const updated = await configStore.removeWorkspace(name);
         replaceRuntimeConfig(config4, updated);
       }
-    }
+    },
+    uploadStore
   });
   const scheduledScheduler = new ScheduledTaskScheduler(scheduledService, {
     dispatchTask: buildScheduledDispatchTask({
@@ -34514,6 +34738,7 @@ async function buildApp(paths, deps = {}) {
     reapStaleQueueOwners: () => reapWarmQueueOwners("startup"),
     dispose: async () => {
       scheduledScheduler.stop();
+      clearInterval(uploadCleanupInterval);
       if (progressHeartbeatInterval !== undefined) {
         clearInterval(progressHeartbeatInterval);
       }
@@ -34584,7 +34809,7 @@ async function prepareChannelMedia(configPath, config4) {
   return { mediaStore, channelDeps: { mediaStore, allowedMediaRoots } };
 }
 function resolveRuntimePaths() {
-  const home = process.env.HOME ?? homedir12();
+  const home = process.env.HOME ?? homedir13();
   if (!home) {
     throw new Error("Unable to resolve the current user home directory");
   }
@@ -34656,6 +34881,7 @@ var init_main = __esm(async () => {
   init_render_text();
   init_quota_manager();
   init_control_service();
+  init_upload_store();
   init_agent_catalog();
   init_perf_tracer();
   init_bootstrap();
@@ -34849,12 +35075,12 @@ var init_config_check = __esm(async () => {
 });
 
 // src/doctor/checks/daemon-check.ts
-import { readdir as readdir5, readFile as readFile15, rm as rm10 } from "node:fs/promises";
+import { readdir as readdir6, readFile as readFile15, rm as rm11 } from "node:fs/promises";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
-import { homedir as homedir13 } from "node:os";
+import { homedir as homedir14 } from "node:os";
 import { join as join23 } from "node:path";
 async function checkDaemon(options = {}) {
-  const home = options.home ?? process.env.HOME ?? homedir13();
+  const home = options.home ?? process.env.HOME ?? homedir14();
   const runtimeDir = options.configPath ? resolveRuntimeDirFromConfigPath(options.configPath) : undefined;
   const paths = (options.resolveDaemonPaths ?? resolveDaemonPaths)({
     home,
@@ -34988,22 +35214,22 @@ async function detectStaleConsumerLockFix(runtimeDir, deps) {
 }
 async function defaultListConsumerLocks(runtimeDir) {
   try {
-    return await readdir5(runtimeDir);
+    return await readdir6(runtimeDir);
   } catch {
     return [];
   }
 }
-async function defaultReadConsumerLock(path15) {
+async function defaultReadConsumerLock(path17) {
   try {
-    const raw = await readFile15(path15, "utf8");
+    const raw = await readFile15(path17, "utf8");
     const parsed = JSON.parse(raw);
     return typeof parsed.pid === "number" ? { pid: parsed.pid } : null;
   } catch {
     return null;
   }
 }
-async function defaultRemoveConsumerLock(path15) {
-  await rm10(path15, { force: true });
+async function defaultRemoveConsumerLock(path17) {
+  await rm11(path17, { force: true });
 }
 function resolveCliEntryPath() {
   return process.argv[1] ?? fileURLToPath6(import.meta.url);
@@ -35018,11 +35244,11 @@ var init_daemon_check = __esm(() => {
 });
 
 // src/doctor/checks/logs-check.ts
-import { stat as stat4, readdir as readdir6 } from "node:fs/promises";
+import { stat as stat5, readdir as readdir7 } from "node:fs/promises";
 import { basename as basename3, join as join24 } from "node:path";
-import { homedir as homedir14 } from "node:os";
+import { homedir as homedir15 } from "node:os";
 async function checkLogs(options = {}) {
-  const home = options.home ?? process.env.HOME ?? homedir14();
+  const home = options.home ?? process.env.HOME ?? homedir15();
   const runtimeDir = options.configPath ? resolveRuntimeDirFromConfigPath(options.configPath) : undefined;
   const paths = (options.resolveDaemonPaths ?? resolveDaemonPaths)({
     home,
@@ -35054,13 +35280,13 @@ async function checkLogs(options = {}) {
   const matched = entries.filter((entry) => isTrackedLogName(entry, tracked));
   const files = [];
   for (const name of matched) {
-    const path15 = join24(paths.runtimeDir, name);
+    const path17 = join24(paths.runtimeDir, name);
     try {
-      const fileStat = await probe.stat(path15);
+      const fileStat = await probe.stat(path17);
       if (fileStat.isDirectory()) {
         continue;
       }
-      files.push({ name, path: path15, size: fileStat.size });
+      files.push({ name, path: path17, size: fileStat.size });
     } catch {
       continue;
     }
@@ -35134,8 +35360,8 @@ function formatBytes(bytes) {
 }
 function createLogsFsProbe() {
   return {
-    stat: async (path15) => await stat4(path15),
-    readdir: async (path15) => await readdir6(path15)
+    stat: async (path17) => await stat5(path17),
+    readdir: async (path17) => await readdir7(path17)
   };
 }
 function formatError6(error2) {
@@ -35204,9 +35430,9 @@ var init_orchestration_health = __esm(() => {
 });
 
 // src/doctor/checks/orchestration-socket-check.ts
-import { homedir as homedir15 } from "node:os";
+import { homedir as homedir16 } from "node:os";
 async function checkOrchestrationSocket(options = {}) {
-  const home = options.home ?? process.env.HOME ?? homedir15();
+  const home = options.home ?? process.env.HOME ?? homedir16();
   const runtimeDir = options.configPath ? resolveRuntimeDirFromConfigPath(options.configPath) : undefined;
   const paths = (options.resolveDaemonPaths ?? resolveDaemonPaths)({
     home,
@@ -35379,11 +35605,11 @@ var init_plugin_check = __esm(async () => {
 
 // src/doctor/checks/runtime-check.ts
 import { constants } from "node:fs";
-import { access as access4, stat as stat5 } from "node:fs/promises";
+import { access as access4, stat as stat6 } from "node:fs/promises";
 import { dirname as dirname13 } from "node:path";
-import { homedir as homedir16 } from "node:os";
+import { homedir as homedir17 } from "node:os";
 async function checkRuntime(options = {}) {
-  const home = options.home ?? process.env.HOME ?? homedir16();
+  const home = options.home ?? process.env.HOME ?? homedir17();
   const runtimeDir = options.configPath ? resolveRuntimeDirFromConfigPath(options.configPath) : undefined;
   const paths = (options.resolveDaemonPaths ?? resolveDaemonPaths)({
     home,
@@ -35477,107 +35703,107 @@ function formatMode(mode) {
 }
 function createRuntimeFsProbe() {
   return {
-    stat: async (path15) => await stat5(path15),
-    access: async (path15, mode) => await access4(path15, mode)
+    stat: async (path17) => await stat6(path17),
+    access: async (path17, mode) => await access4(path17, mode)
   };
 }
-async function checkDirectoryCreatable(label, path15, probe, platform) {
+async function checkDirectoryCreatable(label, path17, probe, platform) {
   try {
-    const stats = await probe.stat(path15);
+    const stats = await probe.stat(path17);
     if (!stats.isDirectory()) {
       return {
         ok: false,
-        detail: `${label}: ${path15} (exists but is not a directory)`
+        detail: `${label}: ${path17} (exists but is not a directory)`
       };
     }
-    await probe.access(path15, directoryAccessMode(platform));
+    await probe.access(path17, directoryAccessMode(platform));
     return {
       ok: true,
-      detail: `${label}: ${path15} (writable)`
+      detail: `${label}: ${path17} (writable)`
     };
   } catch (error2) {
     if (!isMissingPathError2(error2)) {
       return {
         ok: false,
-        detail: `${label}: ${path15} (unusable: ${formatError9(error2)})`
+        detail: `${label}: ${path17} (unusable: ${formatError9(error2)})`
       };
     }
-    const parentCheck = await checkCreatableAncestorDirectory(path15, probe, platform);
+    const parentCheck = await checkCreatableAncestorDirectory(path17, probe, platform);
     if (!parentCheck.ok) {
       return {
         ok: false,
-        detail: `${label}: ${path15} (parent not writable: ${parentCheck.blockingPath})`
+        detail: `${label}: ${path17} (parent not writable: ${parentCheck.blockingPath})`
       };
     }
     return {
       ok: true,
-      detail: `${label}: ${path15} (creatable via ${parentCheck.creatableFrom})`
+      detail: `${label}: ${path17} (creatable via ${parentCheck.creatableFrom})`
     };
   }
 }
-async function checkFileCreatable(label, path15, probe, platform) {
+async function checkFileCreatable(label, path17, probe, platform) {
   try {
-    const stats = await probe.stat(path15);
+    const stats = await probe.stat(path17);
     if (stats.isDirectory()) {
       return {
         ok: false,
-        detail: `${label}: ${path15} (exists but is a directory)`
+        detail: `${label}: ${path17} (exists but is a directory)`
       };
     }
-    await probe.access(path15, constants.W_OK);
+    await probe.access(path17, constants.W_OK);
     return {
       ok: true,
-      detail: `${label}: ${path15} (writable)`
+      detail: `${label}: ${path17} (writable)`
     };
   } catch (error2) {
     if (!isMissingPathError2(error2)) {
       return {
         ok: false,
-        detail: `${label}: ${path15} (unusable: ${formatError9(error2)})`
+        detail: `${label}: ${path17} (unusable: ${formatError9(error2)})`
       };
     }
-    const parentCheck = await checkCreatableAncestorDirectory(dirname13(path15), probe, platform);
+    const parentCheck = await checkCreatableAncestorDirectory(dirname13(path17), probe, platform);
     if (!parentCheck.ok) {
       return {
         ok: false,
-        detail: `${label}: ${path15} (parent not writable: ${parentCheck.blockingPath})`
+        detail: `${label}: ${path17} (parent not writable: ${parentCheck.blockingPath})`
       };
     }
     return {
       ok: true,
-      detail: `${label}: ${path15} (creatable via ${parentCheck.creatableFrom})`
+      detail: `${label}: ${path17} (creatable via ${parentCheck.creatableFrom})`
     };
   }
 }
-async function checkCreatableAncestorDirectory(path15, probe, platform) {
+async function checkCreatableAncestorDirectory(path17, probe, platform) {
   try {
-    const stats = await probe.stat(path15);
+    const stats = await probe.stat(path17);
     if (!stats.isDirectory()) {
       return {
         ok: false,
-        creatableFrom: path15,
-        blockingPath: path15
+        creatableFrom: path17,
+        blockingPath: path17
       };
     }
-    await probe.access(path15, directoryAccessMode(platform));
+    await probe.access(path17, directoryAccessMode(platform));
     return {
       ok: true,
-      creatableFrom: path15
+      creatableFrom: path17
     };
   } catch (error2) {
     if (!isMissingPathError2(error2)) {
       return {
         ok: false,
-        creatableFrom: path15,
-        blockingPath: path15
+        creatableFrom: path17,
+        blockingPath: path17
       };
     }
-    const parent = dirname13(path15);
-    if (parent === path15) {
+    const parent = dirname13(path17);
+    if (parent === path17) {
       return {
         ok: false,
-        creatableFrom: path15,
-        blockingPath: path15
+        creatableFrom: path17,
+        blockingPath: path17
       };
     }
     const parentCheck = await checkCreatableAncestorDirectory(parent, probe, platform);
@@ -36016,10 +36242,10 @@ var init_render_doctor = __esm(() => {
 });
 
 // src/doctor/doctor.ts
-import { homedir as homedir17 } from "node:os";
+import { homedir as homedir18 } from "node:os";
 import { join as join25 } from "node:path";
 async function runDoctor(options = {}, deps = {}) {
-  const home = deps.home ?? process.env.HOME ?? homedir17();
+  const home = deps.home ?? process.env.HOME ?? homedir18();
   const runtimePaths = resolveDoctorRuntimePaths(home, deps.resolveRuntimePaths);
   const sharedLoadConfig = createSharedLoadConfig(runtimePaths, deps.loadConfig ?? loadConfig);
   const runners = [
@@ -36356,7 +36582,7 @@ var init_doctor2 = __esm(async () => {
 // src/cli.ts
 init_core_home();
 import { randomUUID as randomUUID4 } from "node:crypto";
-import { homedir as homedir18 } from "node:os";
+import { homedir as homedir19 } from "node:os";
 import { dirname as dirname14, join as join26, sep as sep2 } from "node:path";
 import { fileURLToPath as fileURLToPath7 } from "node:url";
 
@@ -52962,7 +53188,7 @@ function decodeFirstRunOnboarding(raw) {
   return null;
 }
 function requireHome2() {
-  const home = process.env.HOME ?? homedir18();
+  const home = process.env.HOME ?? homedir19();
   if (!home) {
     throw new Error("Unable to resolve the current user home directory");
   }

package/dist/commands/handlers/session-handler.d.ts

@@ -1,5 +1,5 @@
 import type { CommandRouterContext, RouterResponse, SessionInteractionOps, SessionLifecycleOps, SessionRenderRecoveryOps } from "../router-types";
-import type { PromptMediaInput, ResolvedSession } from "../../transport/types";
+import type { AgentCommand, PromptMediaInput, PromptUsage, ResolvedSession } from "../../transport/types";
 import type { PlanEntry, ToolUseEvent } from "../../channels/types.js";
 import type { PerfSpan } from "../../perf/perf-tracer";
 import type { HelpTopicMetadata } from "../help/help-types";
@@ -39,11 +39,5 @@ export declare function handleSessionReset(context: SessionHandlerContext, chatK
 export declare function handleSessionTail(context: SessionHandlerContext, chatKey: string, lines?: number): Promise<RouterResponse>;
 export declare function handleSessionRemove(context: SessionHandlerContext, chatKey: string, alias: string): Promise<RouterResponse>;
 export declare function handleSessionArchive(context: SessionHandlerContext, chatKey: string, alias: string, archive: (internalAlias: string) => Promise<void>): Promise<RouterResponse>;
-export declare function handlePromptWithSession(context: SessionHandlerContext, session: ResolvedSession, chatKey: string, text: string, reply?: (text: string) => Promise<void>, replyContextToken?: string, accountId?: string, media?: PromptMediaInput, abortSignal?: AbortSignal, onToolEvent?: (event: ToolUseEvent) => void | Promise<void>, onThought?: (chunk: string) => void | Promise<void>, perfSpan?: PerfSpan, metadata?: ChatRequestMetadata, onPlan?: (entries: PlanEntry[]) => void | Promise<void>, onUsage?: (usage: {
-    used: number;
-    size: number;
-}) => void | Promise<void>): Promise<RouterResponse>;
-export declare function handlePrompt(context: SessionHandlerContext, chatKey: string, text: string, reply?: (text: string) => Promise<void>, replyContextToken?: string, accountId?: string, media?: PromptMediaInput, abortSignal?: AbortSignal, onToolEvent?: (event: ToolUseEvent) => void | Promise<void>, onThought?: (chunk: string) => void | Promise<void>, perfSpan?: PerfSpan, metadata?: ChatRequestMetadata, onPlan?: (entries: PlanEntry[]) => void | Promise<void>, onUsage?: (usage: {
-    used: number;
-    size: number;
-}) => void | Promise<void>): Promise<RouterResponse>;
+export declare function handlePromptWithSession(context: SessionHandlerContext, session: ResolvedSession, chatKey: string, text: string, reply?: (text: string) => Promise<void>, replyContextToken?: string, accountId?: string, media?: PromptMediaInput, abortSignal?: AbortSignal, onToolEvent?: (event: ToolUseEvent) => void | Promise<void>, onThought?: (chunk: string) => void | Promise<void>, perfSpan?: PerfSpan, metadata?: ChatRequestMetadata, onPlan?: (entries: PlanEntry[]) => void | Promise<void>, onUsage?: (usage: PromptUsage) => void | Promise<void>, onCommands?: (commands: AgentCommand[]) => void | Promise<void>): Promise<RouterResponse>;
+export declare function handlePrompt(context: SessionHandlerContext, chatKey: string, text: string, reply?: (text: string) => Promise<void>, replyContextToken?: string, accountId?: string, media?: PromptMediaInput, abortSignal?: AbortSignal, onToolEvent?: (event: ToolUseEvent) => void | Promise<void>, onThought?: (chunk: string) => void | Promise<void>, perfSpan?: PerfSpan, metadata?: ChatRequestMetadata, onPlan?: (entries: PlanEntry[]) => void | Promise<void>, onUsage?: (usage: PromptUsage) => void | Promise<void>, onCommands?: (commands: AgentCommand[]) => void | Promise<void>): Promise<RouterResponse>;

package/dist/commands/router-types.d.ts

@@ -3,7 +3,7 @@ import type { AppConfig } from "../config/types";
 import type { AppLogger } from "../logging/app-logger";
 import type { OrchestrationService } from "../orchestration/orchestration-service";
 import type { SessionService } from "../sessions/session-service";
-import type { PromptMediaInput, ReplyQuotaContext, SessionTransport } from "../transport/types";
+import type { AgentCommand, PromptMediaInput, PromptUsage, ReplyQuotaContext, SessionTransport } from "../transport/types";
 import type { QuotaManager } from "../weixin/messaging/quota-manager.js";
 import type { PlanEntry, ToolUseEvent } from "../channels/types.js";
 import type { PerfSpan } from "../perf/perf-tracer";
@@ -113,10 +113,7 @@ export interface SessionInteractionOps {
         cancelled: boolean;
         message: string;
     }>;
-    promptTransportSession: (session: import("../transport/types").ResolvedSession, text: string, reply?: (text: string) => Promise<void>, replyContext?: ReplyQuotaContext, media?: PromptMediaInput, abortSignal?: AbortSignal, onToolEvent?: (event: ToolUseEvent) => void | Promise<void>, onThought?: (chunk: string) => void | Promise<void>, perfSpan?: PerfSpan, onPlan?: (entries: PlanEntry[]) => void | Promise<void>, onUsage?: (usage: {
-        used: number;
-        size: number;
-    }) => void | Promise<void>) => Promise<{
+    promptTransportSession: (session: import("../transport/types").ResolvedSession, text: string, reply?: (text: string) => Promise<void>, replyContext?: ReplyQuotaContext, media?: PromptMediaInput, abortSignal?: AbortSignal, onToolEvent?: (event: ToolUseEvent) => void | Promise<void>, onThought?: (chunk: string) => void | Promise<void>, perfSpan?: PerfSpan, onPlan?: (entries: PlanEntry[]) => void | Promise<void>, onUsage?: (usage: PromptUsage) => void | Promise<void>, onCommands?: (commands: AgentCommand[]) => void | Promise<void>) => Promise<{
         text: string;
     }>;
 }

package/dist/control/control-event-bus.d.ts

@@ -1,5 +1,6 @@
 import type { AppLogger } from "../logging/app-logger";
 import type { ToolUseEvent, PlanEntry } from "../channels/types";
+import type { AgentCommand, UsageBreakdown, UsageCost } from "../transport/types";
 import type { NativeHistoryMessage } from "../transport/native-session-history";
 export interface ScheduledOrigin {
     taskId: string;
@@ -37,6 +38,13 @@ export type ControlEvent = {
     sessionAlias: string;
     used: number;
     size: number;
+    cost?: UsageCost;
+    breakdown?: UsageBreakdown;
+} | {
+    type: "agent-commands";
+    chatKey: string;
+    sessionAlias: string;
+    commands: AgentCommand[];
 } | {
     type: "turn-finished";
     chatKey: string;

package/dist/control/control-service.d.ts

@@ -9,6 +9,8 @@ import type { OrchestrationTaskRecord } from "../orchestration/orchestration-typ
 import type { ControlEventBus } from "./control-event-bus";
 import type { AgentCatalogEntry } from "../config/agent-catalog";
 import { type DirListing, type FileContent, type SearchResult, type WorkspaceDiff } from "./workspace-fs";
+import type { PromptAttachmentRef } from "@ganglion/xacpx-relay-protocol";
+import type { UploadStore } from "./upload-store.js";
 export interface ControlSessionInfo {
     alias: string;
     agent: string;
@@ -63,6 +65,7 @@ export interface ControlServiceDeps {
         create(name: string, cwd: string, description?: string): Promise<ControlWorkspaceInfo>;
         remove(name: string): Promise<void>;
     };
+    uploadStore: UploadStore;
 }
 export interface ControlPromptInput {
     chatKey: string;
@@ -71,6 +74,7 @@ export interface ControlPromptInput {
     accountId?: string;
     senderId: string;
     isOwner?: boolean;
+    media?: PromptAttachmentRef[];
 }
 export interface ControlPromptResult {
     ok: boolean;
@@ -105,6 +109,17 @@ export declare class ControlService {
     readWorkspaceFile(workspace: string, path: string): Promise<FileContent>;
     workspaceGitDiff(workspace: string, path?: string): Promise<WorkspaceDiff>;
     searchWorkspace(workspace: string, query: string): Promise<SearchResult>;
+    uploadFile(input: {
+        filename: string;
+        content: string;
+        mimeType: string;
+    }): Promise<{
+        id: string;
+        path: string;
+        filename: string;
+        mimeType: string;
+        size: number;
+    }>;
     /** Read a session's current model and the agent-advertised available ids. */
     getSessionModel(chatKey: string, alias: string): Promise<{
         current?: string;

package/dist/control/upload-store.d.ts

@@ -0,0 +1,28 @@
+export interface UploadStoreOptions {
+    rootDir?: string;
+    maxBytes?: number;
+    ttlMs?: number;
+    now?: () => Date;
+}
+export interface SavedUpload {
+    id: string;
+    path: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+}
+/** Strip directory components and traversal segments, leaving a safe basename. */
+export declare function sanitizeUploadFilename(raw: string): string;
+export declare class UploadStore {
+    private readonly rootDir;
+    private readonly maxBytes;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(opts?: UploadStoreOptions);
+    /** Sandbox root all uploads are written under. Callers may use this to verify a
+     *  media filePath actually originated from a control.upload (defense-in-depth). */
+    get root(): string;
+    save(filename: string, base64: string, mimeType: string): Promise<SavedUpload>;
+    /** Remove upload dirs whose mtime is older than the TTL. Returns count removed. */
+    cleanup(): Promise<number>;
+}

package/dist/transport/types.d.ts

@@ -3,6 +3,37 @@ import type { QuotaManager } from "../weixin/messaging/quota-manager.js";
 import type { PlanEntry, ToolUseEvent } from "../channels/types.js";
 import type { ToolEventMode } from "./tool-event-mode.js";
 export type { ToolEventMode } from "./tool-event-mode.js";
+/** Cumulative session cost the agent reported (ACP `usage_update.cost`). Both optional. */
+export interface UsageCost {
+    amount?: number;
+    currency?: string;
+}
+/**
+ * Per-turn token breakdown from ACP `usage_update._meta.usage` (Claude reports it;
+ * codex may omit). All fields optional — treat missing as "unknown", not zero.
+ */
+export interface UsageBreakdown {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedReadTokens?: number;
+    cachedWriteTokens?: number;
+    thoughtTokens?: number;
+    totalTokens?: number;
+}
+/** Context-usage side-channel payload: window fill plus optional cost & token breakdown. */
+export interface PromptUsage {
+    used: number;
+    size: number;
+    cost?: UsageCost;
+    breakdown?: UsageBreakdown;
+}
+/** An agent-advertised slash command (ACP `available_commands_update`). */
+export interface AgentCommand {
+    name: string;
+    description?: string;
+    /** Whether the command accepts an argument (ACP advertised a non-null `input`). */
+    hasInput?: boolean;
+}
 export interface ReplyQuotaContext {
     chatKey: string;
     quota: QuotaManager;
@@ -125,10 +156,12 @@ export interface PromptOptions {
      * scalar (re-sent during a turn). Optional — only agents that report it fire this
      * (e.g. claude does, codex does not), and text channels omit the handler.
      */
-    onUsage?: (usage: {
-        used: number;
-        size: number;
-    }) => void | Promise<void>;
+    onUsage?: (usage: PromptUsage) => void | Promise<void>;
+    /**
+     * Agent-advertised slash commands (ACP `available_commands_update`). Replace-latest
+     * list, re-sent when the agent updates it. Optional — not every adapter advertises.
+     */
+    onCommands?: (commands: AgentCommand[]) => void | Promise<void>;
     /**
      * How tool_call / tool_call_update events are surfaced for this prompt.
      *

package/dist/weixin/agent/interface.d.ts

@@ -1,5 +1,6 @@
 import type { ChannelMediaAttachment, OutboundChannelMedia } from "../../channels/media-types.js";
 import type { PlanEntry, ScheduledSessionDescriptor, ToolUseEvent } from "../../channels/types.js";
+import type { AgentCommand, PromptUsage } from "../../transport/types.js";
 import type { PerfSpan } from "../../perf/perf-tracer.js";
 /**
  * Agent interface — any AI backend that can handle a chat message.
@@ -51,10 +52,9 @@ export interface ChatRequest {
     /** Structured plan/todo side-channel; see PromptOptions.onPlan. */
     onPlan?: (entries: PlanEntry[]) => void | Promise<void>;
     /** Context-usage side-channel; see PromptOptions.onUsage. */
-    onUsage?: (usage: {
-        used: number;
-        size: number;
-    }) => void | Promise<void>;
+    onUsage?: (usage: PromptUsage) => void | Promise<void>;
+    /** Agent-advertised slash commands; see PromptOptions.onCommands. */
+    onCommands?: (commands: AgentCommand[]) => void | Promise<void>;
     /**
      * Optional per-turn performance tracing span. When `logging.perf.enabled` is
      * true, the channel handler attaches a `PerfSpan` so downstream layers can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganglion/xacpx",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "随时随地通过聊天频道（微信 / 飞书 / 元宝等）远程控制 `acpx` 上的 Claude Code、Codex 等 Agents。",
   "keywords": [
     "acpx",
@@ -85,7 +85,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "acpx": "^0.9.0",
+    "acpx": "^0.11.0",
     "node-pty": "^1.1.0",
     "proper-lockfile": "^4.1.2",
     "protobufjs": "^7.5.6",