@ganglion/xacpx 0.13.0 → 0.14.1

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;
@@ -46,6 +54,8 @@ export type ControlEvent = {
     cancelled?: boolean;
 } | {
     type: "sessions-changed";
+} | {
+    type: "workspaces-changed";
 } | {
     type: "scheduled-changed";
     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/i18n/types.d.ts

@@ -809,6 +809,7 @@ export interface MiscMessages {
     defaultHomeWorkspaceDescription: string;
     pluginChannelFeishu: string;
     pluginChannelYuanbao: string;
+    pluginChannelRelay: string;
     pluginChannelInstallHint: (channelType: string, packageName: string) => string;
     orchestrationSuggestion1: string;
     orchestrationSuggestion2: string;

package/dist/plugin-api.js

@@ -1050,6 +1050,7 @@ var init_misc = __esm(() => {
     defaultHomeWorkspaceDescription: "Home directory",
     pluginChannelFeishu: "Feishu channel",
     pluginChannelYuanbao: "Tencent Yuanbao channel",
+    pluginChannelRelay: "Relay hub connector (drive this instance from a self-hosted relay hub)",
     pluginChannelInstallHint: (channelType, packageName) => `Channel ${channelType} requires a plugin: xacpx plugin add ${packageName}`,
     orchestrationSuggestion1: "Run /tasks --stuck to locate stuck tasks",
     orchestrationSuggestion2: "/task <id> shows the full timeline to locate errors",
@@ -2146,6 +2147,7 @@ var init_misc2 = __esm(() => {
     defaultHomeWorkspaceDescription: "用户主目录",
     pluginChannelFeishu: "飞书频道",
     pluginChannelYuanbao: "腾讯元宝频道",
+    pluginChannelRelay: "Relay hub 连接器（从自托管 relay hub 遥控这台实例）",
     pluginChannelInstallHint: (channelType, packageName) => `频道 ${channelType} 需要安装插件：xacpx plugin add ${packageName}`,
     orchestrationSuggestion1: "查看 /tasks --stuck 定位卡住的任务",
     orchestrationSuggestion2: "/task <id> 可看完整时间线定位错误点",

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.1",
   "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",