@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.
@@ -8,6 +8,15 @@
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 { mount, unmount } from 'svelte';
@@ -21,9 +30,63 @@ export class GateBusyError extends Error {
21
30
  this.name = 'GateBusyError';
22
31
  }
23
32
  }
33
+ const CONSEQUENTIAL_TOOLS = new Set(['save', 'run']);
34
+ /**
35
+ * One sentence saying what a list of commands does, for the dialog's hint:
36
+ * "3 changes — adds 2 nodes, connects 1 edge. Applied together, undone together."
37
+ * Returns `undefined` for a single command, whose one line already says it all.
38
+ */
39
+ export function summarizeCommands(commands, m) {
40
+ if (commands.length < 2)
41
+ return undefined;
42
+ let adds = 0;
43
+ let deletes = 0;
44
+ let connects = 0;
45
+ let disconnects = 0;
46
+ let configs = 0;
47
+ let other = 0;
48
+ for (const c of commands) {
49
+ switch (c.type) {
50
+ case 'add_node':
51
+ adds++;
52
+ break;
53
+ case 'delete_node':
54
+ deletes++;
55
+ break;
56
+ case 'connect':
57
+ connects++;
58
+ break;
59
+ case 'disconnect_ports':
60
+ case 'disconnect_node':
61
+ disconnects++;
62
+ break;
63
+ case 'set_config':
64
+ configs++;
65
+ break;
66
+ default:
67
+ other++;
68
+ }
69
+ }
70
+ const parts = [];
71
+ if (adds)
72
+ parts.push(m.summaryAdds({ count: adds }));
73
+ if (deletes)
74
+ parts.push(m.summaryDeletes({ count: deletes }));
75
+ if (connects)
76
+ parts.push(m.summaryConnects({ count: connects }));
77
+ if (disconnects)
78
+ parts.push(m.summaryDisconnects({ count: disconnects }));
79
+ if (configs)
80
+ parts.push(m.summaryConfigs({ count: configs }));
81
+ if (other)
82
+ parts.push(m.summaryOther({ count: other }));
83
+ return m.batchSummary({ count: commands.length, parts: parts.join(', ') });
84
+ }
24
85
  export function createApprovalGate(approval, options) {
25
86
  let pending = false;
26
87
  let dismiss = null;
88
+ let editsPreApproved = false;
89
+ const offerRemember = options.rememberEdits ?? true;
27
90
  // The dialog mounts outside any component tree, so it gets its messages
28
91
  // through the same context the root component would have provided. Read
29
92
  // per access so a getter-driven locale switch shows on the next dialog.
@@ -31,14 +94,40 @@ export function createApprovalGate(approval, options) {
31
94
  const override = options.messages;
32
95
  return mergeMessages(defaultMessages, typeof override === 'function' ? override() : override);
33
96
  };
34
- async function decide(commands) {
97
+ const isConsequential = (request) => request.consequential ?? CONSEQUENTIAL_TOOLS.has(request.tool);
98
+ async function decide(commands, request) {
35
99
  if (approval === 'auto')
36
100
  return true;
37
101
  if (typeof approval === 'function')
38
- return approval(commands);
39
- return confirmInPage(commands);
102
+ return approval(commands, { tool: request.tool });
103
+ // The person's earlier "don't ask again" covers edits, never save or run.
104
+ if (editsPreApproved && !isConsequential(request))
105
+ return true;
106
+ return confirmInPage(commands, request);
107
+ }
108
+ // `lines`/`hint` default from the commands for an ordinary change; `save`
109
+ // and `run` have no commands, so they get their own dialog copy.
110
+ function resolveLines(commands, request) {
111
+ if (request.lines)
112
+ return request.lines;
113
+ const m = messages().webmcp;
114
+ if (request.tool === 'save')
115
+ return [m.saveLine({ name: options.editorName() })];
116
+ if (request.tool === 'run')
117
+ return [m.runLine({ name: options.editorName() })];
118
+ return commands.map(describeCommand);
40
119
  }
41
- function confirmInPage(commands) {
120
+ function resolveHint(commands, request) {
121
+ if (request.hint !== undefined)
122
+ return request.hint;
123
+ const m = messages().webmcp;
124
+ if (request.tool === 'save')
125
+ return m.saveHint;
126
+ if (request.tool === 'run')
127
+ return m.runHint;
128
+ return summarizeCommands(commands, m);
129
+ }
130
+ function confirmInPage(commands, request) {
42
131
  const target = options.container ?? (typeof document !== 'undefined' ? document.body : null);
43
132
  if (!target) {
44
133
  // No DOM to ask in: refuse rather than silently apply.
@@ -49,13 +138,15 @@ export function createApprovalGate(approval, options) {
49
138
  const host = document.createElement('div');
50
139
  host.className = 'fd-webmcp-confirm-host';
51
140
  target.appendChild(host);
52
- const finish = (approved) => {
141
+ const finish = (approved, remember = false) => {
53
142
  if (settled)
54
143
  return;
55
144
  settled = true;
56
145
  dismiss = null;
57
146
  void unmount(component);
58
147
  host.remove();
148
+ if (approved && remember)
149
+ editsPreApproved = true;
59
150
  resolve(approved);
60
151
  };
61
152
  const component = mount(WebMCPConfirm, {
@@ -63,7 +154,9 @@ export function createApprovalGate(approval, options) {
63
154
  context: messagesContext(messages),
64
155
  props: {
65
156
  editorName: options.editorName(),
66
- lines: commands.map(describeCommand),
157
+ lines: resolveLines(commands, request),
158
+ hint: resolveHint(commands, request),
159
+ offerRemember: offerRemember && !isConsequential(request),
67
160
  onResolve: finish
68
161
  }
69
162
  });
@@ -74,12 +167,15 @@ export function createApprovalGate(approval, options) {
74
167
  get busy() {
75
168
  return pending;
76
169
  },
77
- async request(commands) {
170
+ get editsPreApproved() {
171
+ return editsPreApproved;
172
+ },
173
+ async request(commands, request) {
78
174
  if (pending)
79
175
  throw new GateBusyError();
80
176
  pending = true;
81
177
  try {
82
- return await decide(commands);
178
+ return await decide(commands, request);
83
179
  }
84
180
  finally {
85
181
  pending = false;
@@ -31,4 +31,6 @@ export { validateToolArgs, VALIDATOR_KEYWORDS } from './validate.js';
31
31
  export { ToolArgumentError } from './types.js';
32
32
  export { createFakeModelContext } from './fake.js';
33
33
  export type { FakeModelContext } from './fake.js';
34
- export type { ToolDescriptor, ToolInputSchema, ToolSchemaProperty, ToolResult, ToolExecuteOptions, RegisteredToolDefinition, RegisterToolOptions, ModelContextLike, WebMCPApproval, WebMCPOptions, WebMCPMountOptions, WebMCPHandle } from './types.js';
34
+ export { createBridgedModelContext, installBridgedModelContext } from './bridge.js';
35
+ export type { WebMCPWidgetLike, BridgedModelContext } from './bridge.js';
36
+ export type { ToolDescriptor, ToolInputSchema, ToolSchemaProperty, ToolResult, ToolExecuteOptions, RegisteredToolDefinition, RegisterToolOptions, ModelContextLike, WebMCPApproval, WebMCPApprovalRequest, HostCode, HostEnvelope, RunStarted, RunPending, RunStatus, WebMCPOptions, WebMCPMountOptions, WebMCPHandle } from './types.js';
@@ -29,3 +29,4 @@ export { buildToolDescriptors, describeCommand, EXPOSED_COMMAND_TYPES, VIEW_COMM
29
29
  export { validateToolArgs, VALIDATOR_KEYWORDS } from './validate.js';
30
30
  export { ToolArgumentError } from './types.js';
31
31
  export { createFakeModelContext } from './fake.js';
32
+ export { createBridgedModelContext, installBridgedModelContext } from './bridge.js';
@@ -72,8 +72,40 @@ function text(payload, isError = false) {
72
72
  ...(isError ? { isError: true } : {})
73
73
  };
74
74
  }
75
- function errorResult(code, message) {
76
- return text({ ok: false, code, error: message }, true);
75
+ function errorResult(code, message, extra = {}) {
76
+ return text({ ok: false, code, error: message, ...extra }, true);
77
+ }
78
+ /**
79
+ * A host envelope as a tool result. `ok: false` is an error result with the
80
+ * host's code; `ok: true` keeps `code` (e.g. `PENDING`) and passes `data` and
81
+ * `can` through untouched — the agent reads them, the adapter never does.
82
+ */
83
+ function envelopeResult(envelope, fallbackMessage) {
84
+ const message = envelope.message ?? fallbackMessage;
85
+ if (!envelope.ok) {
86
+ return errorResult(envelope.code ?? 'FAILED', message, {
87
+ ...(envelope.data !== undefined ? { data: envelope.data } : {}),
88
+ ...(envelope.can ? { can: envelope.can } : {})
89
+ });
90
+ }
91
+ return text({
92
+ ok: true,
93
+ ...(envelope.code ? { code: envelope.code } : {}),
94
+ message,
95
+ ...(envelope.data !== undefined ? { data: envelope.data } : {}),
96
+ ...(envelope.can ? { can: envelope.can } : {})
97
+ });
98
+ }
99
+ /**
100
+ * Whether a thrown save error is the server saying the copy moved on. The
101
+ * library's `ApiError` carries the parsed body as `errorData` (fddo publishes
102
+ * `error_code: 'CONFLICT'` with a 409); a bare 409 counts too.
103
+ */
104
+ function isConflictError(err) {
105
+ if (!err || typeof err !== 'object')
106
+ return false;
107
+ const e = err;
108
+ return e.errorData?.error_code === 'CONFLICT' || e.status === 409;
77
109
  }
78
110
  function stripResult(result) {
79
111
  if (result.ok) {
@@ -132,7 +164,8 @@ export function attachWebMCP(instance, options = {}) {
132
164
  const gate = createApprovalGate(options.approval ?? 'confirm', {
133
165
  container: options.container,
134
166
  editorName,
135
- messages: options.messages
167
+ messages: options.messages,
168
+ rememberEdits: options.rememberEdits
136
169
  });
137
170
  const controller = new AbortController();
138
171
  const descriptors = buildToolDescriptors({ view: Boolean(options.onUIAction) });
@@ -179,7 +212,7 @@ export function attachWebMCP(instance, options = {}) {
179
212
  if (needsApproval(commands)) {
180
213
  let approved;
181
214
  try {
182
- approved = await gate.request(commands);
215
+ approved = await gate.request(commands, { tool: descriptor.verb });
183
216
  }
184
217
  catch (err) {
185
218
  if (err instanceof GateBusyError)
@@ -208,30 +241,234 @@ export function attachWebMCP(instance, options = {}) {
208
241
  ...(batch.ok ? {} : { error: batch.error, rolledBack: true })
209
242
  }, !batch.ok);
210
243
  }
244
+ // ---- host tools: save, run, run_status --------------------------------
245
+ const EMPTY_SCHEMA = {
246
+ type: 'object',
247
+ properties: {},
248
+ additionalProperties: false
249
+ };
250
+ const RUN_SCHEMA = {
251
+ type: 'object',
252
+ properties: {
253
+ inputs: {
254
+ type: 'object',
255
+ description: "Values for the workflow's interface input ports, keyed by port name. Omit for a workflow with no inputs."
256
+ }
257
+ },
258
+ additionalProperties: false
259
+ };
260
+ const RUN_STATUS_SCHEMA = {
261
+ type: 'object',
262
+ properties: {
263
+ runId: { type: 'string', description: 'The `runId` returned by run.' }
264
+ },
265
+ required: ['runId'],
266
+ additionalProperties: false
267
+ };
268
+ /**
269
+ * The host's word on what the user may do with the workflow, when the
270
+ * payload it loaded carried one. `undefined` means the host said nothing —
271
+ * proceed and let the server decide (D3: the server is the authority; the
272
+ * client only pre-empts).
273
+ */
274
+ function workflowCan(key) {
275
+ return instance.workflow.current?.can?.[key];
276
+ }
277
+ function validateOrError(schema, input) {
278
+ try {
279
+ return validateToolArgs(schema, input);
280
+ }
281
+ catch (err) {
282
+ if (err instanceof ToolArgumentError)
283
+ return errorResult('INVALID_ARGUMENTS', err.message);
284
+ throw err;
285
+ }
286
+ }
287
+ const isToolResult = (v) => typeof v === 'object' && v !== null && 'content' in v;
288
+ /** The gate, for a host tool with no commands of its own. */
289
+ async function askHostGate(tool) {
290
+ let approved;
291
+ try {
292
+ approved = await gate.request([], { tool });
293
+ }
294
+ catch (err) {
295
+ if (err instanceof GateBusyError)
296
+ return errorResult('BUSY', err.message);
297
+ throw err;
298
+ }
299
+ if (!approved)
300
+ return errorResult('REJECTED', 'The user rejected the change');
301
+ if (!attached)
302
+ return errorResult('DETACHED', 'This editor is no longer available');
303
+ return null;
304
+ }
305
+ /**
306
+ * `save` persists the workflow via the host's `onSave`. It has no commands
307
+ * of its own — nothing for `executeBatch` to run — so it is gated directly
308
+ * rather than going through `run()`'s command pipeline.
309
+ */
310
+ async function runSave(onSave, input) {
311
+ if (!attached)
312
+ return errorResult('DETACHED', 'This editor is no longer available');
313
+ const args = validateOrError(EMPTY_SCHEMA, input);
314
+ if (isToolResult(args))
315
+ return args;
316
+ if (!instance.workflow.current) {
317
+ return errorResult('NO_WORKFLOW', 'No workflow is loaded in this editor');
318
+ }
319
+ if (workflowCan('save') === false) {
320
+ return errorResult('FORBIDDEN', 'Saving this workflow is not permitted');
321
+ }
322
+ const refused = await askHostGate('save');
323
+ if (refused)
324
+ return refused;
325
+ let envelope;
326
+ try {
327
+ envelope = await onSave();
328
+ }
329
+ catch (err) {
330
+ const message = err instanceof Error ? err.message : String(err);
331
+ if (!isConflictError(err))
332
+ return errorResult('SAVE_FAILED', message);
333
+ // The server's own wording usually already says to reload; add the hint
334
+ // only when it does not, so the agent is not told twice.
335
+ const hint = /reload/i.test(message)
336
+ ? ''
337
+ : ' The workflow changed on the server since it was loaded; reload the page before saving.';
338
+ return errorResult('CONFLICT', `${message}${hint}`);
339
+ }
340
+ if (envelope)
341
+ return envelopeResult(envelope, 'Workflow saved');
342
+ return text({ ok: true, message: 'Workflow saved' });
343
+ }
344
+ /** `run` starts a run through the host's `onRun`; gated like `save`. */
345
+ async function runRun(onRun, input) {
346
+ if (!attached)
347
+ return errorResult('DETACHED', 'This editor is no longer available');
348
+ const args = validateOrError(RUN_SCHEMA, input);
349
+ if (isToolResult(args))
350
+ return args;
351
+ if (!instance.workflow.current) {
352
+ return errorResult('NO_WORKFLOW', 'No workflow is loaded in this editor');
353
+ }
354
+ if (workflowCan('run') === false) {
355
+ return errorResult('FORBIDDEN', 'Running this workflow is not permitted');
356
+ }
357
+ const refused = await askHostGate('run');
358
+ if (refused)
359
+ return refused;
360
+ let envelope;
361
+ try {
362
+ envelope = await onRun(args.inputs ?? {});
363
+ }
364
+ catch (err) {
365
+ return errorResult('RUN_FAILED', err instanceof Error ? err.message : String(err));
366
+ }
367
+ return envelopeResult(envelope, 'Run started');
368
+ }
369
+ /**
370
+ * `run_status` is a read: never gated. A paused run comes back `ok` with
371
+ * `code: 'PENDING'` and the pause's node and message — a person must act in
372
+ * the UI; no tool answers an interrupt (D8).
373
+ */
374
+ async function runRunStatus(onRunStatus, input) {
375
+ if (!attached)
376
+ return errorResult('DETACHED', 'This editor is no longer available');
377
+ const args = validateOrError(RUN_STATUS_SCHEMA, input);
378
+ if (isToolResult(args))
379
+ return args;
380
+ let envelope;
381
+ try {
382
+ envelope = await onRunStatus(args.runId);
383
+ }
384
+ catch (err) {
385
+ return errorResult('STATUS_FAILED', err instanceof Error ? err.message : String(err));
386
+ }
387
+ if (envelope.ok && envelope.data?.status === 'paused' && !envelope.code) {
388
+ const p = envelope.data.pending;
389
+ const where = p?.nodeId ? ` at node ${p.nodeId}` : '';
390
+ const why = p?.message
391
+ ? `: ${p.message}`
392
+ : envelope.data.pausedReason
393
+ ? ` (${envelope.data.pausedReason})`
394
+ : '';
395
+ return envelopeResult({
396
+ ...envelope,
397
+ code: 'PENDING',
398
+ message: envelope.message ??
399
+ `Run ${envelope.data.runId} is paused${where}${why}. A person must act in the editor; tell the user and poll run_status again.`
400
+ }, 'Run paused');
401
+ }
402
+ return envelopeResult(envelope, envelope.data ? `Run ${envelope.data.runId}: ${envelope.data.status}` : 'Run status');
403
+ }
211
404
  // ---- register -----------------------------------------------------------
212
405
  const nameSuffix = ` Editor: "${editorName()}".`;
213
- async function register(descriptor) {
214
- const name = `${prefix}_${descriptor.verb}`;
215
- const tool = {
216
- name,
217
- description: descriptor.description + nameSuffix,
218
- inputSchema: descriptor.inputSchema,
219
- annotations: { readOnlyHint: descriptor.readOnly },
220
- execute: (input) => run(descriptor, input)
221
- };
406
+ async function registerRaw(tool) {
222
407
  try {
223
408
  // The spec returns a promise that rejects when the runtime refuses the
224
409
  // tool; pre-spec runtimes return nothing, which `await` takes as accepted.
225
410
  await runtime.registerTool(tool, { signal: controller.signal });
226
411
  }
227
412
  catch (err) {
228
- logger.warn(`WebMCP: the runtime refused tool "${name}":`, err instanceof Error ? err.message : err);
413
+ logger.warn(`WebMCP: the runtime refused tool "${tool.name}":`, err instanceof Error ? err.message : err);
229
414
  return;
230
415
  }
231
416
  if (attached)
232
- names.push(name);
417
+ names.push(tool.name);
418
+ }
419
+ function register(descriptor) {
420
+ return registerRaw({
421
+ name: `${prefix}_${descriptor.verb}`,
422
+ description: descriptor.description + nameSuffix,
423
+ inputSchema: descriptor.inputSchema,
424
+ annotations: { readOnlyHint: descriptor.readOnly },
425
+ execute: (input) => run(descriptor, input)
426
+ });
427
+ }
428
+ const toolRegistrations = descriptors.map(register);
429
+ const { onSave, onRun, onRunStatus } = options;
430
+ if (onSave) {
431
+ toolRegistrations.push(registerRaw({
432
+ name: `${prefix}_save`,
433
+ description: 'Save the workflow to the server. Nothing an agent changes is persisted until ' +
434
+ 'this runs or the person clicks Save. Asks for approval; cannot be undone from ' +
435
+ 'the editor. Fails with FORBIDDEN when the user may not save, CONFLICT when the ' +
436
+ 'server copy changed since it was loaded (reload the page), INVALID when the ' +
437
+ 'server rejected the workflow — the message says which node or port.' +
438
+ nameSuffix,
439
+ inputSchema: EMPTY_SCHEMA,
440
+ annotations: { readOnlyHint: false, consequentialHint: true },
441
+ execute: (input) => runSave(onSave, input)
442
+ }));
443
+ }
444
+ if (onRun) {
445
+ toolRegistrations.push(registerRaw({
446
+ name: `${prefix}_run`,
447
+ description: 'Run the saved workflow on the server with optional inputs for its interface ports. ' +
448
+ 'Save first: unsaved changes are not part of the run. Asks for approval. Returns a ' +
449
+ '`runId`' +
450
+ (onRunStatus ? ' to poll with run_status.' : '.') +
451
+ ' Fails with FORBIDDEN when the user may not run, UNAVAILABLE when the workflow is not saved yet, ' +
452
+ 'INVALID when the server rejected the workflow.' +
453
+ nameSuffix,
454
+ inputSchema: RUN_SCHEMA,
455
+ annotations: { readOnlyHint: false, consequentialHint: true },
456
+ execute: (input) => runRun(onRun, input)
457
+ }));
458
+ if (onRunStatus) {
459
+ toolRegistrations.push(registerRaw({
460
+ name: `${prefix}_run_status`,
461
+ description: 'Report the status of a run started with run: pending, running, paused, completed, failed or cancelled, ' +
462
+ 'with outputs once it completed. A paused run answers code PENDING with the node and message it waits on — ' +
463
+ 'a person must act in the editor; tell the user, then poll again. Read-only.' +
464
+ nameSuffix,
465
+ inputSchema: RUN_STATUS_SCHEMA,
466
+ annotations: { readOnlyHint: true },
467
+ execute: (input) => runRunStatus(onRunStatus, input)
468
+ }));
469
+ }
233
470
  }
234
- const ready = Promise.all(descriptors.map(register)).then(() => undefined);
471
+ const ready = Promise.all(toolRegistrations).then(() => undefined);
235
472
  // ---- detach -------------------------------------------------------------
236
473
  function detach() {
237
474
  if (!attached)
@@ -81,6 +81,11 @@ export interface RegisteredToolDefinition {
81
81
  annotations?: {
82
82
  readOnlyHint?: boolean;
83
83
  untrustedContentHint?: boolean;
84
+ /**
85
+ * Spec added 2026-09-03: "executing the tool will result in consequential
86
+ * actions that are significant, real-world, or non-reversible."
87
+ */
88
+ consequentialHint?: boolean;
84
89
  };
85
90
  execute(input: unknown, options?: ToolExecuteOptions): Promise<ToolResult>;
86
91
  }
@@ -99,15 +104,79 @@ export interface ModelContextLike {
99
104
  /** Pre-spec runtimes only; called when present, never relied upon. */
100
105
  unregisterTool?(name: string): unknown;
101
106
  }
107
+ /**
108
+ * Stable codes a host hook (`onSave`, `onRun`, `onRunStatus`) may answer with.
109
+ * They align with fddo's API-8 `error_code` vocabulary where the two meet
110
+ * (`CONFLICT`, `NOT_FOUND`); the rest name what a browser agent must do next.
111
+ *
112
+ * - `FORBIDDEN` — the server refused; the agent should tell the user.
113
+ * - `UNAVAILABLE` — nothing to act on yet (unsaved workflow, no runtime).
114
+ * - `NEEDS_APPROVAL` — a person must approve in the UI first.
115
+ * - `INVALID` — the workflow failed validation; `message` says where.
116
+ * - `CONFLICT` — the server copy changed since it was loaded; reload.
117
+ * - `PENDING` — a run is paused for a person (never for the agent, D8).
118
+ * - `NOT_FOUND` — the run id is unknown.
119
+ */
120
+ export type HostCode = 'FORBIDDEN' | 'UNAVAILABLE' | 'NEEDS_APPROVAL' | 'INVALID' | 'CONFLICT' | 'PENDING' | 'NOT_FOUND' | (string & Record<never, never>);
121
+ /**
122
+ * What every host hook returns. `ok: false` needs a `code`; `ok: true` may
123
+ * still carry one (`PENDING`). `can` lets a host refresh what the user may do
124
+ * after the call — passed through to the agent untouched.
125
+ */
126
+ export interface HostEnvelope<T = unknown> {
127
+ ok: boolean;
128
+ code?: HostCode;
129
+ message?: string;
130
+ data?: T;
131
+ can?: Record<string, boolean>;
132
+ }
133
+ /** What `onRun` reports back once a run is accepted. */
134
+ export interface RunStarted {
135
+ /** The id `run_status` polls with. */
136
+ runId: string;
137
+ status?: string;
138
+ queued?: boolean;
139
+ }
140
+ /** The person-facing pause a paused run is waiting on (D8: no tool answers it). */
141
+ export interface RunPending {
142
+ interruptId?: string;
143
+ type?: string;
144
+ nodeId?: string;
145
+ message?: string;
146
+ }
147
+ /** What `onRunStatus` reports. `status` vocabulary is the host's; `paused` is special-cased. */
148
+ export interface RunStatus {
149
+ runId: string;
150
+ status: 'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled' | (string & Record<never, never>);
151
+ startedAt?: string | null;
152
+ finishedAt?: string | null;
153
+ /** Set when `status` is `paused` and a person must act. */
154
+ pending?: RunPending | null;
155
+ /** Why an execution budget paused the run, when it did. */
156
+ pausedReason?: string | null;
157
+ /** The run's output once it has one. Host-shaped. */
158
+ outputs?: unknown;
159
+ /** Per-node status once the host has it. Host-shaped. */
160
+ nodeStatuses?: unknown;
161
+ error?: string;
162
+ }
163
+ /** Context passed to a custom {@link WebMCPApproval} callback alongside the commands. */
164
+ export interface WebMCPApprovalRequest {
165
+ /** The tool being called, without prefix: `add_node`, `batch`, `save`, … */
166
+ tool: string;
167
+ }
102
168
  /**
103
169
  * Approval policy for mutating tools.
104
170
  *
105
171
  * - `'confirm'` (default): a confirm dialog rendered inside the page.
106
172
  * - `'auto'`: run without asking. Only for hosts that already trust every
107
173
  * agent on the page (kiosks, tests).
108
- * - A callback receiving the commands about to run; resolve `true` to run.
174
+ * - A callback receiving the commands about to run and the request they came
175
+ * from; resolve `true` to run. For `save`, `commands` is empty and
176
+ * `request.tool === 'save'` — there is no command to describe, only the
177
+ * act of persisting.
109
178
  */
110
- export type WebMCPApproval = 'confirm' | 'auto' | ((commands: Command[]) => Promise<boolean>);
179
+ export type WebMCPApproval = 'confirm' | 'auto' | ((commands: Command[], request: WebMCPApprovalRequest) => Promise<boolean>);
111
180
  export interface WebMCPOptions {
112
181
  /**
113
182
  * Node type definitions the tools resolve `add_node` and `list_types`
@@ -126,6 +195,39 @@ export interface WebMCPOptions {
126
195
  * it could do.
127
196
  */
128
197
  onUIAction?: (action: UIAction) => void;
198
+ /**
199
+ * Persist the workflow (the editor's Save). When supplied, a `save` tool
200
+ * is registered; it is gated like a change because a save cannot be
201
+ * undone from the editor. When omitted the tool is not registered —
202
+ * there is nothing it could do.
203
+ *
204
+ * May resolve to nothing (saved) or to a {@link HostEnvelope} — e.g.
205
+ * `{ok: false, code: 'CONFLICT'}` when the server copy moved on. A thrown
206
+ * error is reported as `SAVE_FAILED`, except an error whose `errorData.error_code`
207
+ * or `status` says conflict, which is relayed as `CONFLICT`.
208
+ */
209
+ onSave?: () => Promise<void | HostEnvelope>;
210
+ /**
211
+ * Start a run of the workflow being edited, with optional inputs for its
212
+ * interface ports. When supplied, a `run` tool is registered — gated like
213
+ * `save`, and flagged consequential — and `run_status` too when
214
+ * {@link onRunStatus} is also given. The hook answers with an envelope; the
215
+ * tool relays it. `data.runId` is what `run_status` polls with.
216
+ */
217
+ onRun?: (inputs: Record<string, unknown>) => Promise<HostEnvelope<RunStarted>>;
218
+ /**
219
+ * Report a run's status. A read: never gated. `status: 'paused'` is relayed
220
+ * as `code: 'PENDING'` with `pending.nodeId` / `pending.message` — the agent
221
+ * tells the person, and the person acts in the UI (D8).
222
+ */
223
+ onRunStatus?: (runId: string) => Promise<HostEnvelope<RunStatus>>;
224
+ /**
225
+ * Offer "don't ask again for edits in this session" in the confirm dialog.
226
+ * Ticked, later *edits* run without the dialog until the adapter detaches;
227
+ * `save` and `run` always ask. Default true. Irrelevant unless `approval`
228
+ * is `'confirm'`.
229
+ */
230
+ rememberEdits?: boolean;
129
231
  /** Where the built-in confirm dialog mounts. Default `document.body`. */
130
232
  container?: HTMLElement;
131
233
  /**
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "description": "A drop-in visual workflow editor for any web application. You own the backend. You own the data. You own the orchestration.",
4
4
  "license": "MIT",
5
5
  "private": false,
6
- "version": "2.6.0",
6
+ "version": "2.7.0",
7
7
  "author": "Shibin Das (D34dMan)",
8
8
  "bugs": {
9
9
  "url": "https://github.com/flowdrop-io/flowdrop/issues"