qlogicagent 2.18.1 → 2.18.3

package/dist/types/runtime/infra/working-materials-store.d.ts

@@ -17,19 +17,13 @@ export declare function getWorkingMaterials(projectId: string, sessionId: string
     items: WorkingMaterialItem[];
     missing: WorkingMaterialItem[];
 }>;
-export declare function replaceWorkingMaterials(projectId: string, sessionId: string, items: unknown[]): Promise<{
+export interface WorkingMaterialsWriteResult {
     ok: true;
     items: WorkingMaterialItem[];
-}>;
-export declare function upsertWorkingMaterial(projectId: string, sessionId: string, item: unknown): Promise<{
-    ok: true;
-    items: WorkingMaterialItem[];
-}>;
-export declare function removeWorkingMaterial(projectId: string, sessionId: string, id: string): Promise<{
-    ok: true;
-    items: WorkingMaterialItem[];
-}>;
-export declare function reorderWorkingMaterials(projectId: string, sessionId: string, ids: string[]): Promise<{
-    ok: true;
-    items: WorkingMaterialItem[];
-}>;
+    /** 超过上限被淘汰的项;非空时调用方/UI 必须告知用户(绝不静默丢用户 pin 的数据)。 */
+    dropped?: WorkingMaterialItem[];
+}
+export declare function replaceWorkingMaterials(projectId: string, sessionId: string, items: unknown[]): Promise<WorkingMaterialsWriteResult>;
+export declare function upsertWorkingMaterial(projectId: string, sessionId: string, item: unknown): Promise<WorkingMaterialsWriteResult>;
+export declare function removeWorkingMaterial(projectId: string, sessionId: string, id: string): Promise<WorkingMaterialsWriteResult>;
+export declare function reorderWorkingMaterials(projectId: string, sessionId: string, ids: string[]): Promise<WorkingMaterialsWriteResult>;

package/dist/types/runtime/pet/pet-profile-service.d.ts

@@ -81,6 +81,13 @@ export declare class PetProfileService {
     private readonly profilePath;
     constructor(ownerUserId: string);
     loadProfile(): PetProfile;
+    /**
+     * Load the profile for a read-modify-write cycle. A corrupt profile file must
+     * never be replaced by a rebuilt default — throw so the caller fails loudly
+     * instead of silently destroying the user's pet data.
+     */
+    private loadProfileForWrite;
+    private readProfileState;
     updateSoul(soul: PetSoul | null): PetProfile;
     updatePreferences(update: Partial<PetPreferences>): PetProfile;
     saveJourneySnapshot(snapshot: JourneySnapshot): PetProfile;

package/dist/types/runtime/pet/petdex-forge-service.d.ts

@@ -9,7 +9,9 @@ export interface PetdexForgePackageOutput extends PetdexForgeOutput {
     validationPath: string;
     productionRunPath: string;
 }
-export declare function forgePetdexAsset(input: PetdexForgeRequest, generateImage: GeneratePetdexImage, options?: PetdexProductionOptions): Promise<PetdexForgeOutput>;
+export declare function forgePetdexAsset(input: PetdexForgeRequest, generateImage: GeneratePetdexImage, options?: PetdexProductionOptions): Promise<PetdexForgeOutput & {
+    qaSkippedJobs?: string[];
+}>;
 export declare function forgePetdexAssetPackage(params: {
     input: PetdexForgeRequest;
     outputDir: string;

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/memory-provider.d.ts

@@ -4,6 +4,8 @@ export interface MemorySearchOptions {
     minScore?: number;
     preferredCategories?: string[];
     llmConfig?: unknown;
+    /** Drop hits whose tags contain ALL strings of any group (resident-layer exclusion). */
+    excludeTagGroups?: string[][];
 }
 export interface MemorySearchResult {
     blockId: string;

package/dist/types/runtime/ports/project-memory-store.d.ts

@@ -41,4 +41,6 @@ export interface ProjectMemoryStore {
 export interface ProjectMemoryStoreFactory {
     getRootPath(projectRoot: string): string;
     create(projectRoot: string): ProjectMemoryStore;
+    /** Read the user-level global memory INDEX for prompt injection (null when absent/empty). */
+    readUserIndexForPrompt(): string | null;
 }

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).
@@ -45,12 +55,24 @@ export interface ShellInfo {
  */
 export declare function createEnvironmentContextSection(cwdOverride?: string, shellInfo?: ShellInfo): SystemPromptSection;
 /**
- * Create the task guidance system prompt section.
- * Domain-aware: selects appropriate guidance based on detected or overridden task domain.
+ * Domain-specific guidance ONLY — the small, genuinely per-turn-variable block.
+ * Excludes universalGuidance() (which is domain-INVARIANT and lives in its own
+ * stable section, see createUniversalGuidanceSection). This is the single source
+ * of truth for domain content, so the combined section and the split sections
+ * never drift.
  *
  * @param domain - Task domain from auto-detection or host override.
  */
-export declare function createTaskGuidanceSection(domain?: TaskDomain): SystemPromptSection;
+export declare function renderDomainGuidanceBlock(domain?: TaskDomain): string[];
+/**
+ * Universal (domain-INVARIANT) working-approach guidance as a STABLE (memoized)
+ * system section. Byte-identical every turn regardless of the detected domain, so
+ * it belongs in the cacheable system-prompt prefix. The per-turn domain block
+ * (renderDomainGuidanceBlock) is deliberately NOT part of this section — it is
+ * injected as a system message right before the last user message so the system
+ * prompt stays byte-stable when the detected domain switches.
+ */
+export declare function createUniversalGuidanceSection(): SystemPromptSection;
 /**
  * Create a system prompt section that provides tool usage guidance.
  * CC parity: matches claude-code's getUsingYourToolsSection().

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

@@ -16,8 +16,6 @@ export interface FreshWorkspaceEvidencePolicy {
     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;
 /**
@@ -35,4 +33,11 @@ export declare function isExplicitNoToolTurn(messages: readonly PromptMessageLik
  * stay subject to the normal evidence filter.)
  */
 export declare function selectFreshWorkspaceEvidenceTools<TTool extends ToolNameLike>(tools: readonly TTool[], policy: FreshWorkspaceEvidencePolicy): TTool[];
+/**
+ * Prompt notice for an explicit "don't use tools" instruction. This INFORMS the
+ * model and leaves the judgment to it — the engine no longer strips the tool list
+ * (toolChoice="none"), which also silently disabled the reactive guards and
+ * misfired on quoted/reported speech ("he said don't use tools").
+ */
+export declare function createExplicitNoToolNoticeSection(): SystemPromptSection;
 export declare function createFreshWorkspaceEvidenceSection(policy: FreshWorkspaceEvidencePolicy): SystemPromptSection | null;

package/dist/types/runtime/prompt/instruction-loader.d.ts

@@ -54,7 +54,6 @@ export declare function loadInstructions(cwd: string, hooks?: HookRegistry): Pro
  */
 export declare function buildInstructionsPrompt(files: InstructionFileInfo[]): string;
 export declare function extractLiteralResponseRequirements(files: InstructionFileInfo[]): LiteralResponseRequirement[];
-export declare function applyLiteralResponseRequirements(content: string, requirements: readonly LiteralResponseRequirement[]): string;
 /**
  * Get conditional rules that match a target file path.
  * CC parity: getManagedAndUserConditionalRules() + getMemoryFilesForNestedDirectory()

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>;
@@ -26,6 +34,10 @@ export declare function persistInboundUploadUrl(url: string, projectId: string,
 /**
  * Persist + rewrite the inbound uploads on the LAST user message of a turn (the new message;
  * resumed history already carries persisted local URLs). Mutates and returns the message array.
+ *
+ * Failure parity with the document path (appendLocalDocumentNotesToText): when a media upload
+ * could NOT be persisted, the message gets a model-visible note instead of silently keeping a
+ * transport URL that expires with the turn — the model must know the reference is short-lived.
  */
 export declare function persistInboundUploadsForTurn(messages: ChatMessage[], projectId: string | undefined, sessionId: string | undefined): Promise<ChatMessage[]>;
 /**

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

@@ -1,4 +1,12 @@
 import type { SessionListEntry } from "./session-types.js";
 export declare function listSessions(limit: number | undefined, projectRoot: string): Promise<SessionListEntry[]>;
 export declare function deleteSession(sessionId: string, projectRoot: string): Promise<void>;
+/**
+ * ⚠️ Destructive cascade with NO user-visible confirmation: every pruned session goes through
+ * deleteSession, which permanently removes its transcript + metadata + checkpoints + uploads.
+ * Currently has NO caller. If you wire this up, the deletions must be surfaced to the user
+ * (count + which sessions) — silently reaping MAX_SESSIONS-overflow would be exactly the kind of
+ * invisible data loss docs/judgment-over-mechanism.md forbids. Also note listSessions skips
+ * unreadable-metadata sessions, so a prune pass under fs errors could mis-rank what "oldest" is.
+ */
 export declare function pruneOldSessions(projectRoot: string): Promise<number>;

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-resume.d.ts

@@ -1,4 +1,9 @@
 import type { PersistedSession } from "./session-types.js";
+/** Coded error: the session's project root cannot be read at all (deleted dir, unplugged drive,
+ *  permissions). Distinguishable from the `null` return, which strictly means "this session has no
+ *  persisted transcript" — conflating the two made every caller silently start a NEW empty session
+ *  on a read failure (docs/judgment-over-mechanism.md: "read failed" ≠ "does not exist"). */
+export declare const PROJECT_ROOT_UNAVAILABLE = "PROJECT_ROOT_UNAVAILABLE";
 export declare function loadSessionForResume(sessionId: string, projectRoot: string, options?: {
     includeDisplayMetadata?: boolean;
 }): Promise<PersistedSession | null>;

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

@@ -3,11 +3,20 @@ 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[];
 }
+/**
+ * Outcome of an appendMessage call. "skipped-deleted" (the session was deleted — a LEGAL late-write
+ * no-op) is deliberately distinguishable from "failed" (the write itself failed — the message is
+ * LOST and callers must leave a trace / surface it), per docs/judgment-over-mechanism.md:
+ * "does not exist" and "write failed" must never be conflated into one silent boolean.
+ */
+export type AppendMessageOutcome = "appended" | "skipped-deleted" | "failed";
 export declare function appendMessage(sessionId: string, message: ChatMessage, projectRoot: string, turnId?: string, metadata?: {
     usage?: TokenUsage;
     displayMetadata?: MessageDisplayMetadata;
-}): Promise<boolean>;
+}): Promise<AppendMessageOutcome>;
 export declare function countTranscriptMessages(sessionId: string, projectRoot: string): Promise<number | null>;
 export declare function loadTranscript(sessionId: string, projectRoot: string, options?: {
     includeDisplayMetadata?: boolean;

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;
@@ -96,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;

package/dist/types/skills/mcp/mcp-manager.d.ts

@@ -1,4 +1,4 @@
-import type { PortableTool } from "../portable-tool.js";
+import type { PortableTool, PortableToolResult } from "../portable-tool.js";
 interface ToolRegistryLike {
     addTools(tools: PortableTool[]): void;
     getToolNames(): string[];
@@ -35,6 +35,17 @@ export interface McpSecurityIssue {
     code: "dangerous_egress" | "persistence" | "ioc_public_key";
     message: string;
 }
+/**
+ * A configured server that is NOT serving tools this session. Surfaced (not just logged)
+ * so capability queries (e.g. mcp_connectors_list) can disclose "configured but unavailable"
+ * instead of the server silently vanishing from the tool pool.
+ */
+export interface McpServerFailure {
+    name: string;
+    /** "config" = entry invalid, skipped before connect; "connect" = every connect attempt failed. */
+    phase: "config" | "connect";
+    error: string;
+}
 export interface McpManagerConfig {
     servers: McpServerEntry[];
     log?: {
@@ -67,7 +78,10 @@ export declare class McpManager {
     private toolCatalog?;
     private serverToolFilters;
     private serverOAuth;
+    private failedServers;
     constructor(config: McpManagerConfig);
+    /** Record (and loudly report) a server that will serve NO tools this session. */
+    private markServerFailed;
     private toServerDefinition;
     /**
      * Connect to all configured MCP servers and snapshot their tools.
@@ -81,6 +95,8 @@ export declare class McpManager {
     refreshServerTools(serverName: string): Promise<number>;
     /** Get names of all connected servers. */
     getConnectedServers(): string[];
+    /** Configured servers serving NO tools this session (invalid config or terminal connect failure). */
+    getFailedServers(): McpServerFailure[];
     /** Get total number of MCP tools across all servers. */
     getToolCount(): number;
     /**
@@ -95,6 +111,14 @@ export declare class McpManager {
     private registerTools;
     private removeRegisteredTool;
 }
+/**
+ * Flatten an MCP CallToolResult into a text-bearing PortableToolResult.
+ * Non-text blocks (image/audio/resource…) cannot be dropped silently: content is
+ * the only channel the model sees, so the omission is disclosed in the text —
+ * "(no text output)" for a result that DID produce blocks is a lie.
+ * Exported for unit tests only.
+ */
+export declare function toPortableResult(result: unknown): PortableToolResult;
 export declare function validateMcpToolWorkspaceBoundary(toolName: string, args: unknown, workspaceRoot: string | undefined): string | null;
 export declare function parseMcpConfig(json: unknown): McpServerEntry[];
 export declare function filterMcpTools<T extends {

package/dist/types/skills/memory/local-memory-provider.d.ts

@@ -32,6 +32,8 @@ export declare class LocalMemoryProvider implements MemoryProvider {
     private attachmentStore;
     private userIdPrefix;
     private dbPath;
+    /** One-shot flag: the embedding-degradation trace is logged once per provider instance. */
+    private embeddingFailureLogged;
     constructor(config: LocalMemoryProviderConfig);
     /** Persist an uploaded attachment (orphan until linked at commit). */
     adoptAttachment(input: {
@@ -57,9 +59,18 @@ export declare class LocalMemoryProvider implements MemoryProvider {
     /** Persist the understood/extracted text on an attachment row. */
     setAttachmentText(id: string, text: string): void;
     private resolveUserId;
+    /**
+     * The embedding API failing silently downgrades every search to FTS-only —
+     * leave one error-level trace per provider instance (deduped so a broken
+     * endpoint does not flood the log on every query).
+     */
+    private noteEmbeddingFailure;
     private buildEmbedding;
     search(query: string, userId: string, options?: MemorySearchOptions): Promise<MemorySearchResult[]>;
     ingest(messages: MemoryIngestMessage[], userId: string, options?: MemoryIngestOptions): Promise<void>;
+    /** Public embedding access for task-distillation signatures (R3). Null when
+     * the embedding provider is unavailable — callers must degrade, not throw. */
+    embedText(text: string): Promise<Float32Array | null>;
     addText(text: string, userId: string, options?: MemoryIngestOptions & {
         category?: string;
         importance?: number;
@@ -102,6 +113,9 @@ export declare class LocalMemoryProvider implements MemoryProvider {
      * Apply feedback to a memory (useful/irrelevant/outdated/wrong).
      * Adjusts importance or archives/deletes based on signal.
      */
+    /** V3 promote/demote: archive(技能接棒,记忆退役)与 unarchive(降格回归)成对。
+     * claims 状态随动,防 archived 记忆的 claim 继续参与冲突/召回。 */
+    setMemoryArchived(memoryId: string, archived: boolean): boolean;
     feedback(memoryIds: string[], signal: "useful" | "irrelevant" | "outdated" | "wrong"): Promise<{
         affected: number;
     }>;

package/dist/types/skills/memory/local-store.d.ts

@@ -103,6 +103,8 @@ export declare class LocalMemoryStore {
      * Used by dedup gate when a similar but newer memory supersedes an older one.
      */
     archive(id: string): boolean;
+    /** V3 demote(降格)恢复:archived procedure 回归召回池,与 archive 成对。 */
+    unarchive(id: string): boolean;
     /**
      * Temporal expiry: archive event/plan memories whose event_date has passed
      * beyond a grace period (e.g., "meeting tomorrow" 3 days after it happened).

package/dist/types/skills/memory/memdir.d.ts

@@ -8,6 +8,14 @@ export declare const TOPIC_FILE_MAX_CHARS = 8192;
 export declare function getMemdirPath(projectRoot: string): string;
 /** Full path to INDEX.md */
 export declare function getIndexPath(projectRoot: string): string;
+/** Global-layer size budget: a cheat-sheet, not a memory store. */
+export declare const USER_INDEX_MAX_CHARS = 2048;
+export declare const USER_INDEX_MAX_LINES = 40;
+/** Full path to the user-level global INDEX.md (QLOGICAGENT_HOME aware). */
+export declare function getUserIndexPath(): string;
+/** Read the global layer for prompt injection, capped by the cheat-sheet budget.
+ * Returns null when absent/empty — the section simply doesn't render. */
+export declare function readUserIndexForPrompt(): string | null;
 export interface MemdirFileInfo {
     name: string;
     /** Size in bytes */

package/dist/types/skills/memory/task-distillation.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Task distillation (R3, 记忆体系 v2) — 任务后蒸馏的纯逻辑层。
+ * spec: xiaozhiclaw-runtime/docs/memory-layering-and-distillation-spec.md
+ *
+ * 蒸馏对象 = "费了劲才做成的任务的做法"(程序性配方),绝不是每轮都跑:
+ *   候选采集(回合完成,轻量) → 空闲窗聚类(签名 embedding,宁严勿松) →
+ *   簇 ≥ 重复阈值才产 1 条 procedure 记忆 → 高复用晋升技能(见 coordinator)。
+ * 成功闸不用 LLM 自评:正常终态 + 同 session 近窗内未被"重做"(在线否决)。
+ * 与 feedback-distillation(反馈域)无关 —— 这里蒸馏的是任务执行模式。
+ */
+/** 同模式判定的余弦下限。错聚有害(把不同任务蒸成一份配方),漏聚无害(下次再攒)。 */
+export declare const TASK_DISTILL_CLUSTER_SIM = 0.86;
+/** 在线否决窗口:同 session 内距离 ≤N 回合出现高相似任务 = 前一次疑似被重做(纠正信号)。 */
+export declare const TASK_DISTILL_REDO_WINDOW_TURNS = 3;
+/** 候选滚动上限(jsonl 只保留最近 N 条,防无界增长)。 */
+export declare const TASK_DISTILL_MAX_CANDIDATES = 200;
+/** 晋升推荐阈值:procedure 被召回复用 ≥N 次且未被负反馈沉底。 */
+export declare const TASK_DISTILL_PROMOTE_ACCESS = 3;
+export declare const PROCEDURE_TAG = "distilled@v1";
+export declare const PROCEDURE_CATEGORY = "procedure";
+export interface TaskCandidate {
+    id: string;
+    sessionId: string;
+    /** session 内回合序号(在线否决的距离度量) */
+    turnIndex: number;
+    /** 任务首句(user prompt 头部,签名文本) */
+    promptHead: string;
+    toolCallCount: number;
+    distinctToolCount: number;
+    /** 工具调用序列(name 有序去连续重复),配方步骤的原料 */
+    toolSequence: string[];
+    durationMs: number;
+    at: number;
+    /** 签名 embedding(bge-m3);无 embedding 的候选不参与聚类(宁严勿松) */
+    embedding?: number[];
+    status: "pending" | "rejected" | "distilled";
+}
+export interface CandidateStoreFile {
+    candidates: TaskCandidate[];
+}
+export declare function candidateStorePath(profileMemoryDir: string): string;
+export declare function readCandidateStore(path: string): CandidateStoreFile;
+export declare function writeCandidateStore(path: string, store: CandidateStoreFile): void;
+export declare function cosine(a: readonly number[], b: readonly number[]): number;
+export interface CollectInput {
+    id: string;
+    sessionId: string;
+    turnIndex: number;
+    promptHead: string;
+    toolCallCount: number;
+    distinctToolCount: number;
+    toolSequence: string[];
+    durationMs: number;
+    at: number;
+    embedding?: number[];
+    /** 回合终态:非正常终态的任务不候选(成功闸①) */
+    ok: boolean;
+}
+export interface CollectResult {
+    accepted: boolean;
+    /** 被本次采集在线否决(疑似被重做)的旧候选 id */
+    rejectedIds: string[];
+    reason?: string;
+}
+/**
+ * 采集一个回合为蒸馏候选。
+ * 在线否决(成功闸②):同 session、距离 ≤REDO_WINDOW 回合内出现高相似新任务,
+ * 视为前一次被重做/纠正 —— 否决旧候选(新候选照常入列,它可能是成功版)。
+ * 跨 session 或距离更远的相似 = 模式重复,恰是蒸馏想要的信号,全部保留。
+ */
+export declare function collectCandidate(store: CandidateStoreFile, input: CollectInput): CollectResult;
+export declare function clusterCandidates(store: CandidateStoreFile): TaskCandidate[][];
+/** 压缩工具序列:去连续重复,保顺序。 */
+export declare function compressToolSequence(seq: readonly string[]): string[];
+export declare function clusterSignature(cluster: readonly TaskCandidate[]): string;
+export declare function renderProcedureFallback(cluster: readonly TaskCandidate[]): string;
+/** reverted = 升格后被撤销(降格) —— 与"暂不"(dismissed)分开计,是降格率仪表的分子。 */
+export type PromotionStatus = "proposed" | "accepted" | "dismissed" | "reverted";
+export interface PromotionProposal {
+    procedureId: string;
+    /** 配方首行(展示用) */
+    title: string;
+    accessCount: number;
+    proposedAt: number;
+    status: PromotionStatus;
+    /** 状态变迁时间(度量面:接受率/响应时长的数据源) */
+    resolvedAt?: number;
+    /** accepted 时记录升格产出的技能名(demote 反查) */
+    skillName?: string;
+    /** V3.3 自动档升格(非用户点击) */
+    auto?: boolean;
+    /** 自动升格的开场确认卡已读(「知道了」) */
+    acknowledgedAt?: number;
+}
+export interface PromotionStoreFile {
+    proposals: PromotionProposal[];
+}
+export declare function promotionStorePath(profileMemoryDir: string): string;
+export declare function readPromotionStore(path: string): PromotionStoreFile;
+export declare function writePromotionStore(path: string, store: PromotionStoreFile): void;
+/** 达标条目 upsert 为提议。dismissed/accepted 是终态,永不复活(拍板②:暂不=不再打扰)。
+ * 已 proposed 的只刷新 accessCount。返回是否新增。 */
+export declare function upsertProposal(store: PromotionStoreFile, input: {
+    procedureId: string;
+    title: string;
+    accessCount: number;
+    now: number;
+}): boolean;
+export declare function resolveProposal(store: PromotionStoreFile, procedureId: string, status: "accepted" | "dismissed", now: number): boolean;
+/** 降格:accepted → reverted(区分"暂不";降格率=reverted/accepted 家族)。 */
+export declare function revertProposal(store: PromotionStoreFile, procedureId: string, now: number): PromotionProposal | null;
+/** 配方文本 → SKILL.md 的确定性降级模板(LLM 格式转换失败时兜底)。 */
+export declare function renderSkillMarkdownFallback(name: string, procedureText: string): string;
+/** 自动档解锁条件(拍板③):样本、接受率、降格率。 */
+export declare const V3_AUTO_MIN_SAMPLES = 10;
+export declare const V3_AUTO_MIN_ACCEPT_RATE = 0.7;
+export declare const V3_AUTO_MAX_REVERT_RATE = 0.1;
+/** 自动档触发严阈值(拍板④,比手动档 3 更严)。 */
+export declare const V3_AUTO_MIN_ACCESS = 5;
+export declare const V3_AUTO_MIN_SESSIONS = 3;
+export interface ProcedureUsage {
+    /** 召回复用过它的 session 集合 */
+    sessions: string[];
+    /** 复用后回合失败次数(零容忍:自动档要求 0) */
+    negativeCount: number;
+}
+export interface ProcedureUsageStoreFile {
+    usage: Record<string, ProcedureUsage>;
+}
+export declare function procedureUsagePath(profileMemoryDir: string): string;
+export declare function readProcedureUsage(path: string): ProcedureUsageStoreFile;
+export declare function writeProcedureUsage(path: string, store: ProcedureUsageStoreFile): void;
+export declare function recordProcedureRecall(store: ProcedureUsageStoreFile, procedureId: string, sessionId: string): void;
+export declare function recordProcedureNegative(store: ProcedureUsageStoreFile, procedureId: string): void;
+export interface PromotionMetrics {
+    samples: number;
+    accepted: number;
+    dismissed: number;
+    reverted: number;
+    acceptRate: number;
+    revertRate: number;
+    autoEnabled: boolean;
+}
+/** 手动阶段仪表(拍板③):接受率=accepted 家族/已决样本;降格率=reverted/accepted 家族。
+ * 任何时刻降格率回升超限即自动退回手动档(autoEnabled 现算,无粘滞)。 */
+export declare function computePromotionMetrics(proposals: readonly PromotionProposal[]): PromotionMetrics;
+/** 自动档严阈值(拍板④):复用 ≥5 + 跨 ≥3 session + 零负反馈。 */
+export declare function qualifiesForAutoPromotion(accessCount: number, usage: ProcedureUsage | undefined): boolean;

package/dist/types/skills/tools/search-tool.d.ts

@@ -105,6 +105,12 @@ export interface SearchToolDeps {
             contextAfter?: string[];
         }>;
         truncated: boolean;
+        /**
+         * Optional incompleteness note from the backend (e.g. the search process was
+         * killed by timeout/output cap). Appended verbatim to the model-visible
+         * content — details alone would be silent to the model.
+         */
+        note?: string;
     }>;
     /** Resolve relative path to absolute. If omitted, cwd is used. */
     resolvePath?(input: string): string;

package/dist/types/skills/tools/shell/task-output.d.ts

@@ -30,6 +30,8 @@ export declare class TaskOutput {
     /** Get captured stderr. In file mode stderr is interleaved with stdout. */
     getStderr(): string;
     get outputFileSize(): number;
+    /** Non-null when the last spill-to-disk attempt failed (output only in memory). */
+    get spillError(): string | null;
     /**
      * Whether the output file content is fully contained in getStdout().
      * If true, the file can be deleted.