qlogicagent 2.17.10 → 2.18.1

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 {};

package/dist/types/runtime/infra/model-registry.d.ts

@@ -29,6 +29,13 @@ export interface ModelEntry {
     routeIntents: ModelPurpose[];
     baseUrl?: string;
     enabled: boolean;
+    /**
+     * Purposes this model has been individually turned OFF for. Absent/empty = on for all of its
+     * routeIntents (still subject to the master `enabled`). Lets one model serve several purposes
+     * with independent on/off switches, so disabling it under one purpose group never strands the
+     * bindings that use it for another.
+     */
+    disabledPurposes?: ModelPurpose[];
     nativeModelId?: string;
     transport?: string;
     contextWindow?: number;
@@ -40,6 +47,11 @@ export interface ModelEntry {
     pricing?: Record<string, unknown>;
     /** Thinking-strength control class for the UI (see ReasoningMode). */
     reasoningMode?: ReasoningMode;
+    /**
+     * 归一后的「服务端推荐默认用途」(来自 capabilityProfile.default_for)。零配置默认绑定优先选
+     * defaultForIntents 命中本用途的模型,读不到则回退硬编码偏好。空/缺 → 无服务端推荐。
+     */
+    defaultForIntents?: ModelPurpose[];
 }
 export interface ModelCapabilityProfile {
     tasks?: string[];
@@ -55,6 +67,12 @@ export interface ModelCapabilityProfile {
         requires_confirmation?: boolean;
         default_selectable?: boolean;
     };
+    /**
+     * 服务端声明:该模型是这些 route_intent 的「推荐默认」(零配置绑定优先读它)。原始 intent 字符串
+     * (由 llmrouter 归一为规范名);客户端过滤到已知 ModelPurpose 得 defaultForIntents。空/缺 → 无服务端
+     * 推荐 → 客户端回退硬编码偏好(向后兼容:llmrouter 未部署 default_for 时行为与现状完全一致)。
+     */
+    default_for?: string[];
 }
 export type PurposeBindings = Partial<Record<ModelPurpose, string>>;
 export interface ModelRegistryConfig {
@@ -62,6 +80,7 @@ export interface ModelRegistryConfig {
     models: Array<{
         id: string;
         enabled?: boolean;
+        disabledPurposes?: ModelPurpose[];
     }>;
     bindings: PurposeBindings;
     tunables?: Record<string, unknown>;
@@ -84,6 +103,7 @@ export declare class ModelRegistry {
     private catalogProviders;
     private models;
     private modelEnabledOverrides;
+    private modelPurposeDisabled;
     private bindings;
     private injectedKeyStates;
     private settingsPath;
@@ -106,6 +126,12 @@ export declare class ModelRegistry {
      */
     acceptsInputModality(modality: string, purpose?: ModelPurpose): boolean;
     isAvailable(purpose: ModelPurpose): boolean;
+    /**
+     * Whether `id` is enabled for `purpose`. The master `enabled` flag is the global gate; on top of it
+     * a single purpose can be switched off (modelPurposeDisabled) without touching the model's other
+     * purposes. This is what keeps "disable in 文本生成" from stranding the 图像理解 binding.
+     */
+    isEnabledForPurpose(id: string, purpose: ModelPurpose): boolean;
     resolveModelForPurpose(purpose: ModelPurpose): string | null;
     addProvider(providerId: string, opts?: {
         baseUrl?: string;
@@ -132,8 +158,23 @@ export declare class ModelRegistry {
     replaceCatalogModels(entries: ModelEntry[]): void;
     replaceProviderModels(providerId: string, entries: ModelEntry[]): void;
     removeModel(id: string): void;
-    enableModel(id: string): void;
-    disableModel(id: string): void;
+    /**
+     * Enable a model. With `purpose`, enables it for just that purpose (clearing its per-purpose OFF
+     * switch); if the whole model was off, it flips on but keeps its OTHER purposes off so a single
+     * "turn on imageUnderstanding" never silently re-enables textGeneration too. Without `purpose`,
+     * enables the model globally (on for all of its purposes).
+     */
+    enableModel(id: string, purpose?: ModelPurpose): void;
+    /**
+     * Disable a model. With `purpose`, turns it off for just that purpose; the master flag only flips
+     * off once EVERY one of its routeIntents is off, so purpose-agnostic consumers (default-model
+     * pickers) still see the model while any purpose stays live. Without `purpose`, disables globally.
+     */
+    disableModel(id: string, purpose?: ModelPurpose): void;
+    private isMasterEnabled;
+    private setMasterEnabled;
+    private setPurposeDisabled;
+    private purposeDisabledArray;
     listModels(filter?: {
         purpose?: ModelPurpose;
         provider?: string;

package/dist/types/runtime/infra/user-dirs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 跨平台获取用户常见目录(桌面/下载/文档)的真实绝对路径,供 environment-context 注入给 agent——
+ * 让「读桌面/下载的文件」这类桌面端最常见请求有一个确定的绝对路径锚点,而不是相对会话工作区瞎找。
+ *
+ * 各平台权威来源(都不能简单 homedir + "/Desktop" 硬拼——OneDrive/自定义重定向会漏):
+ *   - Windows: 注册表 User Shell Folders(含 OneDrive/自定义重定向);值是 REG_EXPAND_SZ,含 %VAR% 需展开。
+ *              展开用 node 的 process.env(编码正确),所以即便用户名是中文,%USERPROFILE% 模板展开后仍准;
+ *              只有用户把桌面手动重定向到硬编码中文路径时,reg 的 OEM 输出可能乱码 → existsSync 兜底回退。
+ *   - macOS:   ~/Desktop 等固定英文路径(Finder 里的本地化名只是显示,真实路径是英文)。
+ *   - Linux:   XDG user-dirs(~/.config/user-dirs.dirs 的 XDG_DESKTOP_DIR 等),回退 ~/Desktop。
+ * 一次性探测 + 缓存(目录在进程生命周期内不变)。任何一项失败都回退到 homedir 拼接,绝不抛。
+ */
+export interface UserDirs {
+    desktop: string;
+    downloads: string;
+    documents: string;
+}
+/** 用户桌面/下载/文档的真实绝对路径(缓存)。失败项回退 homedir 拼接,绝不抛。 */
+export declare function getUserDirs(): UserDirs;
+/** 仅测试用:清缓存,让不同平台/环境的断言各自重探。 */
+export declare function resetUserDirsCache(): void;

package/dist/types/runtime/permission-model.d.ts

@@ -3,7 +3,7 @@ export interface PermissionPromptOption {
     optionId: string;
     name: string;
     kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
-    scope?: "once" | "directory";
+    scope?: "once" | "directory" | "directory_persistent";
 }
 export interface PermissionModeDescriptor {
     id: PermissionMode;

package/dist/types/runtime/ports/permission-contracts.d.ts

@@ -105,8 +105,11 @@ export interface ApprovalResponse {
     approvalId: string;
     decision: "allow" | "deny";
     updatedInput?: Record<string, unknown>;
-    /** Approval scope chosen by the user: just this call, or the whole directory. */
-    scope?: "once" | "directory";
+    /**
+     * Approval scope chosen by the user: just this call, the whole directory for
+     * this session, or the whole directory persisted across restarts.
+     */
+    scope?: "once" | "directory" | "directory_persistent";
 }
 export interface PermissionRuleEnginePort {
     getMode(): PermissionMode;

package/dist/types/runtime/prompt/fresh-workspace-evidence.d.ts

@@ -11,9 +11,8 @@ export interface ToolNameLike {
 }
 export interface FreshWorkspaceEvidencePolicy {
     requiresFreshTool: boolean;
-    reason?: "file-read" | "file-mutation" | "memory-mutation" | "media-generation" | "directory-list" | "content-search" | "shell" | "web";
+    reason?: "file-read" | "memory-mutation" | "media-generation" | "directory-list" | "content-search" | "shell" | "web";
     mediaKind?: "image" | "tts" | "music";
-    workflowKind?: "artifact-index";
     allowedToolNames: string[];
 }
 export declare function getFreshWorkspaceEvidencePolicy(messages: readonly PromptMessageLike[] | string): FreshWorkspaceEvidencePolicy;

package/dist/types/runtime/prompt/identity-section.d.ts

@@ -6,7 +6,7 @@
  */
 import { type SystemPromptSection } from "./system-prompt-sections.js";
 export interface IdentityInfo {
-    /** 产品名（运营可配置），缺省 QLogicAgent */
+    /** 产品名（运营可配置），缺省 AstraClaw */
     productName?: string;
     /** 可选的品牌/构建方说明行（运营可配置） */
     vendorLine?: string;

package/dist/types/runtime/session/native/claude-session-source.d.ts

@@ -0,0 +1,23 @@
+import type { NativeSessionEntry, NativeSessionRef, NativeSessionSource, TranscriptMessage } from "./native-session-source.js";
+/**
+ * Native session source for Claude Code (claude CLI). Reads directly from
+ * `~/.claude/projects/<claudeProjectDirName(cwd)>/<sessionUuid>.jsonl` — the same on-disk format
+ * Claude Code itself writes, so this is read-only and never touched by qlogicagent.
+ *
+ * `isSidechain: true` events are subagent side-chains, not part of the user-visible conversation,
+ * and are filtered out of both list() (message counting / title / lastActiveAt) and
+ * loadTranscript() (transcript body).
+ */
+export declare class ClaudeSessionSource implements NativeSessionSource {
+    private readonly home;
+    readonly agentId = "claude";
+    readonly kind: "claude";
+    /** `home` is injectable so tests can point at a temp directory instead of the real user home. */
+    constructor(home?: string);
+    list(cwd: string, opts?: {
+        limit?: number;
+    }): Promise<NativeSessionEntry[]>;
+    /** A claude native session is exactly the file `<encoded-cwd>/<sessionUuid>.jsonl` — a single stat. */
+    has(sessionId: string, cwd: string): Promise<boolean>;
+    loadTranscript(ref: NativeSessionRef): Promise<TranscriptMessage[]>;
+}

package/dist/types/runtime/session/native/codex-index.d.ts

@@ -0,0 +1,21 @@
+import type { NativeSessionEntry } from "./native-session-source.js";
+/**
+ * Lists codex-native sessions belonging to `normalizedTargetCwd` (already run through
+ * {@link normalizeCwd} by the caller), sorted by `lastActiveAt` descending.
+ *
+ * Synchronous by design — built entirely on sync fs calls, since it's a Cut 3 building block; a
+ * future CodexSessionSource adapter (mirroring claude-session-source.ts's shape) would wrap this in
+ * the async `NativeSessionSource.list()` contract.
+ *
+ * `messageCount` is always 0: unlike claude's one-line-per-message transcript format, a codex
+ * rollout interleaves many event types per turn, so computing an exact count means fully parsing
+ * every candidate rollout's entire event stream — deliberately out of scope here. Revisit if/when a
+ * caller actually needs an exact count.
+ *
+ * Never throws: a missing/unreadable codexHome, sessions dir, session_index.jsonl, or cache file all
+ * degrade to "as if empty" rather than propagating an error.
+ */
+export declare function listCodexSessionsByCwd(normalizedTargetCwd: string, opts?: {
+    codexHome?: string;
+    cacheDir?: string;
+}): NativeSessionEntry[];

package/dist/types/runtime/session/native/codex-session-source.d.ts

@@ -0,0 +1,31 @@
+import type { NativeSessionEntry, NativeSessionRef, NativeSessionSource, TranscriptMessage } from "./native-session-source.js";
+/**
+ * Native session source for Codex (codex CLI / codex_cli_rs) — Cut 3 Task 3.2.
+ *
+ * `list()` delegates entirely to {@link listCodexSessionsByCwd} (Task 3.1), which already handles
+ * cwd filtering, title/lastActiveAt joining against session_index.jsonl, and mtime-keyed caching;
+ * this adapter only adds the async `NativeSessionSource.list()` contract and cwd normalization on
+ * top of that synchronous building block (mirroring ClaudeSessionSource's shape).
+ *
+ * `loadTranscript()` reads a single rollout file and keeps only `event_msg` lines whose payload is
+ * `user_message` or `agent_message` with `phase: "final_answer"` — see {@link CodexEventMsgLine}'s
+ * doc for why every other line/event/payload type in a rollout is intentionally skipped.
+ */
+export declare class CodexSessionSource implements NativeSessionSource {
+    private readonly opts;
+    readonly agentId = "codex";
+    readonly kind: "codex";
+    /** `opts` is injectable (codexHome/cacheDir) so tests can point at temp directories instead of
+     *  the real user home — mirrors listCodexSessionsByCwd's own opts shape. */
+    constructor(opts?: {
+        codexHome?: string;
+        cacheDir?: string;
+    });
+    list(cwd: string, opts?: {
+        limit?: number;
+    }): Promise<NativeSessionEntry[]>;
+    /** Codex has no id->file mapping without the index (id lives in each rollout's session_meta), so
+     *  membership goes through the mtime-cached listCodexSessionsByCwd (no full re-scan when warm). */
+    has(sessionId: string, cwd: string): Promise<boolean>;
+    loadTranscript(ref: NativeSessionRef): Promise<TranscriptMessage[]>;
+}

package/dist/types/runtime/session/native/cwd-normalize.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Normalize a cwd for CODEX session-cwd equality comparisons (matching a codex rollout's
+ * `session_meta.cwd` against our own workspace cwd). Same rule in spirit as projectId derivation
+ * (see agent-paths.ts `deriveProjectId`: resolve + lowercase) — resolve to an absolute path, then
+ * lowercase and force forward-slash separators so both `E:\Foo\Bar` and `e:/foo/bar` compare equal.
+ * (path.resolve() already normalizes `/` to `\` on win32, so the explicit slash replace below is
+ * belt-and-suspenders rather than load-bearing — verified via `path.resolve("e:/xiaozhiclaw/openclaw")`
+ * === `"e:\\xiaozhiclaw\\openclaw"` on this machine — but kept explicit so the output format doesn't
+ * silently depend on that internal, unstated Node behavior.)
+ */
+export declare function normalizeCwd(cwd: string): string;
+/**
+ * Encode a cwd into the directory name Claude Code uses under `~/.claude/projects/<encoded>`.
+ *
+ * This is Claude Code's OWN encoding (not ours) — we must replicate it byte-for-byte to locate
+ * existing native claude session directories on disk. It has no public spec, so this was reverse
+ * engineered two ways and cross-checked against each other:
+ *
+ *   1. Real directory names from `ls ~/.claude/projects` on this dev machine (see
+ *      cwd-normalize.test.ts for the samples, notably a workspace with a literal space in its name
+ *      — "QA Agent Mention Pool 20260701-1325" — which is what falsified the initially-assumed
+ *      narrower rule).
+ *   2. Decompiling the bundled VS Code extension (anthropic.claude-code-2.1.168,
+ *      extension/extension.js). The relevant minified functions (renamed here for readability;
+ *      originals were Hv/yv/pOe/cOe):
+ *
+ *        const MAX_LEN = 200;
+ *        function hashCode(e) {                               // Java String.hashCode()-style,
+ *          let t = 0;                                          // 32-bit signed, wraps via `|0`
+ *          for (let r = 0; r < e.length; r++) t = (t << 5) - t + e.charCodeAt(r) | 0;
+ *          return t;
+ *        }
+ *        function encodeProjectDirName(e) {
+ *          const t = e.replace(/[^a-zA-Z0-9]/g, "-");
+ *          if (t.length <= MAX_LEN) return t;
+ *          return `${t.slice(0, MAX_LEN)}-${Math.abs(hashCode(e)).toString(36)}`;
+ *        }
+ *
+ * Two things this rule does that a naive "just swap \\/:. for -" guess would get wrong:
+ *   - The replacement set is "everything that isn't [a-zA-Z0-9]", not a fixed 4-character set —
+ *     spaces, underscores, parens, plus signs, and non-ASCII (e.g. Chinese) characters are all
+ *     replaced too. Original casing is preserved (no lowercasing, unlike normalizeCwd above).
+ *   - Encoded names longer than 200 characters are truncated to 200 chars plus a
+ *     "-<base36 32-bit hash>" suffix, where the hash is computed over the ORIGINAL
+ *     (pre-replacement) string, not the truncated one.
+ *
+ * This encoding is lossy/one-way by construction (e.g. `...\\qlogicagent-hub` and
+ * `...\\qlogicagent\\hub` both encode to the same name) — it can only be used to look up a
+ * directory for a known cwd, never to recover a cwd from a directory name. If Claude Code changes
+ * this encoding in a future version, update this function and the fixtures in
+ * cwd-normalize.test.ts together.
+ */
+export declare function claudeProjectDirName(cwd: string): string;

package/dist/types/runtime/session/native/ephemeral-rollout-sweep.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sweep both native stores. Best-effort: never throws (all I/O is guarded); returns how many rollouts were
+ * reclaimed. `home`/`codexHome`/`ttlMs`/`now` are injectable for tests.
+ */
+export declare function sweepEphemeralWorktreeRollouts(opts?: {
+    home?: string;
+    codexHome?: string;
+    ttlMs?: number;
+    now?: number;
+}): Promise<{
+    claudeDeleted: number;
+    codexDeleted: number;
+}>;

package/dist/types/runtime/session/native/native-cwd-agents.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Single source of truth for WHICH third-party ACP backend ids have local, cwd-discoverable
+ * native session history ("native-cwd" adapters registered in register-builtin-sources.ts).
+ *
+ * Consumed by both:
+ *  - acp-detector.ts (assembleBackendDescriptor) — descriptor's capabilities.sessionHistory
+ *  - session-handler.ts (resolveAgentSessionHistory) — session.list routing
+ *
+ * so the two can never drift on which ids are native-adapted (the DRY debt Cut 1 intentionally
+ * left behind — see Cut 3 Task 3.0). To add or remove a native-cwd agent: change this set AND
+ * register/unregister the matching NativeSessionSource adapter in register-builtin-sources.ts.
+ *
+ * Zero imports by design — this file must stay a dependency-free leaf so both acp-detector.ts and
+ * session-handler.ts (which itself imports ACP_BACKENDS from acp-detector.ts) can import it without
+ * risking an import cycle.
+ */
+export declare const NATIVE_CWD_BACKEND_IDS: ReadonlySet<string>;

package/dist/types/runtime/session/native/native-session-source.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Native session source registry.
+ *
+ * A "native" session source lets a third-party ACP agent (codex/claude) expose ITS OWN
+ * CWD-scoped session history — recorded by the agent's own CLI, not by qlogicagent — through
+ * the same session.list / session.get surface as our own sessions.
+ *
+ * Cut 1 shipped only the registry contract with a loose shape; no adapter registered itself, so
+ * {@link getNativeSessionSource} always returned undefined and callers (session-handler's
+ * resolveSessionSource) fell back to an empty list for native-cwd agents. Cut 2 refines the
+ * contract below and adds the claude adapter (see claude-session-source.ts) that calls
+ * {@link registerNativeSessionSource}.
+ */
+/** Opaque locator for a single native session's transcript, round-tripped by the frontend without
+ *  interpretation (session.list returns it, session.loadNativeTranscript consumes it). */
+export interface NativeSessionRef {
+    agentId: string;
+    kind: "codex" | "claude";
+    /** Absolute path to the on-disk transcript file (adapter-specific format). */
+    file: string;
+}
+/** One native session list entry — the `source: "native"` variant of session.list's
+ *  SessionListEntry (see session-types.ts SessionListEntry for the "own" counterpart). */
+export interface NativeSessionEntry {
+    sessionId: string;
+    source: "native";
+    agentId: string;
+    title?: string;
+    lastActiveAt: string;
+    messageCount: number;
+    cwd: string;
+    nativeRef: NativeSessionRef;
+    /** Stamped by handleSessionList from the requested project so the frontend's per-project grouping
+     *  (project-tree filters by projectId) shows native entries under it. The source discovers by cwd
+     *  and cannot know the project, so it leaves this unset. */
+    projectId?: string;
+}
+/**
+ * Minimal transcript-line shape for native session.loadTranscript. This intentionally does NOT
+ * import the frontend's `InboundMessagePayload` (ui-next/src/types/gateway.ts) — that type lives
+ * in a separate package/repo from this engine and carries many fields irrelevant to a bare
+ * transcript line (sessionKey, blocks, attachments, mediaUrl, chatId, ...). Instead this is the
+ * minimal subset every native adapter can populate, documented field-for-field against the
+ * frontend contract so a caller can widen a TranscriptMessage into an InboundMessagePayload by
+ * filling in the rest as optional/absent:
+ *   - messageId -> InboundMessagePayload.messageId (required)
+ *   - content   -> InboundMessagePayload.content (required)
+ *   - timestamp -> InboundMessagePayload.timestamp (required)
+ *   - source    -> InboundMessagePayload.source (required, narrowed here to "user"|"assistant"
+ *                  since that's all a transcript line can be)
+ *   - platform  -> InboundMessagePayload.platform (required there; optional here since every
+ *                  current adapter always sets it to "desktop" — kept optional so future adapters
+ *                  aren't forced to fabricate a value)
+ */
+export interface TranscriptMessage {
+    messageId: string;
+    content: string;
+    timestamp: string;
+    source: "user" | "assistant";
+    platform?: string;
+}
+export interface NativeSessionSource {
+    readonly agentId: string;
+    readonly kind: "codex" | "claude";
+    /** `cwd` is the RAW (un-normalized) project cwd — callers (session-handler's
+     *  resolveSessionSource, via handleSessionList) pass the REQUESTED project's workspaceDir
+     *  (params.projectId's, when present) straight through, falling back to getActiveProjectRoot()
+     *  only when no projectId was given. Each adapter is responsible for whatever
+     *  normalization/encoding its own on-disk storage requires (e.g. claude's
+     *  claudeProjectDirName preserves original casing). */
+    list(cwd: string, opts?: {
+        limit?: number;
+    }): Promise<NativeSessionEntry[]>;
+    /** Cheap existence check: is `sessionId` an existing native session under `cwd` for this agent?
+     *  Used on a COLD spawn to decide whether to resume it (ACP session/load) instead of creating a
+     *  fresh session — so a native conversation regains its authoritative history after pool eviction/
+     *  restart, not only on the one-shot "继续". Optional so test fakes need not implement it. */
+    has?(sessionId: string, cwd: string): Promise<boolean>;
+    loadTranscript(ref: NativeSessionRef): Promise<TranscriptMessage[]>;
+}
+/** Register a native session source for an agentId. Last registration for a given id wins. */
+export declare function registerNativeSessionSource(source: NativeSessionSource): void;
+/** Look up a registered native session source by agentId. Undefined when none is registered for
+ *  that id (no adapter registered itself yet, or the agentId has no native adapter at all). */
+export declare function getNativeSessionSource(agentId?: string): NativeSessionSource | undefined;
+/** Remove a registered native session source by agentId. Symmetric with {@link registerNativeSessionSource};
+ *  exists primarily so tests can deregister a fake adapter afterward without leaking it into other
+ *  test cases that share this module-level registry. No-op if nothing is registered for that id. */
+export declare function unregisterNativeSessionSource(agentId: string): void;

package/dist/types/runtime/session/native/native-title.d.ts

@@ -0,0 +1 @@
+export declare function cleanNativeTitle(message: string, maxLen?: number): string | undefined;

package/dist/types/runtime/session/native/register-builtin-sources.d.ts

@@ -0,0 +1 @@
+export declare function registerBuiltinNativeSources(): void;

package/dist/types/runtime/session/session-types.d.ts

@@ -65,6 +65,14 @@ export interface MessageDisplayMetadata {
     chatId?: string;
     userId?: string;
     userName?: string;
+    /**
+     * Presentation kind for a persisted message whose ROLE alone doesn't capture how
+     * the UI should render it. Currently: "mid_turn_guidance" — a user-authored message
+     * injected into a running turn (运行中引导). It stays role:"user" (the model must see
+     * it as the user's words), but the desktop renders it as an agent-side "收到引导"
+     * receipt line rather than a standalone user bubble.
+     */
+    kind?: string;
 }
 export interface PersistedChatMessage extends ChatMessage {
     timestamp?: string;

package/dist/types/skills/permissions/hook-runner.d.ts

@@ -43,6 +43,14 @@ export interface PermissionCheckerDeps {
     sessionId?: string;
     /** Getter for current turn ID (changes per turn). */
     getTurnId?: () => string;
+    /**
+     * Persist a directory allow-rule across restarts (user picked "始终允许此文件夹").
+     * Wired by the CLI layer to append into the user-level settings.json; optional so
+     * headless/test checkers degrade to session-only memory.
+     */
+    persistPermissionRule?: (rule: {
+        pathPrefix: string;
+    }) => void | Promise<void>;
 }
 export declare class PermissionChecker {
     private readonly ruleEngine;
@@ -57,6 +65,7 @@ export declare class PermissionChecker {
     private readonly auditLogger;
     private readonly sessionId;
     private readonly getTurnId;
+    private readonly persistPermissionRule;
     private unregisterHook;
     /** Tool meta cache — populated from ToolDefinition[] at agent creation */
     private toolMetaCache;

package/dist/types/skills/permissions/settings-watcher.d.ts

@@ -1,6 +1,13 @@
 /**
  * Settings watcher for canonical qlogicagent permission settings.
  *
+ * Two layers (CC settings semantics):
+ *   - user level    ~/.qlogicagent/profiles/<owner>/settings.json  — where config.update persists
+ *   - project level <projectRoot>/.qlogicagent/settings.json       — repo-local overrides
+ * The project file's `permissions` object, when present, overrides the user file's.
+ * Both layers are watched; either changing re-resolves the effective permissions.
+ * (写读同源:此前 config.update 写用户级、watcher 只读项目级,重启后持久模式永远丢失。)
+ *
  * Only the `permissions` object is accepted. Removed top-level aliases such as
  * `permissionMode`, `permissionRules`, and `defaultBehavior` must fail loudly.
  */

package/dist/types/transport/acp-server.d.ts

@@ -154,6 +154,12 @@ export declare class AcpServer {
      * Returns a promise that resolves with the host's chosen option.
      */
     requestPermission(params: AcpPermissionRequestParams): Promise<AcpPermissionRequestResult>;
+    /**
+     * Cancel every in-flight permission request (turn abort / session cancel). Each
+     * awaiter resolves to "deny" and its maps are cleared, so a cancelled turn's
+     * pending approval can't survive to poison the next turn.
+     */
+    cancelAllPendingPermissions(): void;
     /** Whether the host supports extended events */
     get supportsExtendedEvents(): boolean;
     /** Whether the host supports extended methods */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlogicagent",
-  "version": "2.17.10",
+  "version": "2.18.1",
   "description": "XiaozhiClaw Agent CLI — subprocess architecture (JSON-RPC over stdio)",
   "type": "module",
   "main": "dist/index.js",