@pixerate/editor 0.140.4 → 0.142.1

package/dist/tools/playback.d.cts

@@ -0,0 +1,205 @@
+import type { ToolMiddleware, ToolRegistry } from './registry.cjs';
+import { type PresenceActorInfo, type PresenceClock, type PresenceStore } from './presence.cjs';
+export interface PlaybackPoint {
+    x: number;
+    y: number;
+}
+export interface PlaybackRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Something a surface can find: `{ kind: 'node', id }`, `{ kind: 'layer', id }`, a cell range
+ * `{ kind: 'cell', id: 'B7:G7' }` or one of the editor's own controls `{ kind: 'control', id: 'title' }`.
+ */
+export interface PlaybackRef {
+    kind: string;
+    id: string;
+}
+/** One thing the cursor does. Points and rectangles are in the surface's own coordinates. */
+export type PlaybackStep = {
+    type: 'move';
+    to: PlaybackPoint;
+    ms?: number;
+}
+/** Glide to whatever the surface locates for `ref`, and ring it. Skipped when nothing is found. */
+ | {
+    type: 'target';
+    ref: PlaybackRef;
+    ms?: number;
+} | {
+    type: 'focus';
+    rect: PlaybackRect | null;
+} | {
+    type: 'say';
+    text: string;
+    ms?: number;
+} | {
+    type: 'press';
+} | {
+    type: 'release';
+}
+/** Move with the button down (the cursor only; the change lands at `commit`). */
+ | {
+    type: 'drag';
+    to: PlaybackPoint;
+    ms?: number;
+} | {
+    type: 'type';
+    text: string;
+    ms?: number;
+} | {
+    type: 'wait';
+    ms: number;
+}
+/**
+ * Bring a part of the editor into view (a panel or tab): glide to what `ref` locates, click it,
+ * and let the surface's `open(ref)` show it. Skipped when the surface has no `open`.
+ */
+ | {
+    type: 'open';
+    ref: PlaybackRef;
+    ms?: number;
+}
+/** The handler runs here, exactly once (appended when a plan leaves it out). */
+ | {
+    type: 'commit';
+};
+export interface PlaybackPlanResult {
+    steps: PlaybackStep[];
+    /** The surface to play on, when it is not the provider's (e.g. commands of one editor). */
+    surface?: string;
+    /** Treat the call as a read: a glance, no press and no undo gesture. */
+    readOnly?: boolean;
+}
+export type PlaybackPlan = PlaybackStep[] | PlaybackPlanResult | null | undefined;
+/** What a planner may read besides the arguments. */
+export interface PlaybackPlanState {
+    /** The surface the provider plays on, if one is attached. */
+    surfaceId: string | null;
+    /** Finds a ref on that surface (surface coordinates), or null. */
+    locate(ref: PlaybackRef): PlaybackRect | null;
+}
+/**
+ * A pure function from a call's validated arguments (and the state before the call) to the
+ * cursor steps that act it out. Ids the call creates do not exist yet: plan toward where the
+ * change lands. A throw, `null` or no steps falls back to the ids in the arguments.
+ */
+export type ToolPlanner = (args: Record<string, any>, state: PlaybackPlanState) => PlaybackPlan;
+/** An editor's surface, attached by its React / Svelte component while it is on screen. */
+export interface PlaybackSurface {
+    /** The cursors on this surface; the editor's presence layer draws it. */
+    presence: PresenceStore;
+    /** Where `ref` is, in surface coordinates. */
+    locate?(ref: PlaybackRef): PlaybackRect | null;
+    /** The visible part of the surface (surface coordinates), where a cursor enters. */
+    bounds?(): PlaybackRect | null;
+    /** Whether the surface is on screen now (default true). Hidden surfaces play instantly. */
+    visible?(): boolean;
+    /** Surface → viewport (client pixels) and back, so a cursor can move between surfaces. */
+    toViewport?(point: PlaybackPoint): PlaybackPoint;
+    fromViewport?(point: PlaybackPoint): PlaybackPoint;
+    /** Group what a call changes into one undo step (optional; most handlers already do). */
+    beginGesture?(key: string): void;
+    endGesture?(): void;
+    /** Bring the surface on screen (switch to its tab) before playing. */
+    reveal?(): void | Promise<void>;
+    /** Show a part of the editor (a panel or tab) for an `open` step, e.g. by clicking its tab. */
+    open?(ref: PlaybackRef): void | Promise<void>;
+    /** The kind of a bare `id` / `ids` argument on this surface (e.g. `node`, `vector`). */
+    defaultKind?: string;
+}
+export type PlaybackReads = 'glance' | 'skip' | 'play';
+export interface AgentPlaybackOptions {
+    clock?: PresenceClock;
+    /** 1 = natural pace, 2 = twice as fast, `Infinity` = no animation (default 1). */
+    speed?: number;
+    /** Read-only tools: `glance` moves to their target only (default), `skip` doesn't, `play` plays them like writes. */
+    reads?: PlaybackReads;
+    /** Hide a cursor this long after its actor's last call (ms, default 1500; 0 keeps it). */
+    linger?: number;
+    /** The actor for calls that name none (default `{ id: 'agent', name: 'Agent' }`). */
+    actor?: PresenceActorInfo;
+}
+/** A step as played, for tests (`playback.record()`). */
+export interface PlaybackRecord {
+    actor: string;
+    surface: string;
+    tool: string;
+    step: PlaybackStep;
+}
+/**
+ * The things a call's arguments name, by convention: `id` / `ids` (the surface's default kind),
+ * `nodeId(s)`, `layerId(s)`, `clipId(s)`, `trackId(s)`, `seriesId`, `parameterId`, `keyframeId`,
+ * `range` / `cell` (A1, kind `cell`), and the same inside a command's `params`.
+ */
+export declare function playbackRefsFromArgs(args: unknown, defaultKind?: string): PlaybackRef[];
+/**
+ * The things a write's result names: `id`, `ids`, `node.id`, `layerId`, `layer.id`, `created` (a list, or `{ nodes, edges }`),
+ * also inside a command result's `result`. Used to point at what a call created.
+ */
+export declare function playbackRefsFromResult(value: unknown, defaultKind?: string): PlaybackRef[];
+/**
+ * The default performance: visit what the arguments name (at most 8), press, commit. Bare ids get
+ * kind `item` unless `defaultKind` is given; a surface reads `item` as its own `defaultKind`.
+ */
+export declare function derivePlaybackSteps(args: unknown, defaultKind?: string): PlaybackStep[];
+/** Time to read a note: about 15 characters a second, between 0.6 s and 2.2 s. */
+export declare function readingTime(text: string): number;
+/** Smallest rectangle around `rects`, or null. */
+export declare function unionRects(rects: readonly (PlaybackRect | null | undefined)[]): PlaybackRect | null;
+/**
+ * Acts out tool calls on attached surfaces. Install it on a registry (`registry.use(playback.middleware)`
+ * or `playback.install(registry)`); editors attach their surfaces while mounted. Results never change:
+ * a call returns the same value or error with or without playback.
+ */
+export declare class AgentPlayback {
+    /** 1 = natural pace; `Infinity` plays nothing (calls run instantly). Takes effect on the next step. */
+    speed: number;
+    reads: PlaybackReads;
+    readonly clock: PresenceClock;
+    private readonly linger;
+    private readonly defaultActor;
+    private readonly surfaces;
+    private readonly actors;
+    private readonly recordings;
+    private readonly installed;
+    private readonly listeners;
+    private generation;
+    private running;
+    private calls;
+    constructor(options?: AgentPlaybackOptions);
+    /** The registry middleware that plays each call. */
+    readonly middleware: ToolMiddleware;
+    /** Adds the middleware to `registry` once (later calls with the same registry do nothing). */
+    install(registry: ToolRegistry): void;
+    /** Whether a performance is playing now (e.g. to make the editor read-only meanwhile). */
+    get active(): boolean;
+    /** Called when `active` changes. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Attaches a surface under a provider id (or the id providers name as `playbackSurface`). */
+    attach(id: string, surface: PlaybackSurface): () => void;
+    /** The surface attached under `id`. */
+    surface(id: string): PlaybackSurface | undefined;
+    /** Shows `text` in the actor's bubble on the surface it last worked on (until its next step). */
+    say(text: string, options?: {
+        actor?: PresenceActorInfo;
+    }): void;
+    /** Finishes every running performance at once (the calls still run and keep their results). */
+    stop(): void;
+    /** Collects every step played from now on (for tests). */
+    record(): PlaybackRecord[];
+    private actorState;
+    private enqueue;
+    private surfaceFor;
+    private perform;
+    private play;
+    private scheduleLinger;
+    private step;
+    /** Glides along a slight arc with ease-out, by elapsed time (fewer frames in a throttled tab, never longer). */
+    private glide;
+}
+/** An {@link AgentPlayback}: install it on a registry and attach editor surfaces to see calls played. */
+export declare function createAgentPlayback(options?: AgentPlaybackOptions): AgentPlayback;

package/dist/tools/playback.d.ts

@@ -0,0 +1,205 @@
+import type { ToolMiddleware, ToolRegistry } from './registry.js';
+import { type PresenceActorInfo, type PresenceClock, type PresenceStore } from './presence.js';
+export interface PlaybackPoint {
+    x: number;
+    y: number;
+}
+export interface PlaybackRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Something a surface can find: `{ kind: 'node', id }`, `{ kind: 'layer', id }`, a cell range
+ * `{ kind: 'cell', id: 'B7:G7' }` or one of the editor's own controls `{ kind: 'control', id: 'title' }`.
+ */
+export interface PlaybackRef {
+    kind: string;
+    id: string;
+}
+/** One thing the cursor does. Points and rectangles are in the surface's own coordinates. */
+export type PlaybackStep = {
+    type: 'move';
+    to: PlaybackPoint;
+    ms?: number;
+}
+/** Glide to whatever the surface locates for `ref`, and ring it. Skipped when nothing is found. */
+ | {
+    type: 'target';
+    ref: PlaybackRef;
+    ms?: number;
+} | {
+    type: 'focus';
+    rect: PlaybackRect | null;
+} | {
+    type: 'say';
+    text: string;
+    ms?: number;
+} | {
+    type: 'press';
+} | {
+    type: 'release';
+}
+/** Move with the button down (the cursor only; the change lands at `commit`). */
+ | {
+    type: 'drag';
+    to: PlaybackPoint;
+    ms?: number;
+} | {
+    type: 'type';
+    text: string;
+    ms?: number;
+} | {
+    type: 'wait';
+    ms: number;
+}
+/**
+ * Bring a part of the editor into view (a panel or tab): glide to what `ref` locates, click it,
+ * and let the surface's `open(ref)` show it. Skipped when the surface has no `open`.
+ */
+ | {
+    type: 'open';
+    ref: PlaybackRef;
+    ms?: number;
+}
+/** The handler runs here, exactly once (appended when a plan leaves it out). */
+ | {
+    type: 'commit';
+};
+export interface PlaybackPlanResult {
+    steps: PlaybackStep[];
+    /** The surface to play on, when it is not the provider's (e.g. commands of one editor). */
+    surface?: string;
+    /** Treat the call as a read: a glance, no press and no undo gesture. */
+    readOnly?: boolean;
+}
+export type PlaybackPlan = PlaybackStep[] | PlaybackPlanResult | null | undefined;
+/** What a planner may read besides the arguments. */
+export interface PlaybackPlanState {
+    /** The surface the provider plays on, if one is attached. */
+    surfaceId: string | null;
+    /** Finds a ref on that surface (surface coordinates), or null. */
+    locate(ref: PlaybackRef): PlaybackRect | null;
+}
+/**
+ * A pure function from a call's validated arguments (and the state before the call) to the
+ * cursor steps that act it out. Ids the call creates do not exist yet: plan toward where the
+ * change lands. A throw, `null` or no steps falls back to the ids in the arguments.
+ */
+export type ToolPlanner = (args: Record<string, any>, state: PlaybackPlanState) => PlaybackPlan;
+/** An editor's surface, attached by its React / Svelte component while it is on screen. */
+export interface PlaybackSurface {
+    /** The cursors on this surface; the editor's presence layer draws it. */
+    presence: PresenceStore;
+    /** Where `ref` is, in surface coordinates. */
+    locate?(ref: PlaybackRef): PlaybackRect | null;
+    /** The visible part of the surface (surface coordinates), where a cursor enters. */
+    bounds?(): PlaybackRect | null;
+    /** Whether the surface is on screen now (default true). Hidden surfaces play instantly. */
+    visible?(): boolean;
+    /** Surface → viewport (client pixels) and back, so a cursor can move between surfaces. */
+    toViewport?(point: PlaybackPoint): PlaybackPoint;
+    fromViewport?(point: PlaybackPoint): PlaybackPoint;
+    /** Group what a call changes into one undo step (optional; most handlers already do). */
+    beginGesture?(key: string): void;
+    endGesture?(): void;
+    /** Bring the surface on screen (switch to its tab) before playing. */
+    reveal?(): void | Promise<void>;
+    /** Show a part of the editor (a panel or tab) for an `open` step, e.g. by clicking its tab. */
+    open?(ref: PlaybackRef): void | Promise<void>;
+    /** The kind of a bare `id` / `ids` argument on this surface (e.g. `node`, `vector`). */
+    defaultKind?: string;
+}
+export type PlaybackReads = 'glance' | 'skip' | 'play';
+export interface AgentPlaybackOptions {
+    clock?: PresenceClock;
+    /** 1 = natural pace, 2 = twice as fast, `Infinity` = no animation (default 1). */
+    speed?: number;
+    /** Read-only tools: `glance` moves to their target only (default), `skip` doesn't, `play` plays them like writes. */
+    reads?: PlaybackReads;
+    /** Hide a cursor this long after its actor's last call (ms, default 1500; 0 keeps it). */
+    linger?: number;
+    /** The actor for calls that name none (default `{ id: 'agent', name: 'Agent' }`). */
+    actor?: PresenceActorInfo;
+}
+/** A step as played, for tests (`playback.record()`). */
+export interface PlaybackRecord {
+    actor: string;
+    surface: string;
+    tool: string;
+    step: PlaybackStep;
+}
+/**
+ * The things a call's arguments name, by convention: `id` / `ids` (the surface's default kind),
+ * `nodeId(s)`, `layerId(s)`, `clipId(s)`, `trackId(s)`, `seriesId`, `parameterId`, `keyframeId`,
+ * `range` / `cell` (A1, kind `cell`), and the same inside a command's `params`.
+ */
+export declare function playbackRefsFromArgs(args: unknown, defaultKind?: string): PlaybackRef[];
+/**
+ * The things a write's result names: `id`, `ids`, `node.id`, `layerId`, `layer.id`, `created` (a list, or `{ nodes, edges }`),
+ * also inside a command result's `result`. Used to point at what a call created.
+ */
+export declare function playbackRefsFromResult(value: unknown, defaultKind?: string): PlaybackRef[];
+/**
+ * The default performance: visit what the arguments name (at most 8), press, commit. Bare ids get
+ * kind `item` unless `defaultKind` is given; a surface reads `item` as its own `defaultKind`.
+ */
+export declare function derivePlaybackSteps(args: unknown, defaultKind?: string): PlaybackStep[];
+/** Time to read a note: about 15 characters a second, between 0.6 s and 2.2 s. */
+export declare function readingTime(text: string): number;
+/** Smallest rectangle around `rects`, or null. */
+export declare function unionRects(rects: readonly (PlaybackRect | null | undefined)[]): PlaybackRect | null;
+/**
+ * Acts out tool calls on attached surfaces. Install it on a registry (`registry.use(playback.middleware)`
+ * or `playback.install(registry)`); editors attach their surfaces while mounted. Results never change:
+ * a call returns the same value or error with or without playback.
+ */
+export declare class AgentPlayback {
+    /** 1 = natural pace; `Infinity` plays nothing (calls run instantly). Takes effect on the next step. */
+    speed: number;
+    reads: PlaybackReads;
+    readonly clock: PresenceClock;
+    private readonly linger;
+    private readonly defaultActor;
+    private readonly surfaces;
+    private readonly actors;
+    private readonly recordings;
+    private readonly installed;
+    private readonly listeners;
+    private generation;
+    private running;
+    private calls;
+    constructor(options?: AgentPlaybackOptions);
+    /** The registry middleware that plays each call. */
+    readonly middleware: ToolMiddleware;
+    /** Adds the middleware to `registry` once (later calls with the same registry do nothing). */
+    install(registry: ToolRegistry): void;
+    /** Whether a performance is playing now (e.g. to make the editor read-only meanwhile). */
+    get active(): boolean;
+    /** Called when `active` changes. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Attaches a surface under a provider id (or the id providers name as `playbackSurface`). */
+    attach(id: string, surface: PlaybackSurface): () => void;
+    /** The surface attached under `id`. */
+    surface(id: string): PlaybackSurface | undefined;
+    /** Shows `text` in the actor's bubble on the surface it last worked on (until its next step). */
+    say(text: string, options?: {
+        actor?: PresenceActorInfo;
+    }): void;
+    /** Finishes every running performance at once (the calls still run and keep their results). */
+    stop(): void;
+    /** Collects every step played from now on (for tests). */
+    record(): PlaybackRecord[];
+    private actorState;
+    private enqueue;
+    private surfaceFor;
+    private perform;
+    private play;
+    private scheduleLinger;
+    private step;
+    /** Glides along a slight arc with ease-out, by elapsed time (fewer frames in a throttled tab, never longer). */
+    private glide;
+}
+/** An {@link AgentPlayback}: install it on a registry and attach editor surfaces to see calls played. */
+export declare function createAgentPlayback(options?: AgentPlaybackOptions): AgentPlayback;

package/dist/tools/presence.d.cts

@@ -0,0 +1,82 @@
+export interface PresenceActor {
+    id: string;
+    name: string;
+    color: string;
+    /** Cursor position in the surface's own coordinates (scene / canvas). */
+    x: number;
+    y: number;
+    /** The button is down (dragging). */
+    pressed: boolean;
+    /** A short note shown next to the cursor (what the agent is doing). */
+    message?: string;
+    /** A rectangle (surface coordinates) the agent is working on, drawn as a highlight ring. */
+    focus?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface PresenceState {
+    actors: readonly PresenceActor[];
+}
+export declare const PRESENCE_COLORS: readonly string[];
+/** Cursor positions and notes of agents acting on a surface, for an overlay. */
+export declare class PresenceStore {
+    private state;
+    private readonly listeners;
+    getState: () => PresenceState;
+    subscribe: (listener: (state: PresenceState) => void) => (() => void);
+    /** The actor with `id`, if it is on the surface. */
+    get(id: string): PresenceActor | undefined;
+    /** Adds or changes an actor. */
+    set(actor: Pick<PresenceActor, 'id'> & Partial<PresenceActor>): void;
+    remove(id: string): void;
+}
+/** Time for performances: real timers, or an instant clock for tests and recordings. */
+export interface PresenceClock {
+    now(): number;
+    wait(ms: number): Promise<void>;
+}
+export declare const realPresenceClock: PresenceClock;
+/** A clock whose waits finish at once while its time still advances (repeatable performances). */
+export declare function createInstantPresenceClock(start?: number): PresenceClock & {
+    elapsed(): number;
+};
+/**
+ * Glides an actor's cursor from `from` to `to` over `ms` (ease-out cubic, ~60 frames a second),
+ * calling `each` with the eased progress after every frame (e.g. to drag a value along).
+ */
+export declare function tweenPresenceCursor(presence: PresenceStore, clock: PresenceClock, id: string, from: {
+    x: number;
+    y: number;
+}, to: {
+    x: number;
+    y: number;
+}, ms: number, each?: (t: number) => void): Promise<void>;
+export interface PresenceActorInfo {
+    id: string;
+    name?: string;
+    color?: string;
+}
+export interface PerformanceQueueOptions {
+    clock: PresenceClock;
+    /** Hide each actor's cursor this long after its last call (ms, default 1500; 0 keeps it). */
+    linger?: number;
+    /** Called around each call so everything it changes is one undo step. */
+    beginGesture?: (key: string) => void;
+    endGesture?: () => void;
+}
+/**
+ * Runs performances one after another per actor (different actors run side by side). Each
+ * call shows the actor's cursor, wraps the call in one gesture (one undo step), clears the
+ * note when it ends, and hides the cursor after `linger` unless another call followed.
+ */
+export declare class PerformanceQueue {
+    readonly presence: PresenceStore;
+    private readonly options;
+    private readonly queues;
+    private calls;
+    constructor(presence: PresenceStore, options: PerformanceQueueOptions);
+    run<T>(actor: PresenceActorInfo, perform: () => Promise<T>): Promise<T>;
+}

package/dist/tools/presence.d.ts

@@ -0,0 +1,82 @@
+export interface PresenceActor {
+    id: string;
+    name: string;
+    color: string;
+    /** Cursor position in the surface's own coordinates (scene / canvas). */
+    x: number;
+    y: number;
+    /** The button is down (dragging). */
+    pressed: boolean;
+    /** A short note shown next to the cursor (what the agent is doing). */
+    message?: string;
+    /** A rectangle (surface coordinates) the agent is working on, drawn as a highlight ring. */
+    focus?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface PresenceState {
+    actors: readonly PresenceActor[];
+}
+export declare const PRESENCE_COLORS: readonly string[];
+/** Cursor positions and notes of agents acting on a surface, for an overlay. */
+export declare class PresenceStore {
+    private state;
+    private readonly listeners;
+    getState: () => PresenceState;
+    subscribe: (listener: (state: PresenceState) => void) => (() => void);
+    /** The actor with `id`, if it is on the surface. */
+    get(id: string): PresenceActor | undefined;
+    /** Adds or changes an actor. */
+    set(actor: Pick<PresenceActor, 'id'> & Partial<PresenceActor>): void;
+    remove(id: string): void;
+}
+/** Time for performances: real timers, or an instant clock for tests and recordings. */
+export interface PresenceClock {
+    now(): number;
+    wait(ms: number): Promise<void>;
+}
+export declare const realPresenceClock: PresenceClock;
+/** A clock whose waits finish at once while its time still advances (repeatable performances). */
+export declare function createInstantPresenceClock(start?: number): PresenceClock & {
+    elapsed(): number;
+};
+/**
+ * Glides an actor's cursor from `from` to `to` over `ms` (ease-out cubic, ~60 frames a second),
+ * calling `each` with the eased progress after every frame (e.g. to drag a value along).
+ */
+export declare function tweenPresenceCursor(presence: PresenceStore, clock: PresenceClock, id: string, from: {
+    x: number;
+    y: number;
+}, to: {
+    x: number;
+    y: number;
+}, ms: number, each?: (t: number) => void): Promise<void>;
+export interface PresenceActorInfo {
+    id: string;
+    name?: string;
+    color?: string;
+}
+export interface PerformanceQueueOptions {
+    clock: PresenceClock;
+    /** Hide each actor's cursor this long after its last call (ms, default 1500; 0 keeps it). */
+    linger?: number;
+    /** Called around each call so everything it changes is one undo step. */
+    beginGesture?: (key: string) => void;
+    endGesture?: () => void;
+}
+/**
+ * Runs performances one after another per actor (different actors run side by side). Each
+ * call shows the actor's cursor, wraps the call in one gesture (one undo step), clears the
+ * note when it ends, and hides the cursor after `linger` unless another call followed.
+ */
+export declare class PerformanceQueue {
+    readonly presence: PresenceStore;
+    private readonly options;
+    private readonly queues;
+    private calls;
+    constructor(presence: PresenceStore, options: PerformanceQueueOptions);
+    run<T>(actor: PresenceActorInfo, perform: () => Promise<T>): Promise<T>;
+}

package/dist/tools/registry.d.cts

@@ -1,5 +1,7 @@
 import { type JsonSchema, type SchemaValidationError } from './schema.cjs';
 import { ToolRegistryView, type ToolViewOptions } from './view.cjs';
+import type { ToolPlanner } from './playback.cjs';
+import type { PresenceActorInfo } from './presence.cjs';
 /**
  * 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