qlogicagent 2.20.1 → 2.20.3

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

@@ -8,13 +8,15 @@
  * 单一事实源:docs/agent-supervision-authority-migration-spec.md §3.1;契约 host-contract §13
  * (HostRequestParams;wire 形态 = { service:"memory", method, params:<位置参数数组> })。
  *
- * 【PROXY 共享面(16 方法;两仓照此表,一字不差)】
+ * 【PROXY 共享面(以 host-contract 常量为准;两仓照此表,一字不差)】
  *   search / addText / embedText / ingestExtracted / proposeExtracted / consumePendingProposals /
  *   feedback / findRelatedEvents / synthesizeTimeline / getActivitySummary / getAllProfiles /
  *   setProfile / getAtlas / setMemoryArchived / triggerDecay / resolveConflicts
  *   [A9] 追加 listActiveMemoriesByTag(晋升扫描全量列举;无窗/无 clamp/无上限)。
- *   [A10] 追加 promoteDistilledProcedure(升格窄 Saga;幂等/补偿/续跑在 Host)。
+ *   [A10] 追加 readDistilledProcedure / promoteDistilledProcedure / demoteDistilledProcedure
+ *   (精确恢复读与升/降格窄 Saga;幂等/补偿/续跑在 Host)。
  *   [A7] 追加 recordInjectedAccess(注入后记账:search 去记账后 access_count 的唯一召回侧写点)。
+ *   后台提取交接由 enqueue/list/complete/failure 四法持久化；重启不丢完成回合。
  *
  * 面外方法 = fail-loud throw(护栏抓漏):gate 开时 UI RPC 面(atlas 富查询/update/attachments/
  * proposals 消费等)由 gateway host-native 应答,**不该**再落到 qla 的 provider;到达此处 = 路由/
@@ -24,9 +26,9 @@
  * userId 参数原样透传(多租户前缀语义归 gateway store-owner)。
  * 纪律:fail-loud;单轨(创建时刻一次选型,非每调用分支);零 mock。
  */
-import type { HostRequestParams } from "../../host-contract/index.js";
+import type { HostMemoryExtractionTurnInput, HostPendingMemoryExtractionTurn, HostRequestParams } from "../../host-contract/index.js";
 import type { CandidateStoreFile, ProcedureUsageStoreFile, PromotionStoreFile } from "./task-distillation.js";
-import type { MemoryActivitySummary, MemoryAtlasResult, MemoryConsolidationWriteResult, MemoryDreamRuntimeProvider, MemoryExtractionItem, MemoryHandlerProvider, MemoryIngestOptions, MemoryLearningSink, MemoryRuntimeHookProvider, MemorySearchOptions, MemorySearchResult, MemoryToolProvider } from "../../runtime/ports/index.js";
+import type { MemoryActivitySummary, MemoryAtlasResult, MemoryConsolidationWriteResult, MemoryDreamRuntimeProvider, MemoryExtractionItem, MemoryHandlerProvider, MemoryIngestOptions, MemoryLearningSink, MemoryExtractionQueue, MemoryRuntimeHookProvider, MemorySearchOptions, MemorySearchResult, MemoryToolProvider } from "../../runtime/ports/index.js";
 /**
  * 最小转发口(结构化契约,由 coordinator-owned HostRequestClient 满足)。
  * 只取 request 一个方法:provider 不持有判活/连接生命周期(那归协议 coordinator/client)。
@@ -41,12 +43,12 @@ export interface HostMemoryProviderConfig {
     /** x/host.request client; its service gate runs before send. */
     client: HostRequestRequester;
 }
-export declare class HostMemoryProvider implements MemoryRuntimeHookProvider, MemoryLearningSink, MemoryToolProvider, MemoryHandlerProvider, MemoryDreamRuntimeProvider {
+export declare class HostMemoryProvider implements MemoryRuntimeHookProvider, MemoryExtractionQueue, MemoryLearningSink, MemoryToolProvider, MemoryHandlerProvider, MemoryDreamRuntimeProvider {
     private readonly config;
     readonly providerId = "qmemory-host";
     constructor(config: HostMemoryProviderConfig);
     /**
-     * 16 面统一转发:wire 形态 = { service:"memory", method, params:<位置参数数组> }(契约 §13)。
+     * 全部 memory proxy 方法统一转发:wire 形态 = { service:"memory", method, params:<位置参数数组> }(契约 §13)。
      * 尾部 undefined 剔除:JSON 会把数组里的 undefined 序列化成 null,gateway 侧按位展开时
      * null ≠ undefined 会击穿方法默认参(如 days=7)——省略实参才能让默认参生效。
      */
@@ -61,9 +63,26 @@ export declare class HostMemoryProvider implements MemoryRuntimeHookProvider, Me
         memoriesAdded: number;
     }>;
     /** R3 蒸馏签名 embedding(gateway 调 llmrouter 现算);null = 不可用,调用方降级不炸。 */
-    embedText(text: string): Promise<number[] | null>;
+    embedText(text: string, signal?: AbortSignal): Promise<number[] | null>;
     ingestExtracted(items: MemoryExtractionItem[], userId: string, options?: MemoryIngestOptions): Promise<MemoryConsolidationWriteResult>;
     proposeExtracted(items: MemoryExtractionItem[], userId: string, options?: MemoryIngestOptions): Promise<MemoryConsolidationWriteResult>;
+    enqueueExtractionTurn(input: HostMemoryExtractionTurnInput, userId: string): Promise<{
+        jobId: string;
+        created: boolean;
+    }>;
+    claimPendingExtractionTurns(userId: string, workerId: string, options?: {
+        limit?: number;
+        leaseMs?: number;
+    }): Promise<HostPendingMemoryExtractionTurn[]>;
+    completeExtractionTurn(jobId: string, userId: string, workerId: string): Promise<{
+        deleted: boolean;
+    }>;
+    releaseExtractionTurn(jobId: string, userId: string, workerId: string): Promise<{
+        released: boolean;
+    }>;
+    recordExtractionTurnFailure(jobId: string, userId: string, workerId: string, error: string): Promise<{
+        updated: boolean;
+    }>;
     consumePendingProposals(userId: string, opts?: {
         now?: number;
         ttlMs?: number;
@@ -74,7 +93,10 @@ export declare class HostMemoryProvider implements MemoryRuntimeHookProvider, Me
         expiredIds: string[];
         pendingLeft: number;
     }>;
-    feedback(memoryIds: string[], signal: "useful" | "irrelevant" | "outdated" | "wrong"): Promise<{
+    feedback(memoryIds: string[], signal: "useful" | "irrelevant" | "outdated" | "wrong", context?: {
+        sessionId?: string;
+        silent?: boolean;
+    }): Promise<{
         affected: number;
     }>;
     findRelatedEvents(text: string, userId: string, options?: {
@@ -125,6 +147,13 @@ export declare class HostMemoryProvider implements MemoryRuntimeHookProvider, Me
         accessCount: number;
         importance: number;
     }>>;
+    readDistilledProcedure(userId: string, procedureId: string, tag: string): Promise<{
+        id: string;
+        text: string;
+        accessCount: number;
+        importance: number;
+        isArchived: boolean;
+    } | null>;
     /** [A10] 升格窄 Saga(Host 协调):create+verify → archive → proposal accepted 三步
      * 横跨 Capability/Memory 两个 Host 存储,幂等(procedureId+确定性 skillName)、逐步
      * 补偿、崩溃续跑全在 Host;大脑只做推理与提案后单调此法。 */
@@ -144,10 +173,31 @@ export declare class HostMemoryProvider implements MemoryRuntimeHookProvider, Me
             proposalAccepted: boolean;
         };
     }>;
+    demoteDistilledProcedure(input: {
+        procedureId: string;
+    }): Promise<{
+        outcome: "completed" | "already-completed";
+        skillName: string;
+        steps: {
+            skillDeleted: boolean;
+            memoryUnarchived: boolean;
+            proposalReverted: boolean;
+        };
+    }>;
     /** [A7] 注入后访问记账:上报本轮真实进 prompt 的 L2 id 集(memory.after_recall 的
      * post-cap 名单)。Host 是 access_count/last_accessed_at 的唯一写者;search() 已不再
      * 命中即记 —— 漏调此法只会低估复用,绝不虚增。 */
-    recordInjectedAccess(memoryIds: string[], userId: string): Promise<{
+    recordInjectedAccess(memoryIds: string[], userId: string, context?: {
+        sessionId: string;
+        turnId: string;
+    }): Promise<{
+        affected: number;
+    }>;
+    recordRecallOutcome(userId: string, input: {
+        sessionId: string;
+        turnId: string;
+        event: "used" | "helped" | "harmed" | "unattributed";
+    }): Promise<{
         affected: number;
     }>;
     /** 本 provider 不持有 db 句柄/文件资源;close 为 no-op(shutdown 链 closeMemoryProviders 会调)。 */

package/dist/types/skills/memory/memory-tool.d.ts

@@ -49,7 +49,7 @@ export declare const MEMORY_TOOL_SCHEMA: {
         };
         readonly category: {
             readonly type: "string";
-            readonly enum: readonly ["preference", "personal_fact", "lesson", "pattern", "decision", "context"];
+            readonly enum: string[];
             readonly description: "For 'remember': categorize the memory (helps with future recall precision).";
         };
     };
@@ -81,5 +81,7 @@ export interface MemoryToolExecutorDeps {
     /** Runtime memory provider for temporal/feedback (typed narrow for advanced ops). */
     localProvider?: MemoryToolLocalProvider;
     userId: string;
+    /** Owning foreground session for user-visible memory mutations. */
+    sessionId?: string;
 }
 export declare function executeMemoryTool(params: MemoryToolParams, deps: MemoryToolExecutorDeps): Promise<MemoryToolResult>;

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

@@ -4,7 +4,7 @@
  *
  * 蒸馏对象 = "费了劲才做成的任务的做法"(程序性配方),绝不是每轮都跑:
  *   候选采集(回合完成,轻量) → 空闲窗聚类(签名 embedding,宁严勿松) →
- *   簇 ≥ 重复阈值才产 1 条 procedure 记忆 → 高复用晋升技能(见 coordinator)。
+ *   簇 ≥ 重复阈值才产 1 条 procedure 记忆 → 通过来源与前台结果验证后才可晋升技能。
  * 成功闸不用 LLM 自评:正常终态 + 同 session 近窗内未被"重做"(在线否决)。
  * 与 feedback-distillation(反馈域)无关 —— 这里蒸馏的是任务执行模式。
  *
@@ -14,13 +14,15 @@
  * proxy 的 read/write{DistillCandidates,PromotionProposals,ProcedureUsage} 存取,本文件只提供
  * 采集/聚类/晋升的确定性算法。单一事实源 docs/agent-supervision-authority-migration-spec.md。
  */
+import { type HubSkillCategory } from "../skill-system/skill-category.js";
+import type { ProcedureVerificationEvidence } from "../../host-contract/index.js";
 /** 同模式判定的余弦下限。错聚有害(把不同任务蒸成一份配方),漏聚无害(下次再攒)。 */
 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 实际进入 prompt(注入闸后)≥N 次且未被负反馈沉底。
+/** 晋升候选发现阈值:procedure 实际进入 prompt(注入闸后)≥N 次。
  * [A7 重标定] 记账点已从 before_recall(检索命中)移到实际注入之后:旧口径把 dream/
  * planner brief/写入去重探测等 8 条非召回链路的 search 命中都算成"复用",恒 ≥ 真实值;
  * 新口径 = 模型真看到过的次数。阈值数值保留 3:设计意图本就是"真实复用 3 次",旧记账
@@ -42,7 +44,7 @@ export interface TaskCandidate {
     toolSequence: string[];
     durationMs: number;
     at: number;
-    /** 签名 embedding(bge-m3);无 embedding 的候选不参与聚类(宁严勿松) */
+    /** 签名 embedding（优先用于语义聚类）；缺失时仅允许跨会话的严格同配方聚类。 */
     embedding?: number[];
     status: "pending" | "rejected" | "distilled";
 }
@@ -80,6 +82,9 @@ export interface CollectResult {
  * 跨 session 或距离更远的相似 = 模式重复,恰是蒸馏想要的信号,全部保留。
  */
 export declare function collectCandidate(store: CandidateStoreFile, input: CollectInput): CollectResult;
+/** Attach a background-produced embedding to an already durable candidate while
+ * preserving the same-session redo rejection rule used by inline collection. */
+export declare function attachCandidateEmbedding(store: CandidateStoreFile, candidateId: string, embedding: number[]): string[];
 export declare function clusterCandidates(store: CandidateStoreFile): TaskCandidate[][];
 /** 压缩工具序列:去连续重复,保顺序。 */
 export declare function compressToolSequence(seq: readonly string[]): string[];
@@ -89,6 +94,8 @@ export declare function renderProcedureFallback(cluster: readonly TaskCandidate[
 export type PromotionStatus = "proposed" | "accepted" | "dismissed" | "reverted";
 export interface PromotionProposal {
     procedureId: string;
+    /** Host/Hub 单一技能分类；候选展示与最终 SKILL.md 使用同一枚举。 */
+    category: HubSkillCategory;
     /** 配方首行(展示用) */
     title: string;
     accessCount: number;
@@ -102,6 +109,8 @@ export interface PromotionProposal {
     auto?: boolean;
     /** 自动升格的开场确认卡已读(「知道了」) */
     acknowledgedAt?: number;
+    /** Host 根据来源成功样本与前台真实结果账计算；缺失或 passed=false 均不得升格。 */
+    verification: ProcedureVerificationEvidence;
 }
 export interface PromotionStoreFile {
     proposals: PromotionProposal[];
@@ -111,9 +120,13 @@ export interface PromotionStoreFile {
 export declare function upsertProposal(store: PromotionStoreFile, input: {
     procedureId: string;
     title: string;
+    category: HubSkillCategory;
     accessCount: number;
     now: number;
+    verification: ProcedureVerificationEvidence;
 }): boolean;
+/** One-way migration for proposals written before category became a Host contract. */
+export declare function migratePromotionProposalCategories(store: PromotionStoreFile): 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;
@@ -156,6 +169,12 @@ export interface PromotionMetrics {
 /** 手动阶段仪表(拍板③):接受率=accepted 家族/已决样本;降格率=reverted/accepted 家族。
  * 任何时刻降格率回升超限即自动退回手动档(autoEnabled 现算,无粘滞)。 */
 export declare function computePromotionMetrics(proposals: readonly PromotionProposal[]): PromotionMetrics;
+/**
+ * Release acceptance may bypass only the historical manual-decision calibration wait.
+ * The real access/session/negative-feedback gates remain enforced by
+ * qualifiesForAutoPromotion, and the flag is process-scoped by the isolated harness.
+ */
+export declare function isAutoPromotionCalibrationEnabled(metrics: Pick<PromotionMetrics, "autoEnabled">, env?: Readonly<Record<string, string | undefined>>): boolean;
 /** 自动档严阈值(拍板④):复用 ≥5 + 跨 ≥3 session + 零负反馈。
  * [A7] 三个输入如今全部以"实际注入 prompt"为记账点:accessCount 来自 Host 的
  * recordInjectedAccess(post-cap 名单),sessions 来自 after_recall 侧的

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

@@ -51,6 +51,13 @@ export interface PermissionCheckerDeps {
     persistPermissionRule?: (rule: {
         pathPrefix: string;
     }) => void | Promise<void>;
+    /**
+     * Persist a directory allow-rule for this canonical session. Unlike the user-level
+     * persistent option, this record is restored only when the same session resumes.
+     */
+    persistSessionPermissionRule?: (rule: {
+        pathPrefix: string;
+    }) => void | Promise<void>;
 }
 export declare class PermissionChecker {
     private readonly ruleEngine;
@@ -66,6 +73,7 @@ export declare class PermissionChecker {
     private readonly sessionId;
     private readonly getTurnId;
     private readonly persistPermissionRule;
+    private readonly persistSessionPermissionRule;
     private unregisterHook;
     /** Tool meta cache — populated from ToolDefinition[] at agent creation */
     private toolMetaCache;

package/dist/types/skills/permissions/operation-classifier.d.ts

@@ -32,6 +32,13 @@ export interface ClassifyContext {
  */
 export declare const SHELL_TOOL_NAMES: Set<string>;
 export declare function isWithinWorkspace(resolved: string, root: string): boolean;
+/**
+ * Resolve symlinks/junctions for the existing portion of a target path. For a
+ * not-yet-created leaf, resolve the nearest existing ancestor and append the
+ * missing suffix. This keeps permission classification aligned with where the
+ * filesystem operation will actually land.
+ */
+export declare function canonicalizePathForBoundary(input: string): string;
 /**
  * 提取 shell 命令引用的路径(重定向目标 + Unix/Windows/相对路径),解析为绝对路径。
  * 移植自 exec validateCommand;win32 下把 /c/Users → C:\Users;跳过单字母 flag(/c /s …);

package/dist/types/skills/skill-system/skill-category.d.ts

@@ -0,0 +1,10 @@
+import { type HubSkillCategory } from "../../host-contract/skill-category.js";
+export { HUB_SKILL_CATEGORIES, HUB_SKILL_CATEGORY_LABELS, isHubSkillCategory, type HubSkillCategory, } from "../../host-contract/skill-category.js";
+/**
+ * Offline-safe domain selection. Keyword matches are deliberately narrow; an
+ * unclassified general procedure belongs to general productivity rather than
+ * inventing a pseudo category that the Hub/UI cannot render.
+ */
+export declare function classifyProcedureCategory(text: string): HubSkillCategory;
+/** Read an exact allowlisted category only from the leading YAML frontmatter. */
+export declare function extractRenderedSkillCategory(markdown: string): HubSkillCategory | null;

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

@@ -7,17 +7,16 @@ export declare const AGENT_TOOL_NAME: "agent";
 export type BuiltInAgentType = "general" | "explore" | "plan" | "code" | "research" | "verify";
 export declare const BUILT_IN_AGENT_TYPES: BuiltInAgentType[];
 export interface AgentToolParams {
-    /** Built-in agent type to invoke. */
-    agent: BuiltInAgentType;
-    /** Detailed task prompt for the sub-agent. */
+    /** Optional specialization. The engine defaults to a generalist. */
+    agent?: BuiltInAgentType;
+    /** Focused objective for the sub-agent. Context is supplied automatically. */
     prompt: string;
-    /** Short description of the task (3-7 words). Used for status display. */
+    /** Legacy direct-call options. They are intentionally hidden from the model schema. */
     description?: string;
-    /** Max turns override (default varies by agent type). */
     maxTurns?: number;
-    /** Run in background (returns task_id immediately). */
+    /** Run in background. Defaults to true so the parent can keep working. */
     background?: boolean;
-    /** Inherit a trimmed prefix of the parent conversation (default false). */
+    /** Deprecated compatibility field; forks receive a bounded capsule automatically. */
     inheritContext?: boolean;
 }
 export declare const AGENT_TOOL_SCHEMA: {
@@ -32,34 +31,27 @@ export declare const AGENT_TOOL_SCHEMA: {
             readonly type: "string";
             readonly description: string;
         };
-        readonly description: {
-            readonly type: "string";
-            readonly description: "Short description (3-7 words) for status tracking.";
-        };
-        readonly maxTurns: {
-            readonly type: "number";
-            readonly description: "Max turns for the sub-agent. Defaults: general=200, explore=50, plan=80, code=200, research=30, verify=40.";
-        };
         readonly background: {
             readonly type: "boolean";
             readonly description: string;
         };
-        readonly inheritContext: {
-            readonly type: "boolean";
-            readonly description: string;
-        };
     };
-    readonly required: readonly ["agent", "prompt"];
+    readonly required: readonly ["prompt"];
     readonly additionalProperties: false;
 };
 export interface AgentResult {
-    /** Foreground: synthetic fork id. Background: real TaskStore task id (poll via task tool). */
+    /** Foreground: synthetic fork id. Background: real TaskStore task id used for correlation/status. */
     agentId: string;
     status: "completed" | "running" | "failed";
     output?: string;
     error?: string;
     maxTurnsReached?: boolean;
     tokensUsed?: number;
+    uiAcceptanceEvidence?: Array<{
+        source: "fork_verify";
+        status: "passed";
+        summary: string;
+    }>;
 }
 /**
  * Host-provided fork execution backend.

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

@@ -1,9 +1,11 @@
 import type { PortableTool } from "../portable-tool.js";
+import { type TextFileReadResult, type TextFileWriteOptions } from "./file-text-snapshot.js";
 export declare const EDIT_TOOL_NAME: "edit";
 export interface EditToolParams {
     path: string;
     oldText: string;
     newText: string;
+    expectedHash?: string;
 }
 export declare const EDIT_TOOL_SCHEMA: {
     readonly type: "object";
@@ -20,17 +22,23 @@ export declare const EDIT_TOOL_SCHEMA: {
             readonly type: "string";
             readonly description: "New text to replace the old text with.";
         };
+        readonly expectedHash: {
+            readonly type: "string";
+            readonly description: "Optional sha256 hash returned by read. The edit is rejected if the file changed since that read.";
+        };
     };
     readonly required: readonly ["path", "oldText", "newText"];
 };
 /** Deps injected by the host runtime for file editing. */
 export interface EditToolDeps {
     /** Read file content as text. */
-    readFile(path: string): Promise<string>;
+    readFile(path: string): Promise<TextFileReadResult>;
     /** Write content back. */
-    writeFile(path: string, content: string): Promise<void>;
+    writeFile(path: string, content: string, options?: TextFileWriteOptions): Promise<void>;
     /** Resolve a relative path to absolute. */
     resolvePath(input: string): string;
+    /** Validate access to the resolved path. Null means allowed. */
+    validatePath?(path: string): string | null;
     /**
      * Check for concurrent modification before writing.
      * The host tracks when each file was last read vs last modified on disk.

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

@@ -54,9 +54,9 @@ export interface ExecToolOutput {
 export interface ExecProgress {
     type: "exec_progress";
     output: string;
-    fullOutput: string;
+    progressSnapshot: string;
     elapsedTimeSeconds: number;
-    totalLines: number;
+    visibleLines: number;
     totalBytes: number;
     taskId?: string;
 }

package/dist/types/skills/tools/file-text-snapshot.d.ts

@@ -0,0 +1,24 @@
+export type TextFileEncoding = "utf8" | "utf16le" | "utf16be";
+export type TextFileEol = "\n" | "\r\n" | "\r";
+export interface TextFileFormat {
+    encoding: TextFileEncoding;
+    bom: boolean;
+    eol: TextFileEol;
+}
+export interface TextFileSnapshot {
+    text: string;
+    /** SHA-256 of the exact on-disk bytes, including any BOM. */
+    contentHash: string;
+    format: TextFileFormat;
+}
+export interface TextFileWriteOptions {
+    /** Reject the write if the current on-disk byte hash differs. */
+    expectedHash?: string;
+    /** Atomically fail instead of replacing an existing destination. */
+    createOnly?: boolean;
+    /** Explicit output format, used when moving a file to a new path. */
+    format?: TextFileFormat;
+}
+export type TextFileReadResult = string | TextFileSnapshot;
+export declare function textFromReadResult(result: TextFileReadResult): string;
+export declare function snapshotFromReadResult(result: TextFileReadResult): TextFileSnapshot | undefined;

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

@@ -139,7 +139,7 @@ export interface LspToolDeps {
         character?: number;
         newName?: string;
         includeContext?: boolean;
-    }): Promise<LspResult>;
+    }, signal?: AbortSignal): Promise<LspResult>;
     /** Check if file exists and get its size */
     statFile?(filePath: string): Promise<{
         exists: boolean;

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

@@ -1,4 +1,5 @@
 import type { PortableTool } from "../portable-tool.js";
+import { type TextFileReadResult, type TextFileWriteOptions } from "./file-text-snapshot.js";
 export declare const PATCH_TOOL_NAME: "patch";
 export interface PatchToolParams {
     /** V4A unified diff or simple find-replace */
@@ -28,11 +29,17 @@ export interface PatchResult {
     errors: string[];
 }
 export interface PatchToolDeps {
-    readFile(path: string): Promise<string>;
-    writeFile(path: string, content: string): Promise<void>;
-    deleteFile(path: string): Promise<void>;
+    readFile(path: string): Promise<TextFileReadResult>;
+    writeFile(path: string, content: string, options?: TextFileWriteOptions): Promise<void | {
+        contentHash: string;
+    }>;
+    deleteFile(path: string, options?: Pick<TextFileWriteOptions, "expectedHash">): Promise<void>;
     fileExists(path: string): Promise<boolean>;
     resolvePath(input: string): string;
+    /** Validate access to a resolved patch target. Null means allowed. */
+    validatePath?(path: string): string | null;
+    /** Reject stale explicit-read observations before parsing/mutating targets. */
+    checkConcurrentModification?(path: string): string | null;
 }
 export type MatchStrategy = "exact" | "line_trimmed" | "whitespace_normalized" | "indentation_flexible" | "escape_normalized" | "trimmed_boundary" | "unicode_normalized" | "block_anchor" | "context_aware";
 interface MatchResult {

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

@@ -4,6 +4,7 @@ export interface ReadToolParams {
     path: string;
     offset?: number;
     limit?: number;
+    includeMetadata?: boolean;
 }
 export declare const READ_TOOL_SCHEMA: {
     readonly type: "object";
@@ -20,6 +21,10 @@ export declare const READ_TOOL_SCHEMA: {
             readonly type: "number";
             readonly description: "Maximum number of lines to read. Default/max: 2000.";
         };
+        readonly includeMetadata: {
+            readonly type: "boolean";
+            readonly description: "Scan to EOF to return an exact totalLines and sha256 contentHash. Default false for low-latency large-file windows.";
+        };
     };
     readonly required: readonly ["path"];
 };
@@ -27,9 +32,26 @@ export type ReadResultType = "text" | "image" | "binary_rejected";
 /** Deps injected by the host runtime for file reading. */
 export interface ReadToolDeps {
     /** Read file content. Return string for text, image path for images, or rejection. */
-    readFile(path: string): Promise<{
+    readFile(path: string, window?: {
+        offset: number;
+        limit: number;
+        maxBytes: number;
+        scanToEnd?: boolean;
+    }): Promise<{
         type: "text";
         text: string;
+    } | {
+        type: "text_window";
+        text: string;
+        totalLines?: number;
+        startLine: number;
+        endLine: number;
+        hasMore: boolean;
+        fileSizeBytes: number;
+        scannedBytes: number;
+        contentHash?: string;
+        metadataComplete: boolean;
+        truncatedByBytes: boolean;
     } | {
         type: "image";
         localPath: string;

package/dist/types/skills/tools/repo-map-tool.d.ts

@@ -0,0 +1,52 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const REPO_MAP_TOOL_NAME: "repo_map";
+export type RepoMapRefreshMode = "full" | "incremental";
+export type RepoMapSymbolKind = "class" | "function" | "interface" | "type" | "enum" | "constant";
+export interface RepoMapSymbol {
+    kind: RepoMapSymbolKind;
+    name: string;
+    line: number;
+}
+export interface RepoMapFile {
+    path: string;
+    symbols: RepoMapSymbol[];
+    /** Conservative import/module specifiers; a lightweight navigation graph, not compiler resolution. */
+    dependencies?: string[];
+}
+export interface RepoMapMetadata {
+    mode: RepoMapRefreshMode;
+    scannedFiles: number;
+    changedFiles: number;
+    generation: number;
+    totalFiles: number;
+    matchedFiles: number;
+    truncated: boolean;
+    partial?: boolean;
+    stale?: boolean;
+    warning?: string;
+}
+export interface RepoMapResult {
+    files: RepoMapFile[];
+    metadata: RepoMapMetadata;
+}
+export interface RepoMapQuery {
+    query?: string;
+    path?: string;
+    maxFiles?: number;
+    forceFull?: boolean;
+}
+export interface RepoMapService {
+    getMap(query?: RepoMapQuery): Promise<RepoMapResult>;
+}
+export interface RepoMapToolParams {
+    query?: string;
+    path?: string;
+    maxFiles?: number;
+    refresh?: boolean;
+}
+export interface RepoMapToolDeps {
+    workspaceRoot: string;
+    repoMap: RepoMapService;
+    maxResultChars?: number;
+}
+export declare function createRepoMapTool(deps: RepoMapToolDeps): PortableTool<RepoMapToolParams>;

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

@@ -62,7 +62,9 @@ export interface SearchContentResult {
 }
 export interface SearchOutput {
     mode: SearchMode;
-    totalMatches: number;
+    totalMatches?: number;
+    returnedMatches: number;
+    totalMatchesKnown: boolean;
     truncated: boolean;
     fileResults?: SearchFileResult[];
     contentResults?: SearchContentResult[];
@@ -78,9 +80,11 @@ export interface SearchToolDeps {
     glob(pattern: string, options: {
         cwd: string;
         limit: number;
+        offset?: number;
     }): Promise<{
         files: string[];
         truncated: boolean;
+        totalMatches?: number;
     }>;
     /**
      * Search file contents using regex.
@@ -105,6 +109,9 @@ export interface SearchToolDeps {
             contextAfter?: string[];
         }>;
         truncated: boolean;
+        /** Exact match count before pagination, omitted if the backend stopped early. */
+        totalMatches?: number;
+        totalMatchesKnown?: boolean;
         /**
          * Optional incompleteness note from the backend (e.g. the search process was
          * killed by timeout/output cap). Appended verbatim to the model-visible
@@ -114,5 +121,7 @@ export interface SearchToolDeps {
     }>;
     /** Resolve relative path to absolute. If omitted, cwd is used. */
     resolvePath?(input: string): string;
+    /** Validate access to the resolved search root. Null means allowed. */
+    validatePath?(path: string): string | null;
 }
 export declare function createSearchTool(deps: SearchToolDeps): PortableTool<SearchToolParams>;

package/dist/types/skills/tools/shell/index.d.ts

@@ -10,9 +10,8 @@ export { getDestructiveCommandWarning, getPowerShellDestructiveCommandWarning, }
 export type { CommandSemanticResult } from "./command-semantics.js";
 export { interpretCommandResult } from "./command-semantics.js";
 export { TaskOutput, getTaskOutputDir, setTaskOutputDir, getTaskOutputPath, MAX_TASK_OUTPUT_BYTES, } from "./task-output.js";
-export type { ProgressCallback } from "./task-output.js";
 export type { ExecResult, ShellCommand } from "./shell-command.js";
 export { wrapSpawn, createAbortedCommand, createFailedCommand, } from "./shell-command.js";
 export { subprocessEnv } from "./subprocess-env.js";
-export { exec, getCwd, setCwd, initCwd, getOriginalCwd, setShellProvider, getShellProvider, getActiveShellInfo, } from "./shell-exec.js";
+export { exec, getCwd, setCwd, initCwd, runWithCwd, getOriginalCwd, setShellProvider, getShellProvider, getActiveShellInfo, } from "./shell-exec.js";
 export type { ExecOptions } from "./shell-exec.js";

package/dist/types/skills/tools/shell/shell-command.d.ts

@@ -1,4 +1,4 @@
-import type { ChildProcess } from "node:child_process";
+import { type ChildProcess } from "node:child_process";
 import { TaskOutput } from "./task-output.js";
 export interface ExecResult {
     stdout: string;

package/dist/types/skills/tools/shell/shell-exec.d.ts

@@ -1,6 +1,5 @@
 import type { ShellProvider, ShellType } from "./shell-provider.js";
 import { type ShellCommand } from "./shell-command.js";
-import { type ProgressCallback } from "./task-output.js";
 import type { SandboxConfig } from "./sandbox/sandbox-types.js";
 export type { ExecResult } from "./shell-command.js";
 export declare function getCwd(): string;
@@ -9,9 +8,10 @@ export declare function setCwd(path: string, relativeTo?: string, opts?: {
 }): boolean;
 export declare function getOriginalCwd(): string;
 export declare function initCwd(cwd: string): void;
+/** Bind shell and relative file-tool CWD state to one async turn. */
+export declare function runWithCwd<T>(cwd: string, action: () => Promise<T>): Promise<T>;
 export interface ExecOptions {
     timeout?: number;
-    onProgress?: ProgressCallback;
     /** When true, `cd` in the command does NOT update the session CWD. */
     preventCwdChanges?: boolean;
     shouldAutoBackground?: boolean;