@pixerate/editor 0.139.1 → 0.140.1

package/dist/tools/registry.d.cts

@@ -1,4 +1,5 @@
 import { type JsonSchema, type SchemaValidationError } from './schema.cjs';
+import { ToolRegistryView, type ToolViewOptions } from './view.cjs';
 /**
  * MCP-shaped tool definition, as returned by `tools/list`.
  */
@@ -59,12 +60,25 @@ export interface AgentTool extends McpToolDefinition {
 }
 /**
  * A source of tools, typically one per mounted editor, spreadsheet or canvas.
+ * Each provider is a toolset: its tools are exposed as `<namespace>__<name>`
+ * (see {@link ToolRegistryOptions.namespaces}) and grouped under that name by
+ * `toolsets()`, `registry.view()` and the discovery tools.
  */
 export interface AgentToolProvider {
-    /** Unique id within a registry, e.g. `doc-1`. Used as the namespace on collisions. */
+    /** Unique id within a registry, e.g. `doc-1`. The default namespace. */
     id: string;
-    /** Always prefix this provider's tools with `<namespace>__`. */
+    /**
+     * Prefix for this provider's tools (`<namespace>__<name>`). Defaults to the
+     * `id`. Pass `''` to expose bare names (prefixed by `id` only on a collision).
+     * Providers may share a namespace when their tool names differ.
+     */
     namespace?: string;
+    /** Short name of the toolset for agents and UIs, e.g. "Chart editor". */
+    title?: string;
+    /** What the toolset covers and when to use it, in a sentence or two. */
+    description?: string;
+    /** Name of the agent skill that documents these tools, e.g. `pixerate-chart`. */
+    skill?: string;
     /** Tools, or a function returning the current tools (re-read on every `listTools`). */
     tools: readonly AgentTool[] | (() => readonly AgentTool[]);
     /** Lets the provider signal that its tool list changed; returns an unsubscribe function. */
@@ -84,7 +98,18 @@ export declare class ToolRegistryError extends Error {
 }
 export interface ToolRegistryOptions {
     /**
-     * What to do when two providers contribute the same tool name:
+     * `always` (default): every tool is exposed as `<namespace>__<name>`, where the
+     * namespace is the provider's `namespace` or else its `id`, so names don't
+     * change when another editor mounts. `on-collision`: only providers with an
+     * explicit `namespace` are prefixed; other tools keep their bare name unless
+     * two providers share it (see `onCollision`).
+     *
+     * Either way, `callTool`, `hasTool` and `getTool` also accept a bare name
+     * when exactly one exposed tool has it.
+     */
+    namespaces?: 'always' | 'on-collision';
+    /**
+     * What to do when two unprefixed tools share a name:
      * `namespace` (default) exposes every colliding tool as `<providerId>__<name>`;
      * `error` makes `register` throw.
      */
@@ -96,6 +121,48 @@ export interface ToolRegistryOptions {
 }
 /** Separator between namespace and tool name; valid in MCP and LLM tool-name charsets. */
 export declare const TOOL_NAMESPACE_SEPARATOR = "__";
+/** The toolset a provider belongs to: its namespace, or else its id. */
+export declare function toolsetName(provider: Pick<AgentToolProvider, 'id' | 'namespace'>): string;
+/** The name a tool was registered under, without its namespace (`chart__get_chart` → `get_chart`). */
+export declare function baseToolName(name: string): string;
+/** A group of tools from one or more providers that share a namespace. */
+export interface ToolsetInfo {
+    /** Toolset name: the providers' namespace, or the provider id. */
+    name: string;
+    title?: string;
+    description?: string;
+    /** Agent skill that documents these tools. */
+    skill?: string;
+    /** Ids of the providers in this toolset. */
+    providers: string[];
+    /** Exposed names of its tools, in listing order. */
+    tools: string[];
+}
+/**
+ * Anything that serves tools the way a {@link ToolRegistry} does: a registry,
+ * a {@link ToolRegistryView} of one, or the MCP bridge's registry.
+ * `createMcpServer` and `connectToolBridge` accept any of them.
+ */
+export interface ToolSource {
+    readonly capabilities: {
+        tools: {
+            listChanged: boolean;
+        };
+    };
+    listTools(): McpListToolsResult;
+    hasTool(name: string): boolean;
+    getTool(name: string): McpToolDefinition | undefined;
+    callTool(name: string, args?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<McpToolResult>;
+    onListChanged(listener: (tools: McpToolDefinition[]) => void): () => void;
+    /** The toolsets behind `listTools()`, in listing order. */
+    toolsets(): ToolsetInfo[];
+}
+/** `unknown_tool` message, naming the tools a bare name could mean. */
+export declare function unknownToolMessage(name: string, candidates?: readonly string[]): string;
+/** An `isError` tool result carrying a {@link ToolCallError}. */
+export declare function errorResult(error: ToolCallError): McpToolResult;
 /** Normalizes a handler's return value into an MCP `tools/call` result. */
 export declare function toToolResult(value: unknown): McpToolResult;
 /**
@@ -106,7 +173,7 @@ export declare function toToolResult(value: unknown): McpToolResult;
  * tool list changes, mirroring MCP's `notifications/tools/list_changed`, so an
  * MCP server can be a thin wrapper around it.
  */
-export declare class ToolRegistry {
+export declare class ToolRegistry implements ToolSource {
     /** MCP server capabilities this registry supports. */
     readonly capabilities: {
         readonly tools: {
@@ -136,10 +203,18 @@ export declare class ToolRegistry {
     private resolve;
     /** MCP `tools/list` result for the current providers. */
     listTools(): McpListToolsResult;
-    /** Whether a tool with this exposed name exists. */
+    /** Whether a tool with this exposed name (or unique bare name) exists. */
     hasTool(name: string): boolean;
-    /** Looks up a tool definition by exposed name. */
+    /** Looks up a tool definition by exposed name (or unique bare name). */
     getTool(name: string): McpToolDefinition | undefined;
+    /** The registered providers grouped by namespace, in listing order. */
+    toolsets(): ToolsetInfo[];
+    /**
+     * A filtered, optionally self-discovering view of this registry: serve it
+     * with `createMcpServer` or `connectToolBridge` instead of the registry to
+     * show an agent only some toolsets. See {@link ToolRegistryView}.
+     */
+    view(options?: ToolViewOptions): ToolRegistryView;
     /**
      * Calls a tool by exposed name and returns an MCP `tools/call` result.
      * Never rejects: unknown tools, invalid arguments and handler errors come

package/dist/tools/registry.d.ts

@@ -1,4 +1,5 @@
 import { type JsonSchema, type SchemaValidationError } from './schema.js';
+import { ToolRegistryView, type ToolViewOptions } from './view.js';
 /**
  * MCP-shaped tool definition, as returned by `tools/list`.
  */
@@ -59,12 +60,25 @@ export interface AgentTool extends McpToolDefinition {
 }
 /**
  * A source of tools, typically one per mounted editor, spreadsheet or canvas.
+ * Each provider is a toolset: its tools are exposed as `<namespace>__<name>`
+ * (see {@link ToolRegistryOptions.namespaces}) and grouped under that name by
+ * `toolsets()`, `registry.view()` and the discovery tools.
  */
 export interface AgentToolProvider {
-    /** Unique id within a registry, e.g. `doc-1`. Used as the namespace on collisions. */
+    /** Unique id within a registry, e.g. `doc-1`. The default namespace. */
     id: string;
-    /** Always prefix this provider's tools with `<namespace>__`. */
+    /**
+     * Prefix for this provider's tools (`<namespace>__<name>`). Defaults to the
+     * `id`. Pass `''` to expose bare names (prefixed by `id` only on a collision).
+     * Providers may share a namespace when their tool names differ.
+     */
     namespace?: string;
+    /** Short name of the toolset for agents and UIs, e.g. "Chart editor". */
+    title?: string;
+    /** What the toolset covers and when to use it, in a sentence or two. */
+    description?: string;
+    /** Name of the agent skill that documents these tools, e.g. `pixerate-chart`. */
+    skill?: string;
     /** Tools, or a function returning the current tools (re-read on every `listTools`). */
     tools: readonly AgentTool[] | (() => readonly AgentTool[]);
     /** Lets the provider signal that its tool list changed; returns an unsubscribe function. */
@@ -84,7 +98,18 @@ export declare class ToolRegistryError extends Error {
 }
 export interface ToolRegistryOptions {
     /**
-     * What to do when two providers contribute the same tool name:
+     * `always` (default): every tool is exposed as `<namespace>__<name>`, where the
+     * namespace is the provider's `namespace` or else its `id`, so names don't
+     * change when another editor mounts. `on-collision`: only providers with an
+     * explicit `namespace` are prefixed; other tools keep their bare name unless
+     * two providers share it (see `onCollision`).
+     *
+     * Either way, `callTool`, `hasTool` and `getTool` also accept a bare name
+     * when exactly one exposed tool has it.
+     */
+    namespaces?: 'always' | 'on-collision';
+    /**
+     * What to do when two unprefixed tools share a name:
      * `namespace` (default) exposes every colliding tool as `<providerId>__<name>`;
      * `error` makes `register` throw.
      */
@@ -96,6 +121,48 @@ export interface ToolRegistryOptions {
 }
 /** Separator between namespace and tool name; valid in MCP and LLM tool-name charsets. */
 export declare const TOOL_NAMESPACE_SEPARATOR = "__";
+/** The toolset a provider belongs to: its namespace, or else its id. */
+export declare function toolsetName(provider: Pick<AgentToolProvider, 'id' | 'namespace'>): string;
+/** The name a tool was registered under, without its namespace (`chart__get_chart` → `get_chart`). */
+export declare function baseToolName(name: string): string;
+/** A group of tools from one or more providers that share a namespace. */
+export interface ToolsetInfo {
+    /** Toolset name: the providers' namespace, or the provider id. */
+    name: string;
+    title?: string;
+    description?: string;
+    /** Agent skill that documents these tools. */
+    skill?: string;
+    /** Ids of the providers in this toolset. */
+    providers: string[];
+    /** Exposed names of its tools, in listing order. */
+    tools: string[];
+}
+/**
+ * Anything that serves tools the way a {@link ToolRegistry} does: a registry,
+ * a {@link ToolRegistryView} of one, or the MCP bridge's registry.
+ * `createMcpServer` and `connectToolBridge` accept any of them.
+ */
+export interface ToolSource {
+    readonly capabilities: {
+        tools: {
+            listChanged: boolean;
+        };
+    };
+    listTools(): McpListToolsResult;
+    hasTool(name: string): boolean;
+    getTool(name: string): McpToolDefinition | undefined;
+    callTool(name: string, args?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<McpToolResult>;
+    onListChanged(listener: (tools: McpToolDefinition[]) => void): () => void;
+    /** The toolsets behind `listTools()`, in listing order. */
+    toolsets(): ToolsetInfo[];
+}
+/** `unknown_tool` message, naming the tools a bare name could mean. */
+export declare function unknownToolMessage(name: string, candidates?: readonly string[]): string;
+/** An `isError` tool result carrying a {@link ToolCallError}. */
+export declare function errorResult(error: ToolCallError): McpToolResult;
 /** Normalizes a handler's return value into an MCP `tools/call` result. */
 export declare function toToolResult(value: unknown): McpToolResult;
 /**
@@ -106,7 +173,7 @@ export declare function toToolResult(value: unknown): McpToolResult;
  * tool list changes, mirroring MCP's `notifications/tools/list_changed`, so an
  * MCP server can be a thin wrapper around it.
  */
-export declare class ToolRegistry {
+export declare class ToolRegistry implements ToolSource {
     /** MCP server capabilities this registry supports. */
     readonly capabilities: {
         readonly tools: {
@@ -136,10 +203,18 @@ export declare class ToolRegistry {
     private resolve;
     /** MCP `tools/list` result for the current providers. */
     listTools(): McpListToolsResult;
-    /** Whether a tool with this exposed name exists. */
+    /** Whether a tool with this exposed name (or unique bare name) exists. */
     hasTool(name: string): boolean;
-    /** Looks up a tool definition by exposed name. */
+    /** Looks up a tool definition by exposed name (or unique bare name). */
     getTool(name: string): McpToolDefinition | undefined;
+    /** The registered providers grouped by namespace, in listing order. */
+    toolsets(): ToolsetInfo[];
+    /**
+     * A filtered, optionally self-discovering view of this registry: serve it
+     * with `createMcpServer` or `connectToolBridge` instead of the registry to
+     * show an agent only some toolsets. See {@link ToolRegistryView}.
+     */
+    view(options?: ToolViewOptions): ToolRegistryView;
     /**
      * Calls a tool by exposed name and returns an MCP `tools/call` result.
      * Never rejects: unknown tools, invalid arguments and handler errors come

package/dist/tools/safe-json.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Guards against prototype pollution from untrusted JSON (GHSA-cp6q-959q-f8rh).
+ *
+ * `JSON.parse('{"__proto__": {...}}')` creates an *own* `__proto__` key. Code
+ * that later copies keys with bracket assignment (`out[key] = value`,
+ * `Object.assign`) turns it into the copy's prototype, so the copy inherits
+ * attacker-chosen properties that `for…in` loops (ProseMirror's
+ * `DOMSerializer.renderSpec`, for one) then treat as real ones. TipTap's
+ * `mergeAttributes()` did exactly that before `@tiptap/core` 2.27.3 / 3.30.4.
+ *
+ * This file has no dependencies so the tool layer can use it.
+ */
+/** Keys that are dropped from untrusted JSON objects. */
+export declare const UNSAFE_JSON_KEYS: ReadonlySet<string>;
+/** Whether `key` is one of {@link UNSAFE_JSON_KEYS}. */
+export declare const isUnsafeJsonKey: (key: string) => boolean;
+/**
+ * Returns `value` without own `__proto__`, `constructor` and `prototype` keys
+ * at any depth of its plain objects and arrays. Run untrusted JSON through it
+ * before handing it to `setContent`, `Node.fromJSON`, `Slice.fromJSON` or any
+ * code that merges objects key by key.
+ *
+ * Returns `value` itself when there is nothing to strip, and a copy otherwise,
+ * so the input is never mutated. Non-plain objects (class instances) pass
+ * through untouched.
+ */
+export declare function stripPrototypeKeys<T>(value: T): T;

package/dist/tools/safe-json.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Guards against prototype pollution from untrusted JSON (GHSA-cp6q-959q-f8rh).
+ *
+ * `JSON.parse('{"__proto__": {...}}')` creates an *own* `__proto__` key. Code
+ * that later copies keys with bracket assignment (`out[key] = value`,
+ * `Object.assign`) turns it into the copy's prototype, so the copy inherits
+ * attacker-chosen properties that `for…in` loops (ProseMirror's
+ * `DOMSerializer.renderSpec`, for one) then treat as real ones. TipTap's
+ * `mergeAttributes()` did exactly that before `@tiptap/core` 2.27.3 / 3.30.4.
+ *
+ * This file has no dependencies so the tool layer can use it.
+ */
+/** Keys that are dropped from untrusted JSON objects. */
+export declare const UNSAFE_JSON_KEYS: ReadonlySet<string>;
+/** Whether `key` is one of {@link UNSAFE_JSON_KEYS}. */
+export declare const isUnsafeJsonKey: (key: string) => boolean;
+/**
+ * Returns `value` without own `__proto__`, `constructor` and `prototype` keys
+ * at any depth of its plain objects and arrays. Run untrusted JSON through it
+ * before handing it to `setContent`, `Node.fromJSON`, `Slice.fromJSON` or any
+ * code that merges objects key by key.
+ *
+ * Returns `value` itself when there is nothing to strip, and a copy otherwise,
+ * so the input is never mutated. Non-plain objects (class instances) pass
+ * through untouched.
+ */
+export declare function stripPrototypeKeys<T>(value: T): T;

package/dist/tools/search.d.cts

@@ -0,0 +1,30 @@
+import type { McpToolDefinition, ToolsetInfo } from './registry.cjs';
+/** A tool as `search_tools` ranks it. */
+export interface ToolSearchResult {
+    /** Exposed tool name, to call or to pass to `enable_tools`. */
+    name: string;
+    toolset: string;
+    title?: string;
+    /** The first sentence of the tool's description. */
+    summary: string;
+    readOnly: boolean;
+    score: number;
+}
+export interface ToolSearchOptions {
+    /** Only search this toolset. */
+    toolset?: string;
+    /** Maximum results (default 10). */
+    limit?: number;
+}
+/** Lower-cased, stemmed word tokens of `text`, splitting snake_case and camelCase. */
+export declare function searchTokens(text: string): string[];
+/** The first sentence of a description, for compact listings. */
+export declare function summarize(description: string | undefined, max?: number): string;
+/**
+ * Ranks tools against a free-text query: every query word scores by the
+ * fields it appears in (name, title, toolset, description, arguments), weighted by how
+ * rare the word is across all tools, so "trendline" outranks "chart". A word
+ * that prefixes a longer one ("trend" → "trendline") counts at half weight.
+ * Pure and dependency-free; `search_tools` uses it.
+ */
+export declare function searchTools(tools: readonly McpToolDefinition[], toolsets: readonly ToolsetInfo[], query: string, options?: ToolSearchOptions): ToolSearchResult[];

package/dist/tools/search.d.ts

@@ -0,0 +1,30 @@
+import type { McpToolDefinition, ToolsetInfo } from './registry.js';
+/** A tool as `search_tools` ranks it. */
+export interface ToolSearchResult {
+    /** Exposed tool name, to call or to pass to `enable_tools`. */
+    name: string;
+    toolset: string;
+    title?: string;
+    /** The first sentence of the tool's description. */
+    summary: string;
+    readOnly: boolean;
+    score: number;
+}
+export interface ToolSearchOptions {
+    /** Only search this toolset. */
+    toolset?: string;
+    /** Maximum results (default 10). */
+    limit?: number;
+}
+/** Lower-cased, stemmed word tokens of `text`, splitting snake_case and camelCase. */
+export declare function searchTokens(text: string): string[];
+/** The first sentence of a description, for compact listings. */
+export declare function summarize(description: string | undefined, max?: number): string;
+/**
+ * Ranks tools against a free-text query: every query word scores by the
+ * fields it appears in (name, title, toolset, description, arguments), weighted by how
+ * rare the word is across all tools, so "trendline" outranks "chart". A word
+ * that prefixes a longer one ("trend" → "trendline") counts at half weight.
+ * Pure and dependency-free; `search_tools` uses it.
+ */
+export declare function searchTools(tools: readonly McpToolDefinition[], toolsets: readonly ToolsetInfo[], query: string, options?: ToolSearchOptions): ToolSearchResult[];

package/dist/tools/skills.d.cts

@@ -0,0 +1,26 @@
+/**
+ * Agent skill files (`skills/<name>/SKILL.md` plus its `references/*.md`), keyed by
+ * path relative to the skills directory: `pixerate-chart/SKILL.md`,
+ * `pixerate-vector/references/commands.md`. In Node, `loadSkillFiles()` from
+ * `@pixerate/editor/bridge` reads the ones shipped with the package; in a browser,
+ * import them as text (with Vite, `import.meta.glob('…/skills/**\/*.md', { query: '?raw', import: 'default', eager: true })`).
+ */
+export type SkillFiles = Readonly<Record<string, string>>;
+export interface SkillInfo {
+    /** Skill name (its directory), e.g. `pixerate-chart`. */
+    name: string;
+    /** The frontmatter `description`: what the skill covers and when to use it. */
+    description: string;
+    /** Other files of the skill relative to its directory, e.g. `references/commands.md`. */
+    references: string[];
+}
+/** Reads `name` and `description` from a SKILL.md's YAML frontmatter. */
+export declare function parseSkillFrontmatter(markdown: string): {
+    name?: string;
+    description?: string;
+    body: string;
+};
+/** The skills in a set of skill files, sorted by name. */
+export declare function listSkills(files: SkillFiles): SkillInfo[];
+/** One file of a skill (`SKILL.md` by default), or `undefined` if there is none. */
+export declare function readSkillFile(files: SkillFiles, skill: string, file?: string): string | undefined;

package/dist/tools/skills.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Agent skill files (`skills/<name>/SKILL.md` plus its `references/*.md`), keyed by
+ * path relative to the skills directory: `pixerate-chart/SKILL.md`,
+ * `pixerate-vector/references/commands.md`. In Node, `loadSkillFiles()` from
+ * `@pixerate/editor/bridge` reads the ones shipped with the package; in a browser,
+ * import them as text (with Vite, `import.meta.glob('…/skills/**\/*.md', { query: '?raw', import: 'default', eager: true })`).
+ */
+export type SkillFiles = Readonly<Record<string, string>>;
+export interface SkillInfo {
+    /** Skill name (its directory), e.g. `pixerate-chart`. */
+    name: string;
+    /** The frontmatter `description`: what the skill covers and when to use it. */
+    description: string;
+    /** Other files of the skill relative to its directory, e.g. `references/commands.md`. */
+    references: string[];
+}
+/** Reads `name` and `description` from a SKILL.md's YAML frontmatter. */
+export declare function parseSkillFrontmatter(markdown: string): {
+    name?: string;
+    description?: string;
+    body: string;
+};
+/** The skills in a set of skill files, sorted by name. */
+export declare function listSkills(files: SkillFiles): SkillInfo[];
+/** One file of a skill (`SKILL.md` by default), or `undefined` if there is none. */
+export declare function readSkillFile(files: SkillFiles, skill: string, file?: string): string | undefined;

package/dist/tools/view.d.cts

@@ -0,0 +1,95 @@
+import type { McpListToolsResult, McpToolDefinition, McpToolResult, ToolSource, ToolsetInfo } from './registry.cjs';
+import { type SkillFiles } from './skills.cjs';
+export interface ToolDiscoveryOptions {
+    /** Toolsets listed from the start (default none: the agent enables what it needs). */
+    enabled?: readonly string[];
+    /** Skill files `get_skill` serves (see {@link SkillFiles}). Without them there is no `get_skill`. */
+    skills?: SkillFiles;
+    /** Default and maximum number of `search_tools` results (default 10, at most 50). */
+    searchLimit?: number;
+}
+export interface ToolViewOptions {
+    /**
+     * Toolsets the agent may see and call (names from `registry.toolsets()`), or a
+     * predicate. Default: all. Change it later with `setToolsets`, e.g. to follow
+     * the focused editor.
+     */
+    toolsets?: readonly string[] | ((toolset: ToolsetInfo) => boolean);
+    /** Only expose tools annotated `readOnlyHint: true`; write tools are refused with the reason. */
+    readOnly?: boolean;
+    /**
+     * Serve discovery tools (`list_toolsets`, `search_tools`, `enable_tools`,
+     * `disable_tools` and, with skills, `get_skill`) and list only the toolsets
+     * and tools that are enabled, so a large catalogue costs the agent a handful
+     * of tool definitions until it asks for more. Tools that are allowed but not
+     * enabled can still be called by name.
+     */
+    discovery?: boolean | ToolDiscoveryOptions;
+}
+/** Names of the tools a discovery view adds. */
+export declare const TOOL_DISCOVERY_TOOLS: readonly ["list_toolsets", "search_tools", "enable_tools", "disable_tools", "get_skill"];
+/**
+ * A filtered view of a {@link ToolSource} (usually a `ToolRegistry`, from
+ * `registry.view()`) that is itself a `ToolSource`, so `createMcpServer`,
+ * `connectToolBridge` and further views accept it.
+ *
+ * - **Scope** an agent to some toolsets (`toolsets`) or to read tools
+ *   (`readOnly`). Tools outside the scope are neither listed nor callable.
+ * - **Discover** (`discovery`): list only what the agent enabled, plus tools to
+ *   browse and search the rest and to enable it. `listChanged` fires whenever
+ *   the listing changes.
+ */
+export declare class ToolRegistryView implements ToolSource {
+    private readonly source;
+    readonly capabilities: {
+        readonly tools: {
+            readonly listChanged: true;
+        };
+    };
+    private allow;
+    private readonly readOnly;
+    private readonly discovery;
+    private readonly enabledSets;
+    private readonly enabledTools;
+    private readonly listeners;
+    private readonly meta;
+    private unsubscribe;
+    private lastSignature;
+    constructor(source: ToolSource, options?: ToolViewOptions);
+    /** Changes which toolsets the agent may use (`undefined`: all). Fires `listChanged` if the listing changes. */
+    setToolsets(toolsets: ToolViewOptions['toolsets']): void;
+    /**
+     * Lists more tools in a discovery view, as the `enable_tools` tool does.
+     * Throws for names the view does not allow. Returns the tool names newly listed.
+     */
+    enableTools(selection: {
+        tools?: readonly string[];
+        toolsets?: readonly string[];
+    }): string[];
+    /** Stops listing tools in a discovery view, as `disable_tools` does. Returns the tool names no longer listed. */
+    disableTools(selection: {
+        tools?: readonly string[];
+        toolsets?: readonly string[];
+    }): string[];
+    /** Allowed toolsets, each with only its allowed tools. */
+    toolsets(): ToolsetInfo[];
+    listTools(): McpListToolsResult;
+    hasTool(name: string): boolean;
+    getTool(name: string): McpToolDefinition | undefined;
+    callTool(name: string, args?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<McpToolResult>;
+    onListChanged(listener: (tools: McpToolDefinition[]) => void): () => void;
+    /** Stops following the source and drops every listener. */
+    dispose(): void;
+    private changed;
+    private signature;
+    private allowsSet;
+    private catalogue;
+    private listed;
+    /** Resolves an exposed or unique bare name among the allowed tools, or explains why it isn't one. */
+    private find;
+    /** Normalizes names to exposed tool and toolset names, or throws naming every unknown one. */
+    private checkSelection;
+    private createDiscoveryTools;
+}

package/dist/tools/view.d.ts

@@ -0,0 +1,95 @@
+import type { McpListToolsResult, McpToolDefinition, McpToolResult, ToolSource, ToolsetInfo } from './registry.js';
+import { type SkillFiles } from './skills.js';
+export interface ToolDiscoveryOptions {
+    /** Toolsets listed from the start (default none: the agent enables what it needs). */
+    enabled?: readonly string[];
+    /** Skill files `get_skill` serves (see {@link SkillFiles}). Without them there is no `get_skill`. */
+    skills?: SkillFiles;
+    /** Default and maximum number of `search_tools` results (default 10, at most 50). */
+    searchLimit?: number;
+}
+export interface ToolViewOptions {
+    /**
+     * Toolsets the agent may see and call (names from `registry.toolsets()`), or a
+     * predicate. Default: all. Change it later with `setToolsets`, e.g. to follow
+     * the focused editor.
+     */
+    toolsets?: readonly string[] | ((toolset: ToolsetInfo) => boolean);
+    /** Only expose tools annotated `readOnlyHint: true`; write tools are refused with the reason. */
+    readOnly?: boolean;
+    /**
+     * Serve discovery tools (`list_toolsets`, `search_tools`, `enable_tools`,
+     * `disable_tools` and, with skills, `get_skill`) and list only the toolsets
+     * and tools that are enabled, so a large catalogue costs the agent a handful
+     * of tool definitions until it asks for more. Tools that are allowed but not
+     * enabled can still be called by name.
+     */
+    discovery?: boolean | ToolDiscoveryOptions;
+}
+/** Names of the tools a discovery view adds. */
+export declare const TOOL_DISCOVERY_TOOLS: readonly ["list_toolsets", "search_tools", "enable_tools", "disable_tools", "get_skill"];
+/**
+ * A filtered view of a {@link ToolSource} (usually a `ToolRegistry`, from
+ * `registry.view()`) that is itself a `ToolSource`, so `createMcpServer`,
+ * `connectToolBridge` and further views accept it.
+ *
+ * - **Scope** an agent to some toolsets (`toolsets`) or to read tools
+ *   (`readOnly`). Tools outside the scope are neither listed nor callable.
+ * - **Discover** (`discovery`): list only what the agent enabled, plus tools to
+ *   browse and search the rest and to enable it. `listChanged` fires whenever
+ *   the listing changes.
+ */
+export declare class ToolRegistryView implements ToolSource {
+    private readonly source;
+    readonly capabilities: {
+        readonly tools: {
+            readonly listChanged: true;
+        };
+    };
+    private allow;
+    private readonly readOnly;
+    private readonly discovery;
+    private readonly enabledSets;
+    private readonly enabledTools;
+    private readonly listeners;
+    private readonly meta;
+    private unsubscribe;
+    private lastSignature;
+    constructor(source: ToolSource, options?: ToolViewOptions);
+    /** Changes which toolsets the agent may use (`undefined`: all). Fires `listChanged` if the listing changes. */
+    setToolsets(toolsets: ToolViewOptions['toolsets']): void;
+    /**
+     * Lists more tools in a discovery view, as the `enable_tools` tool does.
+     * Throws for names the view does not allow. Returns the tool names newly listed.
+     */
+    enableTools(selection: {
+        tools?: readonly string[];
+        toolsets?: readonly string[];
+    }): string[];
+    /** Stops listing tools in a discovery view, as `disable_tools` does. Returns the tool names no longer listed. */
+    disableTools(selection: {
+        tools?: readonly string[];
+        toolsets?: readonly string[];
+    }): string[];
+    /** Allowed toolsets, each with only its allowed tools. */
+    toolsets(): ToolsetInfo[];
+    listTools(): McpListToolsResult;
+    hasTool(name: string): boolean;
+    getTool(name: string): McpToolDefinition | undefined;
+    callTool(name: string, args?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<McpToolResult>;
+    onListChanged(listener: (tools: McpToolDefinition[]) => void): () => void;
+    /** Stops following the source and drops every listener. */
+    dispose(): void;
+    private changed;
+    private signature;
+    private allowsSet;
+    private catalogue;
+    private listed;
+    /** Resolves an exposed or unique bare name among the allowed tools, or explains why it isn't one. */
+    private find;
+    /** Normalizes names to exposed tool and toolset names, or throws naming every unknown one. */
+    private checkSelection;
+    private createDiscoveryTools;
+}

package/dist/vector/effect-tools.d.cts

@@ -9,7 +9,7 @@ import type { VectorEditorController } from './controller.cjs';
 export interface VectorEffectsToolProviderOptions {
     /** Provider id (unique per registry). Default `vector-effects`. */
     id?: string;
-    /** Always prefix tool names with `<namespace>__`. */
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
     namespace?: string;
     /** The document cannot be edited: write tools are hidden. A string is the reason. */
     readOnly?: boolean | string | (() => boolean | string);

package/dist/vector/effect-tools.d.ts

@@ -9,7 +9,7 @@ import type { VectorEditorController } from './controller.js';
 export interface VectorEffectsToolProviderOptions {
     /** Provider id (unique per registry). Default `vector-effects`. */
     id?: string;
-    /** Always prefix tool names with `<namespace>__`. */
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
     namespace?: string;
     /** The document cannot be edited: write tools are hidden. A string is the reason. */
     readOnly?: boolean | string | (() => boolean | string);