@pixerate/editor 0.18.0 → 0.20.0

package/dist/agent/index.d.ts

@@ -1,4 +1,6 @@
-import { C as CanvasNode, a as CanvasEdge, X as XYPosition, S as Side } from '../types-JV3S8VeR.js';
+import { C as CanvasNode, a as CanvasEdge, X as XYPosition, S as Side } from '../types-DMe0vFB1.js';
+import { Editor } from '@tiptap/core';
+import { W as SpreadsheetController } from '../controller-OUdxPY-X.js';
 
 /**
  * Agent presence state for visual multiplayer/agent choreography.
@@ -93,6 +95,11 @@ type AgentCommand<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdg
 } | {
     type: 'choreography:wait';
     ms: number;
+} | {
+    type: 'tool:call';
+    /** Exposed tool name in a `ToolRegistry`. */
+    name: string;
+    arguments?: Record<string, unknown>;
 };
 /**
  * Atomic execution steps returned by the planner.
@@ -146,6 +153,11 @@ type AgentStep<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge =
 } | {
     type: 'step:wait';
     ms: number;
+} | {
+    /** Execute with `ToolRegistry.callTool(name, arguments)`. */
+    type: 'step:tool_call';
+    name: string;
+    arguments: Record<string, unknown>;
 };
 
 /**
@@ -163,6 +175,20 @@ declare function planAgentCommand<TNode extends CanvasNode = CanvasNode, TEdge e
     };
     idGenerator?: () => string;
 }): AgentStep<TNode, TEdge>[];
+/**
+ * Converts an MCP tool call into a planner command. `edit_canvas` and
+ * `edit_prompt` (see `tools.ts`) map to canvas/prompt commands using the MCP
+ * schema's vocabulary; every other tool, including dynamic `ToolRegistry`
+ * tools, becomes a `tool:call` command. Returns `null` when a static tool's
+ * arguments are missing what the operation needs.
+ */
+declare function toolCallToAgentCommand<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(name: string, args?: Record<string, any>): AgentCommand<TNode, TEdge> | null;
+/**
+ * Plans the steps for an MCP tool call: static editor tools are planned like
+ * the equivalent commands, any other tool becomes a `step:tool_call` to be
+ * executed with `ToolRegistry.callTool`. Returns `[]` for invalid arguments.
+ */
+declare function planToolCall<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(name: string, args: Record<string, any>, snapshot: EditorSnapshot<TNode, TEdge>, options?: Parameters<typeof planAgentCommand>[2]): AgentStep<TNode, TEdge>[];
 
 /**
  * Standard MCP Tool Definitions for @pixerate/editor.
@@ -439,4 +465,262 @@ declare const EDITOR_MCP_TOOLS: readonly [{
     };
 }];
 
-export { type AgentCommand, type AgentPresence, type AgentStep, EDITOR_MCP_TOOLS, EXPORT_EXCLUDED_SELECTORS, type EditorSnapshot, MCP_TOOL_EDIT_CANVAS, MCP_TOOL_EDIT_PROMPT, MCP_TOOL_GET_EDITOR_STATE, MCP_TOOL_VIEW_EDITOR, normalizeSide, planAgentCommand };
+/**
+ * JSON-Schema-lite: the subset of JSON Schema used by MCP tool `inputSchema`s,
+ * plus a small validator for tool-call arguments. Unknown keywords are ignored.
+ */
+type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+interface JsonSchema {
+    type?: JsonSchemaType | readonly JsonSchemaType[];
+    description?: string;
+    title?: string;
+    enum?: readonly unknown[];
+    const?: unknown;
+    default?: unknown;
+    properties?: {
+        readonly [key: string]: JsonSchema;
+    };
+    required?: readonly string[];
+    additionalProperties?: boolean | JsonSchema;
+    items?: JsonSchema;
+    minItems?: number;
+    maxItems?: number;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    [keyword: string]: unknown;
+}
+interface SchemaValidationError {
+    /** JSON-pointer-like path to the offending value, e.g. `/node/id` (`""` is the root). */
+    path: string;
+    message: string;
+}
+/**
+ * Validates `value` against `schema` and returns every error found (an empty
+ * array means valid). Supports `type` (incl. arrays of types), `enum`, `const`,
+ * `properties`, `required`, `additionalProperties`, `items`, `minItems`,
+ * `maxItems`, `minimum`, `maximum`, `minLength`, `maxLength` and `pattern`.
+ */
+declare function validateJsonSchema(value: unknown, schema: JsonSchema | undefined, path?: string): SchemaValidationError[];
+
+/**
+ * MCP-shaped tool definition, as returned by `tools/list`.
+ */
+interface McpToolDefinition {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: JsonSchema & {
+        type: 'object';
+    };
+    outputSchema?: JsonSchema;
+    annotations?: {
+        title?: string;
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+        [key: string]: unknown;
+    };
+}
+type McpToolContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+/** MCP `tools/call` result. */
+interface McpToolResult {
+    content: McpToolContent[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/** MCP `tools/list` result. */
+interface McpListToolsResult {
+    tools: McpToolDefinition[];
+}
+interface ToolCallContext {
+    /** Name the tool was called by (possibly namespaced). */
+    name: string;
+    /** Id of the provider that owns the tool. */
+    providerId: string;
+    signal?: AbortSignal;
+}
+/**
+ * Handler return values are normalized into an {@link McpToolResult}: a full
+ * result (`{ content: [...] }`) is passed through, a string becomes a text
+ * block, `undefined` becomes an empty result, and anything else is returned
+ * as `structuredContent` (plain objects) plus a JSON text block.
+ */
+type AgentToolHandler = (args: Record<string, any>, context: ToolCallContext) => unknown | Promise<unknown>;
+interface AgentTool extends McpToolDefinition {
+    handler: AgentToolHandler;
+}
+/**
+ * A source of tools, typically one per mounted editor, spreadsheet or canvas.
+ */
+interface AgentToolProvider {
+    /** Unique id within a registry, e.g. `doc-1`. Used as the namespace on collisions. */
+    id: string;
+    /** Always prefix this provider's tools with `<namespace>__`. */
+    namespace?: 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. */
+    subscribe?: (notify: () => void) => () => void;
+}
+type ToolErrorCode = 'unknown_tool' | 'invalid_arguments' | 'tool_failed';
+/** Structured error carried in `structuredContent.error` of a failed call. */
+interface ToolCallError {
+    code: ToolErrorCode;
+    message: string;
+    tool: string;
+    details?: SchemaValidationError[];
+}
+declare class ToolRegistryError extends Error {
+    readonly code: 'duplicate_provider' | 'name_collision' | 'invalid_tool';
+    constructor(code: ToolRegistryError['code'], message: string);
+}
+interface ToolRegistryOptions {
+    /**
+     * What to do when two providers contribute the same tool name:
+     * `namespace` (default) exposes every colliding tool as `<providerId>__<name>`;
+     * `error` makes `register` throw.
+     */
+    onCollision?: 'namespace' | 'error';
+    /** Coalescing window for `listChanged` notifications in ms (default 0: same tick). */
+    listChangedDelayMs?: number;
+    /** Validate arguments against `inputSchema` before calling handlers (default `true`). */
+    validateArguments?: boolean;
+}
+/** Separator between namespace and tool name; valid in MCP and LLM tool-name charsets. */
+declare const TOOL_NAMESPACE_SEPARATOR = "__";
+/** Normalizes a handler's return value into an MCP `tools/call` result. */
+declare function toToolResult(value: unknown): McpToolResult;
+/**
+ * Transport-agnostic registry of agent tools contributed by live providers.
+ *
+ * `listTools()` and `callTool()` return MCP `tools/list` / `tools/call`
+ * result shapes, and `onListChanged` fires (coalesced) whenever the exposed
+ * tool list changes, mirroring MCP's `notifications/tools/list_changed`, so an
+ * MCP server can be a thin wrapper around it.
+ */
+declare class ToolRegistry {
+    /** MCP server capabilities this registry supports. */
+    readonly capabilities: {
+        readonly tools: {
+            readonly listChanged: true;
+        };
+    };
+    private readonly entries;
+    private readonly listeners;
+    private readonly options;
+    private timer;
+    private lastSignature;
+    constructor(options?: ToolRegistryOptions);
+    /**
+     * Registers a provider and returns a function that unregisters it.
+     * Throws a {@link ToolRegistryError} for a duplicate provider id, an invalid
+     * tool name, or (with `onCollision: 'error'`) a tool name collision.
+     */
+    register(provider: AgentToolProvider): () => void;
+    /** Removes a provider by id or instance. Returns whether it was registered. */
+    unregister(providerOrId: string | AgentToolProvider): boolean;
+    /** Registered provider ids in registration order. */
+    providerIds(): string[];
+    /**
+     * Resolves exposed names. Tools are ordered by provider registration, then
+     * by their order within the provider.
+     */
+    private resolve;
+    /** MCP `tools/list` result for the current providers. */
+    listTools(): McpListToolsResult;
+    /** Whether a tool with this exposed name exists. */
+    hasTool(name: string): boolean;
+    /** Looks up a tool definition by exposed name. */
+    getTool(name: string): McpToolDefinition | undefined;
+    /**
+     * Calls a tool by exposed name and returns an MCP `tools/call` result.
+     * Never rejects: unknown tools, invalid arguments and handler errors come
+     * back as `isError: true` results with a {@link ToolCallError} in
+     * `structuredContent.error` (MCP transports may map `unknown_tool` to a
+     * JSON-RPC `-32602` error instead).
+     */
+    callTool(name: string, args?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<McpToolResult>;
+    /**
+     * Subscribes to tool-list changes. Notifications are coalesced: many
+     * registrations or provider signals within the delay window produce one
+     * call, and none if the exposed list ends up unchanged (e.g. a provider
+     * unmounted and remounted). Returns an unsubscribe function.
+     */
+    onListChanged(listener: (tools: McpToolDefinition[]) => void): () => void;
+    /** Schedules a coalesced `listChanged` check; providers may call it directly. */
+    notifyListChanged(): void;
+    /** Runs a pending `listChanged` check immediately. */
+    flush(): void;
+    private signature;
+    /** Unregisters every provider and listener and cancels pending notifications. */
+    dispose(): void;
+}
+declare function createToolRegistry(options?: ToolRegistryOptions): ToolRegistry;
+
+interface ToolProviderOptions {
+    /** Provider id (unique per registry). */
+    id: string;
+    /** Always prefix tool names with `<namespace>__`. */
+    namespace?: string;
+}
+/** A TipTap editor, or anything exposing one as `.editor` (e.g. `EditorController`). */
+type RichTextToolTarget = Editor | {
+    editor: Editor;
+};
+/**
+ * Tools for a mounted rich-text editor: `get_text` (always), plus
+ * `insert_text` and `replace_selection` while the editor is editable.
+ * Positions are ProseMirror document positions (as in `selection.from`).
+ * The provider re-announces its tool list when editability changes and
+ * exposes no tools once the editor is destroyed.
+ */
+declare function createRichTextToolProvider(target: RichTextToolTarget, options: ToolProviderOptions): AgentToolProvider;
+/**
+ * Tools for a spreadsheet controller: `get_range` (A1 notation, values and raw
+ * input) and `set_cell` (raw input; values starting with `=` are formulas).
+ */
+declare function createSpreadsheetToolProvider(controller: SpreadsheetController, options: ToolProviderOptions): AgentToolProvider;
+interface EditorMcpToolProviderOptions<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge> extends ToolProviderOptions {
+    /** Current editor / canvas state. */
+    getSnapshot: () => EditorSnapshot<TNode, TEdge>;
+    /** Applies planned steps (e.g. via your canvas runes / editor controller). */
+    applySteps: (steps: AgentStep<TNode, TEdge>[]) => void | Promise<void>;
+    /** Optional `view_editor` implementation; the tool is only exposed when provided. */
+    captureView?: (args: {
+        scope?: 'viewport' | 'canvas';
+        format?: 'jpeg' | 'png';
+        maxEdge?: number;
+    }) => Promise<{
+        data: string;
+        mimeType: string;
+    }> | {
+        data: string;
+        mimeType: string;
+    };
+    /** Options forwarded to the planner. */
+    plannerOptions?: Parameters<typeof planToolCall>[3];
+}
+/**
+ * Exposes the static MCP tools from `tools.ts` (`get_editor_state`,
+ * `edit_canvas`, `edit_prompt`, `view_editor`) through a `ToolRegistry`,
+ * planning edits with `planToolCall` and handing the steps to `applySteps`.
+ */
+declare function createEditorMcpToolProvider<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(options: EditorMcpToolProviderOptions<TNode, TEdge>): AgentToolProvider;
+
+export { type AgentCommand, type AgentPresence, type AgentStep, type AgentTool, type AgentToolHandler, type AgentToolProvider, EDITOR_MCP_TOOLS, EXPORT_EXCLUDED_SELECTORS, type EditorMcpToolProviderOptions, type EditorSnapshot, type JsonSchema, type JsonSchemaType, MCP_TOOL_EDIT_CANVAS, MCP_TOOL_EDIT_PROMPT, MCP_TOOL_GET_EDITOR_STATE, MCP_TOOL_VIEW_EDITOR, type McpListToolsResult, type McpToolContent, type McpToolDefinition, type McpToolResult, type RichTextToolTarget, type SchemaValidationError, TOOL_NAMESPACE_SEPARATOR, type ToolCallContext, type ToolCallError, type ToolErrorCode, type ToolProviderOptions, ToolRegistry, ToolRegistryError, type ToolRegistryOptions, createEditorMcpToolProvider, createRichTextToolProvider, createSpreadsheetToolProvider, createToolRegistry, normalizeSide, planAgentCommand, planToolCall, toToolResult, toolCallToAgentCommand, validateJsonSchema };