qlogicagent 2.17.9 → 2.18.1

package/dist/types/cli/stdio-acp-request-host.d.ts

@@ -6,7 +6,7 @@ import type { CliAcpRequestHandlerHost } from "./cli-acp-request-handler.js";
  * (`this: any`), so members it touches must be forwarded here explicitly;
  * see TURN_PIPELINE_HOST_MEMBERS for the regression-tested list.
  */
-export type StdioAcpRequestHostSource = Pick<CliAcpRequestHandlerHost, "activeTurn" | "acpSessionMeta" | "currentHooks" | "currentSessionId" | "currentTurnId" | "memoryPrefetchState" | "permissionChecker" | "sessionHistory" | "sessionLlmConfig" | "sessionState" | "cancelIdleDreamTimer" | "disposeSessionRuntime" | "enableIdleDream" | "ensureDefaultProject" | "ensureModelRegistryHydrated" | "getActiveProjectRoot" | "log" | "sendNotification" | "setActiveWorkdir"> & {
+export type StdioAcpRequestHostSource = Pick<CliAcpRequestHandlerHost, "activeTurn" | "acpSessionMeta" | "acpSessionMetaBySession" | "currentHooks" | "currentSessionId" | "currentTurnId" | "memoryPrefetchState" | "permissionChecker" | "sessionHistory" | "sessionLlmConfig" | "sessionState" | "cancelIdleDreamTimer" | "disposeSessionRuntime" | "enableIdleDream" | "ensureDefaultProject" | "ensureModelRegistryHydrated" | "getActiveProjectRoot" | "log" | "sendNotification" | "setActiveWorkdir"> & {
     currentModel: string | undefined;
     lastAssistantMessageForExtract: string | undefined;
     lastUserMessageForAutoExtract: string | undefined;

package/dist/types/cli/stdio-rpc-handler-hosts.d.ts

@@ -3,6 +3,9 @@ import type { ModelPurpose } from "../runtime/infra/model-registry.js";
 import type { RpcHandlerHosts } from "./rpc-registry.js";
 type DirectStdioRpcHost = RpcHandlerHosts["config"] & RpcHandlerHosts["control"] & RpcHandlerHosts["files"] & RpcHandlerHosts["skills"] & RpcHandlerHosts["project"] & RpcHandlerHosts["community"] & RpcHandlerHosts["settings"] & RpcHandlerHosts["petConfirm"] & {
     currentTurnId?: string;
+    /** Mid-turn guidance queue (运行中引导) — shared between handleTurnGuide and the tool loop's drain. */
+    pendingTurnGuidance?: string[];
+    getActiveProjectRoot(): string;
     readonly multiAgentHandlerHost: RpcHandlerHosts["multiAgent"];
     readonly workflowHandlerHost: RpcHandlerHosts["workflow"];
 };
@@ -39,6 +42,7 @@ type StdioRpcAdapterSource = DirectStdioRpcHost & {
     sendError: NonNullable<RpcHandlerHosts["session"]["sendError"]>;
     createDreamHandlerHost(): RpcHandlerHosts["dream"];
 };
+export declare function createTurnHost(host: StdioRpcAdapterSource): RpcHandlerHosts["turn"];
 /**
  * Build the per-domain handler-host bundle the RPC registry binds to.
  *

package/dist/types/cli/stdio-server.d.ts

@@ -25,7 +25,7 @@ import { type MultiAgentHandlerHost } from "./multi-agent-handler-host.js";
 import type { WorkflowHandlerHost } from "./handlers/workflow-handler.js";
 import { SessionHistoryCoordinator } from "./session-history-coordinator.js";
 import { PetConfirmCoordinator } from "./pet-confirm-coordinator.js";
-import type { MemoryDreamRuntimeProvider, MemoryHandlerProvider, ProjectMemoryStore } from "../runtime/ports/index.js";
+import type { MemoryDreamRuntimeProvider, MemoryHandlerProvider, PermissionMode, ProjectMemoryStore } from "../runtime/ports/index.js";
 export interface StdioServerConfig {
     verbose: boolean;
     transport?: Transport;
@@ -106,6 +106,13 @@ export declare class StdioServer {
     set currentSessionId(v: string);
     get currentTurnId(): string;
     set currentTurnId(v: string);
+    /**
+     * Mid-turn guidance queue (运行中引导). Reset per turn by runTurnPipeline, pushed by
+     * handleTurnGuide (via the turn host proxy), drained each round by the tool loop.
+     * Declared as a real field so the proxy in createTurnHost has a shared backing store
+     * (turn pipeline and handleTurnGuide must see the SAME array).
+     */
+    pendingTurnGuidance: string[];
     /** LH-10: an explicit cancel of a session stops the background tasks that
      *  session launched — the forked agent + the exec processes it spawned —
      *  instead of leaving them running as zombies. Keyed by session id, which is
@@ -117,9 +124,18 @@ export declare class StdioServer {
     set sessionLlmConfig(v: SessionLlmConfig);
     get acpSessionMeta(): Record<string, unknown> | null;
     set acpSessionMeta(v: Record<string, unknown> | null);
+    get acpSessionMetaBySession(): Map<string, Record<string, unknown>>;
     get currentHooks(): import("../contracts/hooks.js").HookRegistry | null;
     get permissionChecker(): AgentRuntimeSessionState["permissionChecker"];
     private set permissionChecker(value);
+    /**
+     * config.update 权限热应用:写盘的同时立即更新活的 rule engine,
+     * 当前会话(乃至运行中 turn)的下一次工具调用就按新模式判定——
+     * 不再等下一轮 _meta 或重启。settings-watcher 仍监听文件作为外部改动兜底。
+     */
+    applyPermissionConfig(perm: {
+        mode: PermissionMode;
+    }): void;
     private set mcpManager(value);
     get memoryProvider(): MemoryHandlerProvider | null;
     set memoryProvider(value: MemoryHandlerProvider | null);

package/dist/types/cli/tool-bootstrap-core-registration.d.ts

@@ -30,3 +30,5 @@ export declare function setGroupSecurityMode(enabled: boolean): void;
 export declare const localCoreToolRegistrationModule: import("../runtime/ports/tool-contracts.js").ToolRegistrationModule<LocalCoreToolRegistrationContext>;
 export declare function registerLocalCoreTools(context: LocalCoreToolRegistrationContext): void;
 export declare function validateExecCommand(command: string, workdir: string, groupMode?: boolean): string | null;
+/** office/pdf 文档扩展名 → mime;非文档返回 undefined。导出仅为单测。 */
+export declare function documentMimeForExtension(ext: string): string | undefined;

package/dist/types/cli/turn-core.d.ts

@@ -16,6 +16,8 @@ export interface TurnCoreRequest {
     tools: ToolDefinition[];
     /** Live tool-manifest rebuild for same-turn activation (forwarded to the loop). */
     refreshTools?: () => ToolDefinition[];
+    /** Mid-turn guidance drain (运行中引导) — forwarded to the tool loop. */
+    drainPendingGuidance?: () => string[];
     systemPrompt: string;
     config: TurnConfig;
 }

package/dist/types/orchestration/agent-instance.d.ts

@@ -121,6 +121,10 @@ export declare class ProductOrchestrator {
      */
     replayTask(productId: string, taskId: string): Promise<void>;
     /** Get product status. */
+    /** P2-1: the native (codex/claude) session id captured for a delegation's single worker, so the
+     *  DelegationCoordinator can resume it on the next same-(chat×agent) delegation. undefined for a
+     *  multi-instance product, an own agent, or before the worker's first task settles. */
+    getDelegationNativeSessionId(productId: string): string | undefined;
     getStatus(productId: string): ProductStatus | null;
     /** Live DAG progress snapshot for a product (for the planner's execution-phase leader). */
     getProgressSnapshot(productId: string): {

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

@@ -15,6 +15,16 @@ type DelegationStatus = "running" | "completed" | "failed" | "cancelled";
 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(): {

package/dist/types/orchestration/product-persistence.d.ts

@@ -30,6 +30,10 @@ export interface PersistedProductState {
      * PlanningSession is strings / arrays / plain objects (no functions, dates, or class instances).
      */
     leaderDialogue?: PlanningSession;
+    /** P2-1: run tasks in the project cwd instead of per-task worktrees (see
+     *  ProductCreateParams.runInProjectCwd) — persisted so a delegation resumed after an engine restart
+     *  keeps running in the project cwd, not a fresh isolated worktree. */
+    runInProjectCwd?: boolean;
 }
 export interface ProductPersistenceOptions {
     pathService?: PathService;

package/dist/types/orchestration/workflow/capability-catalog.d.ts

@@ -35,7 +35,7 @@ export interface CapabilityCatalogDeps {
     projectRoot: string;
 }
 /** Enumerate every capability a workflow in `projectRoot` can reference right now. */
-export declare function buildCapabilityCatalog(deps: CapabilityCatalogDeps): CapabilityEntry[];
+export declare function buildCapabilityCatalog(deps: CapabilityCatalogDeps): Promise<CapabilityEntry[]>;
 /**
  * Compact catalog text for the AI graph builder's system prompt: category headers + `id — desc`
  * lines, hard-capped per category so huge tool sets don't blow the prompt (the agent uses the

package/dist/types/orchestration/workflow/workflow-controller.d.ts

@@ -215,5 +215,5 @@ export declare function defaultRuntimeFactory(opts: {
     checkpoint?: (workflowId: string, runId: string) => RunCheckpoint | undefined;
     now?: () => Date;
     /** Per-node lifecycle for live canvas coloring; workflowId comes from the run ctx. */
-    emitNodeStatus?: (workflowId: string, nodeId: string, status: NodeRunStatus) => void;
+    emitNodeStatus?: (workflowId: string, nodeId: string, status: NodeRunStatus, error?: string) => void;
 }): RuntimeFactory;

package/dist/types/orchestration/workflow/workflow-runtime.d.ts

@@ -96,7 +96,7 @@ export interface WorkflowRuntimeOptions {
      */
     preserveCheckpoint?: boolean;
     /** Per-node lifecycle callback for live status (canvas coloring). Fire-and-forget, not durable. */
-    onNodeStatus?: (nodeId: string, status: "running" | "completed" | "failed") => void;
+    onNodeStatus?: (nodeId: string, status: "running" | "completed" | "failed", error?: string) => void;
 }
 export declare class WorkflowRuntime {
     private def;

package/dist/types/protocol/notifications.d.ts

@@ -6,4 +6,4 @@
  * This file re-exports the wire types.
  * Internal consumers import from this file — zero churn.
  */
-export type { AgentSource, AgentsErrorNotification, AgentsStatusNotification, ArtifactType, MediaResultType, MemoryDecayCompletedNotification, MemoryUpdatedNotification, NotificationMethod, NotificationMethodMap, NotificationThreadItem, PermissionRuleUpdatedNotification, PlanInterruptedNotification, PongNotification, ProductAgentActivityNotification, ProductBudgetUpdateNotification, ProductBudgetWarningNotification, ProductCheckpointedNotification, ProductCompletedNotification, ProductDagTopologyNotification, ProductMembersNotification, ProductPlanFailedNotification, ProductPlanningDeltaNotification, ProductPlanReadyNotification, ProductTaskCompletedNotification, ProductTaskFailedNotification, ProductTaskOutputDeltaNotification, ProductTaskStartedNotification, ProjectArchivedNotification, ProjectCreatedNotification, ProjectDeletedNotification, ProjectRenamedNotification, ProjectSwitchedNotification, ProjectUnarchivedNotification, SessionInfoNotification, SoloAgentDeltaNotification, SoloAgentUsageNotification, SoloEvaluationNotification, SoloProgressNotification, TeamMemberNotification, ToolApprovalRequestNotification, TurnAnnotationsNotification, TurnArtifactNotification, TurnAskUserNotification, TurnDeltaNotification, TurnEndNotification, TurnErrorNotification, TurnExecProgressNotification, TurnHeartbeatNotification, TurnMediaPersistedNotification, TurnMediaProgressNotification, TurnMediaResultNotification, TurnPlanUpdateNotification, TurnReasoningDeltaNotification, TurnRecoveryNotification, TurnSidechainCompletedNotification, TurnSidechainStartedNotification, TurnSkillInstructionNotification, TurnStartNotification, TurnSubagentDeltaNotification, TurnSuggestionsNotification, TurnTaskUpdatedNotification, TurnTodosUpdatedNotification, TurnToolBlockedNotification, TurnToolCallNotification, TurnToolResultNotification, TurnToolUseSummaryNotification, TurnUsageUpdateNotification, WireTokenUsage, } from "./wire/index.js";
+export type { AgentSource, AgentsErrorNotification, AgentsStatusNotification, ArtifactType, MediaResultType, MemoryDecayCompletedNotification, MemoryUpdatedNotification, NotificationMethod, NotificationMethodMap, NotificationThreadItem, PermissionRuleUpdatedNotification, PlanInterruptedNotification, PongNotification, ProductAgentActivityNotification, ProductBudgetUpdateNotification, ProductBudgetWarningNotification, ProductCheckpointedNotification, ProductCompletedNotification, ProductDagTopologyNotification, ProductMembersNotification, ProductPlanFailedNotification, ProductPlanningDeltaNotification, ProductPlanReadyNotification, ProductTaskCompletedNotification, ProductTaskFailedNotification, ProductTaskOutputDeltaNotification, ProductTaskStartedNotification, ProjectArchivedNotification, ProjectCreatedNotification, ProjectDeletedNotification, ProjectRenamedNotification, ProjectSwitchedNotification, ProjectUnarchivedNotification, SessionInfoNotification, SessionRecoveryPendingNotification, SoloAgentDeltaNotification, SoloAgentUsageNotification, SoloEvaluationNotification, SoloProgressNotification, TeamMemberNotification, ToolApprovalRequestNotification, TurnAnnotationsNotification, TurnArtifactNotification, TurnAskUserNotification, TurnDeltaNotification, TurnEndNotification, TurnErrorNotification, TurnExecProgressNotification, TurnHeartbeatNotification, TurnMediaPersistedNotification, TurnMediaProgressNotification, TurnMediaResultNotification, TurnPlanUpdateNotification, TurnProgressNotification, TurnReasoningDeltaNotification, TurnRecoveryNotification, TurnSidechainCompletedNotification, TurnSidechainStartedNotification, TurnSkillInstructionNotification, TurnStartNotification, TurnSubagentDeltaNotification, TurnSuggestionsNotification, TurnTaskUpdatedNotification, TurnTodosUpdatedNotification, TurnToolBlockedNotification, TurnToolCallNotification, TurnToolResultNotification, TurnToolUseSummaryNotification, TurnUsageUpdateNotification, WireTokenUsage, } from "./wire/index.js";

package/dist/types/protocol/wire/acp-agent-management.d.ts

@@ -337,6 +337,22 @@ export interface ProductCreateParams {
         maxTotalTokens?: number;
         maxDuration?: number;
     };
+    /**
+     * P2-1: run ALL tasks directly in the project cwd (`cwd`) instead of isolated per-task git worktrees.
+     * Set by DelegationCoordinator so a background @mention shares the project workspace exactly like
+     * foreground @codex — its native session then lives under a STABLE cwd (git or not) and resumes across
+     * delegations. Omitted everywhere else (per-task worktree isolation stays the default for parallel
+     * product/goal/solo tasks).
+     */
+    runInProjectCwd?: boolean;
+    /**
+     * P2-1: native (codex/claude) session id to RESUME for this delegation (ACP session/load), so repeated
+     * background @mention to the same (chat×agent) accumulates context — the background analogue of the
+     * foreground U4 resume. The DelegationCoordinator tracks it per (chat×agent): undefined on the first
+     * delegation (→ fresh session, whose id it then captures), the prior id thereafter. Validated by `has()`
+     * before use, so a stale id falls back to a fresh session. Git-independent (id, not cwd, drives reuse).
+     */
+    resumeNativeSessionId?: string;
 }
 /**
  * product.plan RPC params — starts an interactive planning session.

package/dist/types/protocol/wire/agent-events.d.ts

@@ -13,7 +13,7 @@
  * Turn-lifecycle events relayed to the Control UI WebSocket.
  * These are the "chat session" events that every UI client needs.
  */
-export declare const AGENT_WS_EVENT_NAMES: readonly ["turn.start", "turn.delta", "turn.end", "turn.error", "turn.recovery", "turn.file_changes", "turn.tool_call", "turn.tool_result", "turn.tool_blocked", "turn.reasoning_delta", "turn.approval_request", "turn.skill_instruction", "turn.ask_user", "turn.media_result", "turn.media_progress", "turn.media_usage", "turn.media_capability_check", "turn.plan_update", "turn.suggestions", "turn.sidechain_started", "turn.subagent_started", "turn.subagent_delta", "turn.subagent_ended", "turn.sidechain_completed", "turn.task_updated", "turn.todos_updated", "turn.exec_progress", "turn.tool_use_summary", "turn.tool_selection_policy", "turn.lifecycle", "turn.document_maintenance", "turn.artifact_contract", "turn.usage_update", "team.member.notification", "session.info", "memory.updated", "skills.updated", "pet.soul_ready", "pet.reaction", "pet.growth", "pet.state", "pet.confirm", "pet.asset.updated", "system.activity", "workflow.created", "workflow.updated", "workflow.deleted", "workflow.runStarted", "workflow.runCompleted", "workflow.runFailed", "workflow.nodeStatus", "workflow.triggerDropped", "workflow.alert", "workflow.approvalRequested"];
+export declare const AGENT_WS_EVENT_NAMES: readonly ["turn.start", "turn.delta", "turn.end", "turn.error", "turn.recovery", "turn.file_changes", "turn.tool_call", "turn.tool_result", "turn.tool_blocked", "turn.reasoning_delta", "turn.approval_request", "turn.skill_instruction", "turn.ask_user", "turn.media_result", "turn.media_progress", "turn.media_usage", "turn.media_capability_check", "turn.plan_update", "turn.suggestions", "turn.sidechain_started", "turn.subagent_started", "turn.subagent_delta", "turn.subagent_ended", "turn.sidechain_completed", "turn.task_updated", "turn.todos_updated", "turn.exec_progress", "turn.progress", "turn.tool_use_summary", "turn.tool_selection_policy", "turn.lifecycle", "turn.document_maintenance", "turn.artifact_contract", "turn.usage_update", "team.member.notification", "session.info", "session.recovery_pending", "memory.updated", "skills.updated", "pet.soul_ready", "pet.reaction", "pet.growth", "pet.state", "pet.confirm", "pet.asset.updated", "system.activity", "workflow.created", "workflow.updated", "workflow.deleted", "workflow.runStarted", "workflow.runCompleted", "workflow.runFailed", "workflow.nodeStatus", "workflow.triggerDropped", "workflow.alert", "workflow.approvalRequested"];
 /**
  * Agent Team events (Solo Mode, Product Mode, Plan lifecycle).
  * Relayed to the UI's team/orchestration panel.
@@ -23,7 +23,7 @@ export declare const AGENT_TEAM_WS_EVENT_NAMES: readonly ["solo.progress", "solo
  * All agent notifications that Gateway should relay to WS clients.
  * Union of session events + team events.
  */
-export declare const ALL_AGENT_WS_EVENT_NAMES: readonly ["turn.start", "turn.delta", "turn.end", "turn.error", "turn.recovery", "turn.file_changes", "turn.tool_call", "turn.tool_result", "turn.tool_blocked", "turn.reasoning_delta", "turn.approval_request", "turn.skill_instruction", "turn.ask_user", "turn.media_result", "turn.media_progress", "turn.media_usage", "turn.media_capability_check", "turn.plan_update", "turn.suggestions", "turn.sidechain_started", "turn.subagent_started", "turn.subagent_delta", "turn.subagent_ended", "turn.sidechain_completed", "turn.task_updated", "turn.todos_updated", "turn.exec_progress", "turn.tool_use_summary", "turn.tool_selection_policy", "turn.lifecycle", "turn.document_maintenance", "turn.artifact_contract", "turn.usage_update", "team.member.notification", "session.info", "memory.updated", "skills.updated", "pet.soul_ready", "pet.reaction", "pet.growth", "pet.state", "pet.confirm", "pet.asset.updated", "system.activity", "workflow.created", "workflow.updated", "workflow.deleted", "workflow.runStarted", "workflow.runCompleted", "workflow.runFailed", "workflow.nodeStatus", "workflow.triggerDropped", "workflow.alert", "workflow.approvalRequested", "solo.progress", "solo.specProgress", "solo.agentDelta", "solo.agentActivity", "solo.agentUsage", "solo.evaluation", "product.taskStarted", "product.taskOutput", "product.members", "product.agentActivity", "product.taskCompleted", "product.taskFailed", "product.budgetUpdate", "product.budgetWarning", "product.checkpointed", "product.completed", "product.dagTopology", "plan.interrupted", "goal.run_state_changed", "goal.phase_boundary", "goal.goal_edited", "goal.message_queued", "goal.acceptance_updated"];
+export declare const ALL_AGENT_WS_EVENT_NAMES: readonly ["turn.start", "turn.delta", "turn.end", "turn.error", "turn.recovery", "turn.file_changes", "turn.tool_call", "turn.tool_result", "turn.tool_blocked", "turn.reasoning_delta", "turn.approval_request", "turn.skill_instruction", "turn.ask_user", "turn.media_result", "turn.media_progress", "turn.media_usage", "turn.media_capability_check", "turn.plan_update", "turn.suggestions", "turn.sidechain_started", "turn.subagent_started", "turn.subagent_delta", "turn.subagent_ended", "turn.sidechain_completed", "turn.task_updated", "turn.todos_updated", "turn.exec_progress", "turn.progress", "turn.tool_use_summary", "turn.tool_selection_policy", "turn.lifecycle", "turn.document_maintenance", "turn.artifact_contract", "turn.usage_update", "team.member.notification", "session.info", "session.recovery_pending", "memory.updated", "skills.updated", "pet.soul_ready", "pet.reaction", "pet.growth", "pet.state", "pet.confirm", "pet.asset.updated", "system.activity", "workflow.created", "workflow.updated", "workflow.deleted", "workflow.runStarted", "workflow.runCompleted", "workflow.runFailed", "workflow.nodeStatus", "workflow.triggerDropped", "workflow.alert", "workflow.approvalRequested", "solo.progress", "solo.specProgress", "solo.agentDelta", "solo.agentActivity", "solo.agentUsage", "solo.evaluation", "product.taskStarted", "product.taskOutput", "product.members", "product.agentActivity", "product.taskCompleted", "product.taskFailed", "product.budgetUpdate", "product.budgetWarning", "product.checkpointed", "product.completed", "product.dagTopology", "plan.interrupted", "goal.run_state_changed", "goal.phase_boundary", "goal.goal_edited", "goal.message_queued", "goal.acceptance_updated"];
 /** Type-level event name for session events. */
 export type AgentWsEventName = (typeof AGENT_WS_EVENT_NAMES)[number];
 /** Type-level event name for team events. */

package/dist/types/protocol/wire/agent-methods.d.ts

@@ -20,6 +20,8 @@ export interface AgentCapabilities {
     supportsResume: boolean;
     supportsUsageUpdate: boolean;
     skillsDirs?: string[];
+    /** 会话历史来源:native-cwd=有本地按 cwd 可发现的原生会话;省略/own=只显示自有会话 */
+    sessionHistory?: "native-cwd" | "own";
 }
 /** Descriptor for a discovered or registered agent. */
 export interface AgentDescriptor {
@@ -719,6 +721,7 @@ export interface AgentRpcMethodMap extends GatewayRpcMethodMap {
         params: {
             modelId: string;
             enabled: boolean;
+            purpose?: string;
         };
         result: {
             ok: true;

package/dist/types/protocol/wire/index.d.ts

@@ -6,7 +6,7 @@ export { type ChatMessage, type ChatMessageRole, type LocalizedToolText, type Th
 export { type AgentCapabilities, type AgentCategory, type AgentConfig, type AgentDescriptor, type AgentProtocol, type AgentRpcMethodMap, type AgentStatus, type CustomAgentDef, type ProductInstanceDef, type ProductPhase, type ProductStatus, type ProductSummary, type ProductTaskDef, type ProductTaskStatus, type SoloAgentResult, type SoloAgentState, type SoloState, type SoloStatus, } from "./agent-methods.js";
 export type * from "./acp-agent-management.js";
 export { AGENT_TEAM_WS_EVENT_NAMES, AGENT_WS_EVENT_NAMES, ALL_AGENT_WS_EVENT_NAMES, type AgentTeamWsEventName, type AgentWsEventName, type AllAgentWsEventName, } from "./agent-events.js";
-export { type AgentSource, type AgentsErrorNotification, type AgentsStatusNotification, type ArtifactType, type MediaResultType, type MemoryDecayCompletedNotification, type MemoryUpdatedNotification, type NotificationMethod, type NotificationMethodMap, type NotificationThreadItem, type PermissionRuleUpdatedNotification, type PlanInterruptedNotification, type PongNotification, type ProductBudgetUpdateNotification, type ProductBudgetWarningNotification, type ProductCheckpointedNotification, type ProductCompletedNotification, type ProductDagTopologyNotification, type ProductTaskCompletedNotification, type ProductTaskFailedNotification, type ProductTaskOutputDeltaNotification, type ProductMembersNotification, type ProductAgentActivityNotification, type ProductTaskStartedNotification, type ProjectArchivedNotification, type ProjectCreatedNotification, type ProjectDeletedNotification, type ProjectRenamedNotification, type ProjectSwitchedNotification, type ProjectUnarchivedNotification, type SessionInfoNotification, type SoloAgentDeltaNotification, type SoloAgentUsageNotification, type SoloEvaluationNotification, type SoloProgressNotification, type TeamMemberNotification, type ToolApprovalRequestNotification, type TurnAnnotationsNotification, type TurnArtifactContractNotification, type TurnArtifactNotification, type TurnAskUserNotification, type TurnDeltaNotification, type TurnEndNotification, type TurnErrorNotification, type TurnExecProgressNotification, type TurnHeartbeatNotification, type TurnMediaPersistedNotification, type TurnMediaProgressNotification, type TurnMediaResultNotification, type TurnPlanUpdateNotification, type TurnReasoningDeltaNotification, type TurnRecoveryNotification, type TurnSidechainCompletedNotification, type TurnSidechainStartedNotification, type TurnSkillAcquisitionNeededNotification, type TurnSkillInstructionNotification, type TurnStartNotification, type TurnSubagentDeltaNotification, type TurnSubagentEndedNotification, type TurnSubagentStartedNotification, type TurnSuggestionsNotification, type TurnTaskUpdatedNotification, type TurnTodosUpdatedNotification, type TurnToolBlockedNotification, type TurnToolCallNotification, type TurnToolResultNotification, type TurnToolUseSummaryNotification, type TurnUsageUpdateNotification, type WireTokenUsage, type ProductPlanReadyNotification, type ProductPlanFailedNotification, type ProductPlanningDeltaNotification, type PetSoulReadyNotification, type PetReactionNotification, type PetGrowthNotification, type PetStateNotification, type PetConfirmNotification, type WorkflowDeletedNotification, type WorkflowRecordNotification, type WorkflowRunCompletedNotification, type WorkflowRunFailedNotification, type WorkflowRunStartedNotification, } from "./notification-payloads.js";
+export { type AgentSource, type AgentsErrorNotification, type AgentsStatusNotification, type ArtifactType, type MediaResultType, type MemoryDecayCompletedNotification, type MemoryUpdatedNotification, type NotificationMethod, type NotificationMethodMap, type NotificationThreadItem, type PermissionRuleUpdatedNotification, type PlanInterruptedNotification, type PongNotification, type ProductBudgetUpdateNotification, type ProductBudgetWarningNotification, type ProductCheckpointedNotification, type ProductCompletedNotification, type ProductDagTopologyNotification, type ProductTaskCompletedNotification, type ProductTaskFailedNotification, type ProductTaskOutputDeltaNotification, type ProductMembersNotification, type ProductAgentActivityNotification, type ProductTaskStartedNotification, type ProjectArchivedNotification, type ProjectCreatedNotification, type ProjectDeletedNotification, type ProjectRenamedNotification, type ProjectSwitchedNotification, type ProjectUnarchivedNotification, type SessionInfoNotification, type SessionRecoveryPendingNotification, type SoloAgentDeltaNotification, type SoloAgentUsageNotification, type SoloEvaluationNotification, type SoloProgressNotification, type TeamMemberNotification, type ToolApprovalRequestNotification, type TurnAnnotationsNotification, type TurnArtifactContractNotification, type TurnArtifactNotification, type TurnAskUserNotification, type TurnDeltaNotification, type TurnEndNotification, type TurnErrorNotification, type TurnExecProgressNotification, type TurnHeartbeatNotification, type TurnMediaPersistedNotification, type TurnMediaProgressNotification, type TurnMediaResultNotification, type TurnPlanUpdateNotification, type TurnProgressNotification, type TurnReasoningDeltaNotification, type TurnRecoveryNotification, type TurnSidechainCompletedNotification, type TurnSidechainStartedNotification, type TurnSkillAcquisitionNeededNotification, type TurnSkillInstructionNotification, type TurnStartNotification, type TurnSubagentDeltaNotification, type TurnSubagentEndedNotification, type TurnSubagentStartedNotification, type TurnSuggestionsNotification, type TurnTaskUpdatedNotification, type TurnTodosUpdatedNotification, type TurnToolBlockedNotification, type TurnToolCallNotification, type TurnToolResultNotification, type TurnToolUseSummaryNotification, type TurnUsageUpdateNotification, type WireTokenUsage, type ProductPlanReadyNotification, type ProductPlanFailedNotification, type ProductPlanningDeltaNotification, type PetSoulReadyNotification, type PetReactionNotification, type PetGrowthNotification, type PetStateNotification, type PetConfirmNotification, type WorkflowDeletedNotification, type WorkflowRecordNotification, type WorkflowRunCompletedNotification, type WorkflowRunFailedNotification, type WorkflowRunStartedNotification, } from "./notification-payloads.js";
 export { ACP_EXTENDED_METHODS, ACP_EXTENDED_SESSION_UPDATE_TYPES, ACP_METHODS, ACP_PROTOCOL_VERSION, ACP_SESSION_UPDATE_TYPES, isAcpJsonRpcNotification, isAcpJsonRpcRequest, isAcpJsonRpcResponse, isExtendedSessionUpdateType, isStandardSessionUpdateType, parseAcpMessage, type AcpAgentCapabilities, type AcpAgentMessageChunkPayload, type AcpAgentThoughtChunkPayload, type AcpConfigOptionDescriptor, type AcpConfigOptionUpdatePayload, type AcpContentBlock, type AcpEndTurnPayload, type AcpExtendedMethod, type AcpExtendedSessionUpdateType, type AcpFsReadTextFileParams, type AcpFsReadTextFileResult, type AcpFsWriteTextFileParams, type AcpFsWriteTextFileResult, type AcpHostCapabilities, type AcpInitializeParams, type AcpInitializeResult, type AcpJsonRpcError, type AcpJsonRpcMessage, type AcpJsonRpcNotification, type AcpJsonRpcRequest, type AcpJsonRpcResponse, type AcpMode, type AcpPermissionOption, type AcpPermissionRequestParams, type AcpPermissionRequestResult, type AcpPlanPayload, type AcpSessionCancelParams, type AcpSessionCloseParams, type AcpSessionMeta, type AcpSessionLoadParams, type AcpSessionModeState, type AcpSessionNewParams, type AcpSessionNewResult, type AcpSessionPromptParams, type AcpSessionPromptResult, type AcpSessionSetConfigParams, type AcpSessionUpdateNotification, type AcpSessionUpdateType, type AcpStandardMethod, type AcpStandardSessionUpdateType, type AcpStopReason, type AcpToolCallPayload, type AcpToolCallUpdatePayload, type AcpUsage, type AcpUsageUpdatePayload, type AcpXSessionInfoPayload, type AcpXSkillInstructionPayload, } from "./acp-protocol.js";
 export { type ApprovalRequiredToolContract, type ModelSelectionReason, type PendingPromptContract, type RuntimeCapabilitySummaryContract, type RuntimeSessionContract, type SessionIdentityContract, } from "./session.js";
 export { type GatewayChannelExecutionEgressContract, type GatewayChannelExecutionEgressKind, type GatewayChannelExecutionIngressBindingContract, type GatewayChannelExecutionIngressSource, } from "./channel-ingress.js";

package/dist/types/protocol/wire/notification-payloads.d.ts

@@ -284,6 +284,20 @@ export interface TurnExecProgressNotification {
     totalLines: number;
     totalBytes: number;
 }
+/**
+ * Throttled long-turn progress (IM channel feedback). Emitted at most once per throttle
+ * interval while a turn keeps running tools; gateway/IM bridge renders it as a short
+ * progress line. Desktop UIs already show the tool stream and may ignore it.
+ */
+export interface TurnProgressNotification {
+    turnId: string;
+    /** Milliseconds since the turn started. */
+    elapsedMs: number;
+    /** Tool results observed so far this turn. */
+    toolCalls: number;
+    /** Name of the most recently completed tool. */
+    lastTool: string;
+}
 /** Generic progress heartbeat. */
 export interface TurnHeartbeatNotification {
     turnId: string;
@@ -466,6 +480,16 @@ export interface MemoryDecayCompletedNotification {
     archived: number;
     durationMs: number;
 }
+/** L3 启动扫描发现的待恢复会话（崩溃残留的 in-flight turn，session-lifecycle-recovery）。 */
+export interface SessionRecoveryPendingNotification {
+    sessions: Array<{
+        sessionId: string;
+        turnId: string;
+        startedAt: string;
+        lastUserPreview?: string;
+        hadSideEffectTool: boolean;
+    }>;
+}
 /** Session metadata changed. */
 export interface SessionInfoNotification {
     sessionId: string;
@@ -1002,6 +1026,7 @@ export interface NotificationMethodMap {
     "turn.todos_updated": TurnTodosUpdatedNotification;
     "task.updated": TaskUpdatedNotification;
     "turn.exec_progress": TurnExecProgressNotification;
+    "turn.progress": TurnProgressNotification;
     "turn.heartbeat": TurnHeartbeatNotification;
     "turn.tool_use_summary": TurnToolUseSummaryNotification;
     "turn.tool_selection_policy": TurnToolSelectionPolicyNotification;
@@ -1018,6 +1043,7 @@ export interface NotificationMethodMap {
     "memory.decay.completed": MemoryDecayCompletedNotification;
     "skills.updated": SkillsUpdatedNotification;
     "session.info": SessionInfoNotification;
+    "session.recovery_pending": SessionRecoveryPendingNotification;
     "permission.rule_updated": PermissionRuleUpdatedNotification;
     "team.member.notification": TeamMemberNotification;
     "turn.usage_update": TurnUsageUpdateNotification;

package/dist/types/runtime/execution/turn-progress-notifier.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 长任务进度通知（IM 渠道体验）：IM 里看不到工具流，超过 minIntervalMs 的轮次
+ * 以节流方式发 turn.progress，由 gateway/IM 桥接渲染成一条简短进度文本。
+ * 桌面端 UI 已有工具流展示，gateway 可按渠道选择忽略此通知。
+ */
+export interface TurnProgressNotifierOptions {
+    turnId: string;
+    send: (method: string, params: Record<string, unknown>) => void;
+    /** 两条进度通知的最小间隔；默认 10s。 */
+    minIntervalMs?: number;
+    now?: () => number;
+}
+export interface TurnProgressNotifier {
+    onToolResult(toolName: string): void;
+}
+export declare function createTurnProgressNotifier(options: TurnProgressNotifierOptions): TurnProgressNotifier;

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

@@ -6,13 +6,14 @@
  *
  * Reference: AionUI AcpDetector + ACP_BACKENDS_ALL registry.
  */
-import type { AcpBackendConfig, AgentDescriptor, AgentConfigStoreData, AuthPreference } from "../../protocol/wire/acp-agent-management.js";
+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;
@@ -134,6 +135,24 @@ export declare function resolveCatalogKeyEnv(entry: AcpBackendConfig | undefined
  * 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;
     private configStore;
@@ -165,20 +184,20 @@ export declare class AcpDetector {
      */
     scanAsync(force?: boolean): Promise<AgentDescriptor[]>;
     private runScanAsync;
-    /** Return cached results without IO. */
+    /**
+     * Return cached results without IO. 冷缓存时后台预热（scanAsync）并返回 []，
+     * 绝不在 RPC 路径上同步 scan —— 同步探测（11-18s+）会饿死单线程引擎循环
+     * （x/product.confirm 60s 超时的根因）。调用方按"稍后再查"处理空列表。
+     */
     list(): AgentDescriptor[];
     /** Clear the detection cache. */
     clearCache(): void;
     private detectBackend;
     /** Async, NON-BLOCKING twin of {@link detectBackend} — identical detection, async probes. */
     private detectBackendAsync;
-    /** Build a backend's descriptor from already-resolved cliPath/version. Shared by the sync and async
-     *  detection paths so they can never drift (status rules, copilot's version-required gate, etc.). */
-    private assembleBackendDescriptor;
     private detectCustomAgent;
     /** Async, NON-BLOCKING twin of {@link detectCustomAgent}. */
     private detectCustomAgentAsync;
-    private assembleCustomAgentDescriptor;
     private hasAgentConfig;
     /**
      * Descriptor for qlogicagent participating in Solo/Product as a self-hosted ACP agent.
@@ -197,6 +216,21 @@ export declare class AcpDetector {
      * 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

package/dist/types/runtime/infra/acp-protocol-adapter.d.ts

@@ -151,7 +151,20 @@ export declare class AcpProtocolAdapter {
         mcpServers?: McpServerConfig[];
         additionalDirectories?: string[];
         systemPrompt?: string;
+        /** Platform/managed model to select over ACP after session/new (see selectSessionModel). */
+        model?: string;
     }): Promise<AcpSessionResult>;
+    /**
+     * Select the platform/managed model over ACP after session/new. External CLIs (notably
+     * claude-code-acp) default to their OWN model (e.g. Sonnet 4.5) and merely EXPOSE the injected
+     * ANTHROPIC_MODEL/OPENAI_MODEL as an "available" option — they do NOT select it. Left on the default,
+     * the first prompt fails ("issue with the selected model …") because the platform shelf has no such
+     * model, and it surfaces as a cryptic "Agent process stdio closed". Best-effort: when the agent
+     * advertised its models, only switch if it offers `desired` and isn't already on it; otherwise attempt
+     * anyway and swallow rejection (the session still exists on its default model — the wrong-model prompt
+     * error is the backstop). Uses the generic sendRequest because the SDK has no typed set_model yet.
+     */
+    private selectSessionModel;
     /**
      * Send a prompt to a running ACP session (session/prompt). Content streams back via session/update
      * notifications during execution; the response carries only { stopReason, usage? }. On timeout the
@@ -165,6 +178,7 @@ export declare class AcpProtocolAdapter {
     resumeSession(_child: ChildProcess, sessionId: string, options?: {
         cwd?: string;
         mcpServers?: McpServerConfig[];
+        model?: string;
     }): Promise<AcpSessionResult>;
     /**
      * Translate an ACP notification into qlogicagent's internal format.

package/dist/types/runtime/infra/agent-process.d.ts

@@ -52,6 +52,14 @@ export interface AgentProcessConfig {
     mcpServers?: McpServerConfig[];
     /** System prompt to inject into ACP session. */
     systemPrompt?: string;
+    /**
+     * Cut 5 — RESUME a third-party native session (ACP session/load, replays history) instead of
+     * creating a fresh one. The id is the agent's OWN native session id (codex rollout id / claude
+     * UUID). Only honored when the agent advertised loadSession at initialize (handle.supportsResume);
+     * otherwise spawn throws — we never silently open a blank session ("fake continuation" is forbidden
+     * by the Phase 2 design).
+     */
+    resumeSessionId?: string;
 }
 export declare function buildExternalAcpSpawnCommand(cliPath: string, acpArgs: string[]): {
     command: string;
@@ -160,6 +168,7 @@ export declare function applyExternalDescriptorEnv(env: Record<string, string>,
     env?: Record<string, string>;
     suppressEnvKeys?: string[];
 }): Record<string, string>;
+export declare function buildChildEnv(config: AgentProcessConfig): Record<string, string>;
 /**
  * Build LLM-related environment variables for an external ACP teammate.
  *
@@ -295,6 +304,13 @@ export declare class AgentProcessManager {
     isAlive(memberId: string): boolean;
     /** Get usage tracker for an ACP agent (returns null for internal agents). */
     getUsageTracker(memberId: string): AcpUsageTracker | null;
+    /**
+     * The agent-assigned native session id (from ACP session/new or session/load) for a pooled member,
+     * once its session exists — undefined before creation. For native-cwd agents (codex/claude) this is
+     * the id under which the agent persists its OWN transcript (e.g. claude's ~/.claude uuid), distinct
+     * from the engine/stream id; used to converge on a single session identity (own/native unification).
+     */
+    getNativeSessionId(memberId: string): string | undefined;
     /**
      * Feed token usage into the tracker from a child notification (Tier 1). Handles all three shapes a
      * child may use so the tracker is actually populated:

package/dist/types/runtime/infra/astraclaw-capabilities.d.ts

@@ -20,11 +20,11 @@ export declare function buildAstraClawCapabilitiesSystemPrompt(input: {
     mcpAvailable: boolean;
     availableToolNames?: Iterable<string>;
     currentEnvironment?: string;
-}): string | undefined;
+}): Promise<string | undefined>;
 export declare function buildAstraClawCapabilitiesPromptPreamble(input: {
     projectRoot: string;
     mcpAvailable: boolean;
     availableToolNames?: Iterable<string>;
     currentEnvironment?: string;
-}): string | undefined;
+}): Promise<string | undefined>;
 export declare function handleAstraClawCapabilityToolCall(input: AstraClawCapabilityToolInput): Promise<AstraClawCapabilityToolResult>;

package/dist/types/runtime/infra/builtin-skills-seed.d.ts

@@ -0,0 +1,31 @@
+export interface SeedBuiltinSkillsOptions {
+    /** Global skill store dir (getUserSkillsDir()). Each skill lands at <storeDir>/<name>/SKILL.md. */
+    storeDir: string;
+    /** Override the shipped builtin-skills source dir; defaults to the packaged skills/builtin. */
+    builtinDir?: string;
+}
+export interface SeedBuiltinSkillsResult {
+    /** Names of skills newly copied this run (empty when all already present or source missing). */
+    seeded: string[];
+}
+/**
+ * Locate the shipped skills/builtin directory from a module directory.
+ *
+ * The module dir differs by packaging mode — crucially, the production build is an esbuild
+ * BUNDLE: this module is inlined into dist/cli.js, so at runtime import.meta.url resolves to
+ * dist/cli.js itself, NOT dist/runtime/infra/... Probe candidates in order:
+ * 1. hereDir/skills/builtin           — bundle: hereDir = dist/ → dist/skills/builtin
+ *                                       (build.mjs copies skills/builtin there).
+ * 2. hereDir/../../skills/builtin     — unbundled dist module at dist/runtime/infra/.
+ * 3. hereDir/../../../skills/builtin  — dev/tsx/vitest: src/runtime/infra → repo-root skills/builtin.
+ * Returns the first candidate that exists, or undefined when none does (stripped-down build).
+ * Exported pure (hereDir in → path out) so tests can drive it against synthetic layouts.
+ */
+export declare function resolveBuiltinDirFrom(hereDir: string): string | undefined;
+/**
+ * Copy each builtin skill directory into the store only when its target does not yet exist.
+ * Idempotent: a second run with everything already present returns { seeded: [] }.
+ * Missing builtinDir is not an error — returns { seeded: [] } so a stripped-down build
+ * (or a local checkout without the assets) never blocks startup.
+ */
+export declare function seedBuiltinSkills(options: SeedBuiltinSkillsOptions): SeedBuiltinSkillsResult;

package/dist/types/runtime/infra/llmrouter-catalog.d.ts

@@ -1,4 +1,4 @@
-import type { ModelCapabilityProfile, ModelEntry, ModelRegistry, ReasoningMode } from "./model-registry.js";
+import type { ModelCapabilityProfile, ModelEntry, ModelPurpose, ModelRegistry, ReasoningMode } from "./model-registry.js";
 import type { ConfigPort } from "../ports/index.js";
 export declare const LLMROUTER_CATALOG_UNAVAILABLE_MESSAGE = "\u65E0\u6CD5\u8FDE\u63A5 llmrouter \u6A21\u578B\u76EE\u5F55";
 export declare const LLMROUTER_PROVIDER_ID = "llmrouter";
@@ -97,14 +97,34 @@ export declare function refreshRegistryFromLlmrouterApiKey(registry: ModelRegist
     forceCatalog?: boolean;
 }): Promise<ModelEntry[]>;
 export declare function resetLlmrouterCatalogClientCache(): void;
+export interface DefaultBindingsResult {
+    /** 本次真正写入的绑定(用途 → modelId)。 */
+    applied: Array<{
+        purpose: ModelPurpose;
+        modelId: string;
+    }>;
+    /** 跳过的用途 + 原因(已有配置不覆盖 / 该用途 llmrouter 无可用模型)。 */
+    skipped: Array<{
+        purpose: ModelPurpose;
+        reason: "already-bound" | "no-model";
+    }>;
+}
 /**
- * 零配置默认模型:全新安装(无 textGeneration binding)且网关注入了设备账号推理 key 时,
- * 自动把默认文本模型设为一个 DeepSeek(经 llmrouter)。调用方需先刷新过目录(this.models 里要有
- * `llmrouter:deepseek-*` 条目)。已有 binding 则尊重用户配置、不覆盖。返回是否设置了默认。
+ * 零配置默认绑定:给一组「安全」用途补上 llmrouter 默认模型 —— **只补空白**,已有 binding 的用途一律
+ * 不动(尊重用户/老配置)。每用途三级挑选:①服务端推荐(模型 capability_profile.default_for 声明本
+ * 用途)优先 → ②回退硬编码偏好子串(DEFAULT_BINDING_PREFERENCES,向后兼容) → ③再回退该用途第一个
+ * 可用模型;都没有则不绑。**「哪些用途该默认绑」是客户端产品边界(安全白名单),「每用途选哪个模型」
+ * 交服务端** —— 两层职责分离,llmrouter 换模型客户端零发版跟随。
  *
- * key 不在此注册 —— ModelRegistry 取 llmrouter key 时会回退到 QLOGIC_LLMROUTER_INFERENCE_KEY env。
+ * 触发场景:①agent 启动(设备账号推理 key 注入后,stdio-server) ②刷新目录后(settings refresh)
+ * ③手动添加 llmrouter key。"有没有 llmrouter 可用"由 listModels 结果隐含——refresh 成功(key 有效)
+ * 才有 llmrouter 模型条目;无则每个用途 no-model 跳过、不绑。key 不在此注册(ModelRegistry 取 llmrouter
+ * key 时回退到 QLOGIC_LLMROUTER_INFERENCE_KEY env 或用户 key)。调用方需先刷新过目录。
  */
-export declare function ensureLlmrouterDefaultBinding(registry: ModelRegistry, configPort?: ConfigPort): boolean;
+export declare function ensureLlmrouterDefaultBindings(registry: ModelRegistry, opts?: {
+    requireInferenceKey?: boolean;
+    configPort?: ConfigPort;
+}): DefaultBindingsResult;
 export declare function toModelEntry(model: LlmrouterCatalogModel): ModelEntry | null;
 export declare function toModelEntries(model: LlmrouterCatalogModel): ModelEntry[];
 export {};