qlogicagent 2.19.1 → 2.19.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlogicagent",
-  "version": "2.19.1",
+  "version": "2.19.2",
   "description": "XiaozhiClaw Agent CLI — subprocess architecture (JSON-RPC over stdio)",
   "type": "module",
   "main": "dist/index.js",
@@ -60,6 +60,10 @@
       "types": "./dist/types/host-contract/index.d.ts",
       "default": "./dist/host-contract.js"
     },
+    "./host-session-collection-contract": {
+      "types": "./dist/types/host-session-collection-contract.d.ts",
+      "default": "./dist/host-session-collection-contract.js"
+    },
     "./plugin-marketplace-compute": {
       "types": "./dist/types/skills/plugins/plugin-marketplace.d.ts",
       "default": "./dist/plugin-marketplace-compute.js"
@@ -106,6 +110,9 @@
       "host-contract": [
         "./dist/types/host-contract/index.d.ts"
       ],
+      "host-session-collection-contract": [
+        "./dist/types/host-session-collection-contract.d.ts"
+      ],
       "plugin-marketplace-compute": [
         "./dist/types/skills/plugins/plugin-marketplace.d.ts"
       ]

package/dist/types/cli/agent-config-coordinator.d.ts

@@ -1,27 +0,0 @@
-import { AgentConfigStore } from "../runtime/infra/agent-config-store.js";
-import type { AcpDetector } from "../runtime/infra/acp-detector.js";
-export interface AgentConfigCoordinatorDeps {
-    acpDetector: AcpDetector;
-    getActiveProjectRoot(): string;
-}
-export declare function resolveLlmrouterPublicOrigin(rawBaseUrl?: string): string | undefined;
-export declare function resolveLlmrouterProtocolBaseUrl(agentId: string, rawBaseUrl?: string): string | undefined;
-export declare class AgentConfigCoordinator {
-    private readonly deps;
-    private store;
-    /** Last resolved managed text model (llmrouterModel), to detect primary-model switches. */
-    private lastLlmrouterModel;
-    constructor(deps: AgentConfigCoordinatorDeps);
-    get currentStore(): AgentConfigStore | null;
-    ensureStore(): Promise<AgentConfigStore>;
-    private syncKeySources;
-    /**
-     * When the managed text model (llmrouterModel) actually changes, pooled OpenAI-compat agents
-     * (codex/qwen/opencode) still hold the OLD OPENAI_MODEL baked at spawn. Evict the platform-model
-     * followers — managed (explicit「平台额度」) or auto, NOT explicit account/userKey BYO — so the next
-     * turn respawns on the new model. The model-switch analogue of the credential-switch eviction (Cut 6);
-     * busy turns settle first (handled inside evictPooledAgentsByAgentId). Runs per agents operation via
-     * syncKeySources, so a primary-model switch takes effect on the next message.
-     */
-    private evictModelFollowersIfChanged;
-}

package/dist/types/cli/agent-config-runtime.d.ts

@@ -1,11 +0,0 @@
-import type { AgentConfigStore } from "../runtime/infra/agent-config-store.js";
-import type { AcpDetector } from "../runtime/infra/acp-detector.js";
-export interface AgentConfigRuntime {
-    readonly currentStore: AgentConfigStore | null;
-    ensureStore(): Promise<AgentConfigStore>;
-}
-export interface AgentConfigRuntimeDeps {
-    acpDetector: AcpDetector;
-    getActiveProjectRoot(): string;
-}
-export declare function createAgentConfigRuntime(deps: AgentConfigRuntimeDeps): AgentConfigRuntime;

package/dist/types/cli/agent-status-notifier.d.ts

@@ -1,11 +0,0 @@
-import type { AgentsStatusNotification } from "../protocol/notifications.js";
-export interface AgentStatusExtra {
-    missedBeats?: number;
-    lastActivityAt?: number;
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
-}
-export declare function createAgentStatusNotification(agentId: string, state: string, extra?: AgentStatusExtra): AgentsStatusNotification;

package/dist/types/cli/handlers/agents-handler.d.ts

@@ -1,126 +0,0 @@
-/**
- * Agents scan/config/gateway/processes/kill handlers — extracted from StdioServer.
- * Handles: agents.scan, agents.list, agents.config, agents.setConfig, agents.getConfig,
- *          agents.removeConfig, agents.setGateway, agents.getGateway, agents.processes,
- *          agents.kill, agents.listConfigured, agents.getLog, agents.testConnection
- */
-import { type AgentRpcError, type AgentRpcRequest } from "../../protocol/wire/index.js";
-import type { AgentConfigStore } from "../../runtime/infra/agent-config-store.js";
-import { type AcpDetector } from "../../runtime/infra/acp-detector.js";
-import type { DelegateBridge } from "../../orchestration/delegation-coordinator.js";
-import type { AgentDescriptor } from "../../protocol/wire/acp-agent-management.js";
-export declare function refreshInstalledAgentDetection(detector: AcpDetector, agentId: string): Promise<{
-    descriptor: AgentDescriptor;
-    ready: boolean;
-}>;
-export interface AgentsHandlerHost {
-    acpDetector: AcpDetector;
-    ensureAgentConfigStore(): Promise<AgentConfigStore>;
-    getActiveProjectRoot?(): string;
-    handleMcpToolCall?(memberId: string, tool: string, args: Record<string, unknown>): Promise<unknown>;
-    log?(message: string): void;
-    sendResponse(id: string | number, result?: unknown, error?: AgentRpcError): void;
-    sendNotification?(method: string, params: Record<string, unknown>): void;
-    /** 激活层(S3c §1.1):gateway-routed delegate 桥(懒读;未挂/gate 关 = undefined → 旧进程池路径)。 */
-    getDelegateBridge?(): DelegateBridge | undefined;
-}
-interface PooledTurnCtx {
-    sessionId?: string;
-    turnId?: string;
-    requestId?: string;
-    deltas: string[];
-    streamedAny: boolean;
-}
-export declare function relayPooledTurnNotification(input: {
-    agentId: string;
-    turn: PooledTurnCtx | null;
-    method: string;
-    payload: unknown;
-    sendNotification?: (method: string, params: Record<string, unknown>) => void;
-}): void;
-/** Resolve a pending external-agent approval with the user's decision (delivered by the gateway). */
-export declare function handleAgentsApprovalResponse(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsScan(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsList(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-/**
- * Curated Discover-Agent catalog (12 agents) merged with live install status, for the
- * discover grid. Status comes from the detector; install carries the official command
- * summary + source for the confirm dialog (no secrets).
- */
-export declare function handleAgentsCatalog(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsCheckUpdates(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-/**
- * One-click install a catalog agent by id. Runs ONLY the official command from the
- * catalog manifest (never a free-form command), streaming progress via the
- * agent.install.progress notification, then refreshes detection. Returns the outcome.
- */
-export declare function handleAgentsInstall(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-/**
- * Open an OS terminal running an agent's interactive login/setup command (e.g. `kimi login`,
- * `hermes acp --setup`). Lowers the barrier for own-store/oauth agents that can't be driven via
- * injected credentials — the user completes the CLI's native login without leaving the app. The
- * command is resolved server-side from the catalog (fixed string, no user input → no injection).
- */
-export declare function handleAgentsRunSetup(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsConfig(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsSetConfig(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsGetConfig(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsRemoveConfig(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-/**
- * Log out / switch account for an `account`-mode agent: clear the CLI's own native credential store
- * (where we know it — e.g. codex's ~/.codex/auth.json) and invalidate the resident pool so the next
- * turn re-evaluates auth (and re-prompts login). For agents whose store we don't manage, returns a
- * hint to run the CLI's own `logout`. "Switch account" = logout, then log in again.
- */
-export declare function handleAgentsLogout(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsSetGateway(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsGetGateway(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsListConfigured(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsGetLog(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsTestConnection(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-/** Formats a session persisted transcript into a compact prior-conversation block for an external
- *  ACP agent that was cold-spawned (fresh process, empty session). Mirrors the built-in agent
- *  withResumedHistory: the engine on-disk history is authoritative, so we re-supply it and the agent
- *  regains full context after a restart/eviction. Only user/assistant text turns are included;
- *  returns "" when there is no prior history (e.g. the first turn of a new session). */
-export declare function buildExternalHistoryPreamble(messages: Array<{
-    role: string;
-    content: unknown;
-}>): string;
-/** Wraps the owner-level global memory cheat sheet (preferences/boundaries) for an external
- *  agent's cold open. Third-party agents (codex/claude/...) run their own brains and never see
- *  our per-turn memory channel — without this, a user's standing preferences vanish the moment
- *  they switch agents. Injection frequency is ONCE PER PROCESS CONTEXT: it rides the same
- *  cold-spawn moment that (re)builds the agent's context (first turn of a session, or a respawn
- *  after restart/eviction — where the full history is re-sent anyway), and never on warm turns.
- *  That is the floor for a stateless external process, not a per-message tax. Size is capped by
- *  readUserIndexForPrompt itself (2048 chars / 40 lines, visible truncation marker). */
-export declare function buildExternalMemoryPreamble(globalIndex: string | null): string;
-/**
- * Decide how a native-cwd session resumes on a COLD spawn, and whether that resume already carries
- * our injected global memory sheet (so the caller can skip re-injecting it). Pure given its inputs.
- *
- *  - BINDING resume (a `nativeBinding.nativeSessionId` persisted by a prior app turn): that prior
- *    turn injected the sheet into the prompt codex/claude recorded in its OWN rollout, so the
- *    restored context carries it → resumedFromBinding=true (skip re-inject).
- *  - LAZY-MIGRATION resume (no binding yet, but the canonical id exists in the native store — a
- *    session the user may have started in codex/claude directly): its rollout has NEVER seen our
- *    sheet → resumedFromBinding=false (inject once; after this turn the binding persists and
- *    subsequent resumes take the binding branch, injecting exactly once total).
- *  - Neither (brand-new session): no resume → inject as a normal cold open.
- *
- * Conflating binding with lazy-migration (resume===bound) silently starves migrated sessions of the
- * user's preferences — the whole point of the injection is that they follow the user across agents.
- */
-export declare function resolveNativeColdResume(input: {
-    sessionId: string;
-    boundNativeSessionId: string | undefined;
-    nativeSessionExists: () => Promise<boolean>;
-}): Promise<{
-    effectiveResume: string | undefined;
-    resumedFromBinding: boolean;
-}>;
-/** Pre-warm an external agent's process (on agent-select) so the first message skips the cold start. */
-export declare function handleAgentsWarm(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleAgentsPrompt(this: AgentsHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export {};

package/dist/types/cli/handlers/project-handler.d.ts

@@ -1,36 +0,0 @@
-/**
- * Project CRUD handlers extracted from StdioServer.
- * Handles: project.create, project.list, project.delete, project.rename,
- *          project.archive, project.unarchive
- */
-import { type AgentRpcError, type AgentRpcRequest } from "../../protocol/wire/index.js";
-import type { ProjectMemoryStore, ProjectMemoryStoreFactory } from "../../runtime/ports/index.js";
-export interface ProjectHandlerHost {
-    memdir: ProjectMemoryStore | null;
-    projectMemoryStoreFactory: ProjectMemoryStoreFactory;
-    mediaPersistence: {
-        setProjectDir(projectDir: string): void;
-        releaseProjectDir?(projectDir: string): void;
-    };
-    getActiveProjectRoot(): string;
-    setActiveWorkdir(dir: string): void;
-    sendNotification(method: string, params: Record<string, unknown>): void;
-    sendResponse(id: string | number, result?: unknown, error?: AgentRpcError): void;
-}
-export declare function handleProjectCreate(this: ProjectHandlerHost, msg: AgentRpcRequest): Promise<void>;
-export declare function handleProjectList(this: ProjectHandlerHost, msg: AgentRpcRequest): void;
-export declare function handleProjectSwitch(this: ProjectHandlerHost, msg: AgentRpcRequest): Promise<void>;
-/**
- * Reliable recursive directory removal for Windows. fs.rmSync({recursive,force}) cannot be trusted
- * here: on git repos it silently leaves read-only object/pack files (and whole subtrees) behind
- * without throwing. This walks bottom-up, clearing the read-only attribute (chmod) on the EPERM
- * retry, which deletes git worktrees/repos cleanly. Per-entry failures (e.g. a live EBUSY lock) are
- * swallowed; the caller verifies via existsSync and decides success/retry.
- */
-export declare function rmDirRobustSync(target: string): void;
-export declare function handleProjectDelete(this: ProjectHandlerHost, msg: AgentRpcRequest): void;
-export declare function handleProjectPurgeAll(this: ProjectHandlerHost, msg: AgentRpcRequest): void;
-export declare function handleProjectRename(this: ProjectHandlerHost, msg: AgentRpcRequest): void;
-export declare function handleProjectArchive(this: ProjectHandlerHost, msg: AgentRpcRequest): void;
-export declare function handleProjectUnarchive(this: ProjectHandlerHost, msg: AgentRpcRequest): void;
-export declare function handleProjectUpdate(this: ProjectHandlerHost, msg: AgentRpcRequest): void;

package/dist/types/cli/project-command-service.d.ts

@@ -1,28 +0,0 @@
-import type { ProjectInfo } from "../protocol/methods.js";
-import type { ProjectMemoryStore, ProjectMemoryStoreFactory } from "../runtime/ports/index.js";
-export interface ProjectCommandHost {
-    memdir: ProjectMemoryStore | null;
-    projectMemoryStoreFactory: ProjectMemoryStoreFactory;
-    mediaPersistence: {
-        setProjectDir(projectDir: string): void;
-    };
-    setActiveWorkdir(dir: string): void;
-}
-export interface ProjectCreateCommand {
-    name: string;
-    workspaceDir?: string;
-    type?: string;
-    groupId?: string;
-}
-export interface ProjectCreateResult {
-    project: ProjectInfo;
-    nameDuplicate?: ProjectInfo;
-    isAgentTeamProject: boolean;
-    /** True when creation switched the active project (container types never switch). */
-    autoSwitched: boolean;
-    deduplicated?: boolean;
-}
-type ProjectPlanStatus = NonNullable<ProjectInfo["planStatus"]>;
-export declare function isProjectPlanStatus(value: unknown): value is ProjectPlanStatus;
-export declare function createProject(host: ProjectCommandHost, command: ProjectCreateCommand): Promise<ProjectCreateResult>;
-export {};

package/dist/types/orchestration/delegation-coordinator.d.ts

@@ -1,100 +0,0 @@
-import type { ProductOrchestrator } from "./agent-instance.js";
-import type { DelegateRequestParams, SupervisorEventSink, TurnResult } from "../host-contract/index.js";
-/**
- * 激活层(S3c):gateway-routed delegate 传输桥(解耦接口;wire 从 AcpServer.delegate/supportsDelegate 供)。
- * hostSupportsDelegate(=gateway 在 initialize 声明 delegate 能力位)时,run() 改走此桥:leader 请网关代派
- * worker 回合(x/delegate),事件回流经 sink,resolve 统一 TurnResult —— 不再 ProductOrchestrator.create
- * 本地 spawn。gate 关(gateway 未声明)= isSupported()=false = 旧路径保留(单轨,zero-regression)。
- */
-export interface DelegateBridge {
-    /** T9:gateway 声明 delegate 能力才放行(否则旧 ProcessManager/Orchestrator 路径)。 */
-    isSupported(): boolean;
-    /** 上行 x/delegate(resolve TurnResult;回流事件经 sink)。 */
-    send(params: DelegateRequestParams, sink: SupervisorEventSink): Promise<TurnResult>;
-    /** x/delegate.cancel(取消回合,不杀进程;rec.abort 触发时调)。 */
-    cancel(delegationId: string): void;
-    /**
-     * x/delegate.respond(leader 来源审批应答,通知 fire-and-forget;optionId 不透明透传 E2)。
-     * 站点收到 sink.onApprovalRequest 后按用户/策略决议经此应答(chat 站 §1.1 审批往返;
-     * gateway 侧 delegate-server → supervisor.respondApproval,freeze §11 补遗#3 唯一应答口)。
-     */
-    respond(delegationId: string, approvalId: string, optionId: string): void;
-}
-export interface DelegationNotify {
-    (method: string, payload: Record<string, unknown>): void;
-}
-export interface DelegationDeps {
-    orchestrator: ProductOrchestrator;
-    cwd: string;
-    notify: DelegationNotify;
-    log?: {
-        info(m: string): void;
-        warn(m: string): void;
-    };
-    /**
-     * 激活层(S3c):gateway-routed delegate 传输 + 会话上下文(可选;缺省 = 旧 ProductOrchestrator 路径)。
-     * bridge.isSupported()=true(gateway 声明 delegate 能力位)时,run() 改走 gateway 代派 worker;否则旧路径。
-     * projectId = deriveProjectId(cwd)(wire 供,避免 coordinator import agent-paths;单轨解析权威在会话面)。
-     */
-    delegate?: {
-        bridge: DelegateBridge;
-        projectId: string;
-    };
-}
-type DelegationStatus = "running" | "completed" | "failed" | "cancelled" | "timed_out";
-export declare class DelegationCoordinator {
-    private readonly deps;
-    private readonly active;
-    /** Per-(chat×agent) tail promise — the next same-conversation delegation chains after it so they run
-     *  strictly sequentially (single writer to the shared reused worktree + native session). One entry per
-     *  active (chat×agent) pair (keyed, overwritten — not per-delegation), so it stays bounded. */
-    private readonly convChains;
-    /** Per-(chat×agent) native (codex/claude) session id — the background analogue of the foreground U5
-     *  convergence. Seeded from the first delegation's captured session id; passed as resumeNativeSessionId on
-     *  every subsequent same-conversation delegation so context accumulates (git AND non-git projects).
-     *  In-memory (one entry per active pair); an engine restart resets it → the next delegation starts fresh,
-     *  same as a cold foreground turn whose pool was evicted. */
-    private readonly nativeSessions;
-    constructor(deps: DelegationDeps);
-    /** Active + recent delegations for this project (x/mention.list). */
-    list(): {
-        delegationId: string;
-        agentId: string;
-        brief: string;
-        status: DelegationStatus;
-    }[];
-    /** Cancel a running delegation — aborts the poll loop, which drains+kills the worker. */
-    cancel(delegationId: string): {
-        ok: boolean;
-    };
-    /**
-     * Dispatch ONE ad-hoc task to `agentId` in the background. Returns immediately with the delegationId;
-     * the lifecycle (started / settled) is reported via notify(mention.*). An unready/uninstalled agent
-     * surfaces as a `failed` settle (never a thrown RPC).
-     */
-    delegate(agentId: string, brief: string, opts: {
-        canonicalSessionId: string;
-        acceptanceCriteria?: string;
-        delegationId?: string;
-    }): {
-        delegationId: string;
-    };
-    private run;
-    /**
-     * 激活层(S3c):gateway-routed delegate 路径 —— 不本地 spawn,请网关代派一个 worker 回合。
-     * leader 铸 delegationId(rec.delegationId 已是 `del-*`,承 Q4「leader 铸 + gateway 校验唯一」);
-     * 回流 sink 把 worker 工具活动转 mention.delegate_activity(live 进度),final 由 TurnResult 承。
-     * 与旧路径行为对齐:started/settled 通知、cancel 语义(rec.abort → x/delegate.cancel)、convChain 串行不变。
-     *
-     * native session 累积(跨同会话委派的 resume)在此路径由 gateway SessionProjectService.recordNativeSessionId
-     * 于 relay 观察点回填(freeze §11 补遗#2)—— coordinator 不再本地捕获 getDelegationNativeSessionId(单轨,权威上移)。
-     */
-    private runViaDelegate;
-    /** Collect a delegation's produced artifacts: the union of the worktree diff (tasks[].changedFiles,
-     *  omitted by the wire type but carried at runtime) and the mtime-isolated capture of project-root files
-     *  (for workers that write straight to the workspace), plus the worker task + terminal phase. Shared by
-     *  the normal terminal path AND the timeout path, so a timed-out run still hands back its partial output. */
-    private collectProducts;
-    private settle;
-}
-export {};

package/dist/types/runtime/infra/acp-detector.d.ts

@@ -1,273 +0,0 @@
-/**
- * ACP Agent Detector — scans PATH for installed ACP-compatible CLI agents.
- *
- * Uses `which` (Unix) / `where` (Windows) to locate CLI binaries,
- * then optionally probes version. Results are cached with TTL.
- *
- * Reference: AionUI AcpDetector + ACP_BACKENDS_ALL registry.
- */
-import type { AcpBackendConfig, AgentDescriptor, CustomAgentDef, AgentConfigStoreData, AuthPreference } from "../../protocol/wire/acp-agent-management.js";
-export declare const ACP_BACKENDS: Record<string, AcpBackendConfig>;
-export declare const AGENT_CATALOG_IDS: readonly ["claude", "codex", "gemini", "copilot", "cursor", "qwen", "kimi", "glm", "opencode", "kiro", "qoder", "openclaw", "hermes"];
-/** Merged catalog entry (base ACP config + grid/install metadata) for one id. */
-export declare function getCatalogEntry(id: string): AcpBackendConfig | undefined;
-/** Ordered curated catalog: base ACP config merged with grid/install metadata. */
-export declare function getAgentCatalog(): AcpBackendConfig[];
-export declare function buildInternalAgentDescriptors(): AgentDescriptor[];
-export declare function resolveWindowsCopilotLoader(): string | null;
-export declare function getNpmInstallPackageName(command: string | undefined): string | null;
-export declare function compareSemverVersions(a: string, b: string): number;
-export declare function isVersionNewer(latest: string | null | undefined, current: string | null | undefined): boolean;
-export declare function readGlobalNpmPackageVersion(packageName: string | null | undefined): string | null;
-export declare function resolveInstalledNpmPackageVersionFromInstall(install: AcpBackendConfig["install"] | undefined): string | null;
-export declare function getCatalogInstalledVersion(entry: AcpBackendConfig, detectedVersion?: string): string | undefined;
-/** Resolve a package's latest published version via `npm view` (async + cached). Used by the background
- *  update check so N agents resolve concurrently (one `npm view` each) instead of blocking sequentially. */
-export declare function fetchNpmLatestPackageVersionAsync(packageName: string | null | undefined, registry?: string): Promise<string | null>;
-export interface CatalogUpdateInfo {
-    id: string;
-    packageName?: string;
-    installedVersion?: string;
-    latestVersion?: string;
-    updateAvailable: boolean;
-}
-/**
- * Resolve latest-version / update-available info for the catalog's INSTALLED agents, all in PARALLEL
- * (one concurrent `npm view` per package). Non-installed agents are skipped (nothing to update).
- * Returns only entries where a latest version was resolved. Safe to call off the catalog hot path.
- */
-export declare function getCatalogUpdateInfoAsync(entries: ReadonlyArray<{
-    id: string;
-    entry: AcpBackendConfig;
-    detectedVersion?: string;
-}>, registry?: string): Promise<CatalogUpdateInfo[]>;
-/**
- * Synchronous, NETWORK-FREE update info read straight from the persisted cache (disk-seeded on first
- * use). Returns immediately so the panel lights up last-known badges INSTANTLY — VS Code's gallery
- * pattern — without waiting on `npm view`. `stale` is true when any installed package's cached "latest"
- * is missing, errored, or older than the TTL; the caller then refreshes via getCatalogUpdateInfoAsync
- * in the background, and the next call serves the fresh value.
- */
-export declare function getCatalogUpdateInfoCached(entries: ReadonlyArray<{
-    id: string;
-    entry: AcpBackendConfig;
-    detectedVersion?: string;
-}>, registry?: string): {
-    updates: CatalogUpdateInfo[];
-    stale: boolean;
-};
-export declare function normalizeWindowsAcpCommand(cliPath: string, args: string[]): {
-    cliPath: string;
-    acpArgs: string[];
-};
-/**
- * Build the spawn env for an external ACP backend.
- *
- * Maps the agent-config's portable `apiKey`/`baseUrl` onto the backend-declared
- * environment-variable names (`apiKeyEnvVar`/`baseUrlEnvVar`) so a user who only
- * configures an API key + base URL (e.g. via agents.setConfig) actually drives the
- * underlying CLI with a third-party OpenAI/Anthropic-compatible gateway — no official
- * account login required. Without this mapping the backends declared the env-var names
- * but nothing ever populated them.
- *
- * Precedence (lowest → highest), so explicit user input always wins:
- *   1. backend.env            (static backend defaults)
- *   2. mapped apiKey/baseUrl  (config.apiKey → backend.apiKeyEnvVar, etc.)
- *   3. customConfig.env       (raw env the user hand-entered)
- *
- * Injection is conditional: the apiKey/baseUrl mapping only fires when the backend
- * actually declares the corresponding envVar name (so we never invent a var the CLI
- * does not read). Returns undefined when there is nothing to inject, preserving the
- * prior `env?: undefined` behavior for un-configured backends.
- */
-export declare function buildBackendEnv(backend: AcpBackendConfig | undefined, customConfig: import("../../protocol/wire/acp-agent-management.js").AgentConfig | undefined, autoEnv?: Record<string, string>): Record<string, string> | undefined;
-/** Unified key sources for login-free catalog injection (wired by the runtime). */
-export interface CatalogKeySources {
-    /** Gateway-issued inference key (sk-qllm) for keySource:"llmrouter". */
-    llmrouterKey?: string;
-    /** Base URL an llmrouter-routed agent should call (our gateway endpoint). */
-    llmrouterBaseUrl?: string;
-    /** Resolve an agent/protocol-specific LLMRouter base URL. */
-    getLlmrouterBaseUrl?: (agentId: string, entry: AcpBackendConfig) => string | null | undefined;
-    /** Default LLMRouter model for agent CLIs that require an explicit model pin. */
-    llmrouterModel?: string;
-    /** Resolve a provider's direct third-party key for keySource:"direct". */
-    getDirectKey?: (providerId: string) => string | null | undefined;
-    /** The host's active text-generation model (deepseek / volcengine / …) to "pass through" to
-     *  OpenAI-compatible spawned agents (codex/qwen/opencode) that resolve no key of their own — so
-     *  they run on the configured key+baseUrl+model with zero per-agent credentials. */
-    passthroughModel?: {
-        apiKey: string;
-        baseUrl?: string;
-        model?: string;
-    };
-    /** Probe: does this agent have a usable native account/subscription login (e.g. ~/.codex/auth.json,
-     *  present + not expired)? Drives `account`-mode readiness and `auto`'s account-first preference.
-     *  Tri-state: true = detected login, false = probeable but not logged in (blocks readiness), undefined
-     *  = no probe for this agent (treated as ready-if-installed; auto does NOT pick account). Wired in Cut 4. */
-    hasSubscription?: (agentId: string) => boolean | undefined;
-}
-/** Resolve the effective mode, coercing unsupported combinations (claude.account → auto). */
-export declare function effectiveAuthPreference(entry: AcpBackendConfig, mode: AuthPreference): AuthPreference;
-/**
- * The credential-source modes the UI should offer for an agent (derived from catalog metadata, the
- * single source of truth — spec §4.2/§8.2/§15). Never includes a permanently-dead option:
- *   - oauth / keyless (copilot/cursor/kimi/…): ["account"] only (no gateway endpoint to repoint)
- *   - claude (Anthropic bans subscription): ["managed","userKey"] — no account
- *   - codex (llmrouter + account-capable): ["account","userKey","managed"]
- *   - other llmrouter agents: ["userKey","managed"]
- *   - direct agents (qwen/glm/…): ["userKey"] (managed wiring for qwen/opencode is Cut 7)
- */
-export declare function getAvailableAuthModes(entry: AcpBackendConfig): AuthPreference[];
-/**
- * Resolve the login-free key env for a catalog agent, honoring the per-agent `authPreference`.
- *   - "account" → {} (inject nothing; the spawn layer also deletes the forwarded key, see resolveSuppressEnvKeys)
- *   - "userKey" → the user's own provider key against the official endpoint (no gateway baseUrl/model)
- *   - "managed" → force the gateway sk-qllm + baseUrl (ignores any user key) — guarantees a first conversation
- *   - "auto"    → ladder: user's own key (if present) → managed gateway → host-model passthrough
- * oauth / keyless agents never get a key injected. Only emits env vars the backend declares.
- */
-export declare function resolveCatalogKeyEnv(entry: AcpBackendConfig | undefined, sources: CatalogKeySources, mode?: AuthPreference): Record<string, string>;
-/**
- * Env var names the spawn layer must DELETE from the merged child env (account mode), so a
- * forwarded/stale shell key cannot override the CLI's own native login. This is the load-bearing
- * half of the §1.3 override-bug fix: buildBackendEnv alone cannot unset a whitelist-forwarded key.
- * Returns [] when not in account mode (or the agent has no account path — claude is coerced to auto).
- */
-export declare function resolveSuppressEnvKeys(entry: AcpBackendConfig | undefined, mode: AuthPreference, sources?: CatalogKeySources): string[];
-/**
- * Build a backend's descriptor from already-resolved cliPath/version (+ the caller-resolved
- * hasConfig flag). Shared by AcpDetector's sync and async detection paths so they can never drift
- * (status rules, copilot's version-required gate, etc.) — extracted to a standalone, IO-free, pure
- * function (not a class method) so it is directly unit-testable without spawning a real CLI.
- *
- * sessionHistory (Task 1.2, third-party native session discovery): "native-cwd" only for an
- * INSTALLED (status "available") codex or claude backend — the two agents whose native CWD-scoped
- * session stores we've actually adapted to. Every other case — not-installed codex/claude, any other
- * backend regardless of install state — falls back to "own". Unadapted agents ALWAYS get "own"; this
- * is a hard invariant, not a default that later widens implicitly.
- */
-export declare function assembleBackendDescriptor(backend: AcpBackendConfig, cliPath: string | null, version: string | null, hasConfig: boolean): AgentDescriptor;
-/** Build a user-registered custom agent's descriptor. Extracted to a standalone, IO-free, pure
- *  function for the same testability reason as {@link assembleBackendDescriptor}. Custom agents are
- *  never adapted for native session discovery — regardless of what id/name the user gives them —
- *  so sessionHistory is always "own" (the hard own-by-default invariant). */
-export declare function assembleCustomAgentDescriptor(custom: CustomAgentDef, cliPath: string | null, hasConfig: boolean): AgentDescriptor;
-export declare class AcpDetector {
-    private cache;
-    /** Last scan that COMPLETED, surviving clearCache() and failed rescans. list() prefers this
-     *  over an empty [] so a transient probe failure never reads as "no agents installed". */
-    private lastGoodScan;
-    private configStore;
-    private keySources;
-    /** Shared in-flight async scan so concurrent scanAsync() callers (startup warm + a racing RPC)
-     *  collapse onto ONE scan instead of each spawning its own probe storm. Cleared when it settles. */
-    private scanInFlight;
-    private scanInFlightGeneration;
-    private cacheGeneration;
-    /**
-     * Provide the config store data so detector can populate `hasConfig` field
-     * and include user-registered custom agents.
-     */
-    setConfigStore(data: AgentConfigStoreData): void;
-    /** Wire the unified key sources for login-free catalog injection. */
-    setKeySources(sources: CatalogKeySources): void;
-    /**
-     * Scan for installed ACP agent CLIs.
-     * @param force - Clear cache and re-scan.
-     */
-    scan(force?: boolean): AgentDescriptor[];
-    /**
-     * Async, NON-BLOCKING twin of {@link scan}. Probes every backend CONCURRENTLY off the event loop
-     * (async `where`/`which` + version probes), so the engine's single-threaded loop keeps servicing
-     * ACP requests while detection runs — fixing the bug where a cold synchronous scan (11–18s here,
-     * 60s+ with more/slower CLIs) starved an already-dispatched `x/product.confirm` until it tripped
-     * the UI's 60s timeout. Populates the SAME cache as scan(), so a later sync list()/scan(false)
-     * returns instantly. Concurrent callers share one in-flight scan ({@link scanInFlight}).
-     *
-     * @param force - Bypass the fresh-cache short-circuit and re-probe.
-     */
-    scanAsync(force?: boolean): Promise<AgentDescriptor[]>;
-    private runScanAsync;
-    /**
-     * Return cached results without IO. 冷缓存时后台预热（scanAsync）并返回 []，
-     * 绝不在 RPC 路径上同步 scan —— 同步探测（11-18s+）会饿死单线程引擎循环
-     * （x/product.confirm 60s 超时的根因）。调用方按"稍后再查"处理空列表。
-     *
-     * A background-scan failure is reported (console.error), never swallowed: a swallowed
-     * failure made list() return [] forever and downstream (product planning) treated
-     * "scan failed" as "no agents installed". When the fresh cache is gone but an older
-     * scan succeeded, that stale-but-real result is returned instead of [].
-     */
-    list(): AgentDescriptor[];
-    /** Clear the detection cache. */
-    clearCache(): void;
-    private detectBackend;
-    /** Async, NON-BLOCKING twin of {@link detectBackend} — identical detection, async probes. */
-    private detectBackendAsync;
-    private detectCustomAgent;
-    /** Async, NON-BLOCKING twin of {@link detectCustomAgent}. */
-    private detectCustomAgentAsync;
-    private hasAgentConfig;
-    /**
-     * Descriptor for qlogicagent participating in Solo/Product as a self-hosted ACP agent.
-     *
-     * qlogicagent's own CLI speaks ACP by default (cli/main.ts: ACP server unless --no-acp), so a
-     * participant is just another `node <cli.js>` process. The child reads the SAME owner-profile
-     * settings.json (model-registry), so it runs with the configured provider (deepseek / volcengine /
-     * llmrouter) — that is how the configured model "passes through" to every qlogicagent instance,
-     * with no per-agent key. We forward the owner-profile + llmrouter env so the child resolves its
-     * model identically to this (host) process. This lets Solo run N independent qlogicagent sessions
-     * in parallel (each its own worktree) — the core "多个 qlogicagent = 多会话并行" use case.
-     */
-    private buildSelfDescriptor;
-    /**
-     * Build an ExternalAgentDescriptor suitable for Gateway Supervisor resolution.
-     * Returns null if the agent is not available.
-     */
-    buildExternalDescriptor(agentId: string): import("../../protocol/wire/acp-agent-management.js").ExternalAgentDescriptor | null;
-    /**
-     * Async, NON-BLOCKING twin of {@link buildExternalDescriptor} — identical output for the same
-     * detector state, but resolves the agent list via {@link scanAsync} (a real probe, awaited, when
-     * the cache is cold) instead of the sync {@link list}'s cache-or-empty shortcut. Load-bearing for
-     * `agents.warm` (agents-handler.ts): the sync path's detect calls are cache-fronted today, but
-     * that non-blocking guarantee is an implementation detail of `list()` — routing the RPC path
-     * through this method instead makes "never synchronously probe on this path" an explicit
-     * contract that can't silently regress if `list()`'s internals change later.
-     */
-    buildExternalDescriptorAsync(agentId: string): Promise<import("../../protocol/wire/acp-agent-management.js").ExternalAgentDescriptor | null>;
-    /** Shared descriptor-assembly logic for {@link buildExternalDescriptor} and
-     *  {@link buildExternalDescriptorAsync} — everything AFTER "locate this agentId's AgentDescriptor
-     *  in an already-resolved list", so the sync/async twins can never drift on behavior, only on how
-     *  they obtain `agents`. */
-    private assembleExternalDescriptorFromAgents;
-    /**
-     * Whether an agent is ready to compete in Solo/Product: installed/available AND configured.
-     * qlogicagent self-resolves from the owner profile (always ready). External agents need a usable
-     * ACP descriptor (installed) and, for key-auth backends, the key env resolved (configured by the
-     * user on the welcome page). Used by the 启动 pre-check so a race never starts with an agent that
-     * would fail its turn ("No LLM provider"/auth). Does NOT verify the key is *valid* — that's only
-     * known at runtime.
-     */
-    /**
-     * Tri-state native-login state for the credential UI's account label — distinct from isAgentReady.
-     * `true` = a native login/subscription was actually detected (e.g. codex ~/.codex/auth.json); `false`
-     * = probeable but not logged in; `undefined` = no probe for this agent (e.g. hermes' own `acp --setup`
-     * store, which we can't read). isAgentReady treats undefined as ready-if-installed so the CLI gets a
-     * chance to run, but the UI must NOT claim "已登录" on undefined — it just doesn't know.
-     */
-    getNativeLoginState(agentId: string): boolean | undefined;
-    isAgentReady(agentId: string): boolean;
-    /**
-     * Fast-fail guard for the turn path: returns a user-facing error when an agent is in a key-required
-     * credential mode (managed / userKey / auto-resolving-to-key) but NO usable key got injected — so the
-     * caller can reject the turn cleanly instead of spawning a CLI that would silently stall on auth (the
-     * host then goes quiet → the gateway's hang-watchdog kills it → the user sees a cryptic "Agent process
-     * stdio closed"). Returns null when credentialed, or when the mode owns its own native login
-     * (account / oauth / keyless), or when we can't be sure a key is needed.
-     */
-    resolveCredentialError(agentId: string): string | null;
-}
-/** Best-effort resolve the backing model id for an agent (for the planning roster).
- *  Returns the configured/auto model or undefined. No spawn — reads config + auto env only. */
-export declare function resolveAgentModel(detector: AcpDetector, id: string): string | undefined;