@pixerate/editor 0.140.4 → 0.141.0

package/dist/tools/registry.d.ts

@@ -1,5 +1,7 @@
 import { type JsonSchema, type SchemaValidationError } from './schema.js';
 import { ToolRegistryView, type ToolViewOptions } from './view.js';
+import type { ToolPlanner } from './playback.js';
+import type { PresenceActorInfo } from './presence.js';
 /**
  * MCP-shaped tool definition, as returned by `tools/list`.
  */
@@ -47,6 +49,14 @@ export interface ToolCallContext {
     /** Id of the provider that owns the tool. */
     providerId: string;
     signal?: AbortSignal;
+    /** Who is calling (an MCP client, a scripted agent), for agent playback's cursors and queues. */
+    actor?: PresenceActorInfo;
+}
+/** Options for `callTool`. */
+export interface ToolCallOptions {
+    signal?: AbortSignal;
+    /** Who is calling; agent playback gives each actor its own cursor and queue. */
+    actor?: PresenceActorInfo;
 }
 /**
  * Handler return values are normalized into an {@link McpToolResult}: a full
@@ -57,6 +67,17 @@ export interface ToolCallContext {
 export type AgentToolHandler = (args: Record<string, any>, context: ToolCallContext) => unknown | Promise<unknown>;
 export interface AgentTool extends McpToolDefinition {
     handler: AgentToolHandler;
+    /**
+     * How agent playback acts this tool out (see `createAgentPlayback`): `'self'` when the
+     * handler drives its own cursor (a director), `false` to never play it. Default: play it
+     * from `plan`, or from the ids in its arguments and result.
+     */
+    playback?: 'self' | false;
+    /**
+     * Pure planner for agent playback: the cursor steps (surface coordinates) that act out a
+     * call with these arguments, given the state before the call. Not sent to clients.
+     */
+    plan?: ToolPlanner;
 }
 /**
  * A source of tools, typically one per mounted editor, spreadsheet or canvas.
@@ -83,7 +104,23 @@ export interface AgentToolProvider {
     tools: readonly AgentTool[] | (() => readonly AgentTool[]);
     /** Lets the provider signal that its tool list changed; returns an unsubscribe function. */
     subscribe?: (notify: () => void) => () => void;
+    /** The playback surface its calls are acted out on (default: the provider id). */
+    playbackSurface?: string;
 }
+/** A tool call as a {@link ToolMiddleware} sees it (arguments already validated). */
+export interface ToolMiddlewareCall {
+    /** The exposed (possibly namespaced) name. */
+    name: string;
+    tool: AgentTool;
+    provider: AgentToolProvider;
+    args: Record<string, any>;
+    context: ToolCallContext;
+}
+/**
+ * Wraps every tool call of a registry (`registry.use`): call `next()` to run the handler (or
+ * the next middleware) and return its value. A throw becomes an `isError` result.
+ */
+export type ToolMiddleware = (call: ToolMiddlewareCall, next: () => Promise<unknown>) => Promise<unknown>;
 export type ToolErrorCode = 'unknown_tool' | 'invalid_arguments' | 'tool_failed';
 /** Structured error carried in `structuredContent.error` of a failed call. */
 export interface ToolCallError {
@@ -152,9 +189,7 @@ export interface ToolSource {
     listTools(): McpListToolsResult;
     hasTool(name: string): boolean;
     getTool(name: string): McpToolDefinition | undefined;
-    callTool(name: string, args?: Record<string, unknown>, options?: {
-        signal?: AbortSignal;
-    }): Promise<McpToolResult>;
+    callTool(name: string, args?: Record<string, unknown>, options?: ToolCallOptions): Promise<McpToolResult>;
     onListChanged(listener: (tools: McpToolDefinition[]) => void): () => void;
     /** The toolsets behind `listTools()`, in listing order. */
     toolsets(): ToolsetInfo[];
@@ -182,6 +217,7 @@ export declare class ToolRegistry implements ToolSource {
     };
     private readonly entries;
     private readonly listeners;
+    private readonly middleware;
     private readonly options;
     private timer;
     private lastSignature;
@@ -194,6 +230,11 @@ export declare class ToolRegistry implements ToolSource {
     register(provider: AgentToolProvider): () => void;
     /** Removes a provider by id or instance. Returns whether it was registered. */
     unregister(providerOrId: string | AgentToolProvider): boolean;
+    /**
+     * Adds a middleware that wraps every tool call (first added runs outermost), e.g. agent
+     * playback's `playback.middleware`. Returns a function that removes it.
+     */
+    use(middleware: ToolMiddleware): () => void;
     /** Registered provider ids in registration order. */
     providerIds(): string[];
     /**
@@ -222,9 +263,7 @@ export declare class ToolRegistry implements ToolSource {
      * `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>;
+    callTool(name: string, args?: Record<string, unknown>, options?: ToolCallOptions): Promise<McpToolResult>;
     /**
      * Subscribes to tool-list changes. Notifications are coalesced: many
      * registrations or provider signals within the delay window produce one

package/dist/tools/view.d.cts

@@ -1,4 +1,4 @@
-import type { McpListToolsResult, McpToolDefinition, McpToolResult, ToolSource, ToolsetInfo } from './registry.cjs';
+import type { McpListToolsResult, McpToolDefinition, McpToolResult, ToolCallOptions, 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). */
@@ -76,9 +76,7 @@ export declare class ToolRegistryView implements ToolSource {
     listTools(): McpListToolsResult;
     hasTool(name: string): boolean;
     getTool(name: string): McpToolDefinition | undefined;
-    callTool(name: string, args?: Record<string, unknown>, options?: {
-        signal?: AbortSignal;
-    }): Promise<McpToolResult>;
+    callTool(name: string, args?: Record<string, unknown>, options?: ToolCallOptions): Promise<McpToolResult>;
     onListChanged(listener: (tools: McpToolDefinition[]) => void): () => void;
     /** Stops following the source and drops every listener. */
     dispose(): void;

package/dist/tools/view.d.ts

@@ -1,4 +1,4 @@
-import type { McpListToolsResult, McpToolDefinition, McpToolResult, ToolSource, ToolsetInfo } from './registry.js';
+import type { McpListToolsResult, McpToolDefinition, McpToolResult, ToolCallOptions, 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). */
@@ -76,9 +76,7 @@ export declare class ToolRegistryView implements ToolSource {
     listTools(): McpListToolsResult;
     hasTool(name: string): boolean;
     getTool(name: string): McpToolDefinition | undefined;
-    callTool(name: string, args?: Record<string, unknown>, options?: {
-        signal?: AbortSignal;
-    }): Promise<McpToolResult>;
+    callTool(name: string, args?: Record<string, unknown>, options?: ToolCallOptions): Promise<McpToolResult>;
     onListChanged(listener: (tools: McpToolDefinition[]) => void): () => void;
     /** Stops following the source and drops every listener. */
     dispose(): void;