weacpx 0.6.0 → 0.7.0

package/dist/plugin-api.js

@@ -171,9 +171,166 @@ var init_types = __esm(() => {
   init_compatibility();
 });
 
+// src/runtime/conversation-executor.ts
+function createConversationExecutor() {
+  const states = new Map;
+  const getState = (conversationId) => {
+    const existing = states.get(conversationId);
+    if (existing)
+      return existing;
+    const created = { normalTails: new Map, activeControls: 0 };
+    states.set(conversationId, created);
+    return created;
+  };
+  const cleanupState = (conversationId, state) => {
+    if (state.normalTails.size === 0 && state.activeControls === 0) {
+      states.delete(conversationId);
+    }
+  };
+  return {
+    run(conversationId, lane, task, sessionKey) {
+      const state = getState(conversationId);
+      if (lane === "control") {
+        state.activeControls += 1;
+        return Promise.resolve().then(task).finally(() => {
+          state.activeControls -= 1;
+          cleanupState(conversationId, state);
+        });
+      }
+      const key = sessionKey ?? DEFAULT_SESSION_KEY;
+      const previous = state.normalTails.get(key) ?? Promise.resolve();
+      const next = previous.then(() => task(), () => task());
+      state.normalTails.set(key, next);
+      return next.finally(() => {
+        if (state.normalTails.get(key) === next) {
+          state.normalTails.delete(key);
+        }
+        cleanupState(conversationId, state);
+      });
+    }
+  };
+}
+var DEFAULT_SESSION_KEY = "__chat__";
+
+// src/sessions/active-turn-registry.ts
+function createActiveTurnRegistry() {
+  const byChat = new Map;
+  return {
+    markActive(chatKey, alias) {
+      const set = byChat.get(chatKey) ?? new Set;
+      set.add(alias);
+      byChat.set(chatKey, set);
+    },
+    markInactive(chatKey, alias) {
+      const set = byChat.get(chatKey);
+      if (!set)
+        return;
+      set.delete(alias);
+      if (set.size === 0)
+        byChat.delete(chatKey);
+    },
+    isActive(chatKey, alias) {
+      return byChat.get(chatKey)?.has(alias) ?? false;
+    }
+  };
+}
+
+// src/channels/channel-scope.ts
+function registerKnownChannelId(channelId) {
+  const normalized = channelId.trim();
+  if (!normalized || normalized.includes(":")) {
+    throw new Error("channel id must be non-empty and must not contain ':'");
+  }
+  KNOWN_CHANNEL_IDS.add(normalized);
+}
+function listKnownChannelIds() {
+  return Array.from(KNOWN_CHANNEL_IDS);
+}
+function getChannelIdFromChatKey(chatKey) {
+  const first = chatKey.split(":", 1)[0];
+  return first && KNOWN_CHANNEL_IDS.has(first) ? first : "weixin";
+}
+function toInternalSessionAlias(channelId, displayAlias) {
+  const normalized = displayAlias.trim();
+  if (normalized.length === 0) {
+    throw new Error("display session alias must be non-empty");
+  }
+  if (normalized.startsWith(`${channelId}:`)) {
+    return normalized;
+  }
+  return `${channelId}:${normalized}`;
+}
+function toDisplaySessionAlias(internalAlias) {
+  const [first, ...rest] = internalAlias.split(":");
+  if (first && KNOWN_CHANNEL_IDS.has(first) && rest.length > 0) {
+    return rest.join(":");
+  }
+  return internalAlias;
+}
+function isSessionAliasVisibleInChannel(alias, channelId) {
+  const [first] = alias.split(":", 1);
+  if (first && KNOWN_CHANNEL_IDS.has(first)) {
+    return first === channelId;
+  }
+  return channelId === "weixin";
+}
+function resolveSessionAliasForInput(channelId, displayAlias, existingAliases) {
+  const normalized = displayAlias.trim();
+  if (normalized.length === 0) {
+    throw new Error("display session alias must be non-empty");
+  }
+  if (normalized.startsWith(`${channelId}:`)) {
+    return normalized;
+  }
+  const scopedAlias = toInternalSessionAlias(channelId, normalized);
+  for (const alias of existingAliases) {
+    if (alias === scopedAlias)
+      return scopedAlias;
+  }
+  if (channelId === "weixin") {
+    for (const alias of existingAliases) {
+      if (alias === normalized)
+        return alias;
+    }
+  }
+  return scopedAlias;
+}
+function scopeDisplayAliasToInternal(channelId, displayAlias) {
+  const normalized = displayAlias.trim();
+  if (normalized.length === 0) {
+    throw new Error("display session alias must be non-empty");
+  }
+  return channelId === "weixin" ? normalized : toInternalSessionAlias(channelId, normalized);
+}
+function buildDefaultTransportSession(channelId, displayAlias) {
+  const normalized = displayAlias.trim();
+  if (normalized.length === 0) {
+    throw new Error("display session alias must be non-empty");
+  }
+  return channelId === "weixin" ? normalized : toInternalSessionAlias(channelId, normalized);
+}
+var KNOWN_CHANNEL_IDS;
+var init_channel_scope = __esm(() => {
+  KNOWN_CHANNEL_IDS = new Set(["weixin"]);
+});
+
 // src/plugin-api.ts
 init_types();
+
+// src/runtime/turn-lane.ts
+var CONTROL_COMMANDS = new Set(["/use", "/ss", "/cancel", "/stop"]);
+function resolveTurnLane(text) {
+  const command = text.trim().toLowerCase().split(/\s+/)[0] ?? "";
+  return CONTROL_COMMANDS.has(command) ? "control" : "normal";
+}
+
+// src/plugin-api.ts
+init_channel_scope();
 export {
+  toDisplaySessionAlias,
+  resolveTurnLane,
+  createConversationExecutor,
+  createActiveTurnRegistry,
   WEACPX_PLUGIN_MIN_CORE_VERSION,
   WEACPX_PLUGIN_API_VERSION,
   WEACPX_PLUGIN_API_SUPPORTED_VERSIONS

package/dist/{weixin/messaging → runtime}/conversation-executor.d.ts

@@ -1,7 +1,7 @@
 export type ConversationExecutorLane = "normal" | "control";
 type ConversationTask<T> = () => Promise<T>;
 export type ConversationExecutor = {
-    run<T>(conversationId: string, lane: ConversationExecutorLane, task: ConversationTask<T>): Promise<T>;
+    run<T>(conversationId: string, lane: ConversationExecutorLane, task: ConversationTask<T>, sessionKey?: string): Promise<T>;
 };
 export declare function createConversationExecutor(): ConversationExecutor;
 export {};

package/dist/runtime/core-home.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The per-user state directory name (`<home>/.weacpx/`). This is the SINGLE
+ * source of truth for that name; every config / state / runtime / plugin path
+ * is built on top of it.
+ *
+ * The weacpx→xacpx rename (0.8.0) changes the name HERE — and adds any
+ * legacy-directory fallback inside {@link coreHomeDir} (e.g. prefer
+ * `~/.xacpx`, fall back to an existing `~/.weacpx`) — so the whole tree of
+ * derived paths follows from one place rather than ~11 scattered literals.
+ */
+export declare const CORE_HOME_DIR_NAME = ".weacpx";
+/**
+ * The core state root for a given user home: `<home>/.weacpx`.
+ *
+ * Pass the home directory the caller already resolved — this helper imposes no
+ * home-resolution policy of its own, so each caller's existing semantics are
+ * preserved (this is a pure refactor of the directory-name literal). It is the
+ * one function the 0.8.0 rename hooks into.
+ */
+export declare function coreHomeDir(home: string): string;
+/**
+ * Display form for user-facing hints (e.g. "请查看日志：~/.weacpx/runtime/...").
+ * Keeps printed paths single-sourced with the real directory name. Always uses
+ * "/" separators since it is for display, not filesystem access.
+ */
+export declare function coreHomeDisplayPath(...segments: string[]): string;

package/dist/runtime/turn-lane.d.ts

@@ -0,0 +1,2 @@
+import type { ConversationExecutorLane } from "./conversation-executor.js";
+export declare function resolveTurnLane(text: string): ConversationExecutorLane;

package/dist/scheduled/parse-later-time.d.ts

@@ -0,0 +1,11 @@
+export type LaterTimeParseErrorCode = "missing_time" | "unrecognized_time" | "missing_message" | "past_today_time" | "too_soon" | "out_of_range";
+export type LaterTimeParseResult = {
+    ok: true;
+    executeAt: Date;
+    messageStartIndex: number;
+} | {
+    ok: false;
+    code: LaterTimeParseErrorCode;
+    value?: string;
+};
+export declare function parseLaterTime(tokens: string[], now?: Date): LaterTimeParseResult;

package/dist/scheduled/scheduled-render.d.ts

@@ -0,0 +1,7 @@
+import type { ScheduledTaskRecord } from "./scheduled-types";
+export declare function renderLaterHelp(): string;
+export declare function renderLaterUnsupportedChannel(): string;
+export declare function renderTaskCreated(task: ScheduledTaskRecord, displaySession: string): string;
+export declare function renderLaterList(tasks: ScheduledTaskRecord[], displaySession: (internalAlias: string) => string): string;
+export declare function preview(text: string): string;
+export declare function formatLocalDateTime(date: Date): string;

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

@@ -0,0 +1,41 @@
+import { AsyncMutex } from "../orchestration/async-mutex";
+import type { StateStore } from "../state/state-store";
+import type { AppState } from "../state/types";
+import type { ScheduledSessionMode, ScheduledTaskRecord } from "./scheduled-types";
+export interface CreateScheduledTaskInput {
+    chatKey: string;
+    sessionAlias: string;
+    executeAt: Date;
+    message: string;
+    sessionMode?: ScheduledSessionMode;
+    agent?: string;
+    workspace?: string;
+    accountId?: string;
+    replyContextToken?: string;
+    sourceLabel?: string;
+}
+export interface ScheduledTaskServiceOptions {
+    now?: () => Date;
+    generateId?: () => string;
+    stateMutex?: AsyncMutex;
+}
+export declare class ScheduledTaskService {
+    private readonly state;
+    private readonly stateStore;
+    private readonly now;
+    private readonly generateId;
+    private readonly stateMutex;
+    private readonly claimedInThisSession;
+    constructor(state: AppState, stateStore: Pick<StateStore, "save">, options?: ScheduledTaskServiceOptions);
+    createTask(input: CreateScheduledTaskInput): Promise<ScheduledTaskRecord>;
+    listPending(): ScheduledTaskRecord[];
+    cancelPending(inputId: string): Promise<boolean>;
+    markStartupMissed(): Promise<void>;
+    claimDueTasks(): Promise<ScheduledTaskRecord[]>;
+    markExecuted(id: string): Promise<void>;
+    markFailed(id: string, error: unknown): Promise<void>;
+    private nextId;
+    private mutate;
+    private save;
+}
+export declare function normalizeId(input: string): string;

package/dist/scheduled/scheduled-types.d.ts

@@ -0,0 +1,29 @@
+export declare const LATER_MIN_DELAY_MS = 10000;
+export declare const LATER_MAX_DELAY_MS: number;
+export declare const LATER_MESSAGE_PREVIEW_CHARS = 120;
+export type ScheduledTaskStatus = "pending" | "triggering" | "executed" | "cancelled" | "missed" | "failed";
+export type ScheduledSessionMode = "temp" | "bound";
+export interface ScheduledTaskRecord {
+    id: string;
+    chat_key: string;
+    session_alias: string;
+    /** Absent ⇒ "bound" (legacy tasks created before temp mode existed). */
+    session_mode?: ScheduledSessionMode;
+    /** Agent snapshot at creation; only set for "temp" tasks. */
+    agent?: string;
+    /** Workspace snapshot at creation; only set for "temp" tasks. */
+    workspace?: string;
+    execute_at: string;
+    message: string;
+    status: ScheduledTaskStatus;
+    created_at: string;
+    account_id?: string;
+    reply_context_token?: string;
+    source_label?: string;
+    triggered_at?: string;
+    executed_at?: string;
+    cancelled_at?: string;
+    missed_at?: string;
+    failed_at?: string;
+    last_error?: string;
+}

package/dist/sessions/active-turn-registry.d.ts

@@ -0,0 +1,6 @@
+export interface ActiveTurnRegistry {
+    markActive(chatKey: string, alias: string): void;
+    markInactive(chatKey: string, alias: string): void;
+    isActive(chatKey: string, alias: string): boolean;
+}
+export declare function createActiveTurnRegistry(): ActiveTurnRegistry;

package/dist/sessions/session-service.d.ts

@@ -0,0 +1,118 @@
+import type { AppConfig } from "../config/types";
+import { AsyncMutex } from "../orchestration/async-mutex";
+import type { StateStore } from "../state/state-store";
+import type { AppState, BackgroundResult } from "../state/types";
+import type { AgentSession, ResolvedSession } from "../transport/types";
+interface SessionListItem {
+    alias: string;
+    internalAlias: string;
+    agent: string;
+    workspace: string;
+    isCurrent: boolean;
+}
+export interface SessionSwitchResult {
+    alias: string;
+    agent: string;
+    workspace: string;
+    previousAlias?: string;
+}
+export type FuzzyAliasResult = {
+    kind: "match";
+    alias: string;
+} | {
+    kind: "ambiguous";
+    candidates: Array<{
+        alias: string;
+        agent: string;
+        workspace: string;
+    }>;
+} | {
+    kind: "none";
+};
+interface NativeSessionAttachmentInput {
+    alias: string;
+    agent: string;
+    workspace: string;
+    transportSession: string;
+    transportAgentCommand?: string;
+    agentSessionId: string;
+    title?: string | null;
+    updatedAt?: string;
+}
+interface NativeSessionListInput {
+    agent: string;
+    workspace?: string;
+    cwd: string;
+    sessions: AgentSession[];
+    nextCursor?: string | null;
+}
+interface NativeSessionListResult {
+    agent: string;
+    workspace?: string;
+    cwd: string;
+    sessions: AgentSession[];
+    nextCursor?: string | null;
+}
+interface SessionServiceOptions {
+    stateMutex?: AsyncMutex;
+    now?: () => number;
+}
+export declare class SessionService {
+    private readonly config;
+    private readonly stateStore;
+    private readonly state;
+    private readonly stateMutex;
+    private readonly now;
+    constructor(config: AppConfig, stateStore: Pick<StateStore, "save">, state: AppState, options?: SessionServiceOptions);
+    createSession(alias: string, agent: string, workspace: string): Promise<ResolvedSession>;
+    /**
+     * All currently-known logical sessions resolved to transport sessions, deduped by
+     * transport session. Sessions whose agent or workspace is no longer registered are
+     * skipped (toResolvedSession would throw). Used by shutdown cleanup to reap warm
+     * acpx queue owners; never throws.
+     */
+    listAllResolvedSessions(): ResolvedSession[];
+    resolveSession(alias: string, agent: string, workspace: string, transportSession: string): ResolvedSession;
+    attachSession(alias: string, agent: string, workspace: string, transportSession: string, transportAgentCommand?: string): Promise<ResolvedSession>;
+    attachNativeSession(input: NativeSessionAttachmentInput): Promise<ResolvedSession>;
+    getSession(alias: string): Promise<ResolvedSession | null>;
+    /**
+     * Synchronously resolve a session by its internal alias (as stored in state).
+     * Returns null if the alias is unknown or if the referenced agent/workspace is
+     * no longer registered (i.e. toResolvedSession would throw).
+     *
+     * Used by handlePrompt to honour a `boundSessionAlias` captured at dispatch
+     * time without requiring an async state mutation.
+     */
+    getResolvedSessionByInternalAlias(alias: string): ResolvedSession | null;
+    peekCurrentSessionAlias(chatKey: string): string | undefined;
+    getPreferredSessionForTransport(transportSession: string): Promise<ResolvedSession | null>;
+    findAttachedNativeSession(chatKey: string, agent: string, agentSessionId: string): Promise<ResolvedSession | null>;
+    useSession(chatKey: string, alias: string): Promise<SessionSwitchResult>;
+    usePreviousSession(chatKey: string): Promise<SessionSwitchResult | null>;
+    setBackgroundResult(chatKey: string, alias: string, result: BackgroundResult): Promise<void>;
+    takeBackgroundResult(chatKey: string, alias: string): Promise<BackgroundResult | null>;
+    listBackgroundResultAliases(chatKey: string): string[];
+    resolveFuzzyAlias(chatKey: string, fragment: string): FuzzyAliasResult;
+    resolveAliasForChat(chatKey: string, displayAlias: string): Promise<string>;
+    buildDefaultTransportSessionForChat(chatKey: string, displayAlias: string): string;
+    listInternalAliases(): string[];
+    setCurrentSessionMode(chatKey: string, modeId: string | undefined): Promise<void>;
+    setCurrentSessionReplyMode(chatKey: string, replyMode: "stream" | "final" | "verbose" | undefined): Promise<void>;
+    getCurrentSession(chatKey: string): Promise<ResolvedSession | null>;
+    listSessions(chatKey: string): Promise<SessionListItem[]>;
+    countAliasesSharingTransport(transportSession: string, excludeAlias?: string): number;
+    removeSession(alias: string): Promise<{
+        wasActive: boolean;
+    }>;
+    cacheNativeSessionList(chatKey: string, input: NativeSessionListInput): Promise<void>;
+    getNativeSessionList(chatKey: string, ttlMs?: number): Promise<NativeSessionListResult | null>;
+    private deleteNativeSessionListIfCurrent;
+    private toResolvedSession;
+    setSessionTransportAgentCommand(alias: string, transportAgentCommand: string | undefined): Promise<void>;
+    private mutate;
+    private persist;
+    private createLogicalSession;
+    private validateSession;
+}
+export {};

package/dist/state/state-store.d.ts

@@ -0,0 +1,8 @@
+import { type AppState } from "./types";
+export declare function parseState(raw: unknown, path: string): AppState;
+export declare class StateStore {
+    private readonly path;
+    constructor(path: string);
+    load(): Promise<AppState>;
+    save(state: AppState): Promise<void>;
+}

package/dist/state/types.d.ts

@@ -0,0 +1,51 @@
+import { type OrchestrationState } from "../orchestration/orchestration-types";
+import type { ScheduledTaskRecord } from "../scheduled/scheduled-types";
+export type LogicalSessionSource = "weacpx" | "agent-side";
+export interface NativeSessionCacheEntry {
+    session_id: string;
+    cwd?: string;
+    title?: string | null;
+    updated_at?: string;
+}
+export interface NativeSessionListCacheRecord {
+    created_at: string;
+    agent: string;
+    workspace?: string;
+    cwd: string;
+    sessions: NativeSessionCacheEntry[];
+    next_cursor?: string | null;
+}
+export interface LogicalSession {
+    alias: string;
+    agent: string;
+    workspace: string;
+    transport_session: string;
+    source?: LogicalSessionSource;
+    agent_session_id?: string;
+    agent_session_title?: string;
+    agent_session_updated_at?: string;
+    attached_at?: string;
+    transport_agent_command?: string;
+    mode_id?: string;
+    reply_mode?: "stream" | "final" | "verbose";
+    created_at: string;
+    last_used_at: string;
+}
+export interface BackgroundResult {
+    text: string;
+    status: "done" | "error";
+    finished_at: string;
+}
+export interface ChatContextState {
+    current_session: string;
+    previous_session?: string;
+    background_results?: Record<string, BackgroundResult>;
+}
+export interface AppState {
+    sessions: Record<string, LogicalSession>;
+    chat_contexts: Record<string, ChatContextState>;
+    native_session_lists: Record<string, NativeSessionListCacheRecord>;
+    orchestration: OrchestrationState;
+    scheduled_tasks: Record<string, ScheduledTaskRecord>;
+}
+export declare function createEmptyState(): AppState;

package/dist/transport/tool-event-mode.d.ts

@@ -0,0 +1,14 @@
+import type { ToolUseEvent } from "../channels/types.js";
+export type ToolEventMode = "text" | "structured" | "both";
+/**
+ * Resolves the effective tool-event rendering mode.
+ *
+ * Resolution order (hard contract — preserves Phase 0 invariant):
+ *   1. Explicit `toolEventMode` always wins.
+ *   2. `onToolEvent` present → "structured" (structured consumer, suppress text tool calls).
+ *   3. Default → "text" (legacy text tool calls; no structured consumer).
+ */
+export declare function resolveToolEventMode(input?: {
+    toolEventMode?: ToolEventMode;
+    onToolEvent?: (event: ToolUseEvent) => void | Promise<void>;
+}): ToolEventMode;

package/dist/transport/types.d.ts

@@ -0,0 +1,129 @@
+import type { NonInteractivePermissions, PermissionMode } from "../config/types";
+import type { QuotaManager } from "../weixin/messaging/quota-manager.js";
+import type { ToolUseEvent } from "../channels/types.js";
+import type { ToolEventMode } from "./tool-event-mode.js";
+export type { ToolEventMode } from "./tool-event-mode.js";
+export interface ReplyQuotaContext {
+    chatKey: string;
+    quota: QuotaManager;
+}
+export interface PromptMedia {
+    type: "image" | "audio" | "video" | "file";
+    filePath: string;
+    mimeType: string;
+    fileName?: string;
+}
+export interface PermissionPolicy {
+    permissionMode: PermissionMode;
+    nonInteractivePermissions: NonInteractivePermissions;
+    permissionPolicy?: string;
+}
+export interface ResolvedSession {
+    alias: string;
+    agent: string;
+    agentCommand?: string;
+    workspace: string;
+    transportSession: string;
+    source?: "weacpx" | "agent-side";
+    agentSessionId?: string;
+    agentSessionTitle?: string;
+    agentSessionUpdatedAt?: string;
+    attachedAt?: string;
+    mcpCoordinatorSession?: string;
+    mcpSourceHandle?: string;
+    modeId?: string;
+    replyMode?: "stream" | "final" | "verbose";
+    cwd: string;
+    /**
+     * True for a non-persisted, single-use session (e.g. a `/later` temp-mode
+     * scheduled run). Transport errors for such a session must not suggest
+     * `/session new`/`attach`, and missing-session recovery (which mutates
+     * persisted state by alias) does not apply.
+     */
+    transient?: boolean;
+}
+export interface AgentSession {
+    sessionId: string;
+    cwd?: string;
+    title?: string | null;
+    updatedAt?: string;
+    _meta?: Record<string, unknown>;
+}
+export interface AgentSessionListQuery {
+    agent: string;
+    agentCommand?: string;
+    cwd: string;
+    cursor?: string;
+    filterCwd?: string;
+}
+export interface AgentSessionListResult {
+    source: "agent";
+    sessions: AgentSession[];
+    cursor?: string;
+    nextCursor?: string | null;
+    cwd?: string;
+}
+export type EnsureSessionProgressStage = "spawn" | "initializing" | "ready";
+export type EnsureSessionProgress = EnsureSessionProgressStage | {
+    kind: "note";
+    text: string;
+};
+export type PromptMediaInput = PromptMedia | PromptMedia[];
+export interface PromptOptions {
+    onSegment?: (text: string) => void | Promise<void>;
+    /**
+     * Structured side-channel for tool calls. See `toolEventMode` for routing.
+     *
+     * Async semantics: callbacks are invoked in event order and serialized —
+     * each invocation is awaited before the next is dispatched. The transport
+     * waits for all callbacks to settle before resolving the prompt. If any
+     * invocation throws or returns a rejected promise, the prompt rejects
+     * with the first observed error (matching `onSegment` behavior).
+     */
+    onToolEvent?: (event: ToolUseEvent) => void | Promise<void>;
+    /**
+     * Optional structured side-channel for the agent's thinking/reasoning.
+     *
+     * Each acpx `agent_thought_chunk` is forwarded raw (no buffering, no
+     * paragraph splitting). Channels that register this callback opt in to
+     * receiving thoughts and are responsible for their own accumulation /
+     * rendering. When omitted, thought chunks are dropped at the transport
+     * boundary — the built-in WeChat channel does not register it.
+     *
+     * Async semantics match `onSegment`: invocations are serialized and the
+     * transport awaits all of them before resolving the prompt; the first
+     * error observed rejects the prompt.
+     */
+    onThought?: (chunk: string) => void | Promise<void>;
+    /**
+     * How tool_call / tool_call_update events are surfaced for this prompt.
+     *
+     * - "text" (default when no handler): legacy emoji-prefixed segments in the reply stream.
+     * - "structured" (default when a handler is provided): events go to `onToolEvent` only.
+     * - "both": events go to `onToolEvent` AND legacy text segments — useful for migration.
+     *
+     * Resolved at the transport boundary via `resolveToolEventMode`.
+     */
+    toolEventMode?: ToolEventMode;
+    media?: PromptMediaInput;
+}
+export interface SessionTransport {
+    ensureSession(session: ResolvedSession, onProgress?: (progress: EnsureSessionProgress) => void): Promise<void>;
+    tailSessionHistory(session: ResolvedSession, lines: number): Promise<{
+        text: string;
+    }>;
+    prompt(session: ResolvedSession, text: string, reply?: (text: string) => Promise<void>, replyContext?: ReplyQuotaContext, options?: PromptOptions): Promise<{
+        text: string;
+    }>;
+    setMode(session: ResolvedSession, modeId: string): Promise<void>;
+    cancel(session: ResolvedSession): Promise<{
+        cancelled: boolean;
+        message: string;
+    }>;
+    hasSession(session: ResolvedSession): Promise<boolean>;
+    listAgentSessions?(query: AgentSessionListQuery): Promise<AgentSessionListResult | undefined>;
+    resumeAgentSession?(session: ResolvedSession, agentSessionId: string): Promise<void>;
+    removeSession?(session: ResolvedSession): Promise<void>;
+    updatePermissionPolicy?(policy: PermissionPolicy): Promise<void>;
+    dispose?(): Promise<void>;
+}

package/dist/util/path.d.ts

@@ -0,0 +1,4 @@
+export declare function normalizePath(input: string): string;
+export declare function basenameForPath(input: string): string;
+export declare function isSamePath(left: string, right: string): boolean;
+export declare function isWindowsLikePath(input: string): boolean;

package/dist/util/sanitize.d.ts

@@ -0,0 +1,10 @@
+export interface SanitizeOptions {
+    allow?: RegExp;
+    deny?: RegExp;
+    replacement?: string;
+    collapse?: boolean;
+    trim?: boolean;
+    lowercase?: boolean;
+    fallback?: string;
+}
+export declare function sanitizeString(input: string, options?: SanitizeOptions): string;

package/dist/util/text.d.ts

@@ -0,0 +1,3 @@
+export declare function truncateText(text: string, maxLength: number, ellipsis?: string): string;
+export declare function escapeForDoubleQuotes(input: string): string;
+export declare function quoteIfNeeded(input: string): string;

package/dist/version.d.ts

@@ -1 +1,3 @@
 export declare function readVersion(moduleUrl?: string): string;
+/** weacpx 核心版本，派生自 package.json（经 readVersion 动态读取，无硬编码漂移）。 */
+export declare const WEACPX_CORE_VERSION: string;

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

@@ -66,6 +66,7 @@ export interface ChatRequestMetadata {
     scheduledSessionAlias?: string;
     /** Transient session descriptor for temp-mode scheduled prompts (no persisted alias). */
     scheduledSessionDescriptor?: ScheduledSessionDescriptor;
+    boundSessionAlias?: string;
 }
 export interface ChatResponse {
     /**