qlogicagent 2.17.10 → 2.18.2

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/agent-runtime-ports.d.ts

@@ -39,6 +39,8 @@ export interface StreamingToolExecutorPortConfig {
     signal?: AbortSignal;
     maxConcurrentTools?: number;
     maxExecutionMs?: number;
+    /** Turn workspace/cwd — routes oversized tool-result spillover to the session's reachable data dir. */
+    projectRoot?: string;
 }
 export interface ContextCompressionEnginePort {
     compressAsync(messages: RuntimeCompressibleMessage[], budget: number, context: {
@@ -52,9 +54,10 @@ export interface ToolLoopRuntimePorts {
         role: string;
         content?: string | unknown;
         tool_call_id?: string;
-    }>, state: unknown, sessionId: string): Promise<{
+    }>, state: unknown, sessionId: string, projectRoot: string | undefined): Promise<{
         messages: unknown[];
         newlyReplacedCount: number;
+        newlyPersistedBytes?: number;
     }>;
     getActiveContextCompressionEngine(): ContextCompressionEnginePort | null;
     compressMessages(messages: RuntimeCompressibleMessage[], options: {

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/environment-context.d.ts

@@ -32,6 +32,16 @@ export interface ShellInfo {
     psEdition?: "5.1" | "7+";
     isGitBashOnWindows?: boolean;
 }
+/**
+ * Dynamic, platform-specific shell guidance lines appended to `# Environment`.
+ *
+ * When `shellInfo` is present it reflects the REAL active shell (edition +
+ * Git-Bash-on-Windows), so the advice matches what commands will actually run
+ * against. When absent, we fall back to the env-guessed `shellType` and keep the
+ * old one-line PowerShell/CMD note (never crashes, never over-claims an edition
+ * we don't know).
+ */
+export declare function shellGuidanceLines(shellInfo: ShellInfo | undefined, shellType: ShellType): string[];
 /**
  * Create a system prompt section that provides environment context.
  * Memoized — computed once per session (environment doesn't change mid-session).

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

@@ -11,14 +11,11 @@ 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;
-/** 显式构建/创建类请求(做个游戏/网站/app…)。命中 → 第一回合就强制工具调用。 */
-export declare function looksLikeBuildIntent(messages: readonly PromptMessageLike[] | string): boolean;
 export declare function isLightweightChatTurn(messages: readonly PromptMessageLike[] | string): boolean;
 export declare function isExplicitNoToolTurn(messages: readonly PromptMessageLike[] | string): boolean;
 /**

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/inbound-upload-persistence.d.ts

@@ -15,6 +15,14 @@ import type { ChatMessage } from "../../protocol/wire/index.js";
 export interface PersistedUpload {
     url: string;
     localPath?: string;
+    /**
+     * Whether the bytes were actually written to durable storage. `true` on success, `false` when a
+     * transport upload was found but persisting it FAILED (fetch error / non-ok / write error) — the
+     * returned `url` is then the short-lived transport URL that dies with the turn. `undefined` means
+     * the input was not a transport upload to begin with (already-persisted / remote / file://), which
+     * is not a failure. Honesty over silence: callers use `false` to warn instead of pretending it saved.
+     */
+    persisted?: boolean;
 }
 /** 同 persistInboundUploadUrl，但返回持久化后的本地绝对路径（供模型直接 read/exec）。 */
 export declare function persistInboundUploadUrlDetailed(url: string, projectId: string, sessionId: string): Promise<PersistedUpload>;

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-resource-key.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Single source of truth for session resource keys (canonical identity) and the derived
+ * resident-pool / delegation keys. Forbids scattered ad-hoc string concatenation of session keys
+ * (invariant I2, docs/session-identity-alignment-spec.md). Leaf module — imports nothing.
+ */
+/** Canonical session identity: our-minted, stable-from-creation id + its owning agent + project. */
+export interface SessionResource {
+    /** Owning agent kind: own ("qlogicagent") / codex / claude / … (= SessionMetadata.agentId). */
+    agentId: string;
+    /** Owning project id (path-derived / opaque; not minted here). */
+    projectId: string;
+    /** Our-minted session id, stable from creation — never the native Y (Y lives in nativeBinding). */
+    canonicalSessionId: string;
+}
+/** Serialize the canonical session resource to its single opaque key string. */
+export declare function buildSessionResourceKey(r: SessionResource): string;
+/** Parse a key produced by {@link buildSessionResourceKey}; throws on a malformed key. */
+export declare function parseSessionResourceKey(key: string): SessionResource;
+/**
+ * Resident external-agent pool key: same agent + workspace + session ⇒ same resident process.
+ * `sessionId` may be a canonical id, the WARM_SESSION token, or undefined (defaults to "default").
+ * Byte-identical to the historical inline pool key it replaces.
+ */
+export declare function buildAgentPoolKey(agentId: string, cwd: string, sessionId?: string): string;
+/** Prefix matching every pool key for `agentId` (agent-scoped eviction, exact id-boundary). */
+export declare function agentPoolKeyPrefix(agentId: string): string;
+/** @mention delegation serialization key for one (agent × conversation) pair. */
+export declare function buildConvKey(agentId: string, canonicalSessionId: string): string;

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

@@ -3,6 +3,8 @@ import type { MessageDisplayMetadata, PersistedChatMessage, TokenUsage } from ".
 export interface TranscriptLoadResult {
     messages: PersistedChatMessage[];
     corruptLines: number;
+    /** 1-based line numbers that failed to parse (bounded to the first MAX_REPORTED_CORRUPT_LINES). */
+    corruptLineNumbers: number[];
 }
 export declare function appendMessage(sessionId: string, message: ChatMessage, projectRoot: string, turnId?: string, metadata?: {
     usage?: TokenUsage;

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

@@ -18,6 +18,25 @@ export interface InflightTurnMarker {
     /** 该轮是否已执行过有副作用的工具（写文件/发消息/外部 API）。安全档不据此自动续，仅用于 UI"可能重复"提示 + 为智能档铺路。 */
     hadSideEffectTool?: boolean;
 }
+/**
+ * Native (codex/claude) session binding — present only on native sessions, written once the
+ * external agent reports its own session id (Y). Our `sessionId` stays the canonical identity;
+ * `nativeSessionId` is an ATTRIBUTE used ONLY when talking to the external CLI (ACP session/load),
+ * never as a map/pool/list key. `nativeRef` independently locates the external transcript file so
+ * content loads (and the binding is recoverable) without relying on `sessionId === nativeSessionId`.
+ */
+export interface NativeBinding {
+    /** External agent's own session id (Y) — used only for ACP session/load resume. */
+    nativeSessionId: string;
+    /** Locator for the external transcript file (loadTranscript + binding-loss fallback). */
+    nativeRef: {
+        agentId: string;
+        kind: "codex" | "claude";
+        file: string;
+    };
+    /** ISO time the binding was established (first turn the external agent reported Y). */
+    boundAt: string;
+}
 export interface SessionMetadata {
     schemaVersion?: number;
     sessionId: string;
@@ -52,10 +71,18 @@ export interface SessionMetadata {
     interruptedTurnCount?: number;
     /** 达熔断阈值放弃恢复的时间戳（UI 显示"多次中断已停止自动恢复"）。 */
     recoveryAbandonedAt?: string;
+    /** native(codex/claude)会话绑定：外部 Y + nativeRef;own 会话恒 undefined。见 {@link NativeBinding}。 */
+    nativeBinding?: NativeBinding;
 }
 export interface PersistedSession {
     metadata: SessionMetadata;
     messages: PersistedChatMessage[];
+    /**
+     * Count of transcript lines that failed to parse and were skipped on load. Surfaced so the UI can
+     * tell the user "N 条消息无法读取" instead of silently resuming a conversation with holes in it.
+     * Omitted/0 for a clean transcript.
+     */
+    corruptLines?: number;
 }
 export interface MessageDisplayMetadata {
     messageId?: string;
@@ -65,6 +92,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;
@@ -88,6 +123,8 @@ export interface SessionListEntry {
     groupKey?: string;
     previousSessionId?: string;
     carryoverSummary?: string | null;
+    /** N4: native (codex/claude) binding, surfaced so session.list can shape source:"native" + nativeRef. */
+    nativeBinding?: NativeBinding;
 }
 export interface TaskSummaryDeps {
     transport: import("../ports/index.js").LLMTransport;