attention-manifest-protocol 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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

package/CHANGELOG.zh-CN.md

@@ -5,6 +5,18 @@
 格式遵循 [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
 
 ### 新增

package/README.md

@@ -208,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

@@ -211,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/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[];

package/lib/module/mcp/binding.js

@@ -0,0 +1,97 @@
+import { ProtocolVersion } from "./protocol.js";
+/** Family tag every MCP entry carries. */
+export const McpProtocolFamily = "mcp";
+/**
+ * Type guard for `resolveImplementation`.
+ */
+export const isMcpProtocol = (value) => typeof (value) === "object" && value !== null && value.family === McpProtocolFamily
+    && typeof (value.client) === "object" && value.client !== null;
+/**
+ * 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 const mcpToolRisk = (tool) => {
+    if (tool.annotations?.destructiveHint === true) {
+        return "destructive";
+    }
+    return tool.annotations?.readOnlyHint === true ? "read" : "write";
+};
+/**
+ * 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 const mcpToolDescriptor = (tool) => ({
+    name: tool.name,
+    description: tool.description ?? tool.title ?? tool.name,
+    inputSchema: structuredClone(tool.inputSchema),
+    risk: mcpToolRisk(tool),
+});
+/**
+ * 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 const mcpProtocolEntry = (id, name, options = {}) => ({
+    id,
+    name,
+    version: options.version ?? ProtocolVersion,
+    description: options.description ?? "Model Context Protocol endpoint",
+    family: McpProtocolFamily,
+    ...(options.status === (void 0) ? {} : { status: options.status }),
+    ...(options.endpoint === (void 0) ? {} : { endpoint: options.endpoint }),
+    capabilities: [...(options.capabilities ?? ["tools"])],
+});
+/**
+ * Read one endpoint's advertised tool list again.
+ *
+ * @param protocol - Bound implementation.
+ * @returns The advertised tools.
+ */
+export const mcpListTools = async (protocol) => (await protocol.client.listTools()).tools;
+/**
+ * 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 const mcpSyncTools = async (protocol, tools) => {
+    const listed = await mcpListTools(protocol);
+    const descriptors = listed.map(mcpToolDescriptor);
+    const advertised = descriptors.map((descriptor) => descriptor.name);
+    const added = [];
+    const updated = [];
+    for (const descriptor of descriptors) {
+        if (tools.get(descriptor.name) === (void 0)) {
+            tools.register(descriptor);
+            added.push(descriptor);
+        }
+        else {
+            tools.update(descriptor);
+            updated.push(descriptor);
+        }
+    }
+    const removed = [];
+    for (const name of protocol.tools ?? []) {
+        if (!advertised.includes(name) && tools.remove(name)) {
+            removed.push(name);
+        }
+    }
+    return { added, updated, removed };
+};
+/**
+ * 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 const mcpWithdrawTools = (protocol, tools) => (protocol.tools ?? []).filter((name) => tools.remove(name));

package/lib/protocol/registry.d.ts

@@ -8,15 +8,58 @@ export interface ProtocolEntry {
     status?: ProtocolStatus;
     endpoint?: string;
     capabilities?: string[];
+    /**
+     * Protocol family this entry implements, for example `mcp` or `a2a`.
+     * Discovery projects it as metadata only; it never grants execution.
+     */
+    family?: string;
 }
+/**
+ * Runtime handler a protocol entry can bind to.
+ *
+ * The implementation is a host-supplied value: it may carry a client, a
+ * transport or any other executor. The registry stores and returns it by
+ * reference, so binding a protocol cannot change the entry's discoverable
+ * metadata and discovery never exposes it.
+ */
+export type ProtocolImplementation = object;
 export declare class ProtocolRegistry {
     private readonly entries;
+    private readonly implementations;
     register(protocol: ProtocolEntry): ProtocolEntry;
     /** Replace an existing protocol. The id must stay the same. */
     update(protocol: ProtocolEntry): ProtocolEntry;
-    /** Remove one protocol; the result says whether it existed. */
+    /**
+     * Bind or replace the runtime implementation of one registered protocol.
+     *
+     * @param id - Registered protocol id.
+     * @param implementation - Host-supplied handler; stored by reference.
+     * @returns The implementation.
+     * @throws When the protocol id is not registered.
+     */
+    bind(id: string, implementation: ProtocolImplementation): ProtocolImplementation;
+    /**
+     * Runtime implementation bound to one protocol.
+     *
+     * @param id - Protocol id.
+     * @returns The implementation, or `undefined` when none is bound.
+     */
+    implementation(id: string): ProtocolImplementation | undefined;
+    /**
+     * Bound implementation narrowed to one known protocol type.
+     *
+     * @param id - Protocol id.
+     * @param isProtocol - Type guard for the expected implementation.
+     * @param family - Optional family that must match the entry.
+     * @returns The implementation, or `undefined` when absent, unbound or of
+     * another family.
+     */
+    resolveImplementation<T extends ProtocolImplementation>(id: string, isProtocol: (value: unknown) => value is T, family?: string): T | undefined;
+    /** Protocol ids that currently have a bound implementation. */
+    bound(): string[];
+    /** Remove one protocol and any bound implementation; says whether it existed. */
     remove(id: string): boolean;
-    /** Remove every protocol and report how many were dropped. */
+    /** Remove every protocol and bound implementation; reports how many entries were dropped. */
     clear(): number;
     get(id: string): ProtocolEntry | undefined;
     list(options?: {

package/lib/protocol/registry.js

@@ -20,6 +20,9 @@ const validateProtocol = (protocol) => {
     if (protocol.endpoint !== (void 0) && protocol.endpoint.trim().length === 0) {
         throw new Error("protocol endpoint must be a non-empty string");
     }
+    if (protocol.family !== (void 0) && protocol.family.trim().length === 0) {
+        throw new Error("protocol family must be a non-empty string");
+    }
     if (protocol.capabilities !== (void 0) &&
         (!Array.isArray(protocol.capabilities) || protocol.capabilities.some((value) => typeof (value) !== "string" || value.trim().length === 0))) {
         throw new Error("protocol capabilities must contain non-empty strings");
@@ -27,6 +30,7 @@ const validateProtocol = (protocol) => {
 };
 export class ProtocolRegistry {
     entries = new InMemoryRegistry(cloneProtocol, (id) => new Error(`protocol ${id} is already registered`));
+    implementations = new Map();
     register(protocol) {
         validateProtocol(protocol);
         return this.entries.register(protocol);
@@ -36,12 +40,62 @@ export class ProtocolRegistry {
         validateProtocol(protocol);
         return this.entries.update(protocol.id, protocol);
     }
-    /** Remove one protocol; the result says whether it existed. */
+    /**
+     * Bind or replace the runtime implementation of one registered protocol.
+     *
+     * @param id - Registered protocol id.
+     * @param implementation - Host-supplied handler; stored by reference.
+     * @returns The implementation.
+     * @throws When the protocol id is not registered.
+     */
+    bind(id, implementation) {
+        if (!this.entries.has(id)) {
+            throw new Error(`protocol ${id} is not registered`);
+        }
+        if (implementation === null || typeof (implementation) !== "object") {
+            throw new TypeError("protocol implementation must be an object");
+        }
+        this.implementations.set(id, implementation);
+        return implementation;
+    }
+    /**
+     * Runtime implementation bound to one protocol.
+     *
+     * @param id - Protocol id.
+     * @returns The implementation, or `undefined` when none is bound.
+     */
+    implementation(id) {
+        return this.implementations.get(id);
+    }
+    /**
+     * Bound implementation narrowed to one known protocol type.
+     *
+     * @param id - Protocol id.
+     * @param isProtocol - Type guard for the expected implementation.
+     * @param family - Optional family that must match the entry.
+     * @returns The implementation, or `undefined` when absent, unbound or of
+     * another family.
+     */
+    resolveImplementation(id, isProtocol, family) {
+        const entry = this.entries.get(id);
+        if (entry === (void 0) || (family !== (void 0) && entry.family !== family)) {
+            return (void 0);
+        }
+        const implementation = this.implementations.get(id);
+        return implementation !== (void 0) && isProtocol(implementation) ? implementation : (void 0);
+    }
+    /** Protocol ids that currently have a bound implementation. */
+    bound() {
+        return [...this.implementations.keys()].sort();
+    }
+    /** Remove one protocol and any bound implementation; says whether it existed. */
     remove(id) {
+        this.implementations.delete(id);
         return this.entries.remove(id);
     }
-    /** Remove every protocol and report how many were dropped. */
+    /** Remove every protocol and bound implementation; reports how many entries were dropped. */
     clear() {
+        this.implementations.clear();
         return this.entries.clear();
     }
     get(id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "attention-manifest-protocol",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "files": [
     "lib",
     "docs/schemas",