@ganglion/xacpx 0.8.0

package/dist/plugins/compatibility.d.ts

@@ -0,0 +1,18 @@
+export declare const WEACPX_PLUGIN_API_VERSION: 1;
+export declare const WEACPX_PLUGIN_API_SUPPORTED_VERSIONS: readonly number[];
+export declare const WEACPX_PLUGIN_MIN_CORE_VERSION: "0.5.0";
+export declare function normalizeCoreVersionForCompat(version: string): string;
+export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
+export declare function isVersionSatisfied(current: string, requirement: string): boolean;
+export interface PluginCompatibilityMetadata {
+    apiVersion?: unknown;
+    minWeacpxVersion?: unknown;
+    compatibleWeacpxVersions?: unknown;
+    minXacpxVersion?: unknown;
+    compatibleXacpxVersions?: unknown;
+}
+export interface PluginCompatibilityContext {
+    packageName: string;
+    currentWeacpxVersion: string;
+}
+export declare function validatePluginCompatibility(metadata: PluginCompatibilityMetadata, context: PluginCompatibilityContext): void;

package/dist/plugins/known-plugins.d.ts

@@ -0,0 +1,9 @@
+export interface KnownPlugin {
+    packageName: string;
+    channels: string[];
+    description: string;
+    official: true;
+}
+export declare function listKnownPlugins(): KnownPlugin[];
+export declare function findKnownPluginByChannel(channelType: string): KnownPlugin | null;
+export declare function getMovedChannelInstallHint(channelType: string): string | null;

package/dist/plugins/types.d.ts

@@ -0,0 +1,31 @@
+import type { ChannelPluginDefinition } from "../channels/plugin.js";
+import { WEACPX_PLUGIN_API_VERSION, WEACPX_PLUGIN_API_SUPPORTED_VERSIONS, WEACPX_PLUGIN_MIN_CORE_VERSION } from "./compatibility.js";
+export { WEACPX_PLUGIN_API_VERSION, WEACPX_PLUGIN_API_SUPPORTED_VERSIONS, WEACPX_PLUGIN_MIN_CORE_VERSION, };
+export interface WeacpxPlugin {
+    apiVersion: 1;
+    name?: string;
+    /**
+     * Minimum core version required by this plugin (e.g. "0.8.0").
+     * First-party plugins must declare this; third-party plugins are encouraged to.
+     *
+     * The core was renamed weacpx→xacpx at 0.8.0. New plugins should prefer
+     * {@link minXacpxVersion}; the legacy `minWeacpxVersion` is still read for
+     * already-published plugins (when both are present, `minXacpxVersion` wins).
+     */
+    minWeacpxVersion?: string;
+    /**
+     * Optional explicit core compatibility range, e.g. ">=0.3.3" or "^0.3.3".
+     * If both a min version and a compatibility range are set, both must hold.
+     */
+    compatibleWeacpxVersions?: string;
+    /** Preferred (post-rename) alias of {@link minWeacpxVersion}. */
+    minXacpxVersion?: string;
+    /** Preferred (post-rename) alias of {@link compatibleWeacpxVersions}. */
+    compatibleXacpxVersions?: string;
+    channels?: ChannelPluginDefinition[];
+}
+/**
+ * Post-rename alias for {@link WeacpxPlugin}. New plugins should author against
+ * `XacpxPlugin`; the legacy name remains exported for backward compatibility.
+ */
+export type XacpxPlugin = WeacpxPlugin;

package/dist/runtime/conversation-executor.d.ts

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

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

@@ -0,0 +1,28 @@
+/**
+ * Centralized environment-variable access for the core (`xacpx`).
+ *
+ * The project was renamed `weacpx` → `xacpx` at 0.8.0. To keep existing
+ * deployments working, every core environment variable is read through
+ * {@link coreEnv}, which prefers the new `XACPX_` prefix but falls back to the
+ * legacy `WEACPX_` one. This is the single seam the rename hooks into — callers
+ * pass the bare suffix (e.g. `"CONFIG"`), never the full prefixed name.
+ *
+ * When the core *sets* an env var for one of its own subprocesses (daemon /
+ * bridge / mcp handshakes), it writes the canonical {@link coreEnvName} (the
+ * new `XACPX_` prefix); the same-generation reader resolves it via `coreEnv`,
+ * while any externally-set legacy `WEACPX_` value still wins fallback.
+ */
+/**
+ * Read a core env var by its suffix, preferring `XACPX_<suffix>` and falling
+ * back to the legacy `WEACPX_<suffix>`. Returns `undefined` if neither is set.
+ */
+export declare function coreEnv(suffix: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * The canonical (new-prefix) env var name for a suffix, e.g.
+ * `coreEnvName("DAEMON_RUN")` → `"XACPX_DAEMON_RUN"`. Use this when the core
+ * writes an env var for its own subprocess so the value is set under the
+ * current name; readers still resolve it through {@link coreEnv}.
+ */
+export declare function coreEnvName(suffix: string): string;
+/** The legacy env var name for a suffix, e.g. `"WEACPX_CONFIG"`. */
+export declare function legacyCoreEnvName(suffix: string): string;

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

@@ -0,0 +1,31 @@
+/**
+ * The per-user state directory name (`<home>/.xacpx/`). This is the SINGLE
+ * source of truth for that name; every config / state / runtime / plugin path
+ * is built on top of it.
+ *
+ * The project was renamed `weacpx` → `xacpx` at 0.8.0. New installs use
+ * `~/.xacpx`; existing `~/.weacpx` directories are migrated once on first run
+ * (see `migrate-core-home.ts`). Until that migration runs (or while it is
+ * intentionally skipped because a legacy daemon is still alive),
+ * {@link coreHomeDir} keeps resolving to the legacy directory so the process
+ * operates on existing state rather than a fresh empty tree.
+ */
+export declare const CORE_HOME_DIR_NAME = ".xacpx";
+/** The pre-rename state directory name, kept for one-time migration / fallback. */
+export declare const CORE_HOME_LEGACY_DIR_NAME = ".weacpx";
+/**
+ * The core state root for a given user home.
+ *
+ * Resolution order: prefer `<home>/.xacpx` if it exists; otherwise fall back to
+ * an existing legacy `<home>/.weacpx` (so we keep reading/writing pre-rename
+ * state until it is migrated); otherwise return `<home>/.xacpx` for a fresh
+ * install. Pass the home directory the caller already resolved — this helper
+ * imposes no home-resolution policy of its own.
+ */
+export declare function coreHomeDir(home: string): string;
+/**
+ * Display form for user-facing hints (e.g. "请查看日志：~/.xacpx/runtime/...").
+ * Keeps printed paths single-sourced with the canonical 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/private-file.d.ts

@@ -0,0 +1,26 @@
+export declare function writePrivateFileAtomic(path: string, content: string): Promise<void>;
+/**
+ * Synchronous private-file write for hot-path callers that cannot await
+ * (e.g. per-message weixin credential/sync-buf/context-token persistence).
+ * Atomic via write-file-atomic's temp+rename, created at 0600 so the secret is
+ * never momentarily world-readable. No cross-process lock: weixin's per-account
+ * consumer lock already serializes the single writing daemon.
+ */
+interface WritePrivateFileSyncDeps {
+    platform?: NodeJS.Platform;
+    atomicWrite?: (path: string, content: string) => void;
+    directWrite?: (path: string, content: string) => void;
+}
+export declare function writePrivateFileSync(path: string, content: string, deps?: WritePrivateFileSyncDeps): void;
+interface RetryTransientWriteOptions {
+    platform?: NodeJS.Platform;
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    delay?: (ms: number) => Promise<void>;
+}
+export declare function retryTransientWriteErrors(run: () => Promise<void>, options?: RetryTransientWriteOptions): Promise<void>;
+export declare const __privateFileForTests: {
+    retryTransientWriteErrors: typeof retryTransientWriteErrors;
+};
+export {};

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

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