@flowdrop/flowdrop 2.6.0 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -17,25 +17,42 @@
17
17
  editorName: string;
18
18
  /** One human-readable line per command (see `describeCommand`). */
19
19
  lines: string[];
20
- /** Called exactly once with the decision. */
21
- onResolve: (approved: boolean) => void;
20
+ /**
21
+ * Overrides the default "N changes — applied together, undone together"
22
+ * hint, e.g. for `save`, which has no commands to count.
23
+ */
24
+ hint?: string;
25
+ /**
26
+ * Show the "apply further edits without asking" checkbox. Off for
27
+ * consequential calls (`save`, `run`), which always ask.
28
+ */
29
+ offerRemember?: boolean;
30
+ /** Called exactly once with the decision and whether to remember it for edits. */
31
+ onResolve: (approved: boolean, remember?: boolean) => void;
22
32
  }
23
33
 
24
- let { editorName, lines, onResolve }: Props = $props();
34
+ let { editorName, lines, hint, offerRemember = false, onResolve }: Props = $props();
25
35
 
26
36
  let rejectButton = $state<HTMLButtonElement | null>(null);
27
37
  let approveButton = $state<HTMLButtonElement | null>(null);
38
+ let rememberBox = $state<HTMLInputElement | null>(null);
39
+ let remember = $state(false);
28
40
 
29
- // Focus starts on Apply and stays inside the dialog: Tab and Shift+Tab move
30
- // between the two buttons, Escape rejects. The handler sits on the dialog
31
- // itself, which holds focus through its buttons, not on the window.
41
+ // Focus starts on Apply and stays inside the dialog: Tab cycles Apply →
42
+ // Reject → (checkbox) → Apply, Escape rejects. The handler sits on the
43
+ // dialog itself, which holds focus through its controls, not on the window.
32
44
  function handleKeydown(event: KeyboardEvent): void {
33
45
  if (event.key === 'Escape') {
34
46
  event.preventDefault();
35
47
  onResolve(false);
36
48
  } else if (event.key === 'Tab') {
37
49
  event.preventDefault();
38
- (document.activeElement === approveButton ? rejectButton : approveButton)?.focus();
50
+ const order = [approveButton, rejectButton, rememberBox].filter(
51
+ (el): el is HTMLButtonElement | HTMLInputElement => el !== null
52
+ );
53
+ const i = order.indexOf(document.activeElement as HTMLButtonElement | HTMLInputElement);
54
+ const step = event.shiftKey ? -1 : 1;
55
+ order[(i + step + order.length) % order.length]?.focus();
39
56
  }
40
57
  }
41
58
  </script>
@@ -54,13 +71,24 @@
54
71
  {m().webmcp.confirmTitle({ name: editorName })}
55
72
  </h2>
56
73
  <p class="fd-webmcp-confirm__hint">
57
- {m().webmcp.confirmCount({ count: lines.length })}
74
+ {hint ?? m().webmcp.confirmCount({ count: lines.length })}
58
75
  </p>
59
76
  <ol id="fd-webmcp-confirm-list" class="fd-webmcp-confirm__list">
60
77
  {#each lines as line, i (i)}
61
78
  <li class="fd-webmcp-confirm__line">{line}</li>
62
79
  {/each}
63
80
  </ol>
81
+ {#if offerRemember}
82
+ <label class="fd-webmcp-confirm__remember">
83
+ <input
84
+ type="checkbox"
85
+ data-testid="flowdrop-webmcp-remember"
86
+ bind:this={rememberBox}
87
+ bind:checked={remember}
88
+ />
89
+ {m().webmcp.rememberEdits}
90
+ </label>
91
+ {/if}
64
92
  <div class="fd-webmcp-confirm__actions">
65
93
  <button
66
94
  type="button"
@@ -77,7 +105,7 @@
77
105
  data-testid="flowdrop-webmcp-approve"
78
106
  bind:this={approveButton}
79
107
  {@attach focusOnMount()}
80
- onclick={() => onResolve(true)}
108
+ onclick={() => onResolve(true, remember)}
81
109
  >
82
110
  {m().webmcp.apply}
83
111
  </button>
@@ -94,7 +122,10 @@
94
122
  align-items: center;
95
123
  justify-content: center;
96
124
  background: rgb(0 0 0 / 0.4);
97
- font-family: inherit;
125
+ /* Mounted on document.body, outside the editor: no host font to inherit. */
126
+ font-family: var(--fd-font-sans, system-ui, sans-serif);
127
+ font-size: var(--fd-text-md, 1rem);
128
+ line-height: var(--fd-leading-normal, 1.5);
98
129
  }
99
130
 
100
131
  .fd-webmcp-confirm__dialog {
@@ -137,6 +168,21 @@
137
168
  overflow-wrap: anywhere;
138
169
  }
139
170
 
171
+ .fd-webmcp-confirm__remember {
172
+ display: flex;
173
+ align-items: flex-start;
174
+ gap: var(--fd-space-sm, 0.5rem);
175
+ margin: 0 0 var(--fd-space-lg, 1rem);
176
+ font-size: var(--fd-text-sm, 0.875rem);
177
+ color: var(--fd-muted-foreground, #71717a);
178
+ cursor: pointer;
179
+ }
180
+
181
+ .fd-webmcp-confirm__remember input {
182
+ margin: 0.2em 0 0;
183
+ accent-color: var(--fd-primary, #2563eb);
184
+ }
185
+
140
186
  .fd-webmcp-confirm__actions {
141
187
  display: flex;
142
188
  justify-content: flex-end;
@@ -3,8 +3,18 @@ interface Props {
3
3
  editorName: string;
4
4
  /** One human-readable line per command (see `describeCommand`). */
5
5
  lines: string[];
6
- /** Called exactly once with the decision. */
7
- onResolve: (approved: boolean) => void;
6
+ /**
7
+ * Overrides the default "N changes — applied together, undone together"
8
+ * hint, e.g. for `save`, which has no commands to count.
9
+ */
10
+ hint?: string;
11
+ /**
12
+ * Show the "apply further edits without asking" checkbox. Off for
13
+ * consequential calls (`save`, `run`), which always ask.
14
+ */
15
+ offerRemember?: boolean;
16
+ /** Called exactly once with the decision and whether to remember it for edits. */
17
+ onResolve: (approved: boolean, remember?: boolean) => void;
8
18
  }
9
19
  declare const WebMCPConfirm: import("svelte").Component<Props, {}, "">;
10
20
  type WebMCPConfirm = ReturnType<typeof WebMCPConfirm>;
@@ -0,0 +1,63 @@
1
+ /**
2
+ * WebMCP adapter — a bridge to a desktop MCP client for browsers without the
3
+ * origin trial.
4
+ *
5
+ * Chrome's `document.modelContext` is the runtime the adapter was written for,
6
+ * but it sits behind a flag and only Chrome's own agent consumes it. This
7
+ * module presents the same {@link ModelContextLike} surface over a *widget*
8
+ * that relays tools to a local MCP server — the shape of
9
+ * `@jason.today/webmcp`'s page-side `WebMCP` class:
10
+ * `registerTool(name, description, inputSchema, execute)`, with tool calls
11
+ * arriving over its websocket and the returned value passed to the MCP client
12
+ * as the tool result. The adapter's tools already return MCP-shaped
13
+ * `{content: [{type: 'text', text}]}` results, so nothing is translated.
14
+ *
15
+ * Install it before the editor mounts:
16
+ *
17
+ * ```ts
18
+ * import { installBridgedModelContext } from '@flowdrop/flowdrop/webmcp';
19
+ * const widget = new WebMCP(); // the bridge's page-side script
20
+ * installBridgedModelContext(widget); // no-op when a real runtime exists
21
+ * ```
22
+ *
23
+ * The widget cannot unregister a tool. When the adapter aborts a
24
+ * registration (editor destroyed), the relayed function keeps answering — with
25
+ * a structured `UNAVAILABLE` error — until the page unloads. A re-registration
26
+ * under the same name takes over again.
27
+ *
28
+ * The relay's MCP server answers a tool call with a timeout after 30 seconds.
29
+ * A confirm dialog left open longer than that returns a timeout to the agent
30
+ * while the dialog stays up; approving it then still applies the change. Hosts
31
+ * that expect slow approvals should say so in the dialog copy or use a custom
32
+ * `approval` callback.
33
+ *
34
+ * Nothing here decides *who* may reach the page: the bridge is localhost-only
35
+ * and token-gated by design, and the adapter's confirm dialog and the
36
+ * server's permissions still gate every mutation. Hosts should still make the
37
+ * bridge an explicit opt-in rather than a default.
38
+ *
39
+ * @module webmcp/bridge
40
+ */
41
+ import type { ModelContextLike, RegisteredToolDefinition, ToolInputSchema } from './types.js';
42
+ /** The page-side widget surface the bridge relays to (`@jason.today/webmcp`). */
43
+ export interface WebMCPWidgetLike {
44
+ registerTool(name: string, description: string, inputSchema: ToolInputSchema, execute: (args: unknown) => unknown): unknown;
45
+ }
46
+ export interface BridgedModelContext extends ModelContextLike {
47
+ /** Tools currently registered through the bridge, by name. */
48
+ readonly tools: ReadonlyMap<string, RegisteredToolDefinition>;
49
+ }
50
+ /**
51
+ * Wrap a bridge widget as a `modelContext`-shaped runtime.
52
+ *
53
+ * Each `registerTool` is relayed once per name; the relayed function looks the
54
+ * tool up at call time so aborts and re-registrations are honoured without the
55
+ * widget having to know about them.
56
+ */
57
+ export declare function createBridgedModelContext(widget: WebMCPWidgetLike): BridgedModelContext;
58
+ /**
59
+ * Install a bridged runtime as `document.modelContext` unless a runtime is
60
+ * already present (Chrome's, or one installed earlier). Returns the runtime
61
+ * in effect, or null outside a browser (or when `target` is null).
62
+ */
63
+ export declare function installBridgedModelContext(widget: WebMCPWidgetLike, target?: object | null): ModelContextLike | null;
@@ -0,0 +1,106 @@
1
+ /**
2
+ * WebMCP adapter — a bridge to a desktop MCP client for browsers without the
3
+ * origin trial.
4
+ *
5
+ * Chrome's `document.modelContext` is the runtime the adapter was written for,
6
+ * but it sits behind a flag and only Chrome's own agent consumes it. This
7
+ * module presents the same {@link ModelContextLike} surface over a *widget*
8
+ * that relays tools to a local MCP server — the shape of
9
+ * `@jason.today/webmcp`'s page-side `WebMCP` class:
10
+ * `registerTool(name, description, inputSchema, execute)`, with tool calls
11
+ * arriving over its websocket and the returned value passed to the MCP client
12
+ * as the tool result. The adapter's tools already return MCP-shaped
13
+ * `{content: [{type: 'text', text}]}` results, so nothing is translated.
14
+ *
15
+ * Install it before the editor mounts:
16
+ *
17
+ * ```ts
18
+ * import { installBridgedModelContext } from '@flowdrop/flowdrop/webmcp';
19
+ * const widget = new WebMCP(); // the bridge's page-side script
20
+ * installBridgedModelContext(widget); // no-op when a real runtime exists
21
+ * ```
22
+ *
23
+ * The widget cannot unregister a tool. When the adapter aborts a
24
+ * registration (editor destroyed), the relayed function keeps answering — with
25
+ * a structured `UNAVAILABLE` error — until the page unloads. A re-registration
26
+ * under the same name takes over again.
27
+ *
28
+ * The relay's MCP server answers a tool call with a timeout after 30 seconds.
29
+ * A confirm dialog left open longer than that returns a timeout to the agent
30
+ * while the dialog stays up; approving it then still applies the change. Hosts
31
+ * that expect slow approvals should say so in the dialog copy or use a custom
32
+ * `approval` callback.
33
+ *
34
+ * Nothing here decides *who* may reach the page: the bridge is localhost-only
35
+ * and token-gated by design, and the adapter's confirm dialog and the
36
+ * server's permissions still gate every mutation. Hosts should still make the
37
+ * bridge an explicit opt-in rather than a default.
38
+ *
39
+ * @module webmcp/bridge
40
+ */
41
+ function unavailable(name) {
42
+ return {
43
+ content: [
44
+ {
45
+ type: 'text',
46
+ text: JSON.stringify({
47
+ ok: false,
48
+ code: 'UNAVAILABLE',
49
+ error: `Tool "${name}" is no longer registered; the editor that offered it was closed. Reload the page and try again.`
50
+ })
51
+ }
52
+ ],
53
+ isError: true
54
+ };
55
+ }
56
+ /**
57
+ * Wrap a bridge widget as a `modelContext`-shaped runtime.
58
+ *
59
+ * Each `registerTool` is relayed once per name; the relayed function looks the
60
+ * tool up at call time so aborts and re-registrations are honoured without the
61
+ * widget having to know about them.
62
+ */
63
+ export function createBridgedModelContext(widget) {
64
+ const tools = new Map();
65
+ const relayed = new Set();
66
+ return {
67
+ tools,
68
+ registerTool(tool, options) {
69
+ tools.set(tool.name, tool);
70
+ options?.signal?.addEventListener('abort', () => {
71
+ if (tools.get(tool.name) === tool)
72
+ tools.delete(tool.name);
73
+ }, { once: true });
74
+ if (!relayed.has(tool.name)) {
75
+ relayed.add(tool.name);
76
+ widget.registerTool(tool.name, tool.description, tool.inputSchema, (args) => {
77
+ const live = tools.get(tool.name);
78
+ if (!live)
79
+ return unavailable(tool.name);
80
+ return live.execute((args ?? {}));
81
+ });
82
+ }
83
+ return Promise.resolve();
84
+ }
85
+ };
86
+ }
87
+ /**
88
+ * Install a bridged runtime as `document.modelContext` unless a runtime is
89
+ * already present (Chrome's, or one installed earlier). Returns the runtime
90
+ * in effect, or null outside a browser (or when `target` is null).
91
+ */
92
+ export function installBridgedModelContext(widget, target = typeof document === 'undefined' ? null : document) {
93
+ if (!target)
94
+ return null;
95
+ const host = target;
96
+ if (host.modelContext)
97
+ return host.modelContext;
98
+ const nav = typeof navigator === 'undefined'
99
+ ? undefined
100
+ : navigator;
101
+ if (nav?.modelContext)
102
+ return nav.modelContext;
103
+ const bridged = createBridgedModelContext(widget);
104
+ Object.defineProperty(target, 'modelContext', { value: bridged, configurable: true });
105
+ return bridged;
106
+ }
@@ -22,7 +22,7 @@ import { type ToolDescriptor, type ToolInputSchema } from './types.js';
22
22
  import { validateToolArgs } from './validate.js';
23
23
  export { validateToolArgs };
24
24
  /** Command types exposed as one tool each (verb === command type). */
25
- export declare const EXPOSED_COMMAND_TYPES: readonly ["add_node", "delete_node", "rename_node", "move_node", "swap_node", "set_config", "get_config", "connect", "disconnect_ports", "disconnect_node", "list_nodes", "list_edges", "list_types", "info", "undo", "redo", "auto_layout", "beautify_layout"];
25
+ export declare const EXPOSED_COMMAND_TYPES: readonly ["add_node", "delete_node", "rename_node", "move_node", "swap_node", "set_config", "get_config", "connect", "disconnect_ports", "disconnect_node", "list_nodes", "list_edges", "list_types", "describe_type", "search_types", "info", "undo", "redo", "auto_layout", "beautify_layout"];
26
26
  /**
27
27
  * Command types folded into the single `view` tool (its `action` enum). The
28
28
  * list itself lives in the command classifier, next to `isViewCommand`, so
@@ -38,6 +38,8 @@ export const EXPOSED_COMMAND_TYPES = [
38
38
  'list_nodes',
39
39
  'list_edges',
40
40
  'list_types',
41
+ 'describe_type',
42
+ 'search_types',
41
43
  'info',
42
44
  'undo',
43
45
  'redo',
@@ -65,7 +67,15 @@ export const COMPOSITE_VERBS = ['view', 'batch'];
65
67
  // ============================================================================
66
68
  // Schema fragments
67
69
  // ============================================================================
68
- const NODE_ID_DESCRIPTION = 'Node id in short form, e.g. "llm_node.1" — the `nodeId` values returned by list_nodes and add_node. Full ids are accepted too.';
70
+ const NODE_ID_DESCRIPTION = 'Node id in short form, e.g. "http_request.1" — the `nodeId` values returned by list_nodes and add_node. Full ids are accepted too.';
71
+ /**
72
+ * The recommended call order, appended to the tools where it applies —
73
+ * add_node, set_config, swap_node and batch, the ones that take a type or a
74
+ * config key. For a browser agent the tool descriptions are the whole manual,
75
+ * so the manual says how the tools fit together; saying it once per relevant
76
+ * tool keeps the manual short.
77
+ */
78
+ const CALL_ORDER = ' Call describe_type before adding or configuring a type you have not seen; group several changes in one batch; save when done.';
69
79
  const nodeId = (description = NODE_ID_DESCRIPTION) => ({
70
80
  type: 'string',
71
81
  description
@@ -121,11 +131,12 @@ const PORT_PAIR = object({
121
131
  /** One record per exposed command, keyed by command type. */
122
132
  const COMMANDS = {
123
133
  add_node: {
124
- description: 'Add a node of the given type to the workflow. Returns the new node id.',
134
+ description: "Add a node of the given type to the workflow. Returns the new node id; the node starts with the type's default config." +
135
+ CALL_ORDER,
125
136
  inputSchema: object({
126
137
  nodeTypeId: {
127
138
  type: 'string',
128
- description: 'Node type id as returned by list_types (`typeId`), e.g. "llm_node". Call list_types first.'
139
+ description: 'Node type id as returned by list_types / search_types (`typeId`), e.g. "http_request". Unknown ids fail and name near misses.'
129
140
  },
130
141
  position: {
131
142
  ...position,
@@ -158,12 +169,13 @@ const COMMANDS = {
158
169
  summarize: (c) => `Move ${c.nodeId} to ${at(c.position)}`
159
170
  },
160
171
  swap_node: {
161
- description: 'Replace a node with one of another type, keeping compatible connections and config. Reports what was dropped.',
172
+ description: 'Replace a node with one of another type, keeping compatible connections and config. Reports what was dropped.' +
173
+ CALL_ORDER,
162
174
  inputSchema: object({
163
175
  nodeId: nodeId('Node to replace.'),
164
176
  newTypeId: {
165
177
  type: 'string',
166
- description: 'Replacement node type id (see list_types). Compatible ports and config carry over.'
178
+ description: 'Replacement node type id (see list_types / describe_type). Compatible ports and config carry over.'
167
179
  }
168
180
  }, ['nodeId', 'newTypeId']),
169
181
  build: (a) => ({
@@ -174,12 +186,13 @@ const COMMANDS = {
174
186
  summarize: (c) => `Swap ${c.nodeId} for a ${c.newTypeId}`
175
187
  },
176
188
  set_config: {
177
- description: 'Set one configuration value on a node. Validation warnings are returned, not fatal, unless strict.',
189
+ description: 'Set one configuration value on a node. A value outside the enum, of the wrong type, or under a key the schema does not declare is stored with a warning that names the allowed values / keys — fatal only when strict.' +
190
+ CALL_ORDER,
178
191
  inputSchema: object({
179
192
  nodeId: nodeId(),
180
193
  key: {
181
194
  type: 'string',
182
- description: 'Config key, as listed under `config` by the info tool.'
195
+ description: 'Config key, as listed under `config` by describe_type (with type, enum and default) or get_config.'
183
196
  },
184
197
  value: configValue,
185
198
  strict: {
@@ -197,13 +210,23 @@ const COMMANDS = {
197
210
  summarize: (c) => `Set ${c.nodeId}.${c.key} = ${c.value}`
198
211
  },
199
212
  get_config: {
200
- description: 'Read one configuration value from a node.',
201
- inputSchema: object({ nodeId: nodeId(), key: { type: 'string', description: 'Config key to read.' } }, ['nodeId', 'key']),
202
- build: (a) => ({ type: 'get_config', nodeId: a.nodeId, key: a.key }),
203
- summarize: (c) => `Read ${c.nodeId}.${c.key}`
213
+ description: 'Read configuration from a node. With `key`: that value and its schema entry (type, enum, default). Without: every current value under `values` plus the whole config schema.',
214
+ inputSchema: object({
215
+ nodeId: nodeId(),
216
+ key: {
217
+ type: 'string',
218
+ description: 'Config key to read; omit for all values and the schema.'
219
+ }
220
+ }, ['nodeId']),
221
+ build: (a) => ({
222
+ type: 'get_config',
223
+ nodeId: a.nodeId,
224
+ ...(a.key !== undefined ? { key: a.key } : {})
225
+ }),
226
+ summarize: (c) => c.key !== undefined ? `Read ${c.nodeId}.${c.key}` : `Read config of ${c.nodeId}`
204
227
  },
205
228
  connect: {
206
- description: 'Connect an output port of one node to an input port of another. Fails on type mismatch or cycle.',
229
+ description: 'Connect an output port of one node to an input port of another. An unknown port fails and lists the ports on both sides; the existing edge is kept when the connection is already there.',
207
230
  inputSchema: PORT_PAIR,
208
231
  build: (a) => ({
209
232
  type: 'connect',
@@ -245,19 +268,36 @@ const COMMANDS = {
245
268
  summarize: () => 'List edges'
246
269
  },
247
270
  list_types: {
248
- description: 'List the node types that can be added, with their `typeId`, name and category. Call this before add_node.',
271
+ description: 'List every node type that can be added: `typeId`, name, category, description, tags. A type not in this list is unavailable in this editor. Use search_types to narrow, describe_type for ports and config.',
249
272
  inputSchema: EMPTY,
250
273
  build: () => ({ type: 'list_types' }),
251
274
  summarize: () => 'List node types'
252
275
  },
276
+ describe_type: {
277
+ description: 'Describe one node type before using it: input and output ports (id, data type, required), config keys (type, enum, default, description), and — when the host publishes them — the confirmation policy (`ask` means a run pauses for a person at this node), what you may do with it (`can`) and host guidance (`agent`). Call this before add_node and set_config.',
278
+ inputSchema: object({
279
+ nodeTypeId: {
280
+ type: 'string',
281
+ description: 'Node type id (`typeId` from list_types / search_types), e.g. "http_request".'
282
+ }
283
+ }, ['nodeTypeId']),
284
+ build: (a) => ({ type: 'describe_type', nodeTypeId: a.nodeTypeId }),
285
+ summarize: (c) => `Describe type ${c.nodeTypeId}`
286
+ },
287
+ search_types: {
288
+ description: 'Find node types by a case-insensitive substring of their id, name, description or tags, e.g. "markdown" or "http". Returns the same rows as list_types.',
289
+ inputSchema: object({ query: { type: 'string', description: 'Text to look for.' } }, ['query']),
290
+ build: (a) => ({ type: 'search_types', query: a.query }),
291
+ summarize: (c) => `Search types for ${q(c.query)}`
292
+ },
253
293
  info: {
254
- description: 'Describe one node: type, position, current config, input and output ports, and connected edges.',
294
+ description: "Describe one node instance: type, position, current config values, input and output ports, and connected edges. For the type's schema and defaults use describe_type.",
255
295
  inputSchema: object({ nodeId: nodeId() }, ['nodeId']),
256
296
  build: (a) => ({ type: 'info', nodeId: a.nodeId }),
257
297
  summarize: (c) => `Describe ${c.nodeId}`
258
298
  },
259
299
  undo: {
260
- description: 'Undo the last change. Each tool call that changed the workflow is one undo step.',
300
+ description: 'Undo the last change. Each tool call that changed the workflow is one undo step; a save cannot be undone.',
261
301
  inputSchema: EMPTY,
262
302
  build: () => ({ type: 'undo' }),
263
303
  summarize: () => 'Undo'
@@ -359,7 +399,7 @@ const BATCH_ITEM_TYPES = [...EXPOSED_COMMAND_TYPES, 'view'];
359
399
  const BATCH_SCHEMA = object({
360
400
  commands: {
361
401
  type: 'array',
362
- description: 'Commands to run in order. Each item is the argument object of one tool plus a `type` naming that tool (without the prefix), e.g. {"type":"add_node","nodeTypeId":"llm_node"}. Read-only items are allowed but pointless here.',
402
+ description: 'Commands to run in order. Each item is the argument object of one tool plus a `type` naming that tool (without the prefix), e.g. {"type":"add_node","nodeTypeId":"http_request"}. Read-only items are allowed but pointless here.',
363
403
  items: {
364
404
  type: 'object',
365
405
  properties: {
@@ -430,7 +470,7 @@ export function buildToolDescriptors(options = {}) {
430
470
  : [];
431
471
  const batch = {
432
472
  verb: 'batch',
433
- description: 'Run several commands as one transaction: all succeed or none apply, and one undo reverts them all. Prefer this over many single calls when building a flow.',
473
+ description: 'Run several commands as one transaction: all succeed or none apply, one approval covers them all, and one undo reverts them all. Prefer this over many single calls when building a flow — describe the types first, batch the adds, connects and set_configs, then save.',
434
474
  inputSchema: BATCH_SCHEMA,
435
475
  readOnly: false,
436
476
  toCommands: (args) => buildBatchCommands(args, viewEnabled)
@@ -8,20 +8,48 @@
8
8
  * change the user's document. Any agent or extension on the page can call a
9
9
  * tool, so the gate must not be weaker than the chat panel's click-to-apply.
10
10
  *
11
+ * Two ergonomics live here too. A batch shows a *summary* of what changes
12
+ * (nodes added, edges connected, config keys set) above the line list, so the
13
+ * person reads what the agent is doing rather than a verb list. And the
14
+ * dialog can offer "apply further edits without asking" for the rest of the
15
+ * page's life — edits only: `save` and `run` are consequential and always ask.
16
+ * The gate cannot tell one agent from another, so the offer is worded as what
17
+ * it is: every caller on the page is covered once it is ticked. It is still a
18
+ * click-to-apply — one the person chose to make once.
19
+ *
11
20
  * @module webmcp/gate
12
21
  */
13
22
  import type { Command } from '../commands/types.js';
14
- import type { MessagesOverride } from '../messages/index.js';
15
- import type { WebMCPApproval } from './types.js';
23
+ import type { Messages, MessagesOverride } from '../messages/index.js';
24
+ import type { WebMCPApproval, WebMCPApprovalRequest } from './types.js';
25
+ /** What the gate needs to know about the call it is asking approval for. */
26
+ export interface GateRequest extends WebMCPApprovalRequest {
27
+ /**
28
+ * Dialog lines, one per command. Defaults to `commands.map(describeCommand)`;
29
+ * `save` and `run` have no commands to describe, so the gate fills in their
30
+ * line itself when this is omitted.
31
+ */
32
+ lines?: string[];
33
+ /** Extra sentence shown under the title, e.g. "This cannot be undone." */
34
+ hint?: string;
35
+ /**
36
+ * A consequential call (`save`, `run`) is never covered by the "don't ask
37
+ * again for edits" choice and never offers it. Defaults to `tool` being
38
+ * `save` or `run`.
39
+ */
40
+ consequential?: boolean;
41
+ }
16
42
  export interface ApprovalGate {
17
43
  /**
18
44
  * Ask whether `commands` may run. Resolves `true` to run. Rejects with
19
45
  * {@link GateBusyError} when a decision is already pending — the caller
20
46
  * turns that into a `busy` tool error instead of stacking dialogs.
21
47
  */
22
- request(commands: Command[]): Promise<boolean>;
48
+ request(commands: Command[], request: GateRequest): Promise<boolean>;
23
49
  /** True while a decision is pending. */
24
50
  readonly busy: boolean;
51
+ /** True once the person chose to apply further edits without asking. */
52
+ readonly editsPreApproved: boolean;
25
53
  /** Dismiss any open dialog (as a rejection) and release resources. */
26
54
  dispose(): void;
27
55
  }
@@ -36,5 +64,13 @@ export interface CreateGateOptions {
36
64
  editorName: () => string;
37
65
  /** Strings for the dialog, as a partial override or a getter for one. */
38
66
  messages?: MessagesOverride | (() => MessagesOverride);
67
+ /** Offer the "don't ask again for edits" choice. Default true. */
68
+ rememberEdits?: boolean;
39
69
  }
70
+ /**
71
+ * One sentence saying what a list of commands does, for the dialog's hint:
72
+ * "3 changes — adds 2 nodes, connects 1 edge. Applied together, undone together."
73
+ * Returns `undefined` for a single command, whose one line already says it all.
74
+ */
75
+ export declare function summarizeCommands(commands: Command[], m: Messages['webmcp']): string | undefined;
40
76
  export declare function createApprovalGate(approval: WebMCPApproval, options: CreateGateOptions): ApprovalGate;