attention-manifest-protocol 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.1] - 2026-11-03
+
+### Added
+
+- `ProtocolRegistry` can bind a runtime implementation to a registered protocol entry: `bind`, `implementation`, `resolveImplementation` (type-guarded, optional family check) and `bound`. Implementations are stored by reference and never appear in discovery metadata, and `remove`/`clear` drop the bound implementation together with the entry.
+- `ProtocolEntry.family` names the protocol family, so entries registered by `ProtocolRegistry` can be filtered by protocol (`mcp`, `a2a`, ...).
+- MCP is registered as a concrete protocol rather than a separate registry: `mcpProtocolEntry` builds a `family: "mcp"` entry with its protocol version, endpoint and capabilities, and `mcpListTools`, `mcpSyncTools` and `mcpWithdrawTools` read and mirror an endpoint's tools through the bound implementation.
+
+### Validation
+
+- Joint regression: 189/189 and 50/50 across protocol, registry, discovery, MCP executor, workspace and database suites; source and tools typechecks passed.
+
+## [0.6.0] - 2026-11-03
+
+### Added
+
+- `outlineAddress(range, charset, bounds)` and the related line/byte request helpers convert an outline node's `range` into the `startLine`/`endLine` and `offsetBytes`/`endBytes` fields the workspace read and write tools accept, removing the UTF-8 BOM prefix and failing closed on reversed, out-of-bounds or non-representable values.
+- Every mutable registry is read-write: `SkillRegistry`, `KnowledgeRegistry`, `ProtocolRegistry`, `ToolRegistry`, `OutlineRegistry`, `OutlineKeywordRegistry`, `SyntaxRegistry`, `SqlDialectRegistry`, `CalibrationRegistry`, `BehaviorRegistry` and `EntityRegistry` expose `update` and `remove` (plus `clear` for list-shaped containers) on top of `register`.
+
+### Changed
+
+- Writing a file now rebuilds that file's outline and drops its previous cache generation in the same call, so a later outline read never serves the pre-write tree and storage keeps one cache row per file instead of one per edit.
+- `SyntaxRegistry.updateLanguage` and `removeLanguage` release the language's extensions so a new language can claim them.
+
+### Fixed
+
+- The session-scoped filesystem store did not forward `removeOutline`, silently dropping cache invalidation; it now scopes and forwards it.
+- The calibration registry now accepts a host-supplied model for a scope it has never fitted, so persisted calibration can be restored.
+
+### Validation
+
+- Joint regression: 168/168 across registry, discovery, outline, runtime and database suites; source and tools typechecks passed.
+
 ## [0.5.0] - 2026-11-03
 
 ### Added

package/CHANGELOG.zh-CN.md

@@ -5,6 +5,39 @@
 格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循
 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.6.1] - 2026-11-03
+
+### 新增
+
+- `ProtocolRegistry` 可为已登记的协议绑定运行时实现：`bind`、`implementation`、`resolveImplementation`（带类型守卫，可选 family 校验）与 `bound`。实现按引用保存，不会出现在发现元数据中；`remove`/`clear` 会连同条目一起丢弃已绑定的实现。
+- `ProtocolEntry.family` 标注协议族，登记到 `ProtocolRegistry` 的条目可按协议（`mcp`、`a2a` 等）筛选。
+- MCP 作为具体协议登记，而不是单开注册中心：`mcpProtocolEntry` 生成携带协议版本、endpoint 与能力的 `family: "mcp"` 条目，`mcpListTools`、`mcpSyncTools` 与 `mcpWithdrawTools` 通过绑定实现读取并镜像该 endpoint 的工具。
+
+### 验证
+
+- 联合回归 189/189 与 50/50 通过（协议、注册中心、发现、MCP 执行器、工作区与数据库套件）；源代码与工具两套类型检查通过。
+
+## [0.6.0] - 2026-11-03
+
+### 新增
+
+- `outlineAddress(range, charset, bounds)` 及配套的行/字节请求辅助函数，把大纲节点的 `range` 转成 workspace 读写工具接受的 `startLine`/`endLine` 与 `offsetBytes`/`endBytes`，扣除 UTF-8 BOM 前缀；倒序、越界或无法精确表示时报错而不静默裁剪。
+- 所有可变注册中心均可读写：`SkillRegistry`、`KnowledgeRegistry`、`ProtocolRegistry`、`ToolRegistry`、`OutlineRegistry`、`OutlineKeywordRegistry`、`SyntaxRegistry`、`SqlDialectRegistry`、`CalibrationRegistry`、`BehaviorRegistry` 与 `EntityRegistry` 在 `register` 之外提供 `update` 与 `remove`（列表型容器另有 `clear`）。
+
+### 变更
+
+- 写入文件时在同一次调用内重建该文件大纲并删除旧缓存代次，之后读取大纲不会返回写入前的树，存储中也保持每个文件一条缓存而非每次编辑一条。
+- `SyntaxRegistry.updateLanguage` 与 `removeLanguage` 会释放语言的扩展名，允许新语言重新占用。
+
+### 修复
+
+- 会话限定的文件存储未转发 `removeOutline`，导致缓存失效被静默丢弃；现已按会话键转发。
+- 校准注册中心现在接受宿主为从未拟合过的 scope 提供模型，便于恢复已持久化的校准。
+
+### 验证
+
+- 联合回归 168/168 通过（注册中心、发现、大纲、运行时与数据库套件）；源代码与工具两套类型检查通过。
+
 ## [0.5.0] - 2026-11-03
 
 ### 新增

package/README.md

@@ -59,6 +59,8 @@ The catalog follows `entity → cache → service → repository → SQL → SQL
 
 These registries are domain-owned catalogs, not a mandate to duplicate every concept as a generic registry. Existing runtime state and policies for ability, cognition, progress and behavior should stay in their domain models; add a read-only catalog/discovery projection only when enumeration is needed. Agents should not write directly to active registries by default. A future contribution flow should create a sourced, versioned proposal and require host authorization, review and audit before activation.
 
+Every mutable registry is read-write for the host that owns it: `SkillRegistry`, `KnowledgeRegistry`, `ProtocolRegistry`, `ToolRegistry`, `OutlineRegistry`, `OutlineKeywordRegistry`, `SyntaxRegistry` (languages, token kinds and node kinds), `SqlDialectRegistry`, `CalibrationRegistry`, `BehaviorRegistry` and `EntityRegistry` all expose `update`/`remove` (and `clear` where the container is a list), on top of `register` and their read accessors. An update keeps the entry's registration slot and re-runs the same validation as register, so a host can change or drop an entry in place instead of building a second registry that disagrees with the first; `SyntaxRegistry.updateLanguage`/`removeLanguage` also release and re-use extensions. The host is still the only caller allowed to write these catalogs.
+
 The `environment` module describes runtimes, applications, languages and project types as `HostCatalog` modules. `category` is `runtime`, `application`, `language` or `projectType`; `availability` is `unknown`, `available` or `unavailable`, independent of the component lifecycle `status`. Optional `platforms`, `extensions`, `relatedIds`, `skillIds`, `knowledgeIds`, `toolIds` and `protocolIds` link metadata without granting execution access. Hosts explicitly confirm availability; catalog registration does not install software or probe the machine.
 
 ```ts
@@ -185,7 +187,7 @@ The `amp_protocol_workspace` v1 response contains `protocol`, `version`, `revisi
 | `amp_tool_filesystem_dependency` | Cycles, topological order and bounded closures |
 | `amp_tool_filesystem_ast` | Lossless syntax tree: every non-whitespace token, declaration/markup hierarchy, UTF-8/line ranges; read-only, never executes |
 
-The global variant is `amp_tool_globalfs_*`, a naming adapter in [src/global/filesystem.ts](src/global/filesystem.ts) that grants no new root or permission. Outline nodes carry `isFile`/`isDirectory`/`file?`/`directory?`/`path` (for example `add.py#add`) and `range` (UTF-8 bytes plus 1-based lines as bigint; decimal strings on the wire). Strategies cover code, Vue, project manifests, Markdown/TeX/plain text, CSS/SCSS/Sass, HTML, XML/OPML and Office; Office parsing covers DOCX/XLSX/PPTX and treats DOC/XLS/PPT/PUB/ACCDB as best-effort CFB.
+The global variant is `amp_tool_globalfs_*`, a naming adapter in [src/global/filesystem.ts](src/global/filesystem.ts) that grants no new root or permission. Outline nodes carry `isFile`/`isDirectory`/`file?`/`directory?`/`path` (for example `add.py#add`) and `range` (UTF-8 bytes plus 1-based lines as bigint; decimal strings on the wire). `outlineAddress(range, charset, bounds)` in [src/outline/rangeBridge.ts](src/outline/rangeBridge.ts) converts that range into the `startLine`/`endLine` and `offsetBytes`/`endBytes` fields the workspace `read`, `write` and `diff_write` tools accept: it removes the UTF-8 BOM prefix, keeps bytes half-open and lines inclusive, and fails closed on reversed, out-of-bounds or non-representable values instead of clamping. A successful file write rebuilds that file's outline and drops its previous cache generation in the same call, so a later outline read never serves the pre-write tree. Strategies cover code, Vue, project manifests, Markdown/TeX/plain text, CSS/SCSS/Sass, HTML, XML/OPML and Office; Office parsing covers DOCX/XLSX/PPTX and treats DOC/XLS/PPT/PUB/ACCDB as best-effort CFB.
 
 ### Hooks
 
@@ -206,6 +208,8 @@ await diff.run({ path: "src/new.ts", before: "" });
 
 ### MCP stdio
 
+MCP is a concrete protocol, so it is registered in `ProtocolRegistry` rather than a registry of its own. `mcpProtocolEntry(id, name, options)` builds a `family: "mcp"` entry carrying the protocol version (default `2026-07-28`), endpoint and capabilities; `protocols.bind(id, implementation)` attaches the host-built client and transport, and discovery keeps exposing only the entry's metadata. `protocols.resolveImplementation(id, isMcpProtocol, "mcp")` returns the bound endpoint or `undefined` when the family or the object does not match, `mcpListTools(protocol)` reads the advertised tools, `mcpSyncTools(protocol, toolRegistry)` registers new tools, updates changed ones in place and removes tools the endpoint no longer advertises, and `mcpWithdrawTools` drops one endpoint's tools without touching host tools or other protocols. Risk comes only from annotations (`destructiveHint` → destructive, `readOnlyHint` → read, otherwise write), and nothing here turns a URL string into a connection, so registering cannot make the agent reach a host it was not given. `ProtocolRegistry.remove`/`clear` drop the bound implementation together with the entry.
+
 ```sh
 npm run workspace-agent-demo
 npm run workspace-agent -- --config .cache/workspace-agent.local

package/README.zh-CN.md

@@ -59,6 +59,8 @@ Context 使用结构树和类型化关系图。项目依赖、导入、调用与
 
 这些 registry 是各自领域的宿主目录，不要求每个概念都复制成同构 registry。Ability、cognition、progress 等若已有运行时状态、策略或事件模型，应由现有领域模块维护；需要统一枚举时增加只读 catalog/discovery 投影即可。Agent 默认只读正式目录；可选的登记工作流应先创建带来源、版本和提案状态的候选项，再经宿主权限校验、人工审核与审计后发布，不授予模型直接改写已生效条目的能力。
 
+每个可变的注册中心对宿主都是可读写的：`SkillRegistry`、`KnowledgeRegistry`、`ProtocolRegistry`、`ToolRegistry`、`OutlineRegistry`、`OutlineKeywordRegistry`、`SyntaxRegistry`（语言、token 类别与节点类别）、`SqlDialectRegistry`、`CalibrationRegistry`、`BehaviorRegistry` 与 `EntityRegistry` 都在 `register` 和读取接口之外提供 `update`/`remove`（列表型容器另有 `clear`）。更新保留原登记位置并执行与注册相同的校验，宿主可以原地修改或删除条目，而不必再建一份与前者不一致的注册中心；`SyntaxRegistry.updateLanguage`/`removeLanguage` 会释放并允许复用扩展名。写这些目录的仍只能是宿主。
+
 `environment` 模块将运行时、应用程序、编程语言与项目类型作为 `HostCatalog` 的 module 条目维护。`category` 为 `runtime`、`application`、`language` 或 `projectType`；`availability` 为 `unknown`、`available` 或 `unavailable`，与组件生命周期 `status` 分开。可选的 `platforms`、`extensions`、`relatedIds`、`skillIds`、`knowledgeIds`、`toolIds`、`protocolIds` 描述平台、格式与关联，不授予执行权限。可用性由宿主确认，登记目录不会安装软件或探测本机。
 
 ```ts
@@ -188,7 +190,7 @@ import { ToolIds, parseId } from "attention-manifest-protocol/naming";
 | `amp_tool_filesystem_ast` | 无损语法树：每个非空白 token、声明/块/标签层级、UTF-8 字节与行范围；只读，不执行 |
 
 全局变体为 `amp_tool_globalfs_*`，由 [src/global/filesystem.ts](src/global/filesystem.ts) 做命名适配；它不扩大任何根或权限。
-大纲节点带 `isFile`/`isDirectory`/`file?`/`directory?`/`path`（如 `add.py#add`）与 `range`（UTF-8 字节 + 1-based 行，bigint；JSON 中为十进制字符串）。策略覆盖代码、Vue、项目清单、Markdown/TeX/纯文本、CSS/SCSS/Sass、HTML、XML/OPML 与 Office；Office 文件由 `office.ts` 解析 DOCX/XLSX/PPTX，DOC/XLS/PPT/PUB/ACCDB 为 CFB best-effort。
+大纲节点带 `isFile`/`isDirectory`/`file?`/`directory?`/`path`（如 `add.py#add`）与 `range`（UTF-8 字节 + 1-based 行，bigint；JSON 中为十进制字符串）。`outlineAddress(range, charset, bounds)`（[src/outline/rangeBridge.ts](src/outline/rangeBridge.ts)）把该 range 转成 workspace `read`、`write`、`diff_write` 接受的 `startLine`/`endLine` 与 `offsetBytes`/`endBytes`：扣除 UTF-8 BOM 前缀，字节半开、行闭区间；倒序、越界或无法精确表示时直接报错而不做静默裁剪。文件写入成功后会在同一次调用内重建该文件大纲并删除旧的缓存代次，之后读取大纲不会返回写入前的树。策略覆盖代码、Vue、项目清单、Markdown/TeX/纯文本、CSS/SCSS/Sass、HTML、XML/OPML 与 Office；Office 文件由 `office.ts` 解析 DOCX/XLSX/PPTX，DOC/XLS/PPT/PUB/ACCDB 为 CFB best-effort。
 
 ### Hooks
 
@@ -209,6 +211,8 @@ await diff.run({ path: "src/new.ts", before: "" });
 
 ### MCP stdio 接入
 
+MCP 是一种具体协议，因此登记在 `ProtocolRegistry` 中，而不是单开一个注册中心。`mcpProtocolEntry(id, name, options)` 生成 `family: "mcp"` 的协议条目，携带协议版本（默认 `2026-07-28`）、endpoint 与能力；`protocols.bind(id, implementation)` 绑定宿主自己建好的 client 与 transport，发现接口仍只暴露条目元数据。`protocols.resolveImplementation(id, isMcpProtocol, "mcp")` 在 family 或对象不匹配时返回 `undefined`；`mcpListTools(protocol)` 读取通告的工具，`mcpSyncTools(protocol, toolRegistry)` 注册新工具、原地更新变化的工具、移除 endpoint 不再通告的工具，`mcpWithdrawTools` 撤下一个 endpoint 的工具而不影响宿主工具和其他协议。风险等级只由注解决定（`destructiveHint` → destructive，`readOnlyHint` → read，其余为 write），且不会把 URL 字符串变成连接，因此登记不能让 agent 访问未经宿主的地址。`ProtocolRegistry.remove`/`clear` 会连同条目一起丢弃已绑定的实现。
+
 ```sh
 npm run workspace-agent-demo
 npm run workspace-agent -- --config .cache/workspace-agent.local

package/lib/bayes/calibrationRegistry.d.ts

@@ -35,5 +35,17 @@ export declare class CalibrationRegistry {
     register(scope: string, points: readonly CalibrationPoint[], options?: RegisterOptions): RegisterResult;
     calibrate(scope: string, predicted: number): number;
     model(scope: string): CalibrationModel | undefined;
+    /**
+     * Set the model of one scope.
+     *
+     * Unlike `register`, which fits a model from samples, this stores a complete
+     * model as-is: it replaces the scope's current model or creates it. Hosts
+     * that persist or hand-author a calibration use this to restore it.
+     */
+    update(model: CalibrationModel): CalibrationModel;
+    /** Remove one scope's model, returning it to raw probabilities. */
+    remove(scope: string): boolean;
+    /** Remove every calibrated scope. */
+    clear(): number;
     scopes(): string[];
 }

package/lib/bayes/calibrationRegistry.js

@@ -55,6 +55,28 @@ export class CalibrationRegistry {
     model(scope) {
         return this.models.get(scope);
     }
+    /**
+     * Set the model of one scope.
+     *
+     * Unlike `register`, which fits a model from samples, this stores a complete
+     * model as-is: it replaces the scope's current model or creates it. Hosts
+     * that persist or hand-author a calibration use this to restore it.
+     */
+    update(model) {
+        const stored = { ...model };
+        this.models.set(stored.scope, stored);
+        return { ...stored };
+    }
+    /** Remove one scope's model, returning it to raw probabilities. */
+    remove(scope) {
+        return this.models.delete(scope);
+    }
+    /** Remove every calibrated scope. */
+    clear() {
+        const count = this.models.size;
+        this.models.clear();
+        return count;
+    }
     scopes() {
         return [...this.models.keys()];
     }

package/lib/database/adapter/filesystemStore.d.ts

@@ -88,6 +88,13 @@ export declare class SqliteFilesystemStore implements FilesystemStore {
      * @param outline - Parsed outline.
      */
     saveOutline(rootId: string, outline: OutlineResult): void;
+    /**
+     * Drop every cached outline of one file, whatever its fingerprint.
+     *
+     * @param rootId - Session root id.
+     * @param path - Root-relative POSIX path.
+     */
+    removeOutline(rootId: string, path: string): void;
     /**
      * Load a cached import report by exact fingerprint.
      *

package/lib/database/adapter/filesystemStore.js

@@ -236,6 +236,15 @@ export class SqliteFilesystemStore {
     saveOutline(rootId, outline) {
         this.outlines.save(rootId, outline, now());
     }
+    /**
+     * Drop every cached outline of one file, whatever its fingerprint.
+     *
+     * @param rootId - Session root id.
+     * @param path - Root-relative POSIX path.
+     */
+    removeOutline(rootId, path) {
+        this.outlines.remove(rootId, path);
+    }
     /**
      * Load a cached import report by exact fingerprint.
      *

package/lib/database/entity/entity.d.ts

@@ -688,6 +688,21 @@ export declare class EntityRegistry {
      * @throws EntityMetadataError for invalid or duplicate metadata.
      */
     register(entity: Entity): this;
+    /**
+     * Replace one registered entity, keeping its registration position.
+     *
+     * @param entity - Validated replacement metadata with the same name.
+     * @returns This registry, for chaining.
+     * @throws EntityMetadataError for invalid metadata or an unknown name.
+     */
+    update(entity: Entity): this;
+    /**
+     * Remove one entity.
+     *
+     * @param name - Logical entity name.
+     * @returns `true` when it was registered.
+     */
+    remove(name: EntityName): boolean;
     /**
      * Look up an entity by logical name.
      *

package/lib/database/entity/entity.js

@@ -225,6 +225,33 @@ export class EntityRegistry {
         this.entities.set(entity.name, entity);
         return this;
     }
+    /**
+     * Replace one registered entity, keeping its registration position.
+     *
+     * @param entity - Validated replacement metadata with the same name.
+     * @returns This registry, for chaining.
+     * @throws EntityMetadataError for invalid metadata or an unknown name.
+     */
+    update(entity) {
+        const problems = validateEntity(entity);
+        if (problems.length > 0) {
+            throw new EntityMetadataError(entity.name, problems);
+        }
+        if (!this.entities.has(entity.name)) {
+            throw new EntityMetadataError(entity.name, ["no entity with this name is registered"]);
+        }
+        this.entities.set(entity.name, entity);
+        return this;
+    }
+    /**
+     * Remove one entity.
+     *
+     * @param name - Logical entity name.
+     * @returns `true` when it was registered.
+     */
+    remove(name) {
+        return this.entities.delete(name);
+    }
     /**
      * Look up an entity by logical name.
      *

package/lib/database/repository/fileOutlineRepository.d.ts

@@ -28,6 +28,18 @@ export declare class FileOutlineRepository extends BaseRepository<FileOutlineRow
      * @param at - ISO timestamp for the write.
      */
     save(rootId: string, outline: OutlineResult, at: string): void;
+    /**
+     * Drop every cached outline of one file regardless of fingerprint.
+     *
+     * The cache is keyed by content fingerprint, so a write leaves the previous
+     * generation behind forever. A writer calls this after it replaces the file
+     * and saves the new outline, keeping one row per file instead of one row per
+     * edit.
+     *
+     * @param rootId - Session root id.
+     * @param path - Root-relative POSIX path.
+     */
+    remove(rootId: string, path: string): void;
     /**
      * Load the outline of one exact fingerprint.
      *

package/lib/database/repository/fileOutlineRepository.js

@@ -73,6 +73,20 @@ export class FileOutlineRepository extends BaseRepository {
             created_at: at,
         });
     }
+    /**
+     * Drop every cached outline of one file regardless of fingerprint.
+     *
+     * The cache is keyed by content fingerprint, so a write leaves the previous
+     * generation behind forever. A writer calls this after it replaces the file
+     * and saves the new outline, keeping one row per file instead of one row per
+     * edit.
+     *
+     * @param rootId - Session root id.
+     * @param path - Root-relative POSIX path.
+     */
+    remove(rootId, path) {
+        this.deleteWhere(conditions(FileOutlineTable, ["root_id", "path"]), rootId, path);
+    }
     /**
      * Load the outline of one exact fingerprint.
      *

package/lib/file/index.d.ts

@@ -32,6 +32,8 @@ export { DefaultSyntaxRegistry, SyntaxRegistry, buildSyntaxTreeFromText, createS
 export type { SyntaxLanguage, SyntaxLanguageDefinition, SyntaxNode, SyntaxNodeKind, SyntaxNodeKindDefinition, SyntaxToken, SyntaxTokenKind, SyntaxTokenKindDefinition, SyntaxTree, SyntaxTreeOptions, WireSyntaxNode, WireSyntaxToken, WireSyntaxTree, } from "../syntax/syntaxTree.js";
 export { OutlineIndex, buildOutlineIndex, filterOutline, hasLabelPrefix, wireOutline, wireOutlineNode, wireOutlineRange, outlineFromWire } from "../outline/outlineIndex.js";
 export type { OutlinePayload } from "../outline/outlineIndex.js";
+export { OutlineRangeError, outlineAddress, outlineBomOffset, outlineByteRange, outlineLineRange, readByteRequest, readLineRequest, writeByteRequest, writeLineRequest, } from "../outline/rangeBridge.js";
+export type { OutlineAddress, OutlineByteRange, OutlineLineRange, OutlineRangeErrorCode } from "../outline/rangeBridge.js";
 export { extractImports, importedBy, isParseableSource, readSourceFile, resolveImportSpecifier, tokenizeSource } from "./importGraph.js";
 export type { ResolvedSpecifier, SourceFileSnapshot, SourceToken } from "./importGraph.js";
 export { extractExports } from "./exportGraph.js";

package/lib/file/index.js

@@ -22,6 +22,7 @@ export { DefaultOutlineKeywords, OutlineKeywordRegistry, createOutlineKeywordReg
 export { buildSyntaxTree } from "./syntaxTree.js";
 export { DefaultSyntaxRegistry, SyntaxRegistry, buildSyntaxTreeFromText, createSyntaxRegistry, disposeSyntaxNode, syntaxLanguageOf, wireSyntaxTree, } from "../syntax/syntaxTree.js";
 export { OutlineIndex, buildOutlineIndex, filterOutline, hasLabelPrefix, wireOutline, wireOutlineNode, wireOutlineRange, outlineFromWire } from "../outline/outlineIndex.js";
+export { OutlineRangeError, outlineAddress, outlineBomOffset, outlineByteRange, outlineLineRange, readByteRequest, readLineRequest, writeByteRequest, writeLineRequest, } from "../outline/rangeBridge.js";
 export { extractImports, importedBy, isParseableSource, readSourceFile, resolveImportSpecifier, tokenizeSource } from "./importGraph.js";
 export { extractExports } from "./exportGraph.js";
 export { DependencyGraph, buildDependencyReport, graphFromImports } from "./dependency.js";

package/lib/file/runtime.d.ts

@@ -50,6 +50,8 @@ export declare class SessionRuntime {
     persistenceKey(rootId: string): string;
     loadOutline(rootId: string, path: string, fingerprint: string): import("./types.js").OutlineResult | undefined;
     saveOutline(rootId: string, outline: import("../outline/types.js").OutlineResult): void;
+    /** Drop every cached generation of one file's outline after it changed. */
+    removeOutline(rootId: string, path: string): void;
     /**
      * Resolve a caller path and return the tree that owns it.
      */

package/lib/file/runtime.js

@@ -25,6 +25,8 @@ export class SessionRuntime {
     persistenceKey(rootId) { return JSON.stringify([this.descriptor.workspaceId ?? "default", this.descriptor.id, rootId]); }
     loadOutline(rootId, path, fingerprint) { return this.store?.loadOutline(rootId, path, fingerprint); }
     saveOutline(rootId, outline) { this.store?.saveOutline(rootId, outline); }
+    /** Drop every cached generation of one file's outline after it changed. */
+    removeOutline(rootId, path) { this.store?.removeOutline?.(rootId, path); }
     /**
      * Resolve a caller path and return the tree that owns it.
      */

package/lib/file/scopedStore.js

@@ -13,6 +13,7 @@ export const scopeFilesystemStore = (store, session) => {
         }),
         loadOutline: (rootId, path, fingerprint) => store.loadOutline(key(rootId), path, fingerprint),
         saveOutline: (rootId, outline) => store.saveOutline(key(rootId), outline),
+        ...(store.removeOutline === (void 0) ? {} : { removeOutline: (rootId, path) => store.removeOutline(key(rootId), path) }),
         loadImports: (rootId, path, fingerprint) => store.loadImports(key(rootId), path, fingerprint),
         saveImports: (rootId, report) => store.saveImports(key(rootId), report),
         loadExports: (rootId, path, fingerprint) => store.loadExports(key(rootId), path, fingerprint),

package/lib/file/service.d.ts

@@ -152,6 +152,22 @@ export declare class FilesystemService {
      */
     read(runtime: SessionRuntime, request: import("./types.js").ReadRequest): ReadPage;
     write(runtime: SessionRuntime, request: import("./types.js").WriteRequest): Promise<WriteResult>;
+    /**
+     * Rebuild the outline cache of one written file.
+     *
+     * A write changes the file's fingerprint, and the cache is keyed by that
+     * fingerprint, so a stale row can never be read — but the old generation
+     * would linger in storage forever and the next read would parse again. This
+     * replaces every generation of the file with the outline of the new content
+     * at write time, so "the file changed" and "its outline changed" happen
+     * together. A file that cannot be outlined (binary, oversized, Office) is
+     * dropped from the cache and is not an error for the write itself.
+     *
+     * @param runtime - Session runtime owning the root.
+     * @param root - The root the written path belongs to.
+     * @param path - Caller path of the written file.
+     */
+    private refreshOutline;
     outline(runtime: SessionRuntime, request: OutlineRequest): OutlineResult;
     imports(runtime: SessionRuntime, request: ImportRequest): ImportReport;
     exports(runtime: SessionRuntime, request: ExportRequest): ExportReport;

package/lib/file/service.js

@@ -28,7 +28,7 @@ import { isOfficeFile, officeExports, officeReferences, parseOffice } from "../o
 import { buildSyntaxTree } from "./syntaxTree.js";
 import { wireSyntaxTree } from "../syntax/syntaxTree.js";
 import { buildDependencyReport, graphFromImports } from "./dependency.js";
-import { isFilesystemError } from "./errors.js";
+import { fail, isFilesystemError } from "./errors.js";
 import { readPage } from "./read.js";
 import { writeFile } from "./write.js";
 import { SessionRuntime } from "./runtime.js";
@@ -276,8 +276,52 @@ export class FilesystemService {
         };
         const result = await writeFile(runtime.sandbox, runtime.descriptor.id, request, settings);
         runtime.persist(rooted.root, tree.snapshot());
+        this.refreshOutline(runtime, rooted.root, request.path);
         return result;
     }
+    /**
+     * Rebuild the outline cache of one written file.
+     *
+     * A write changes the file's fingerprint, and the cache is keyed by that
+     * fingerprint, so a stale row can never be read — but the old generation
+     * would linger in storage forever and the next read would parse again. This
+     * replaces every generation of the file with the outline of the new content
+     * at write time, so "the file changed" and "its outline changed" happen
+     * together. A file that cannot be outlined (binary, oversized, Office) is
+     * dropped from the cache and is not an error for the write itself.
+     *
+     * @param runtime - Session runtime owning the root.
+     * @param root - The root the written path belongs to.
+     * @param path - Caller path of the written file.
+     */
+    refreshOutline(runtime, root, path) {
+        let relative;
+        let node;
+        try {
+            const rooted = runtime.sandbox.resolve(path, "read");
+            relative = rooted.relative;
+            node = runtime.treeFor(root).node(relative);
+        }
+        catch {
+            return;
+        }
+        if (node === (void 0) || node.type !== "File") {
+            return;
+        }
+        try {
+            runtime.removeOutline(root.id, relative);
+        }
+        catch {
+            return fail("store_failure");
+        }
+        try {
+            const outline = buildOutline(runtime.sandbox, relative, { anchor: { file: node } }, { file: node });
+            runtime.saveOutline(root.id, outline);
+        }
+        catch {
+            // An unoutlinable file stays uncached; the write already succeeded.
+        }
+    }
     outline(runtime, request) {
         const { rooted, node, tree } = runtime.node(request.path, "read");
         const cached = runtime.loadOutline(rooted.root.id, rooted.relative, node.fingerprint);

package/lib/file/types.d.ts

@@ -354,6 +354,12 @@ export interface FilesystemStore {
     listWrites(sessionId: string, limit: number): WriteJournalEntry[];
     loadOutline(rootId: string, path: string, fingerprint: string): OutlineResult | undefined;
     saveOutline(rootId: string, outline: OutlineResult): void;
+    /**
+     * Drop every cached outline of one file. A writer calls this before saving
+     * the rebuilt outline so one file keeps one cache row instead of one per
+     * edited fingerprint. Optional: in-memory stores may only keep the latest.
+     */
+    removeOutline?(rootId: string, path: string): void;
     loadImports(rootId: string, path: string, fingerprint: string): ImportReport | undefined;
     saveImports(rootId: string, report: ImportReport): void;
     loadExports(rootId: string, path: string, fingerprint: string): ExportReport | undefined;

package/lib/knowledge/registry.d.ts

@@ -13,6 +13,12 @@ export interface KnowledgeEntry {
 export declare class KnowledgeRegistry {
     private readonly entries;
     register(knowledge: KnowledgeEntry): KnowledgeEntry;
+    /** Replace an existing knowledge entry. The id must stay the same. */
+    update(knowledge: KnowledgeEntry): KnowledgeEntry;
+    /** Remove one knowledge entry; the result says whether it existed. */
+    remove(id: string): boolean;
+    /** Remove every knowledge entry and report how many were dropped. */
+    clear(): number;
     get(id: string): KnowledgeEntry | undefined;
     list(): KnowledgeEntry[];
     has(id: string): boolean;

package/lib/knowledge/registry.js

@@ -25,6 +25,19 @@ export class KnowledgeRegistry {
         validateKnowledge(knowledge);
         return this.entries.register(knowledge);
     }
+    /** Replace an existing knowledge entry. The id must stay the same. */
+    update(knowledge) {
+        validateKnowledge(knowledge);
+        return this.entries.update(knowledge.id, knowledge);
+    }
+    /** Remove one knowledge entry; the result says whether it existed. */
+    remove(id) {
+        return this.entries.remove(id);
+    }
+    /** Remove every knowledge entry and report how many were dropped. */
+    clear() {
+        return this.entries.clear();
+    }
     get(id) {
         return this.entries.get(id);
     }

package/lib/module/index.d.ts

@@ -9,6 +9,7 @@ export * from "./tool/globalExecutor.js";
 export * from "./tool/controlExecutor.js";
 export * from "./tool/filesystemExecutor.js";
 export * from "./tool/globalFilesystemExecutor.js";
+export * from "./mcp/binding.js";
 export * from "./mcp/workspaceServer.js";
 export * from "./mcp/filesystemServer.js";
 export * from "./sandbox/sandbox.js";

package/lib/module/index.js

@@ -9,6 +9,7 @@ export * from "./tool/globalExecutor.js";
 export * from "./tool/controlExecutor.js";
 export * from "./tool/filesystemExecutor.js";
 export * from "./tool/globalFilesystemExecutor.js";
+export * from "./mcp/binding.js";
 export * from "./mcp/workspaceServer.js";
 export * from "./mcp/filesystemServer.js";
 export * from "./sandbox/sandbox.js";

package/lib/module/mcp/binding.d.ts

@@ -0,0 +1,94 @@
+/**
+ * MCP as one concrete protocol registered in the protocol registry.
+ *
+ * MCP is a specific wire protocol, not an extension of the tool registry: it
+ * has its own version, its own capability set and its own transport. Rather
+ * than a second registry, an MCP endpoint is an ordinary `ProtocolEntry`
+ * (`family: "mcp"`) whose bound implementation is an `McpProtocol`. That keeps
+ * "which protocols does this host speak" in one place, next to A2A, the
+ * workspace protocol and anything else a host registers.
+ *
+ * The implementation owns the client the host already built. Nothing here turns
+ * a URL string into a connection, so registering cannot widen what the agent
+ * can reach.
+ */
+import type { McpClient } from "./client.js";
+import type { McpTool } from "./protocol.js";
+import type { Transport } from "./transport.js";
+import type { ProtocolEntry } from "../../protocol/registry.js";
+import type { ToolDescriptor, ToolRegistry } from "../tool/tool.js";
+/** Family tag every MCP entry carries. */
+export declare const McpProtocolFamily: string;
+/**
+ * Implementation bound to an `mcp` protocol entry.
+ */
+export interface McpProtocol {
+    readonly family: typeof McpProtocolFamily;
+    /** Client used for `listTools`/`callTool`. */
+    readonly client: McpClient;
+    /** Optional transport, kept so a host can inspect or close it. */
+    readonly transport?: Transport;
+    /** Tools last read from this endpoint, in advertised order. */
+    readonly tools?: readonly string[];
+}
+/**
+ * Type guard for `resolveImplementation`.
+ */
+export declare const isMcpProtocol: (value: unknown) => value is McpProtocol;
+/**
+ * Risk tier for one MCP tool, derived only from its declared annotations.
+ * An unannotated tool is `write`: the safest assumption is that it may act.
+ */
+export declare const mcpToolRisk: (tool: McpTool) => ToolDescriptor["risk"];
+/**
+ * Convert one advertised MCP tool into a tool descriptor. The executable name
+ * is the bare MCP name, so a server cannot rename it into another namespace.
+ */
+export declare const mcpToolDescriptor: (tool: McpTool) => ToolDescriptor;
+/**
+ * Protocol entry for one MCP endpoint.
+ *
+ * @param id - Host-chosen protocol id, unique in the protocol registry.
+ * @param name - Human label.
+ * @param options - Optional endpoint, version override, description and status.
+ * @returns A validated `family: "mcp"` entry carrying the MCP capabilities.
+ */
+export declare const mcpProtocolEntry: (id: string, name: string, options?: {
+    endpoint?: string;
+    version?: string;
+    description?: string;
+    status?: ProtocolEntry["status"];
+    capabilities?: readonly string[];
+}) => ProtocolEntry;
+/**
+ * Read one endpoint's advertised tool list again.
+ *
+ * @param protocol - Bound implementation.
+ * @returns The advertised tools.
+ */
+export declare const mcpListTools: (protocol: McpProtocol) => Promise<McpTool[]>;
+/**
+ * Mirror one endpoint's tools into a tool registry.
+ *
+ * A new tool is registered, a changed schema/description/risk is updated in
+ * place, and a tool the endpoint no longer advertises is removed. The reply
+ * lists all three sets so a host can audit the change instead of diffing
+ * silently.
+ *
+ * @param protocol - Bound implementation; `tools` is used as the previous set.
+ * @param tools - Registry the runtime executes from.
+ * @returns Added, updated and removed descriptors.
+ */
+export declare const mcpSyncTools: (protocol: McpProtocol, tools: ToolRegistry) => Promise<{
+    added: ToolDescriptor[];
+    updated: ToolDescriptor[];
+    removed: string[];
+}>;
+/**
+ * Withdraw one endpoint's tools from a tool registry.
+ *
+ * @param protocol - Bound implementation; `tools` is the last advertised set.
+ * @param tools - Registry to withdraw from.
+ * @returns Names actually removed.
+ */
+export declare const mcpWithdrawTools: (protocol: McpProtocol, tools: ToolRegistry) => string[];