@sigrun/ext-mcp 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -6,6 +6,26 @@ 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).
 
 ## [Unreleased]
+## [0.2.3] - 2026-11-05
+
+### Added
+
+- Tool annotations kept from `tools/list` and published as the
+  `mcp.tool-annotations` hook (readOnlyHint/destructiveHint per tool,
+  boolean-only, per-user catalog first then shared servers the calling
+  user may reach; unknown tools answer `{unknown: true}`). Downstream
+  safety consumers (@sigrun/warden) classify from real metadata instead
+  of the MCP default.
+
+### Changed
+- Forward-compatible with pi-durable 1.4.0 (explicit `checkpointWhen`;
+  widened peer range). No behaviour change.
+- Block-validator tests now compile against core's real generated
+  `@sigrun/sigrun/blocks` declarations instead of a local ambient shim.
+  A content-hash build stamp rejects missing or stale sibling output with
+  an explicit core rebuild instruction; the sibling CI path builds core
+  before the validator-form test.
+
 ### Security
 - **stdio MCP servers receive an allowlisted environment instead of sigrun's
   process environment.** `SIGRUN_API_TOKEN` and provider keys were inherited

package/dist/annotations.d.ts

@@ -0,0 +1,36 @@
+/** The `mcp.tool-annotations` published hook: a downstream safety extension
+ * asks "what did this tool's server declare about it?" and this extension
+ * answers from its live connection maps — the caller's per-user catalog
+ * first, then shared servers the caller may reach, else unknown. */
+import { Type, type Static } from "@earendil-works/pi-ai";
+import type { PublishedHook } from "@sigrun/sigrun/extension";
+import type { McpServerConfig } from "./config.js";
+import { type SigrunHost, type ToolAnnotationEntry, type UserCatalog } from "./user-servers.js";
+declare const Input: Type.TObject<{
+    tool: Type.TString;
+}>;
+export declare const TOOL_ANNOTATIONS_INPUT: Type.TObject<{
+    tool: Type.TString;
+}>;
+export declare const TOOL_ANNOTATIONS_OUTPUT: Type.TUnion<[Type.TObject<{
+    server: Type.TString;
+    mcpName: Type.TString;
+    annotations: Type.TObject<{
+        readOnlyHint: Type.TOptional<Type.TBoolean>;
+        destructiveHint: Type.TOptional<Type.TBoolean>;
+        idempotentHint: Type.TOptional<Type.TBoolean>;
+        openWorldHint: Type.TOptional<Type.TBoolean>;
+    }>;
+}>, Type.TObject<{
+    unknown: Type.TLiteral<true>;
+}>]>;
+export type ToolAnnotationsPayload = Static<typeof Input>;
+export type ToolAnnotationsResult = ToolAnnotationEntry | {
+    readonly unknown: true;
+};
+export declare const TOOL_ANNOTATIONS_HOOK = "mcp.tool-annotations";
+export declare function createToolAnnotationsHook(host: SigrunHost, catalog: UserCatalog, shared: ReadonlyMap<string, {
+    readonly server: McpServerConfig;
+    readonly annotations: ReadonlyMap<string, ToolAnnotationEntry>;
+}>): PublishedHook;
+export {};

package/dist/annotations.js

@@ -0,0 +1,67 @@
+/** The `mcp.tool-annotations` published hook: a downstream safety extension
+ * asks "what did this tool's server declare about it?" and this extension
+ * answers from its live connection maps — the caller's per-user catalog
+ * first, then shared servers the caller may reach, else unknown. */
+import { Type } from "@earendil-works/pi-ai";
+import { sharedServerAllowed, } from "./user-servers.js";
+const Input = Type.Object({
+    tool: Type.String({ minLength: 1, maxLength: 512 }),
+});
+const Hints = Type.Object({
+    readOnlyHint: Type.Optional(Type.Boolean()),
+    destructiveHint: Type.Optional(Type.Boolean()),
+    idempotentHint: Type.Optional(Type.Boolean()),
+    openWorldHint: Type.Optional(Type.Boolean()),
+});
+const Output = Type.Union([
+    Type.Object({
+        server: Type.String(),
+        mcpName: Type.String(),
+        annotations: Hints,
+    }),
+    Type.Object({ unknown: Type.Literal(true) }),
+]);
+// Exported for the compile round-trip test (the hook exposes the same
+// schemas via `input`/`output`; test code imports these constants to
+// avoid re-deriving them from the wiring).
+export const TOOL_ANNOTATIONS_INPUT = Input;
+export const TOOL_ANNOTATIONS_OUTPUT = Output;
+export const TOOL_ANNOTATIONS_HOOK = "mcp.tool-annotations";
+export function createToolAnnotationsHook(host, catalog, shared) {
+    const lookup = async (tool, call) => {
+        if (call.user !== undefined) {
+            const own = catalog.annotationsFor(call.user).get(tool);
+            if (own !== undefined)
+                return own;
+            // Shared servers lend operator authority, so reachability is gated
+            // by the acting user of the conversation; an unidentified caller
+            // fails closed, matching sharedServerAllowed's own posture.
+            if (call.conversationId !== undefined) {
+                for (const [name, entry] of shared) {
+                    const found = entry.annotations.get(tool);
+                    if (found === undefined)
+                        continue;
+                    try {
+                        if (await sharedServerAllowed(host, call.conversationId, name, entry.server)) {
+                            return found;
+                        }
+                    }
+                    catch {
+                        // A failed access check is not a reachability grant.
+                    }
+                }
+            }
+        }
+        return { unknown: true };
+    };
+    return {
+        name: TOOL_ANNOTATIONS_HOOK,
+        description: "Resolve a sigrun MCP tool name to its server-declared annotations.",
+        input: Input,
+        output: Output,
+        run: async (payload, call) => {
+            const { tool } = payload;
+            return await lookup(tool, call);
+        },
+    };
+}

package/dist/config.js

@@ -144,6 +144,13 @@ export function parseMcpConfig(text, source) {
         if (name.startsWith("u_")) {
             throw new Error(`mcp config ${source}: server "${name}" uses the reserved "u_" prefix`);
         }
+        // The tool namespace is `<server>/<tool>` and settings keys use dots
+        // for paths, so a server named `acme.tools` or `acme/tools` would
+        // produce ambiguous or conflicting keys. Reject at the source, before
+        // any settings section can be generated from the bad name.
+        if (name.includes(".") || name.includes("/")) {
+            throw new Error(`mcp config ${source}: server "${name}" contains forbidden characters ("." or "/") — dots conflict with settings key paths and slashes conflict with the <server>/<tool> namespace`);
+        }
         if (!isRecord(entry)) {
             throw new Error(`mcp config ${source}: server "${name}" must be an object`);
         }

package/dist/extension.d.ts

@@ -2,6 +2,7 @@
  * per-user entries connect and publish through the structural sigrun host. */
 import { type Extension } from "@earendil-works/pi-durable";
 import { type CatalogSettingsSection, type OwnerEvent, type SigrunHost, type UserService } from "./user-servers.js";
+import type { PublishedHook } from "@sigrun/sigrun/extension";
 export declare const MCP_EXTENSION_NAME = "sigrun.mcp";
 export interface ExtensionRouteContribution {
     readonly method: "POST";
@@ -22,6 +23,7 @@ export interface McpWiring {
     readonly surfaces: {
         readonly settings: readonly CatalogSettingsSection[];
     };
+    readonly publishedHooks: readonly PublishedHook[];
     conversationCreated(event: OwnerEvent): Promise<void>;
     runSettled(event: OwnerEvent): Promise<void>;
     onSettingsChanged(keys: readonly string[], user?: string): Promise<void>;

package/dist/extension.js

@@ -7,6 +7,7 @@ import { createUserOauthFlows, exchangeCode, extractCode, } from "./oauth.js";
 import { storeUserMcpToken } from "./tokens.js";
 import { MCP_SERVERS_SECTION_KEY, partitionForSection, renderMcpServersSection, } from "./section.js";
 import { catalogEnabledFromSettings, createUserCatalog, sharedServerAllowed, discoverMcpTools, } from "./user-servers.js";
+import { createToolAnnotationsHook } from "./annotations.js";
 export const MCP_EXTENSION_NAME = "sigrun.mcp";
 /** Standalone tokens need no registry install; the kind/version must match
  * core's session-meta document so its committed owner is readable here. */
@@ -17,6 +18,7 @@ const SessionOwnerDoc = defineDoc({
     history: "latest",
     fork: "current",
     initial: () => ({}),
+    checkpointWhen: () => false,
 });
 function denied(message) {
     return {
@@ -57,6 +59,7 @@ export function createMcpExtension(host) {
     const clients = new Map();
     const serverExposures = new Map();
     const shared = Object.entries(config.servers).filter(([, server]) => server.credentials === "shared" && serverEnabled(server));
+    const sharedAnnotations = new Map();
     const catalog = createUserCatalog(host, config.servers, config.userServers ?? "none");
     const oauthFlows = createUserOauthFlows();
     let closed = false;
@@ -115,12 +118,17 @@ export function createMcpExtension(host) {
                     return;
                 }
                 tools.push(...discovered.tools.map((tool) => sharedTool(host, name, server, tool)));
+                sharedAnnotations.set(name, {
+                    server,
+                    annotations: discovered.annotations,
+                });
                 if (discovered.exposure !== undefined) {
                     serverExposures.set(name, discovered.exposure);
                 }
             }
             catch (cause) {
                 clients.delete(name);
+                sharedAnnotations.delete(name);
                 client.close();
                 console.warn(`mcp server "${name}" quarantined during discovery: ${errorMessage(cause)}`);
             }
@@ -240,6 +248,7 @@ export function createMcpExtension(host) {
         clients.clear();
         tools.length = 0;
         serverExposures.clear();
+        sharedAnnotations.clear();
         await Promise.all(pending);
         oauthFlows.clear();
         catalog.close();
@@ -318,6 +327,7 @@ export function createMcpExtension(host) {
         routes,
         userServices: catalog.userServices,
         surfaces: { settings: catalog.settings },
+        publishedHooks: [createToolAnnotationsHook(host, catalog, sharedAnnotations)],
         conversationCreated: activate,
         runSettled: activate,
         onSettingsChanged: async (keys, user) => {

package/dist/types.d.ts

@@ -1,9 +1,22 @@
 /** Wire types for the MCP stdio protocol surface this extension uses. */
 import type { McpServerConfig } from "./config.js";
+/** The MCP-declared hint surface, narrowed to the four boolean hints a
+ * downstream safety classifier reads. Non-boolean values are dropped at
+ * discovery time rather than trusted blindly. */
+export interface ToolAnnotations {
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+}
 /** One tool as `tools/list` reports it. */
 export interface McpToolDefinition {
     readonly name: string;
     readonly description?: string;
+    /** Server-advertised hints; only boolean values are retained. */
+    readonly annotations?: {
+        readonly [key: string]: unknown;
+    };
     /** JSON Schema for the tool's arguments object. */
     readonly inputSchema?: {
         readonly type?: unknown;

package/dist/user-servers.d.ts

@@ -4,6 +4,7 @@
 import { type ConversationId, type ToolRegistration } from "@earendil-works/pi-durable";
 import { type McpClient, type McpServiceHandle } from "./client.js";
 import { type McpServerConfig, type UserServersMode } from "./config.js";
+import type { ToolAnnotations } from "./types.js";
 export interface HandlerContext {
     readonly abortSignal: AbortSignal | undefined;
 }
@@ -61,9 +62,18 @@ export interface ServerExposure {
     readonly description: string;
     readonly count: number;
 }
+/** One discovered tool's annotation record, keyed by the sigrun tool name. */
+export interface ToolAnnotationEntry {
+    readonly server: string;
+    readonly mcpName: string;
+    readonly annotations: ToolAnnotations;
+}
 export interface DiscoveredTools {
     readonly tools: ToolRegistration[];
     readonly exposure: ServerExposure | undefined;
+    /** Annotations keyed by the sigrun tool name (`<server>/<tool>`); only
+     * tools that advertised at least one boolean hint appear. */
+    readonly annotations: ReadonlyMap<string, ToolAnnotationEntry>;
 }
 /** The one discovery-to-registration mapping shared by system and user tools. */
 export declare function discoverMcpTools(name: string, server: McpServerConfig, client: McpClient): Promise<DiscoveredTools>;
@@ -86,6 +96,9 @@ export interface UserCatalog {
     activate(user: string, ctx?: HandlerContext): Promise<void>;
     retire(user: string, server: string): Promise<void>;
     exposures(user: string): ReadonlyMap<string, ServerExposure>;
+    /** Live annotation maps for this user's current connections; retirement
+     * removes entries because the underlying connections map is the source. */
+    annotationsFor(user: string): ReadonlyMap<string, ToolAnnotationEntry>;
     reconcileAll(mode?: UserServersMode): Promise<void>;
     close(): void;
 }

package/dist/user-servers.js

@@ -5,6 +5,23 @@ import { Type } from "@earendil-works/pi-ai";
 import { defineTool, } from "@earendil-works/pi-durable";
 import { connectMcpServer, } from "./client.js";
 import { isStdioServer, parseMcpConfig, resolveToolExposure, serverEnabled, } from "./config.js";
+/** Copy only the four boolean hint values; anything else is untrusted noise. */
+function keepBooleanAnnotations(annotations) {
+    if (annotations === undefined)
+        return undefined;
+    const kept = {};
+    for (const hint of [
+        "readOnlyHint",
+        "destructiveHint",
+        "idempotentHint",
+        "openWorldHint",
+    ]) {
+        const value = annotations[hint];
+        if (typeof value === "boolean")
+            kept[hint] = value;
+    }
+    return Object.keys(kept).length > 0 ? kept : undefined;
+}
 function toContent(block) {
     return block.type === "text" && typeof block.text === "string"
         ? { type: "text", text: block.text }
@@ -14,11 +31,20 @@ function toContent(block) {
 export async function discoverMcpTools(name, server, client) {
     const discovered = await client.listTools();
     const tools = [];
+    const annotations = new Map();
     const mix = { codemode: false, deferred: false, count: 0 };
     for (const tool of discovered) {
         const exposure = resolveToolExposure(server, tool.name);
         if (exposure === "hidden")
             continue;
+        const kept = keepBooleanAnnotations(tool.annotations);
+        if (kept !== undefined) {
+            annotations.set(`${name}/${tool.name}`, {
+                server: name,
+                mcpName: tool.name,
+                annotations: kept,
+            });
+        }
         if (exposure === "codemode")
             mix.codemode = true;
         if (exposure === "deferred")
@@ -61,7 +87,7 @@ export async function discoverMcpTools(name, server, client) {
         }));
     }
     if (mix.count === 0 || (!mix.codemode && !mix.deferred)) {
-        return { tools, exposure: undefined };
+        return { tools, exposure: undefined, annotations };
     }
     const origin = isStdioServer(server)
         ? `${server.command} ${server.args.join(" ")}`.trim()
@@ -72,6 +98,7 @@ export async function discoverMcpTools(name, server, client) {
             ...mix,
             description: `${mix.count} tool${mix.count === 1 ? "" : "s"} from ${origin}`,
         },
+        annotations,
     };
 }
 export function catalogEnabledFromSettings(name, server, settings) {
@@ -132,6 +159,7 @@ function trackConnection(name, client, discovered) {
     return {
         registrations,
         exposure: discovered.exposure,
+        annotations: discovered.annotations,
         retire: () => {
             retired = true;
             drain();
@@ -407,6 +435,7 @@ export function createUserCatalog(host, servers, initialMode = "none") {
         retire,
         reconcileAll,
         exposures: (user) => new Map([...(states.get(user)?.connections ?? [])].flatMap(([name, connection]) => connection.exposure === undefined ? [] : [[name, connection.exposure]])),
+        annotationsFor: (user) => new Map([...(states.get(user)?.connections ?? [])].flatMap(([, connection]) => [...connection.annotations])),
         close: () => {
             if (closed)
                 return;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sigrun/ext-mcp",
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"description": "MCP extension for sigrun (pi-durable): registers MCP server tools as <server>/<toolname> tools",
 	"type": "module",
 	"engines": {
@@ -28,15 +28,15 @@
 		"prepublishOnly": "npm run build"
 	},
 	"peerDependencies": {
-		"@earendil-works/chord": "1.3.0",
-		"@earendil-works/pi-ai": "1.3.0",
-		"@earendil-works/pi-durable": "1.3.0",
+		"@earendil-works/chord": "1.3.0 || 1.4.0",
+		"@earendil-works/pi-ai": "1.3.0 || 1.4.0",
+		"@earendil-works/pi-durable": "1.3.0 || 1.4.0",
 		"typebox": "1.3.27"
 	},
 	"devDependencies": {
-		"@earendil-works/chord": "1.3.0",
-		"@earendil-works/pi-ai": "1.3.0",
-		"@earendil-works/pi-durable": "1.3.0",
+		"@earendil-works/chord": "1.4.0",
+		"@earendil-works/pi-ai": "1.4.0",
+		"@earendil-works/pi-durable": "1.4.0",
 		"@sigrun/sigrun": "file:../sigrun",
 		"@types/node": "^26.6.4",
 		"tsx": "^4.23.15",