@pixerate/editor 0.140.4 → 0.142.1

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/script.d.cts

@@ -0,0 +1,77 @@
+import type { AgentPlayback } from './playback.cjs';
+import type { PresenceActorInfo } from './presence.cjs';
+import type { McpToolResult, ToolSource } from './registry.cjs';
+/** What earlier steps returned, for the arguments of later ones. */
+export interface ToolScriptContext {
+    /** Results kept with `as`, by name (a tool's `structuredContent`, or its JSON text). */
+    results: Record<string, any>;
+    /** The result of the step before. */
+    last: any;
+}
+export interface ToolScriptStep {
+    /** What the agent tells the user before it acts (the transcript and the cursor's bubble). */
+    say?: string;
+    /** Tool to call (an exposed registry name such as `sheet__set_range`). */
+    tool?: string;
+    /** The tool's arguments, or a function of earlier results that returns them. */
+    args?: Record<string, unknown> | ((ctx: ToolScriptContext) => Record<string, unknown>);
+    /** Keep the result under this name in `ctx.results`. */
+    as?: string;
+}
+export interface ToolScript {
+    id: string;
+    /** The user's request, as they would type it. */
+    prompt: string;
+    steps: ToolScriptStep[];
+}
+export type ToolScriptEvent = {
+    type: 'say';
+    step: number;
+    text: string;
+} | {
+    type: 'call';
+    step: number;
+    tool: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'result';
+    step: number;
+    tool: string;
+    result: McpToolResult;
+} | {
+    type: 'error';
+    step: number;
+    message: string;
+} | {
+    type: 'done';
+    ok: boolean;
+    stopped: boolean;
+};
+/** Speed and stop for a run in progress (`speed: Infinity` finishes without pauses). */
+export interface ToolScriptControl {
+    speed: number;
+    stopped: boolean;
+}
+export interface RunToolScriptOptions {
+    /** Shows each note on the agent's cursor (`playback.say`) and stops its performance on stop. */
+    playback?: AgentPlayback | null;
+    /** The actor the calls are made as (its own cursor and queue). */
+    actor?: PresenceActorInfo;
+    onEvent?: (event: ToolScriptEvent) => void;
+    control?: ToolScriptControl;
+    /** Waits `ms` (already scaled by the speed); real timers by default. */
+    wait?: (ms: number) => Promise<void>;
+}
+/** A tool result as a plain value: its `structuredContent`, else its first text block (parsed when JSON). */
+export declare function toolResultValue(result: McpToolResult): any;
+/** The error message of a failed tool result. */
+export declare function toolResultError(result: McpToolResult): string;
+/**
+ * Plays `script` against `source` (a `ToolRegistry` or a view of one): each step's note, then its
+ * tool call. Stops at the first failure (a tool error or arguments that cannot be built), like an
+ * agent that has to rethink, and resolves with the results kept so far.
+ */
+export declare function runToolScript(source: ToolSource, script: ToolScript, options?: RunToolScriptOptions): Promise<{
+    ok: boolean;
+    ctx: ToolScriptContext;
+}>;

package/dist/tools/script.d.ts

@@ -0,0 +1,77 @@
+import type { AgentPlayback } from './playback.js';
+import type { PresenceActorInfo } from './presence.js';
+import type { McpToolResult, ToolSource } from './registry.js';
+/** What earlier steps returned, for the arguments of later ones. */
+export interface ToolScriptContext {
+    /** Results kept with `as`, by name (a tool's `structuredContent`, or its JSON text). */
+    results: Record<string, any>;
+    /** The result of the step before. */
+    last: any;
+}
+export interface ToolScriptStep {
+    /** What the agent tells the user before it acts (the transcript and the cursor's bubble). */
+    say?: string;
+    /** Tool to call (an exposed registry name such as `sheet__set_range`). */
+    tool?: string;
+    /** The tool's arguments, or a function of earlier results that returns them. */
+    args?: Record<string, unknown> | ((ctx: ToolScriptContext) => Record<string, unknown>);
+    /** Keep the result under this name in `ctx.results`. */
+    as?: string;
+}
+export interface ToolScript {
+    id: string;
+    /** The user's request, as they would type it. */
+    prompt: string;
+    steps: ToolScriptStep[];
+}
+export type ToolScriptEvent = {
+    type: 'say';
+    step: number;
+    text: string;
+} | {
+    type: 'call';
+    step: number;
+    tool: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'result';
+    step: number;
+    tool: string;
+    result: McpToolResult;
+} | {
+    type: 'error';
+    step: number;
+    message: string;
+} | {
+    type: 'done';
+    ok: boolean;
+    stopped: boolean;
+};
+/** Speed and stop for a run in progress (`speed: Infinity` finishes without pauses). */
+export interface ToolScriptControl {
+    speed: number;
+    stopped: boolean;
+}
+export interface RunToolScriptOptions {
+    /** Shows each note on the agent's cursor (`playback.say`) and stops its performance on stop. */
+    playback?: AgentPlayback | null;
+    /** The actor the calls are made as (its own cursor and queue). */
+    actor?: PresenceActorInfo;
+    onEvent?: (event: ToolScriptEvent) => void;
+    control?: ToolScriptControl;
+    /** Waits `ms` (already scaled by the speed); real timers by default. */
+    wait?: (ms: number) => Promise<void>;
+}
+/** A tool result as a plain value: its `structuredContent`, else its first text block (parsed when JSON). */
+export declare function toolResultValue(result: McpToolResult): any;
+/** The error message of a failed tool result. */
+export declare function toolResultError(result: McpToolResult): string;
+/**
+ * Plays `script` against `source` (a `ToolRegistry` or a view of one): each step's note, then its
+ * tool call. Stops at the first failure (a tool error or arguments that cannot be built), like an
+ * agent that has to rethink, and resolves with the results kept so far.
+ */
+export declare function runToolScript(source: ToolSource, script: ToolScript, options?: RunToolScriptOptions): Promise<{
+    ok: boolean;
+    ctx: ToolScriptContext;
+}>;

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;