@ganglion/xacpx 0.11.0 → 0.12.0

package/dist/bridge/bridge-main.js

@@ -68,6 +68,10 @@ function encodeBridgePromptPlanEvent(event) {
   return `${JSON.stringify(event)}
 `;
 }
+function encodeBridgePromptUsageEvent(event) {
+  return `${JSON.stringify(event)}
+`;
+}
 function encodeBridgeSessionProgressEvent(event) {
   return `${JSON.stringify(event)}
 `;
@@ -424,6 +428,7 @@ function createStreamingPromptState(formatToolCalls = false, options) {
   let onToolEvent;
   let onThought;
   let onPlan;
+  let onUsage;
   let rawStream = false;
   if (options === undefined) {
     toolEventMode = "text";
@@ -435,6 +440,7 @@ function createStreamingPromptState(formatToolCalls = false, options) {
     onToolEvent = options.onToolEvent;
     onThought = options.onThought;
     onPlan = options.onPlan;
+    onUsage = options.onUsage;
     rawStream = options.rawStream ?? false;
     toolEventMode = resolveToolEventMode({
       toolEventMode: options.mode,
@@ -453,6 +459,7 @@ function createStreamingPromptState(formatToolCalls = false, options) {
     onToolEvent,
     onThought,
     onPlan,
+    onUsage,
     finalize() {
       if (this.pendingLine.trim().length > 0) {
         parseStreamingChunks(this, this.pendingLine);
@@ -517,6 +524,13 @@ function parseStreamingChunks(state, line) {
       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;
@@ -3989,7 +4003,8 @@ async function runStreamingPrompt(command, args, onEvent, options = {}) {
       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 ? { onPlan: (entries) => onEvent({ type: "prompt.plan", entries }) } : {}
+      ...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 = () => {
@@ -4280,6 +4295,13 @@ class BridgeServer {
               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":

package/dist/cli.js

@@ -22355,7 +22355,7 @@ async function handleSessionRemove(context, chatKey, alias) {
   return { text: lines.join(`
 `) };
 }
-async function promptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan) {
+async function promptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage) {
   const effectiveReplyMode = resolveEffectiveReplyMode(context.config, chatKey, session3.replyMode);
   if (!session3.replyMode)
     session3.replyMode = effectiveReplyMode;
@@ -22387,7 +22387,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);
+    const result = await context.interaction.promptTransportSession(session3, promptText, transportReply, replyContext, media, abortSignal, onToolEvent, onThought, perfSpan, onPlan, onUsage);
     if (claimHumanReply) {
       try {
         await context.orchestration?.claimActiveHumanReply?.(claimHumanReply);
@@ -22407,23 +22407,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) {
+async function handlePromptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage) {
   try {
-    return await promptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan);
+    return await promptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage);
   } 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);
+      return await promptWithSession(context, recovered, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage);
     }
     return context.recovery.renderTransportError(session3, error2);
   }
 }
-async function handlePrompt(context, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan) {
+async function handlePrompt(context, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage) {
   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);
+  return await handlePromptWithSession(context, session3, chatKey, text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage);
 }
 function toCoordinatorRouteChatMetadata(metadata) {
   if (!metadata) {
@@ -24682,7 +24682,7 @@ class CommandRouter {
     this.logger = logger2 ?? createNoopAppLogger();
     this.activeTurns = activeTurns;
   }
-  async handle(chatKey, input, reply, replyContextToken, accountId, media, metadata, abortSignal, onToolEvent, onThought, perfSpan, onPlan) {
+  async handle(chatKey, input, reply, replyContextToken, accountId, media, metadata, abortSignal, onToolEvent, onThought, perfSpan, onPlan, onUsage) {
     const startedAt = Date.now();
     let command = parseCommand(input);
     if (metadata?.channel === "control" && command.kind !== "prompt") {
@@ -24842,16 +24842,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);
+            return await handlePromptWithSession(sessionContext, transientSession, chatKey, command.text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage);
           }
           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);
+            return await handlePromptWithSession(sessionContext, scheduledSession, 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);
+          return await handlePrompt(sessionContext, chatKey, command.text, reply, replyContextToken, accountId, media, abortSignal, onToolEvent, onThought, perfSpan, metadata, onPlan, onUsage);
         }
       }
     });
@@ -24999,7 +24999,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) => this.promptTransportSession(session3, text, reply, replyContext, media, abortSignal, onToolEvent, onThought, perfSpanOverride ?? perfSpan, onPlan)
+      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)
     };
   }
   createSessionRenderRecoveryOps() {
@@ -25178,7 +25178,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) {
+  async promptTransportSession(session3, text, reply, replyContext, media, abortSignal, onToolEvent, onThought, perfSpan, onPlan, onUsage) {
     session3.mcpCoordinatorSession ??= stableCoordinatorSession(session3.transportSession);
     let done = false;
     let abortRequested = false;
@@ -25236,7 +25236,8 @@ class CommandRouter {
         ...reply ? { onSegment } : {},
         ...onToolEvent ? { onToolEvent } : {},
         ...onThought ? { onThought } : {},
-        ...onPlan ? { onPlan } : {}
+        ...onPlan ? { onPlan } : {},
+        ...onUsage ? { onUsage } : {}
       }));
     } catch (error2) {
       localOutcome = isAbortError2(error2) || abortRequested ? "aborted" : "error";
@@ -25422,7 +25423,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);
+    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);
   }
   isKnownCommand(text) {
     return isKnownXacpxCommandText(text);
@@ -30478,6 +30479,10 @@ function encodeBridgePromptPlanEvent(event) {
   return `${JSON.stringify(event)}
 `;
 }
+function encodeBridgePromptUsageEvent(event) {
+  return `${JSON.stringify(event)}
+`;
+}
 function encodeBridgeSessionProgressEvent(event) {
   return `${JSON.stringify(event)}
 `;
@@ -30780,6 +30785,12 @@ class AcpxBridgeClient {
           type: "prompt.plan",
           entries: message.entries
         });
+      } else if (message.event === "prompt.usage") {
+        pending.onEvent?.({
+          type: "prompt.usage",
+          used: message.used,
+          size: message.size
+        });
       } else if (message.event === "session.progress") {
         pending.onEvent?.({
           type: "session.progress",
@@ -31239,6 +31250,8 @@ class AcpxBridgeTransport {
     let thoughtChain = Promise.resolve();
     let planError;
     let planChain = Promise.resolve();
+    let usageError;
+    let usageChain = Promise.resolve();
     let toolEventMode = resolveToolEventMode(options);
     if ((toolEventMode === "structured" || toolEventMode === "both") && !options?.onToolEvent) {
       toolEventMode = "text";
@@ -31291,11 +31304,22 @@ class AcpxBridgeTransport {
         }
         return;
       }
+      if (event.type === "prompt.usage") {
+        const onUsage = options?.onUsage;
+        if (onUsage) {
+          const usage = { used: event.used, size: event.size };
+          usageChain = usageChain.then(() => onUsage(usage)).catch((error2) => {
+            usageError ??= error2;
+          });
+        }
+        return;
+      }
     });
     await segmentChain;
     await toolEventChain;
     await thoughtChain;
     await planChain;
+    await usageChain;
     if (sink) {
       const { overflowCount } = sink.finalize();
       await sink.drain({ timeoutMs: 30000 });
@@ -31316,6 +31340,9 @@ class AcpxBridgeTransport {
       if (planError) {
         throw planError;
       }
+      if (usageError) {
+        throw usageError;
+      }
       return { text: summary ? `${summary}
 
 ${result.text}` : "" };
@@ -31332,6 +31359,9 @@ ${result.text}` : "" };
     if (planError) {
       throw planError;
     }
+    if (usageError) {
+      throw usageError;
+    }
     return result;
   }
   async setMode(session3, modeId) {
@@ -31537,6 +31567,7 @@ function createStreamingPromptState(formatToolCalls = false, options) {
   let onToolEvent;
   let onThought;
   let onPlan;
+  let onUsage;
   let rawStream = false;
   if (options === undefined) {
     toolEventMode = "text";
@@ -31548,6 +31579,7 @@ function createStreamingPromptState(formatToolCalls = false, options) {
     onToolEvent = options.onToolEvent;
     onThought = options.onThought;
     onPlan = options.onPlan;
+    onUsage = options.onUsage;
     rawStream = options.rawStream ?? false;
     toolEventMode = resolveToolEventMode({
       toolEventMode: options.mode,
@@ -31566,6 +31598,7 @@ function createStreamingPromptState(formatToolCalls = false, options) {
     onToolEvent,
     onThought,
     onPlan,
+    onUsage,
     finalize() {
       if (this.pendingLine.trim().length > 0) {
         parseStreamingChunks(this, this.pendingLine);
@@ -31630,6 +31663,13 @@ function parseStreamingChunks(state, line) {
       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;
@@ -33259,7 +33299,29 @@ class WorkspaceFs {
       }
     }
     const truncated = diff.length > DIFF_CAP;
-    return { workspace: workspace3, files, diff: truncated ? diff.slice(0, DIFF_CAP) : diff, truncated };
+    return { workspace: workspace3, files, diff: truncated ? diff.slice(0, DIFF_CAP) : diff, truncated, ...await this.gitContext(root) };
+  }
+  async gitContext(root) {
+    const run = async (...args) => {
+      try {
+        return (await execFileAsync("git", ["-C", root, ...args], { maxBuffer: GIT_MAX_BUFFER })).stdout.trim();
+      } catch {
+        return null;
+      }
+    };
+    const ctx = {};
+    const head = await run("rev-parse", "--abbrev-ref", "HEAD");
+    if (head === "HEAD")
+      ctx.detached = true;
+    else if (head)
+      ctx.branch = head;
+    const top = await run("rev-parse", "--show-toplevel");
+    if (top) {
+      const gitDir = await run("rev-parse", "--absolute-git-dir");
+      const commonDir = await run("rev-parse", "--path-format=absolute", "--git-common-dir");
+      ctx.worktree = { root: top, linked: !!gitDir && !!commonDir && gitDir !== commonDir };
+    }
+    return ctx;
   }
 }
 var execFileAsync, MAX_ENTRIES = 2000, FILE_READ_CAP, DIFF_CAP, GIT_MAX_BUFFER, SEARCH_MAX_RESULTS = 200, SEARCH_MAX_SCAN = 20000, SEARCH_SKIP_DIRS;
@@ -33526,6 +33588,15 @@ ${chunk}` : chunk
             sessionAlias: params.sessionAlias,
             entries
           });
+        },
+        onUsage: (usage) => {
+          this.deps.events.emit({
+            type: "turn-usage",
+            chatKey: params.chatKey,
+            sessionAlias: params.sessionAlias,
+            used: usage.used,
+            size: usage.size
+          });
         }
       });
       if (response.text) {

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

@@ -38,5 +38,11 @@ export declare function handleCancel(context: SessionHandlerContext, chatKey: st
 export declare function handleSessionReset(context: SessionHandlerContext, chatKey: string): Promise<RouterResponse>;
 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 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>): 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>): 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>;

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

@@ -113,7 +113,10 @@ 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>) => 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: {
+        used: number;
+        size: number;
+    }) => void | Promise<void>) => Promise<{
         text: string;
     }>;
 }

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

@@ -31,6 +31,12 @@ export type ControlEvent = {
     chatKey: string;
     sessionAlias: string;
     entries: PlanEntry[];
+} | {
+    type: "turn-usage";
+    chatKey: string;
+    sessionAlias: string;
+    used: number;
+    size: number;
 } | {
     type: "turn-finished";
     chatKey: string;

package/dist/control/workspace-fs.d.ts

@@ -31,6 +31,15 @@ export interface WorkspaceDiff {
     files: DiffFile[];
     diff: string;
     truncated: boolean;
+    /** Symbolic branch name (abbrev-ref HEAD); omitted when HEAD is detached. */
+    branch?: string;
+    /** True when HEAD is detached (no branch). */
+    detached?: boolean;
+    /** Working-tree context: its top-level root, and whether it's a linked (non-primary) worktree. */
+    worktree?: {
+        root: string;
+        linked: boolean;
+    };
 }
 export interface WorkspaceRef {
     name: string;
@@ -49,4 +58,7 @@ export declare class WorkspaceFs {
      *  (so it stays contained), bounded by a scan budget and a result cap. */
     search(workspace: string, query: string): Promise<SearchResult>;
     gitDiff(workspace: string, relPath?: string): Promise<WorkspaceDiff>;
+    /** Branch + worktree context for a repo root. Best-effort: any git hiccup just
+     *  omits the fields so the diff itself still returns. */
+    private gitContext;
 }

package/dist/transport/types.d.ts

@@ -114,6 +114,16 @@ export interface PromptOptions {
      * re-sent on every update (REPLACE, not append). Optional — text channels omit it.
      */
     onPlan?: (entries: PlanEntry[]) => void | Promise<void>;
+    /**
+     * Context-usage side-channel: the agent's ACP `usage_update` — `used` tokens
+     * currently in context and `size`, the model's total context window. Replace-latest
+     * 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>;
     /**
      * How tool_call / tool_call_update events are surfaced for this prompt.
      *

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

@@ -50,6 +50,11 @@ export interface ChatRequest {
     onThought?: (chunk: string) => void | Promise<void>;
     /** 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>;
     /**
      * 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.11.0",
+  "version": "0.12.0",
   "description": "随时随地通过聊天频道（微信 / 飞书 / 元宝等）远程控制 `acpx` 上的 Claude Code、Codex 等 Agents。",
   "keywords": [
     "acpx",