@ganglion/xacpx 0.10.0 → 0.11.0

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

@@ -2,5 +2,5 @@ import type { HelpTopicMetadata } from "../help/help-types";
 import type { CommandRouterContext, RouterResponse } from "../router-types";
 export declare function agentHelp(): HelpTopicMetadata;
 export declare function handleAgents(context: CommandRouterContext): RouterResponse;
-export declare function handleAgentAdd(context: CommandRouterContext, templateName: string): Promise<RouterResponse>;
+export declare function handleAgentAdd(context: CommandRouterContext, templateName: string, model?: string): Promise<RouterResponse>;
 export declare function handleAgentRemove(context: CommandRouterContext, agentName: string): Promise<RouterResponse>;

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

@@ -1,6 +1,6 @@
 import type { CommandRouterContext, RouterResponse, SessionInteractionOps, SessionLifecycleOps, SessionRenderRecoveryOps } from "../router-types";
 import type { PromptMediaInput, ResolvedSession } from "../../transport/types";
-import type { ToolUseEvent } from "../../channels/types.js";
+import type { PlanEntry, ToolUseEvent } from "../../channels/types.js";
 import type { PerfSpan } from "../../perf/perf-tracer";
 import type { HelpTopicMetadata } from "../help/help-types";
 import type { ChatRequestMetadata } from "../../weixin/agent/interface";
@@ -13,11 +13,12 @@ export interface SessionHandlerContext extends CommandRouterContext {
 export declare function sessionHelp(): HelpTopicMetadata;
 export declare function nativeSessionHelp(): HelpTopicMetadata;
 export declare function modeHelp(): HelpTopicMetadata;
+export declare function modelHelp(): HelpTopicMetadata;
 export declare function replyModeHelp(): HelpTopicMetadata;
 export declare function statusHelp(): HelpTopicMetadata;
 export declare function cancelHelp(): HelpTopicMetadata;
 export declare function handleSessions(context: SessionHandlerContext, chatKey: string): Promise<RouterResponse>;
-export declare function handleSessionNew(context: SessionHandlerContext, chatKey: string, alias: string, agent: string, workspace: string): Promise<RouterResponse>;
+export declare function handleSessionNew(context: SessionHandlerContext, chatKey: string, alias: string, agent: string, workspace: string, model?: string): Promise<RouterResponse>;
 export declare function handleSessionShortcut(context: SessionHandlerContext, chatKey: string, agent: string, target: {
     cwd?: string;
     workspace?: string;
@@ -27,6 +28,8 @@ export declare function handleSessionUse(context: SessionHandlerContext, chatKey
 export declare function handleSessionUsePrevious(context: SessionHandlerContext, chatKey: string): Promise<RouterResponse>;
 export declare function handleModeShow(context: SessionHandlerContext, chatKey: string): Promise<RouterResponse>;
 export declare function handleModeSet(context: SessionHandlerContext, chatKey: string, modeId: string): Promise<RouterResponse>;
+export declare function handleModelShow(context: SessionHandlerContext, chatKey: string): Promise<RouterResponse>;
+export declare function handleModelSet(context: SessionHandlerContext, chatKey: string, modelId: string): Promise<RouterResponse>;
 export declare function handleReplyModeShow(context: SessionHandlerContext, chatKey: string): Promise<RouterResponse>;
 export declare function handleReplyModeSet(context: SessionHandlerContext, chatKey: string, replyMode: "stream" | "final" | "verbose"): Promise<RouterResponse>;
 export declare function handleReplyModeReset(context: SessionHandlerContext, chatKey: string): Promise<RouterResponse>;
@@ -35,5 +38,5 @@ 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): 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): 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>;

package/dist/commands/parse-command.d.ts

@@ -19,6 +19,7 @@ export type ParsedCommand = {
 } | {
     kind: "agent.add";
     template: string;
+    model?: string;
 } | {
     kind: "agent.rm";
     name: string;
@@ -109,6 +110,11 @@ export type ParsedCommand = {
 } | {
     kind: "mode.set";
     modeId: string;
+} | {
+    kind: "model.show";
+} | {
+    kind: "model.set";
+    modelId: string;
 } | {
     kind: "replymode.show";
 } | {
@@ -126,6 +132,7 @@ export type ParsedCommand = {
     alias: string;
     agent: string;
     workspace: string;
+    model?: string;
 } | {
     kind: "session.shortcut";
     agent: string;

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

@@ -5,7 +5,7 @@ import type { OrchestrationService } from "../orchestration/orchestration-servic
 import type { SessionService } from "../sessions/session-service";
 import type { PromptMediaInput, ReplyQuotaContext, SessionTransport } from "../transport/types";
 import type { QuotaManager } from "../weixin/messaging/quota-manager.js";
-import type { ToolUseEvent } from "../channels/types.js";
+import type { PlanEntry, ToolUseEvent } from "../channels/types.js";
 import type { PerfSpan } from "../perf/perf-tracer";
 export interface RouterResponse {
     text?: string;
@@ -104,11 +104,16 @@ export interface SessionLifecycleOps {
 }
 export interface SessionInteractionOps {
     setModeTransportSession: (session: import("../transport/types").ResolvedSession, modeId: string) => Promise<void>;
+    setModelTransportSession: (session: import("../transport/types").ResolvedSession, modelId: string) => Promise<void>;
+    getModelTransportSession: (session: import("../transport/types").ResolvedSession) => Promise<{
+        current?: string;
+        available: string[];
+    }>;
     cancelTransportSession: (session: import("../transport/types").ResolvedSession) => Promise<{
         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) => 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>) => Promise<{
         text: string;
     }>;
 }

package/dist/config/agent-catalog.d.ts

@@ -0,0 +1,14 @@
+import type { AppConfig } from "./types";
+export interface AgentCatalogEntry {
+    driver: string;
+    configured: boolean;
+    installed: "builtin" | "yes" | "unknown";
+}
+/** True if `binary` is found in any PATH directory (no extension assumptions on POSIX). */
+export declare function isBinaryOnPath(binary: string): boolean;
+/**
+ * Catalog of every acpx driver xacpx knows (from `listAgentTemplates()`), each
+ * tagged with whether it's already configured and a best-effort install hint.
+ * `probe` is injectable for tests; defaults to a real PATH lookup.
+ */
+export declare function listAgentCatalog(config: AppConfig, probe?: (binary: string) => boolean): AgentCatalogEntry[];

package/dist/config/local-agent-bin.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Executable-file extensions to try for a bare command name. POSIX: just the name;
+ * Windows: the PATHEXT list (executability there is decided by extension, not a mode bit).
+ */
+export declare function executableExtensions(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string[];
+/**
+ * Is `name` an executable on PATH? Cross-platform: honours PATHEXT on Windows so
+ * `opencode` matches `opencode.cmd`/`.exe`. `env`/`isExecutableFile` are injectable for tests.
+ */
+export declare function isExecutableOnPath(name: string, env?: NodeJS.ProcessEnv, isExecutableFile?: (p: string) => boolean): boolean;
+/**
+ * If `driver` is a known npx-fallback agent AND its native CLI is on PATH, return the
+ * native command (e.g. `"opencode acp"`) to hand acpx via `--agent`; otherwise undefined
+ * (let acpx fall back to its npx default). Returns the bare bin name — acpx resolves it
+ * on PATH at spawn time, sidestepping any path-with-spaces quoting concerns.
+ */
+export declare function resolveLocalAgentCommand(driver: string, onPath?: (name: string) => boolean): string | undefined;

package/dist/config/resolve-agent-command.d.ts

@@ -1,2 +1,13 @@
 export declare function resolveAgentCommand(driver: string, command: string | undefined): string | undefined;
+/**
+ * Agent command for the RUNTIME spawn/reap paths. An explicit per-agent `command`
+ * always wins; otherwise, when `preferLocal` (default true), prefer a locally-installed
+ * native CLI over acpx's npx fallback; otherwise undefined (acpx resolves the driver).
+ *
+ * Use this — not bare resolveAgentCommand — wherever an agentCommand is built to spawn
+ * OR reap a queue owner, so both resolve identically (a mismatch would orphan the owner).
+ * It is deliberately NOT used on the config-persistence paths (load/ensure-config), so a
+ * machine-specific local binary is never baked into the shareable config file.
+ */
+export declare function resolveRuntimeAgentCommand(driver: string, command: string | undefined, preferLocal?: boolean): string | undefined;
 export declare function isLegacyCodexCommand(command: string): boolean;

package/dist/config/types.d.ts

@@ -33,6 +33,14 @@ export interface TransportConfig {
      * `0` keeps the owner alive forever. Defaults to 1800 (30 min).
      */
     queueOwnerTtlSeconds?: number;
+    /**
+     * Prefer a locally-installed native agent CLI over acpx's `npx -y <pkg>` fallback
+     * when one is on PATH (currently the unpinned-npx drivers: opencode, kilocode). This
+     * avoids a per-cold-start npm-registry fetch — faster and immune to network blips
+     * (e.g. ECONNRESET during agent init). Defaults to `true`; set `false` to always use
+     * acpx's default resolution. A per-agent `command` override still takes precedence.
+     */
+    preferLocalAgents?: boolean;
 }
 export type LoggingLevel = "error" | "info" | "debug";
 export interface PerfLogConfig {
@@ -51,6 +59,8 @@ export interface LoggingConfig {
 export interface AgentConfig {
     driver: string;
     command?: string;
+    /** Default LLM model id for sessions of this agent (e.g. `gpt-5.2[high]`); a session-level model overrides it. */
+    model?: string;
 }
 export interface WorkspaceConfig {
     cwd: string;

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

@@ -0,0 +1,59 @@
+import type { AppLogger } from "../logging/app-logger";
+import type { ToolUseEvent, PlanEntry } from "../channels/types";
+import type { NativeHistoryMessage } from "../transport/native-session-history";
+export interface ScheduledOrigin {
+    taskId: string;
+    executeAt: string;
+}
+export type ControlEvent = {
+    type: "turn-output";
+    chatKey: string;
+    sessionAlias: string;
+    chunk: string;
+} | {
+    type: "turn-started";
+    chatKey: string;
+    sessionAlias: string;
+    prompt?: string;
+    scheduled?: ScheduledOrigin;
+} | {
+    type: "tool-event";
+    chatKey: string;
+    sessionAlias: string;
+    event: ToolUseEvent;
+} | {
+    type: "turn-thought";
+    chatKey: string;
+    sessionAlias: string;
+    chunk: string;
+} | {
+    type: "plan";
+    chatKey: string;
+    sessionAlias: string;
+    entries: PlanEntry[];
+} | {
+    type: "turn-finished";
+    chatKey: string;
+    sessionAlias: string;
+    ok: boolean;
+    errorMessage?: string;
+    cancelled?: boolean;
+} | {
+    type: "sessions-changed";
+} | {
+    type: "scheduled-changed";
+    chatKey: string;
+} | {
+    type: "session-history";
+    chatKey: string;
+    sessionAlias: string;
+    messages: NativeHistoryMessage[];
+} | {
+    type: "orchestration-changed";
+};
+export type ControlEventListener = (event: ControlEvent) => void;
+export interface ControlEventBus {
+    subscribe(listener: ControlEventListener): () => void;
+    emit(event: ControlEvent): void;
+}
+export declare function createControlEventBus(logger?: AppLogger): ControlEventBus;

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

@@ -0,0 +1,147 @@
+import type { Agent as ChatAgent } from "../weixin/agent/interface";
+import type { SessionService } from "../sessions/session-service";
+import type { AgentSession, ResolvedSession, SessionTransport } from "../transport/types";
+import type { ActiveTurnRegistry } from "../sessions/active-turn-registry";
+import type { CreateScheduledTaskInput, ScheduledTaskService } from "../scheduled/scheduled-service";
+import type { ScheduledTaskRecord } from "../scheduled/scheduled-types";
+import type { CancelTaskInput, OrchestrationService, OrchestrationTaskFilter } from "../orchestration/orchestration-service";
+import type { OrchestrationTaskRecord } from "../orchestration/orchestration-types";
+import type { ControlEventBus } from "./control-event-bus";
+import type { AgentCatalogEntry } from "../config/agent-catalog";
+import { type DirListing, type FileContent, type SearchResult, type WorkspaceDiff } from "./workspace-fs";
+export interface ControlSessionInfo {
+    alias: string;
+    agent: string;
+    workspace: string;
+    transportSession: string;
+    running: boolean;
+}
+export interface ControlAgentInfo {
+    name: string;
+    driver: string;
+}
+/** An agent-native (acpx-owned) session available to attach as a new logical session. */
+export interface ControlNativeSessionInfo {
+    sessionId: string;
+    title?: string | null;
+    updatedAt?: string;
+    cwd?: string;
+}
+export interface ControlWorkspaceInfo {
+    name: string;
+    cwd: string;
+    description?: string;
+}
+export interface ControlServiceDeps {
+    agent: Pick<ChatAgent, "chat">;
+    sessions: Pick<SessionService, "listAllResolvedSessions" | "removeSession" | "useSession" | "resolveAliasForChat" | "getSession" | "setSessionModel">;
+    transport: Pick<SessionTransport, "setModel" | "getSessionModel">;
+    createSessionWithTransport: (internalAlias: string, agent: string, workspace: string, model?: string) => Promise<ResolvedSession>;
+    listNativeSessions: (agent: string, workspace: string) => Promise<AgentSession[]>;
+    attachNativeSessionWithTransport: (internalAlias: string, agent: string, workspace: string, agentSessionId: string, nativeMeta?: {
+        title?: string | null;
+        updatedAt?: string;
+    }) => Promise<ResolvedSession>;
+    activeTurns: Pick<ActiveTurnRegistry, "isActiveAnywhere">;
+    scheduled: Pick<ScheduledTaskService, "listPending" | "listRecentForChat" | "createTask" | "cancelPending">;
+    orchestration: Pick<OrchestrationService, "listTasks" | "getTask" | "requestTaskCancellation">;
+    events: ControlEventBus;
+    agents: {
+        list(): ControlAgentInfo[];
+        catalog(): AgentCatalogEntry[];
+        create(name: string, driver: string): Promise<ControlAgentInfo>;
+        remove(name: string): Promise<void>;
+    };
+    workspaces: {
+        list(): ControlWorkspaceInfo[];
+        create(name: string, cwd: string, description?: string): Promise<ControlWorkspaceInfo>;
+        remove(name: string): Promise<void>;
+    };
+}
+export interface ControlPromptInput {
+    chatKey: string;
+    sessionAlias: string;
+    text: string;
+    accountId?: string;
+    senderId: string;
+    isOwner?: boolean;
+}
+export interface ControlPromptResult {
+    ok: boolean;
+    text?: string;
+    errorMessage?: string;
+}
+/** A turn started by a fired scheduled task. Runs through the same agent + turn-event
+ *  machinery as a normal prompt, so it streams live and persists to history — but it
+ *  also carries the prompt text + schedule origin in turn-started, so the hub can
+ *  persist the inbound message and the web can badge the run. */
+export interface ControlScheduledTurnInput {
+    chatKey: string;
+    sessionAlias: string;
+    promptText: string;
+    taskId: string;
+    executeAt: string;
+    accountId?: string;
+    abortSignal?: AbortSignal;
+}
+export interface ControlExecuteCommandInput {
+    chatKey: string;
+    text: string;
+    accountId?: string;
+    senderId: string;
+    isOwner?: boolean;
+}
+export declare class ControlService {
+    private readonly deps;
+    constructor(deps: ControlServiceDeps);
+    private readonly workspaceFs;
+    listDirectory(workspace: string, path?: string): Promise<DirListing>;
+    readWorkspaceFile(workspace: string, path: string): Promise<FileContent>;
+    workspaceGitDiff(workspace: string, path?: string): Promise<WorkspaceDiff>;
+    searchWorkspace(workspace: string, query: string): Promise<SearchResult>;
+    /** Read a session's current model and the agent-advertised available ids. */
+    getSessionModel(chatKey: string, alias: string): Promise<{
+        current?: string;
+        available: string[];
+    }>;
+    /** Switch a session's model (acpx validates the id) and persist the override. */
+    setSessionModel(chatKey: string, alias: string, modelId: string): Promise<void>;
+    /** Resolve a chat-scoped display alias to its ResolvedSession, or null. */
+    private resolveControlSession;
+    get events(): ControlEventBus;
+    listSessions(chatKey: string): ControlSessionInfo[];
+    /**
+     * List the agent-native (acpx-owned) sessions for an agent + workspace, so the web
+     * add-session dialog can offer "attach an existing native session". These are the
+     * agent's own rollouts on disk (per-cwd), not chat-scoped — chatKey is accepted only
+     * for call-shape symmetry with the other session control methods.
+     */
+    listNativeSessions(_chatKey: string, agent: string, workspace: string): Promise<ControlNativeSessionInfo[]>;
+    createSession(chatKey: string, alias: string, agent: string, workspace: string, agentSessionId?: string, model?: string): Promise<ControlSessionInfo>;
+    removeSession(chatKey: string, alias: string): Promise<{
+        wasActive: boolean;
+    }>;
+    listAgents(): ControlAgentInfo[];
+    listWorkspaces(): ControlWorkspaceInfo[];
+    createWorkspace(name: string, cwd: string, description?: string): Promise<ControlWorkspaceInfo>;
+    listAgentCatalog(): AgentCatalogEntry[];
+    createAgent(name: string, driver: string): Promise<ControlAgentInfo>;
+    removeAgent(name: string): Promise<void>;
+    removeWorkspace(name: string): Promise<void>;
+    listScheduledTasks(chatKey: string): ScheduledTaskRecord[];
+    createScheduledTask(input: CreateScheduledTaskInput): Promise<ScheduledTaskRecord>;
+    cancelScheduledTask(id: string, chatKey: string): Promise<boolean>;
+    listOrchestrationTasks(filter?: OrchestrationTaskFilter): Promise<OrchestrationTaskRecord[]>;
+    getOrchestrationTask(taskId: string): Promise<OrchestrationTaskRecord | null>;
+    cancelOrchestrationTask(input: CancelTaskInput): Promise<OrchestrationTaskRecord>;
+    private readonly inFlight;
+    prompt(input: ControlPromptInput): Promise<ControlPromptResult>;
+    /** Run a fired scheduled task as a real turn through the same machinery as a manual
+     *  prompt — so it streams live and persists to history — while tagging turn-started
+     *  with the prompt text + schedule origin so the hub records the inbound message and
+     *  the web can badge it. Owner-authorized: the task was owner-gated at creation. */
+    runScheduledTurn(input: ControlScheduledTurnInput): Promise<ControlPromptResult>;
+    private executeTurn;
+    cancelTurn(chatKey: string, sessionAlias: string): boolean;
+    executeCommand(input: ControlExecuteCommandInput): Promise<string>;
+}

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

@@ -0,0 +1,52 @@
+export interface FsEntry {
+    name: string;
+    type: "dir" | "file";
+    size?: number;
+}
+export interface DirListing {
+    workspace: string;
+    path: string;
+    entries: FsEntry[];
+}
+export interface FileContent {
+    workspace: string;
+    path: string;
+    content: string;
+    size: number;
+    truncated: boolean;
+    binary: boolean;
+}
+export interface DiffFile {
+    path: string;
+    status: string;
+}
+export interface SearchResult {
+    workspace: string;
+    query: string;
+    matches: string[];
+    truncated: boolean;
+}
+export interface WorkspaceDiff {
+    workspace: string;
+    files: DiffFile[];
+    diff: string;
+    truncated: boolean;
+}
+export interface WorkspaceRef {
+    name: string;
+    cwd: string;
+}
+export declare class WorkspaceFs {
+    private readonly listWorkspaces;
+    constructor(listWorkspaces: () => WorkspaceRef[]);
+    /** Resolve `relPath` within a named workspace, symlink-safe and contained. Throws
+     *  on unknown workspace, missing target, or any path that escapes the root. */
+    private resolve;
+    listDirectory(workspace: string, relPath?: string): Promise<DirListing>;
+    readFile(workspace: string, relPath: string): Promise<FileContent>;
+    /** Find files whose relative path contains `query` (case-insensitive). Walks the
+     *  tree breadth-first, skipping `.git`/`node_modules` and never following symlinks
+     *  (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>;
+}

package/dist/i18n/types.d.ts

@@ -25,6 +25,13 @@ export interface SessionMessages {
     modeModeLabel: (modeId: string) => string;
     modeNotSet: string;
     modeSet: (modeId: string) => string;
+    modelHeader: string;
+    modelSessionLabel: (alias: string) => string;
+    modelModelLabel: (modelId: string) => string;
+    modelNotSet: string;
+    modelAvailableLabel: (models: string) => string;
+    modelSet: (modelId: string) => string;
+    modelSetFailed: (modelId: string, detail: string) => string;
     replyModeHeader: string;
     replyModeSessionLabel: (alias: string) => string;
     replyModeGlobalDefault: (value: string) => string;
@@ -101,6 +108,11 @@ export interface SessionMessages {
     modeHelpCmdShowDesc: string;
     modeHelpCmdSet: string;
     modeHelpCmdSetDesc: string;
+    modelHelpSummary: string;
+    modelHelpCmdShow: string;
+    modelHelpCmdShowDesc: string;
+    modelHelpCmdSet: string;
+    modelHelpCmdSetDesc: string;
     replyModeHelpSummary: string;
     replyModeHelpCmdShow: string;
     replyModeHelpCmdShowDesc: string;

package/dist/plugin-api.d.ts

@@ -18,3 +18,6 @@ export type { BackgroundResult } from "./state/types.js";
 export type { ChatRequestMetadata } from "./weixin/agent/interface.js";
 export { getLocale } from "./i18n/index.js";
 export type { Locale } from "./i18n/index.js";
+export type { ControlExecuteCommandInput, ControlPromptInput, ControlPromptResult, ControlService, ControlSessionInfo, } from "./control/control-service.js";
+export type { ControlEvent, ControlEventBus, ControlEventListener } from "./control/control-event-bus.js";
+export { coreHomeDir } from "./runtime/core-home.js";

package/dist/plugin-api.js

@@ -90,6 +90,14 @@ var init_session = __esm(() => {
     modeModeLabel: (modeId) => `- mode: ${modeId}`,
     modeNotSet: "not set",
     modeSet: (modeId) => `Current session mode set to: ${modeId}`,
+    modelHeader: "Current model:",
+    modelSessionLabel: (alias) => `- Session: ${alias}`,
+    modelModelLabel: (modelId) => `- model: ${modelId}`,
+    modelNotSet: "not set (using agent default)",
+    modelAvailableLabel: (models) => `- available: ${models}`,
+    modelSet: (modelId) => `Current session model switched to: ${modelId}`,
+    modelSetFailed: (modelId, detail) => `Failed to switch model: ${modelId}
+${detail}`,
     replyModeHeader: "Current reply mode:",
     replyModeSessionLabel: (alias) => `- Session: ${alias}`,
     replyModeGlobalDefault: (value) => `- Global default: ${value}`,
@@ -166,6 +174,11 @@ var init_session = __esm(() => {
     modeHelpCmdShowDesc: "Show the saved mode of the current session",
     modeHelpCmdSet: "/mode <id>",
     modeHelpCmdSetDesc: "Set the current session mode",
+    modelHelpSummary: "View or switch the LLM model for the current session.",
+    modelHelpCmdShow: "/model",
+    modelHelpCmdShowDesc: "Show the current session model and the available ones",
+    modelHelpCmdSet: "/model <id>",
+    modelHelpCmdSetDesc: "Switch the current session model (e.g. gpt-5.2[high])",
     replyModeHelpSummary: "View or set the reply output mode for the current logical session.",
     replyModeHelpCmdShow: "/replymode",
     replyModeHelpCmdShowDesc: "Show global default, current override, and effective value",
@@ -1169,6 +1182,14 @@ var init_session2 = __esm(() => {
     modeModeLabel: (modeId) => `- mode：${modeId}`,
     modeNotSet: "未设置",
     modeSet: (modeId) => `已设置当前会话 mode：${modeId}`,
+    modelHeader: "当前 model：",
+    modelSessionLabel: (alias) => `- 会话：${alias}`,
+    modelModelLabel: (modelId) => `- model：${modelId}`,
+    modelNotSet: "未设置（使用 agent 默认）",
+    modelAvailableLabel: (models) => `- 可选：${models}`,
+    modelSet: (modelId) => `已切换当前会话 model：${modelId}`,
+    modelSetFailed: (modelId, detail) => `切换 model 失败：${modelId}
+${detail}`,
     replyModeHeader: "当前 reply mode：",
     replyModeSessionLabel: (alias) => `- 会话：${alias}`,
     replyModeGlobalDefault: (value) => `- 全局默认：${value}`,
@@ -1245,6 +1266,11 @@ var init_session2 = __esm(() => {
     modeHelpCmdShowDesc: "查看当前会话已保存的 mode",
     modeHelpCmdSet: "/mode <id>",
     modeHelpCmdSetDesc: "设置当前会话 mode",
+    modelHelpSummary: "查看或切换当前会话的 LLM model。",
+    modelHelpCmdShow: "/model",
+    modelHelpCmdShowDesc: "查看当前会话 model 及可选项",
+    modelHelpCmdSet: "/model <id>",
+    modelHelpCmdSetDesc: "切换当前会话 model（如 gpt-5.2[high]）",
     replyModeHelpSummary: "查看或设置当前逻辑会话的回复输出模式。",
     replyModeHelpCmdShow: "/replymode",
     replyModeHelpCmdShowDesc: "查看全局默认、当前覆盖和实际生效值",
@@ -2444,6 +2470,13 @@ function createActiveTurnRegistry() {
     },
     isActive(chatKey, alias) {
       return byChat.get(chatKey)?.has(alias) ?? false;
+    },
+    isActiveAnywhere(alias) {
+      for (const set of byChat.values()) {
+        if (set.has(alias))
+          return true;
+      }
+      return false;
     }
   };
 }
@@ -2527,6 +2560,24 @@ var init_channel_scope = __esm(() => {
   KNOWN_CHANNEL_IDS = new Set(["weixin"]);
 });
 
+// src/runtime/core-home.ts
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+function coreHomeDir(home) {
+  const primary = join(home, CORE_HOME_DIR_NAME);
+  if (existsSync(primary))
+    return primary;
+  const legacy = join(home, CORE_HOME_LEGACY_DIR_NAME);
+  if (existsSync(legacy))
+    return legacy;
+  return primary;
+}
+function coreHomeDisplayPath(...segments) {
+  return ["~", CORE_HOME_DIR_NAME, ...segments].join("/");
+}
+var CORE_HOME_DIR_NAME = ".xacpx", CORE_HOME_LEGACY_DIR_NAME = ".weacpx";
+var init_core_home = () => {};
+
 // src/plugin-api.ts
 init_types();
 
@@ -2540,12 +2591,14 @@ function resolveTurnLane(text) {
 // src/plugin-api.ts
 init_channel_scope();
 init_i18n();
+init_core_home();
 export {
   toDisplaySessionAlias,
   resolveTurnLane,
   getLocale,
   createConversationExecutor,
   createActiveTurnRegistry,
+  coreHomeDir,
   XACPX_PLUGIN_MIN_CORE_VERSION,
   XACPX_PLUGIN_API_VERSION,
   XACPX_PLUGIN_API_SUPPORTED_VERSIONS,

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

@@ -29,6 +29,9 @@ export declare class ScheduledTaskService {
     constructor(state: AppState, stateStore: Pick<StateStore, "save">, options?: ScheduledTaskServiceOptions);
     createTask(input: CreateScheduledTaskInput): Promise<ScheduledTaskRecord>;
     listPending(chatKey: string): ScheduledTaskRecord[];
+    listRecentForChat(chatKey: string, opts?: {
+        terminalLimit?: number;
+    }): ScheduledTaskRecord[];
     listPendingAllChats(): ScheduledTaskRecord[];
     cancelPending(inputId: string, chatKey: string): Promise<boolean>;
     cancelPendingAnyChat(inputId: string): Promise<boolean>;

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

@@ -2,5 +2,7 @@ export interface ActiveTurnRegistry {
     markActive(chatKey: string, alias: string): void;
     markInactive(chatKey: string, alias: string): void;
     isActive(chatKey: string, alias: string): boolean;
+    /** True when any chat currently has a turn running for this alias. */
+    isActiveAnywhere(alias: string): boolean;
 }
 export declare function createActiveTurnRegistry(): ActiveTurnRegistry;

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

@@ -113,6 +113,10 @@ export declare class SessionService {
     getNativeSessionList(chatKey: string, ttlMs?: number): Promise<NativeSessionListResult | null>;
     private deleteNativeSessionListIfCurrent;
     private toResolvedSession;
+    /** Persist (or clear) a session's model override by internal alias. */
+    setSessionModel(alias: string, modelId: string | undefined): Promise<void>;
+    /** Persist (or clear) the model override of the chat's current session. */
+    setCurrentSessionModel(chatKey: string, modelId: string | undefined): Promise<void>;
     setSessionTransportAgentCommand(alias: string, transportAgentCommand: string | undefined): Promise<void>;
     private mutate;
     private persist;

package/dist/state/types.d.ts

@@ -27,6 +27,8 @@ export interface LogicalSession {
     attached_at?: string;
     transport_agent_command?: string;
     mode_id?: string;
+    /** Per-session LLM model override (e.g. `gpt-5.2[high]`); falls back to the agent config default. */
+    model?: string;
     reply_mode?: "stream" | "final" | "verbose";
     created_at: string;
     last_used_at: string;

package/dist/transport/native-session-history.d.ts

@@ -0,0 +1,34 @@
+import type { ToolUseEvent } from "../channels/types";
+export type NativeHistoryPart = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "reasoning";
+    text: string;
+} | {
+    kind: "tool";
+    tool: ToolUseEvent;
+};
+export interface NativeHistoryMessage {
+    role: "user" | "agent";
+    /** Flattened text (the `out`/`in` body); `parts` carries the ordered transcript for agents. */
+    text: string;
+    /** Ordered transcript for agent turns (text / reasoning / tool), as the agent produced it. */
+    parts?: NativeHistoryPart[];
+}
+/** Map an acpx SessionMessage[] (the persisted conversation) to neutral history. The
+ *  `"Resume"` marker entries are dropped. Pure + defensive: unknown shapes are skipped. */
+export declare function mapAcpxMessagesToHistory(raw: unknown): NativeHistoryMessage[];
+export interface ReadNativeHistoryOptions {
+    agentSessionId: string;
+    agentCommand?: string;
+    /** Override for the acpx sessions dir (tests). Defaults to `<home>/.acpx/sessions`. */
+    sessionsDir?: string;
+    homeDir?: string;
+}
+/** Recover a native (agent-side) session's prior conversation from acpx's own persisted
+ *  record. Best-effort: any I/O or shape problem yields `[]` so a native attach never
+ *  fails just because history couldn't be read. When several records share the same
+ *  acp_session_id (the source record + the freshly-created empty attach record), the
+ *  one with the most messages wins — i.e. the real history, not the empty stub. */
+export declare function readNativeSessionHistory(opts: ReadNativeHistoryOptions): Promise<NativeHistoryMessage[]>;