@ganglion/xacpx 0.20.3 → 0.22.0

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

@@ -8,6 +8,12 @@ export declare function executableExtensions(platform: NodeJS.Platform, env: Nod
  * `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;
+/**
+ * Is `driver` listed as a local-fallback agent in LOCAL_AGENT_BINS? Use this — not a
+ * hand-copied allow-list — for drift guards that need to exempt drivers xacpx itself
+ * supplies at runtime (e.g. `agent-catalog.test.ts`'s acpx-registry drift guard).
+ */
+export declare function isLocalAgentBinDriver(driver: string): boolean;
 /**
  * If `driver` is a known npx-fallback agent AND its native CLI is on PATH, return the
  * structured argv (e.g. `["opencode", "acp"]`); otherwise undefined (let acpx fall back

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

@@ -31,7 +31,7 @@ export interface ResolveAgentLaunchOptions {
  * 2. user `argv`: content-addressed overlay alias + canonical identity.
  * 3. managed codex/claude: structured pinned npx argv (alias launch).
  * 4. hermes: ACP shim argv (alias launch).
- * 5. local fallback (opencode/kilocode on PATH): structured argv (alias launch).
+ * 5. local fallback (opencode/kilocode/reasonix/omp on PATH): structured argv (alias launch).
  * 6. anything else: bare built-in driver positional.
  */
 export declare function resolveConfiguredAgentLaunch(agent: Pick<AgentConfig, "driver" | "command" | "argv">, transport?: Pick<TransportConfig, "preferLocalAgents" | "adapterVersions" | "adapterRegistry">, options?: ResolveAgentLaunchOptions): AgentLaunchSpec;

package/dist/config/types.d.ts

@@ -37,10 +37,12 @@ export interface TransportConfig {
     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.
+     * when one is on PATH (currently opencode, kilocode, plus the local-fallback drivers
+     * reasonix and omp that aren't in acpx's registry but speak ACP via `<bin> acp`).
+     * 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;
     /** Exact local overrides for xacpx-managed ACP adapter versions. Omitted entries

package/dist/i18n/types.d.ts

@@ -700,6 +700,7 @@ export interface ChannelCliMessages {
     channelAdded: (type: string) => string;
     cannotRemoveLastEnabled: string;
     channelRemoved: (id: string) => string;
+    channelRetirementFailed: (id: string, error: string) => string;
     channelCredentialsCleared: (id: string) => string;
     channelCredentialsClearFailed: (id: string, error: string) => string;
     channelCredentialsKept: (id: string) => string;

package/dist/plugin-api.d.ts

@@ -1,9 +1,9 @@
-export type { ChannelPluginDefinition } from "./channels/plugin.js";
+export type { ChannelPluginDefinition, ChannelRetireContext, ChannelRetireDaemonState, ChannelRetireHook, } from "./channels/plugin.js";
 export type { ChannelFactory, CreateChannelDeps } from "./channels/create-channel.js";
-export type { ChannelStartInput, ConsumerLock, ConsumerLockMetadata, ConsumerLockOptions, CoordinatorMessageInput, MessageChannelRuntime, ScheduledChannelMessageInput, OrchestrationDeliveryCallbacks, OutboundQuota, PlanEntry, PlanEntryStatus, ToolUseEvent, ToolUseKind, ToolUseStatus, } from "./channels/types.js";
+export type { ChannelStartInput, ConsumerLock, ConsumerLockMetadata, ConsumerLockOptions, ChannelStopReason, CoordinatorMessageInput, MessageChannelRuntime, ScheduledChannelMessageInput, OrchestrationDeliveryCallbacks, OutboundQuota, PlanEntry, PlanEntryStatus, ToolUseEvent, ToolUseKind, ToolUseStatus, } from "./channels/types.js";
 export { formatSubagentNotice, SubagentNoticeTracker } from "./channels/subagent-notice.js";
 export type { AgentCommand, PromptUsage, UsageBreakdown, UsageCost, } from "./transport/types.js";
-export type { ChannelCliInput, ChannelCliIo, ChannelCliParseResult, ChannelCliProvider, ChannelCliValidationIssue, } from "./channels/cli/provider.js";
+export type { ChannelCliInput, ChannelCliIo, ChannelCliParseResult, ChannelCliProvider, ChannelCliValidationIssue, ChannelDoctorFinding, ChannelDoctorFindingLevel, } from "./channels/cli/provider.js";
 export type { ChannelRuntimeConfig } from "./config/types.js";
 export type { CommandHint } from "./commands/command-hints.js";
 export type { AppLogger } from "./logging/app-logger.js";
@@ -22,4 +22,5 @@ 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 type { SessionResourceCatalog, SessionResourceDescriptor, SessionResourceLifecycleEvent, } from "./sessions/session-resource-catalog.js";
 export { coreHomeDir } from "./runtime/core-home.js";

package/dist/plugin-api.js

@@ -927,6 +927,7 @@ var init_channel_cli = __esm(() => {
     channelAdded: (type) => `Channel ${type} added`,
     cannotRemoveLastEnabled: "Cannot remove the last enabled channel.",
     channelRemoved: (id) => `Channel ${id} removed`,
+    channelRetirementFailed: (id, error) => `Channel ${id} retirement cleanup failed: ${error}`,
     channelCredentialsCleared: (id) => `Removed stored credentials for channel ${id}`,
     channelCredentialsClearFailed: (id, error) => `Channel ${id} removed, but clearing its stored credentials failed: ${error}`,
     channelCredentialsKept: (id) => `Kept stored credentials for channel ${id} (--keep-credentials)`,
@@ -2053,6 +2054,7 @@ var init_channel_cli2 = __esm(() => {
     channelAdded: (type) => `频道 ${type} 已添加`,
     cannotRemoveLastEnabled: "不能删除最后一个启用的频道。",
     channelRemoved: (id) => `频道 ${id} 已删除`,
+    channelRetirementFailed: (id, error) => `频道 ${id} 退役清理失败：${error}`,
     channelCredentialsCleared: (id) => `已移除频道 ${id} 的存储凭证`,
     channelCredentialsClearFailed: (id, error) => `频道 ${id} 已删除，但清除其存储凭证失败：${error}`,
     channelCredentialsKept: (id) => `已保留频道 ${id} 的存储凭证（--keep-credentials）`,

package/dist/sessions/session-resource-catalog.d.ts

@@ -0,0 +1,96 @@
+import type { AppConfig } from "../config/types";
+import type { AppLogger } from "../logging/app-logger";
+import type { LogicalSession } from "../state/types";
+import type { SessionService } from "./session-service";
+/**
+ * A point-in-time snapshot of one logical session's resource identity. The
+ * immutable `logicalSessionId` is the ONLY stable key: aliases, display names
+ * and transport bindings can all change under the same id. `cwd` is resolved
+ * authoritatively from the core workspace config — callers (e.g. browsers)
+ * never contribute a cwd. Descriptors are snapshots: a previously returned
+ * descriptor never mutates when the underlying session changes.
+ */
+export interface SessionResourceDescriptor {
+    logicalSessionId: string;
+    channelId: string;
+    internalAlias: string;
+    displayAlias: string;
+    workspace: string;
+    cwd: string;
+    archived: boolean;
+}
+export type SessionResourceLifecycleEvent = {
+    type: "archived";
+    session: SessionResourceDescriptor;
+} | {
+    type: "restored";
+    session: SessionResourceDescriptor;
+} | {
+    type: "removed";
+    session: SessionResourceDescriptor;
+};
+/**
+ * Write-side seam handed to SessionService: after a lifecycle transition has
+ * been durably persisted (never before), the service reports the transition
+ * type plus the persisted record; the catalog maps the record to a descriptor
+ * and publishes the event to subscribers. For `removed` the record is the
+ * pre-delete snapshot, so the event carries the session's final identity.
+ */
+export interface SessionResourceLifecyclePublishInput {
+    type: SessionResourceLifecycleEvent["type"];
+    record: LogicalSession;
+}
+/**
+ * Generic, channel-agnostic catalog over logical session resources. Contains
+ * no channel- or consumer-specific vocabulary; structured channels (and their
+ * plugins) use it to enumerate and resolve the sessions they own.
+ */
+export interface SessionResourceCatalog {
+    /**
+     * Resolve a chat-scoped alias (display or internal form) to a descriptor.
+     * Uses the same chat-scope resolution as ControlService: a caller can never
+     * reach another channel's sessions. Returns null for unknown aliases and
+     * for sessions whose workspace is no longer registered (their cwd cannot be
+     * authoritatively resolved).
+     */
+    resolve(chatKey: string, alias: string): Promise<SessionResourceDescriptor | null>;
+    /** All sessions of one channel, active AND archived, for reconciliation. */
+    list(channelId: string): Promise<SessionResourceDescriptor[]>;
+    /**
+     * Register a lifecycle listener; returns an unsubscribe function. Listener
+     * exceptions are caught and logged to the app log: they never roll back the
+     * underlying session operation and never block other listeners.
+     */
+    subscribe(listener: (event: SessionResourceLifecycleEvent) => void): () => void;
+}
+interface SessionResourceCatalogDeps {
+    sessions: SessionService;
+    config: AppConfig;
+    logger: AppLogger;
+}
+/**
+ * Production catalog assembled by the core runtime over the live SessionService
+ * and workspace config. Plugin/channel tests should use their own in-memory
+ * implementation of the interface instead of this adapter.
+ */
+export declare class CoreSessionResourceCatalog implements SessionResourceCatalog {
+    private readonly deps;
+    private readonly listeners;
+    constructor(deps: SessionResourceCatalogDeps);
+    resolve(chatKey: string, alias: string): Promise<SessionResourceDescriptor | null>;
+    list(channelId: string): Promise<SessionResourceDescriptor[]>;
+    subscribe(listener: (event: SessionResourceLifecycleEvent) => void): () => void;
+    /**
+     * Publish one durably-persisted lifecycle transition. SessionService calls
+     * this (via the publisher it was handed at runtime wiring) strictly AFTER
+     * saveNow succeeded and the runtime state was published; the catalog itself
+     * never persists anything. Records whose workspace is no longer registered
+     * produce no event: such sessions are invisible in resolve()/list(), so
+     * consumers never tracked a resource for them.
+     */
+    publishLifecycleEvent(input: SessionResourceLifecyclePublishInput): void;
+    /** Fan an event out to all subscribers; listener throws are isolated. */
+    private emit;
+    private toDescriptor;
+}
+export {};

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

@@ -1,7 +1,8 @@
 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 { AppState, BackgroundResult, LogicalSession } from "../state/types";
+import type { SessionResourceLifecyclePublishInput } from "./session-resource-catalog";
 import type { AgentSession, ResolvedSession } from "../transport/types";
 interface SessionListItem {
     alias: string;
@@ -79,6 +80,7 @@ export declare class SessionService {
     private readonly platform;
     private readonly runtimeRoot;
     private readonly pendingSessionAliasOperations;
+    private lifecyclePublisher;
     constructor(config: AppConfig, stateStore: SessionStateWriter, state: AppState, options?: SessionServiceOptions);
     createSession(alias: string, agent: string, workspace: string): Promise<ResolvedSession>;
     /**
@@ -109,6 +111,8 @@ export declare class SessionService {
     getPreferredSessionForTransport(transportSession: string): Promise<ResolvedSession | null>;
     findAttachedNativeSession(chatKey: string, agent: string, agentSessionId: string): Promise<ResolvedSession | null>;
     useSession(chatKey: string, alias: string): Promise<SessionSwitchResult>;
+    /** Apply the use-session mutation (switch, plus restore when archived). */
+    private applyUseSession;
     usePreviousSession(chatKey: string): Promise<SessionSwitchResult | null>;
     setBackgroundResult(chatKey: string, alias: string, result: BackgroundResult): Promise<void>;
     takeBackgroundResult(chatKey: string, alias: string): Promise<BackgroundResult | null>;
@@ -155,11 +159,36 @@ export declare class SessionService {
      */
     buildFreshTransportSession(stableTransportSession: string): string;
     listInternalAliases(): string[];
+    /**
+     * Read-only access to the persisted logical session record by internal alias.
+     * Returns the LIVE record — callers must treat it as immutable. Exists for
+     * consumers (the session resource catalog) that need fields ResolvedSession
+     * does not carry (immutable logical_session_id, archived flag).
+     */
+    getLogicalSessionRecord(alias: string): LogicalSession | null;
+    /** Read-only view of every persisted logical session record, across all channels. */
+    listLogicalSessionRecords(): LogicalSession[];
     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;
+    /**
+     * Wire the sink for resource lifecycle events (production: the core
+     * SessionResourceCatalog; the runtime calls this once after constructing
+     * the catalog). Archive/restore/remove transitions report through it only
+     * AFTER their state has been durably persisted — never before.
+     */
+    setSessionResourceLifecyclePublisher(publish: (input: SessionResourceLifecyclePublishInput) => void): void;
+    private publishLifecycleEvent;
+    /**
+     * Durability gate for lifecycle transitions: persist the copy-on-write
+     * snapshot first (saveNow rejects on write failure, so the live state, chat
+     * contexts and event stream all stay untouched), then publish the persisted
+     * snapshot to the runtime state. Only after this resolves may the lifecycle
+     * event be emitted.
+     */
+    private commitLifecycleTransition;
     setArchived(alias: string, archived: boolean): Promise<void>;
     removeSession(alias: string): Promise<{
         wasActive: boolean;

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

@@ -12,6 +12,12 @@ export interface StateLoadDroppedRecord {
 }
 export interface StateLoadReport {
     dropped: StateLoadDroppedRecord[];
+    /**
+     * Legacy session records that were assigned a fresh logical_session_id
+     * during load. Kept separate from {@link dropped}: a migrated record is
+     * healthy and survives, a dropped record is corrupt and was removed.
+     */
+    migrated?: StateLoadDroppedRecord[];
     /** Backup copy of the original file, written because records were dropped. */
     quarantinePath?: string;
     /** Unreadable original renamed aside (whole-file JSON corruption). */
@@ -19,6 +25,12 @@ export interface StateLoadReport {
     /** Best-effort backup/rename failure; load still returned the cleaned state. */
     backupError?: string;
 }
+/**
+ * A logical_session_id is always a UUIDv4 (randomUUID). Present-but-invalid
+ * values are treated as corruption and quarantined with the record; only a
+ * genuinely MISSING field (legacy record) enters the load-time migration.
+ */
+export declare function isLogicalSessionId(value: unknown): value is string;
 /**
  * Lenient state parser: a malformed record (or wrong-typed section) is skipped
  * and collected in `dropped` instead of throwing, so one bad record can never
@@ -27,7 +39,7 @@ export interface StateLoadReport {
  * non-object top level still throws (StateStore.load treats that as a corrupt
  * file and renames it aside).
  */
-export declare function parseState(raw: unknown, path: string, dropped?: StateLoadDroppedRecord[]): AppState;
+export declare function parseState(raw: unknown, path: string, dropped?: StateLoadDroppedRecord[], migrated?: StateLoadDroppedRecord[]): AppState;
 export interface StateStoreOptions {
     /** Injectable clock used for quarantine/corrupt backup file names. */
     now?: () => Date;
@@ -37,6 +49,11 @@ export interface StateStoreOptions {
      * writer suffix-retries instead of overwriting an existing backup).
      */
     writeBackup?: (targetPath: string, content: string) => Promise<string | void>;
+    /**
+     * Injectable durable writer for the legacy logical_session_id migration
+     * (tests simulate write failures). Defaults to the regular atomic save.
+     */
+    writeMigration?: (state: AppState) => Promise<void>;
 }
 /** Result of a side-effect-free {@link StateStore.inspect}. */
 export interface StateLoadInspection {
@@ -56,11 +73,13 @@ export declare class StateStore {
      */
     get lastLoadReport(): StateLoadReport | null;
     load(): Promise<AppState>;
+    /** Synchronous (awaited) atomic write of a migrated state, via the private-file writer. */
+    private persistMigration;
     /**
      * Side-effect-free variant of load() for diagnostic callers (doctor): parses
-     * and reports exactly what load() would drop/repair, but never writes a
-     * quarantine backup, never renames a corrupt file, and does not touch
-     * {@link lastLoadReport}.
+     * and reports exactly what load() would drop/repair/migrate, but never writes
+     * a quarantine backup, never renames a corrupt file, never persists pending
+     * logical_session_id migrations, and does not touch {@link lastLoadReport}.
      */
     inspect(): Promise<StateLoadInspection>;
     private readAndParse;

package/dist/state/types.d.ts

@@ -20,6 +20,14 @@ export interface LogicalSession {
     agent: string;
     workspace: string;
     transport_session: string;
+    /**
+     * Immutable identity of this logical session (UUIDv4), assigned once at
+     * create/attach time. Never changes across rename, display-name, agent,
+     * workspace, or transport-binding updates; never reused after the alias is
+     * deleted. Legacy records missing the field are migrated once at load time
+     * and persisted before startup proceeds.
+     */
+    logical_session_id: string;
     source?: LogicalSessionSource;
     agent_session_id?: string;
     agent_session_title?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganglion/xacpx",
-  "version": "0.20.3",
+  "version": "0.22.0",
   "description": "随时随地通过聊天频道（微信 / 飞书 / 元宝等）远程控制 `acpx` 上的 Claude Code、Codex 等 Agents。",
   "keywords": [
     "acpx",
@@ -54,6 +54,7 @@
     "build:relay": "bun run build:relay-web && bun run clean:relay && bun build ./packages/relay/src/cli.ts --outdir ./packages/relay/dist --target node --external ws --external hono --external @hono/node-server --external @ganglion/xacpx-relay-protocol && tsc -p packages/relay/tsconfig.json && bun run bundle:relay-web",
     "clean:channel-relay": "node -e \"require('node:fs').rmSync('packages/channel-relay/dist', { recursive: true, force: true })\"",
     "build:channel-relay": "bun run build:plugin-api && bun run build:relay-protocol && bun run clean:channel-relay && bun build ./packages/channel-relay/src/index.ts --outdir ./packages/channel-relay/dist --target node --external xacpx --external ws --external @ganglion/xacpx-relay-protocol && tsc -p packages/channel-relay/tsconfig.json",
+    "pack:rmux-bridge": "node ./scripts/pack-rmux-bridge-platform.mjs",
     "clean:relay-web": "node -e \"require('node:fs').rmSync('packages/relay-web/dist',{recursive:true,force:true})\"",
     "build:relay-web": "bun run build:relay-protocol && bun run clean:relay-web && bun run --cwd packages/relay-web build",
     "test:web": "bun run --cwd packages/relay-web test",