weacpx 0.5.2 → 0.6.1

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

@@ -0,0 +1,83 @@
+import type { AppConfig } from "../config/types";
+import { AsyncMutex } from "../orchestration/async-mutex";
+import type { StateStore } from "../state/state-store";
+import type { AppState } from "../state/types";
+import type { AgentSession, ResolvedSession } from "../transport/types";
+interface SessionListItem {
+    alias: string;
+    internalAlias: string;
+    agent: string;
+    workspace: string;
+    isCurrent: boolean;
+}
+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>;
+    getPreferredSessionForTransport(transportSession: string): Promise<ResolvedSession | null>;
+    findAttachedNativeSession(chatKey: string, agent: string, agentSessionId: string): Promise<ResolvedSession | null>;
+    useSession(chatKey: string, alias: string): Promise<void>;
+    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 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,44 @@
+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 ChatContextState {
+    current_session: string;
+}
+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/auth/accounts.d.ts

@@ -1,6 +1,5 @@
 export declare const DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
 export declare const CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c";
-/** Normalize an account ID to a filesystem-safe string. */
 export declare function normalizeAccountId(raw: string): string;
 /**
  * Pattern-based reverse of normalizeWeixinAccountId for known weixin ID suffixes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weacpx",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "使用微信 ClawBot 随时随地通过 `acpx` 控制 Claude Code、Codex 等 Agents。",
   "keywords": [
     "acpx",