@flowdrop/flowdrop 2.7.0 → 2.8.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.
Files changed (55) hide show
  1. package/CHANGELOG.md +31 -1
  2. package/dist/api/enhanced-client.d.ts +29 -1
  3. package/dist/api/enhanced-client.js +83 -9
  4. package/dist/chat/index.d.ts +5 -1
  5. package/dist/chat/index.js +2 -0
  6. package/dist/chat/toolCatalogue.d.ts +27 -0
  7. package/dist/chat/toolCatalogue.js +35 -0
  8. package/dist/chat/turnDriver.d.ts +143 -0
  9. package/dist/chat/turnDriver.js +124 -0
  10. package/dist/components/App.svelte +47 -56
  11. package/dist/components/SettingsPanel.svelte +13 -0
  12. package/dist/components/WorkflowEditor.svelte +4 -2
  13. package/dist/components/WorkflowEditor.svelte.d.ts +2 -0
  14. package/dist/components/chat/AIChatPanel.svelte +410 -22
  15. package/dist/components/toast/DismissibleToast.svelte +53 -0
  16. package/dist/components/toast/DismissibleToast.svelte.d.ts +24 -0
  17. package/dist/components/toast/WarningIcon.svelte +28 -0
  18. package/dist/components/toast/WarningIcon.svelte.d.ts +26 -0
  19. package/dist/config/constants.d.ts +7 -3
  20. package/dist/config/constants.js +7 -3
  21. package/dist/config/endpoints.d.ts +7 -0
  22. package/dist/config/endpoints.js +2 -1
  23. package/dist/editor/index.d.ts +1 -1
  24. package/dist/editor/index.js +1 -1
  25. package/dist/messages/defaults.d.ts +41 -0
  26. package/dist/messages/defaults.js +20 -0
  27. package/dist/services/chatService.d.ts +21 -3
  28. package/dist/services/chatService.js +33 -1
  29. package/dist/services/globalSave.js +3 -1
  30. package/dist/services/toastService.d.ts +23 -2
  31. package/dist/services/toastService.js +72 -28
  32. package/dist/stores/instanceContainer.svelte.d.ts +34 -0
  33. package/dist/stores/instanceContainer.svelte.js +30 -0
  34. package/dist/styles/toast.css +62 -0
  35. package/dist/svelte-app.d.ts +12 -2
  36. package/dist/svelte-app.js +29 -12
  37. package/dist/types/chat.d.ts +59 -0
  38. package/dist/types/events.d.ts +23 -0
  39. package/dist/types/events.js +3 -1
  40. package/dist/types/settings.d.ts +18 -1
  41. package/dist/types/settings.js +1 -0
  42. package/dist/webmcp/WebMCPConfirm.svelte +129 -68
  43. package/dist/webmcp/WebMCPConfirm.svelte.d.ts +2 -2
  44. package/dist/webmcp/descriptors.d.ts +7 -0
  45. package/dist/webmcp/descriptors.js +51 -0
  46. package/dist/webmcp/gate.d.ts +13 -7
  47. package/dist/webmcp/gate.js +8 -53
  48. package/dist/webmcp/index.d.ts +5 -2
  49. package/dist/webmcp/index.js +3 -1
  50. package/dist/webmcp/register.d.ts +11 -10
  51. package/dist/webmcp/register.js +59 -384
  52. package/dist/webmcp/runtime.d.ts +33 -0
  53. package/dist/webmcp/runtime.js +500 -0
  54. package/dist/webmcp/types.d.ts +92 -0
  55. package/package.json +1 -1
@@ -0,0 +1,500 @@
1
+ /**
2
+ * WebMCP adapter — the tool runtime.
3
+ *
4
+ * One place that turns a tool name and its arguments into an effect on the
5
+ * editor: validate → map to commands → honour the layout opt-out → ask the
6
+ * gate → run one `executeBatch` transaction → strip the result. The three
7
+ * host tools (`save`, `run`, `run_status`) live here too, behind the hooks
8
+ * the host supplied.
9
+ *
10
+ * Two callers share it. The WebMCP registration (`register.ts`) wraps
11
+ * `runTool` in each tool's `execute`; the chat panel's turn driver calls it
12
+ * for the tool calls the assistant makes. Both therefore go through the same
13
+ * validation, the same consent dialog, the same teaching errors and the same
14
+ * undo step — the point of the shared runtime is that there is no second,
15
+ * weaker path to the user's document.
16
+ *
17
+ * @module webmcp/runtime
18
+ */
19
+ import { executeBatch } from '../commands/batch.js';
20
+ import { createStoreCommandContext } from '../commands/storeIntegration.svelte.js';
21
+ import { isLayoutCommand, isMutatingCommand, isViewCommand } from '../chat/commandClassifier.js';
22
+ import { getBehaviorSettings } from '../stores/settingsStore.svelte.js';
23
+ import { errorDetails } from '../api/enhanced-client.js';
24
+ import { buildToolDescriptors } from './descriptors.js';
25
+ import { validateToolArgs } from './validate.js';
26
+ import { createApprovalGate, GateBusyError } from './gate.js';
27
+ import { ToolArgumentError } from './types.js';
28
+ /** Wording shared with the chat panel's CommandPreview (issue #36). */
29
+ const LAYOUT_SKIPPED = 'Skipped — AI layout changes are disabled in Settings';
30
+ // ============================================================================
31
+ // Result formatting
32
+ // ============================================================================
33
+ function text(payload, isError = false) {
34
+ return {
35
+ content: [{ type: 'text', text: JSON.stringify(payload) }],
36
+ ...(isError ? { isError: true } : {})
37
+ };
38
+ }
39
+ function errorResult(code, message, extra = {}) {
40
+ return text({ ok: false, code, error: message, ...extra }, true);
41
+ }
42
+ /**
43
+ * A host envelope as a tool result. `ok: false` is an error result with the
44
+ * host's code; `ok: true` keeps `code` (e.g. `PENDING`) and passes `data` and
45
+ * `can` through untouched — the agent reads them, the adapter never does.
46
+ */
47
+ function envelopeResult(envelope, fallbackMessage) {
48
+ const message = envelope.message ?? fallbackMessage;
49
+ if (!envelope.ok) {
50
+ return errorResult(envelope.code ?? 'FAILED', message, {
51
+ ...(envelope.data !== undefined ? { data: envelope.data } : {}),
52
+ ...(envelope.can ? { can: envelope.can } : {})
53
+ });
54
+ }
55
+ return text({
56
+ ok: true,
57
+ ...(envelope.code ? { code: envelope.code } : {}),
58
+ message,
59
+ ...(envelope.data !== undefined ? { data: envelope.data } : {}),
60
+ ...(envelope.can ? { can: envelope.can } : {})
61
+ });
62
+ }
63
+ /**
64
+ * Whether a thrown save error is the server saying the copy moved on. The
65
+ * library's `ApiError` carries the parsed body as `errorData` (fddo publishes
66
+ * `error_code: 'CONFLICT'` with a 409); a bare 409 counts too.
67
+ */
68
+ function isConflictError(err) {
69
+ if (!err || typeof err !== 'object')
70
+ return false;
71
+ const e = err;
72
+ return e.errorData?.error_code === 'CONFLICT' || e.status === 409;
73
+ }
74
+ /**
75
+ * The error as one line of text for an agent. An `ApiError` keeps the
76
+ * server's reasons apart from its headline (`details`); a text channel has
77
+ * no list to render them in, so they are joined back on here.
78
+ */
79
+ function describeError(err) {
80
+ if (!(err instanceof Error))
81
+ return String(err);
82
+ const reasons = errorDetails(err);
83
+ return reasons.length ? `${err.message}: ${reasons.join('; ')}` : err.message;
84
+ }
85
+ function stripResult(result) {
86
+ if (result.ok) {
87
+ const out = { ok: true, message: result.message };
88
+ if (result.data !== undefined)
89
+ out.data = result.data;
90
+ if (result.uiActionPending)
91
+ out.uiActionPending = true;
92
+ return out;
93
+ }
94
+ return { ok: false, code: result.code, error: result.error };
95
+ }
96
+ /**
97
+ * The gate exists because any agent on the page can alter the user's
98
+ * document. A command that only moves the view — selection, a panel, the
99
+ * viewport — alters nothing the user would need to undo, so it runs unasked;
100
+ * `undo` and `redo` change the document and stay gated. A batch is gated as a
101
+ * whole when any of its items is.
102
+ */
103
+ function needsApproval(commands) {
104
+ return commands.some((c) => isMutatingCommand(c.type) && !isViewCommand(c.type));
105
+ }
106
+ /**
107
+ * D4: the layout opt-out. Layout commands rewrite every node's position, so
108
+ * with `chatAllowLayoutChanges` off they are skipped, not run — a skip is not
109
+ * a failure and the rest of a batch still applies. `preview` and `runTool`
110
+ * both go through here so what is announced is what happens.
111
+ */
112
+ function applyLayoutOptOut(commands) {
113
+ if (getBehaviorSettings().chatAllowLayoutChanges)
114
+ return { commands, skipped: [] };
115
+ const skipped = [];
116
+ const kept = commands.filter((c) => {
117
+ if (isLayoutCommand(c.type)) {
118
+ skipped.push(c);
119
+ return false;
120
+ }
121
+ return true;
122
+ });
123
+ return { commands: kept, skipped };
124
+ }
125
+ // ============================================================================
126
+ // Host tool schemas and descriptions
127
+ // ============================================================================
128
+ const EMPTY_SCHEMA = {
129
+ type: 'object',
130
+ properties: {},
131
+ additionalProperties: false
132
+ };
133
+ const RUN_SCHEMA = {
134
+ type: 'object',
135
+ properties: {
136
+ inputs: {
137
+ type: 'object',
138
+ description: "Values for the workflow's interface input ports, keyed by port name. Omit for a workflow with no inputs."
139
+ }
140
+ },
141
+ additionalProperties: false
142
+ };
143
+ const RUN_STATUS_SCHEMA = {
144
+ type: 'object',
145
+ properties: {
146
+ runId: { type: 'string', description: 'The `runId` returned by run.' }
147
+ },
148
+ required: ['runId'],
149
+ additionalProperties: false
150
+ };
151
+ /**
152
+ * The host tools a set of hooks makes available, in registration order.
153
+ * `save` needs `onSave`; `run` needs `onRun`; `run_status` needs both `onRun`
154
+ * and `onRunStatus` (a status tool without a way to start a run has nothing
155
+ * to report on).
156
+ */
157
+ export function buildHostToolDescriptors(hooks) {
158
+ const out = [];
159
+ if (hooks.onSave) {
160
+ out.push({
161
+ verb: 'save',
162
+ description: 'Save the workflow to the server. Nothing an agent changes is persisted until ' +
163
+ 'this runs or the person clicks Save. Asks for approval; cannot be undone from ' +
164
+ 'the editor. Fails with FORBIDDEN when the user may not save, CONFLICT when the ' +
165
+ 'server copy changed since it was loaded (reload the page), INVALID when the ' +
166
+ 'server rejected the workflow — the message says which node or port.',
167
+ inputSchema: EMPTY_SCHEMA,
168
+ readOnly: false,
169
+ consequential: true
170
+ });
171
+ }
172
+ if (hooks.onRun) {
173
+ out.push({
174
+ verb: 'run',
175
+ description: 'Run the saved workflow on the server with optional inputs for its interface ports. ' +
176
+ 'Save first: unsaved changes are not part of the run. Asks for approval. Returns a ' +
177
+ '`runId`' +
178
+ (hooks.onRunStatus ? ' to poll with run_status.' : '.') +
179
+ ' Fails with FORBIDDEN when the user may not run, UNAVAILABLE when the workflow is not saved yet, ' +
180
+ 'INVALID when the server rejected the workflow.',
181
+ inputSchema: RUN_SCHEMA,
182
+ readOnly: false,
183
+ consequential: true
184
+ });
185
+ if (hooks.onRunStatus) {
186
+ out.push({
187
+ verb: 'run_status',
188
+ description: 'Report the status of a run started with run: pending, running, paused, completed, failed or cancelled, ' +
189
+ 'with outputs once it completed. A paused run answers code PENDING with the node and message it waits on — ' +
190
+ 'a person must act in the editor; tell the user, then poll again. Read-only.',
191
+ inputSchema: RUN_STATUS_SCHEMA,
192
+ readOnly: true,
193
+ consequential: false
194
+ });
195
+ }
196
+ }
197
+ return out;
198
+ }
199
+ // ============================================================================
200
+ // createToolRuntime
201
+ // ============================================================================
202
+ /**
203
+ * Build the runtime for one editor instance. Pure of the WebMCP API: it
204
+ * touches no `document.modelContext`, so it serves the chat panel as well as
205
+ * the registration. Dispose it when the caller goes away; a disposed runtime
206
+ * answers every call with `DETACHED`.
207
+ */
208
+ export function createToolRuntime(options) {
209
+ const { instance } = options;
210
+ const hooks = options.hooks ?? {};
211
+ let disposed = false;
212
+ const nodeTypes = () => {
213
+ const source = options.nodeTypes;
214
+ if (source === undefined)
215
+ return instance.nodeTypes.current;
216
+ return typeof source === 'function' ? source() : source;
217
+ };
218
+ const editorName = () => instance.workflow.current?.name ?? instance.id;
219
+ const gate = options.gate ??
220
+ createApprovalGate(options.approval ?? 'confirm', {
221
+ container: options.container,
222
+ editorName,
223
+ messages: options.messages,
224
+ rememberEdits: options.rememberEdits
225
+ });
226
+ const ownsGate = !options.gate;
227
+ const gateRequest = (tool) => {
228
+ const title = options.dialogTitle?.(editorName());
229
+ return title === undefined ? { tool } : { tool, title };
230
+ };
231
+ const onUIAction = options.onUIAction;
232
+ const descriptors = buildToolDescriptors({ view: Boolean(onUIAction) });
233
+ const hostTools = buildHostToolDescriptors(hooks);
234
+ const byVerb = new Map(descriptors.map((d) => [d.verb, d]));
235
+ const hostByVerb = new Map(hostTools.map((d) => [d.verb, d]));
236
+ const detached = () => errorResult('DETACHED', 'This editor is no longer available');
237
+ // ---- editor tools -------------------------------------------------------
238
+ function toCommands(descriptor, input) {
239
+ try {
240
+ return { commands: descriptor.toCommands(validateToolArgs(descriptor.inputSchema, input)) };
241
+ }
242
+ catch (err) {
243
+ if (err instanceof ToolArgumentError) {
244
+ return { error: errorResult('INVALID_ARGUMENTS', err.message) };
245
+ }
246
+ throw err;
247
+ }
248
+ }
249
+ async function runDescriptor(descriptor, input) {
250
+ if (disposed)
251
+ return detached();
252
+ const mapped = toCommands(descriptor, input);
253
+ if ('error' in mapped)
254
+ return mapped.error;
255
+ const { commands, skipped } = applyLayoutOptOut(mapped.commands);
256
+ if (commands.length === 0) {
257
+ return text({
258
+ ok: true,
259
+ results: [],
260
+ skipped: skipped.map((c) => ({ type: c.type, reason: LAYOUT_SKIPPED })),
261
+ completedCount: 0,
262
+ totalCount: 0
263
+ });
264
+ }
265
+ const context = createStoreCommandContext(nodeTypes(), onUIAction, instance);
266
+ if (!context)
267
+ return errorResult('NO_WORKFLOW', 'No workflow is loaded in this editor');
268
+ // D3: reads and view changes run; document changes wait for the gate.
269
+ if (needsApproval(commands)) {
270
+ let approved;
271
+ try {
272
+ approved = await gate.request(commands, gateRequest(descriptor.verb));
273
+ }
274
+ catch (err) {
275
+ if (err instanceof GateBusyError)
276
+ return errorResult('BUSY', err.message);
277
+ throw err;
278
+ }
279
+ if (!approved)
280
+ return errorResult('REJECTED', 'The user rejected the change');
281
+ if (disposed)
282
+ return detached();
283
+ }
284
+ // Every call is one transaction and one undo step, like the chat panel.
285
+ const batch = executeBatch(commands, context);
286
+ if (commands.length === 1 && descriptor.verb !== 'batch' && skipped.length === 0) {
287
+ const only = batch.results[0];
288
+ return text(stripResult(only), !only.ok);
289
+ }
290
+ return text({
291
+ ok: batch.ok,
292
+ results: batch.results.map(stripResult),
293
+ ...(skipped.length > 0
294
+ ? { skipped: skipped.map((c) => ({ type: c.type, reason: LAYOUT_SKIPPED })) }
295
+ : {}),
296
+ completedCount: batch.completedCount,
297
+ totalCount: batch.totalCount,
298
+ ...(batch.ok ? {} : { error: batch.error, rolledBack: true })
299
+ }, !batch.ok);
300
+ }
301
+ // ---- host tools: save, run, run_status --------------------------------
302
+ /**
303
+ * The host's word on what the user may do with the workflow, when the
304
+ * payload it loaded carried one. `undefined` means the host said nothing —
305
+ * proceed and let the server decide (D3: the server is the authority; the
306
+ * client only pre-empts).
307
+ */
308
+ function workflowCan(key) {
309
+ return instance.workflow.current?.can?.[key];
310
+ }
311
+ function validateOrError(schema, input) {
312
+ try {
313
+ return validateToolArgs(schema, input);
314
+ }
315
+ catch (err) {
316
+ if (err instanceof ToolArgumentError)
317
+ return errorResult('INVALID_ARGUMENTS', err.message);
318
+ throw err;
319
+ }
320
+ }
321
+ const isToolResult = (v) => typeof v === 'object' && v !== null && 'content' in v;
322
+ /** The gate, for a host tool with no commands of its own. */
323
+ async function askHostGate(tool) {
324
+ let approved;
325
+ try {
326
+ approved = await gate.request([], gateRequest(tool));
327
+ }
328
+ catch (err) {
329
+ if (err instanceof GateBusyError)
330
+ return errorResult('BUSY', err.message);
331
+ throw err;
332
+ }
333
+ if (!approved)
334
+ return errorResult('REJECTED', 'The user rejected the change');
335
+ if (disposed)
336
+ return detached();
337
+ return null;
338
+ }
339
+ /**
340
+ * `save` persists the workflow via the host's `onSave`. It has no commands
341
+ * of its own — nothing for `executeBatch` to run — so it is gated directly
342
+ * rather than going through the command pipeline.
343
+ */
344
+ async function runSave(onSave, input) {
345
+ if (disposed)
346
+ return detached();
347
+ const args = validateOrError(EMPTY_SCHEMA, input);
348
+ if (isToolResult(args))
349
+ return args;
350
+ if (!instance.workflow.current) {
351
+ return errorResult('NO_WORKFLOW', 'No workflow is loaded in this editor');
352
+ }
353
+ if (workflowCan('save') === false) {
354
+ return errorResult('FORBIDDEN', 'Saving this workflow is not permitted');
355
+ }
356
+ const refused = await askHostGate('save');
357
+ if (refused)
358
+ return refused;
359
+ let envelope;
360
+ try {
361
+ envelope = await onSave();
362
+ }
363
+ catch (err) {
364
+ const message = describeError(err);
365
+ if (!isConflictError(err))
366
+ return errorResult('SAVE_FAILED', message);
367
+ // The server's own wording usually already says to reload; add the hint
368
+ // only when it does not, so the agent is not told twice.
369
+ const hint = /reload/i.test(message)
370
+ ? ''
371
+ : ' The workflow changed on the server since it was loaded; reload the page before saving.';
372
+ return errorResult('CONFLICT', `${message}${hint}`);
373
+ }
374
+ if (envelope)
375
+ return envelopeResult(envelope, 'Workflow saved');
376
+ return text({ ok: true, message: 'Workflow saved' });
377
+ }
378
+ /** `run` starts a run through the host's `onRun`; gated like `save`. */
379
+ async function runRun(onRun, input) {
380
+ if (disposed)
381
+ return detached();
382
+ const args = validateOrError(RUN_SCHEMA, input);
383
+ if (isToolResult(args))
384
+ return args;
385
+ if (!instance.workflow.current) {
386
+ return errorResult('NO_WORKFLOW', 'No workflow is loaded in this editor');
387
+ }
388
+ if (workflowCan('run') === false) {
389
+ return errorResult('FORBIDDEN', 'Running this workflow is not permitted');
390
+ }
391
+ const refused = await askHostGate('run');
392
+ if (refused)
393
+ return refused;
394
+ let envelope;
395
+ try {
396
+ envelope = await onRun(args.inputs ?? {});
397
+ }
398
+ catch (err) {
399
+ return errorResult('RUN_FAILED', err instanceof Error ? err.message : String(err));
400
+ }
401
+ return envelopeResult(envelope, 'Run started');
402
+ }
403
+ /**
404
+ * `run_status` is a read: never gated. A paused run comes back `ok` with
405
+ * `code: 'PENDING'` and the pause's node and message — a person must act in
406
+ * the UI; no tool answers an interrupt (D8).
407
+ */
408
+ async function runRunStatus(onRunStatus, input) {
409
+ if (disposed)
410
+ return detached();
411
+ const args = validateOrError(RUN_STATUS_SCHEMA, input);
412
+ if (isToolResult(args))
413
+ return args;
414
+ let envelope;
415
+ try {
416
+ envelope = await onRunStatus(args.runId);
417
+ }
418
+ catch (err) {
419
+ return errorResult('STATUS_FAILED', err instanceof Error ? err.message : String(err));
420
+ }
421
+ if (envelope.ok && envelope.data?.status === 'paused' && !envelope.code) {
422
+ const p = envelope.data.pending;
423
+ const where = p?.nodeId ? ` at node ${p.nodeId}` : '';
424
+ const why = p?.message
425
+ ? `: ${p.message}`
426
+ : envelope.data.pausedReason
427
+ ? ` (${envelope.data.pausedReason})`
428
+ : '';
429
+ return envelopeResult({
430
+ ...envelope,
431
+ code: 'PENDING',
432
+ message: envelope.message ??
433
+ `Run ${envelope.data.runId} is paused${where}${why}. A person must act in the editor; tell the user and poll run_status again.`
434
+ }, 'Run paused');
435
+ }
436
+ return envelopeResult(envelope, envelope.data ? `Run ${envelope.data.runId}: ${envelope.data.status}` : 'Run status');
437
+ }
438
+ // ---- dispatch -----------------------------------------------------------
439
+ async function runTool(name, input) {
440
+ if (disposed)
441
+ return detached();
442
+ const descriptor = byVerb.get(name);
443
+ if (descriptor)
444
+ return runDescriptor(descriptor, input);
445
+ if (hostByVerb.has(name)) {
446
+ if (name === 'save' && hooks.onSave)
447
+ return runSave(hooks.onSave, input);
448
+ if (name === 'run' && hooks.onRun)
449
+ return runRun(hooks.onRun, input);
450
+ if (name === 'run_status' && hooks.onRunStatus)
451
+ return runRunStatus(hooks.onRunStatus, input);
452
+ }
453
+ return errorResult('UNKNOWN_TOOL', `No tool named "${name}". Available: ${[...byVerb.keys(), ...hostByVerb.keys()].join(', ')}.`);
454
+ }
455
+ function preview(name, input) {
456
+ const host = hostByVerb.get(name);
457
+ if (host) {
458
+ const mutating = !host.readOnly;
459
+ return {
460
+ commands: [],
461
+ skipped: [],
462
+ mutating,
463
+ consequential: host.consequential,
464
+ asks: gate.asks && mutating
465
+ };
466
+ }
467
+ const descriptor = byVerb.get(name);
468
+ if (!descriptor)
469
+ return null;
470
+ const mapped = toCommands(descriptor, input);
471
+ if ('error' in mapped)
472
+ return null;
473
+ const { commands, skipped } = applyLayoutOptOut(mapped.commands);
474
+ const mutating = needsApproval(commands);
475
+ return {
476
+ commands,
477
+ skipped,
478
+ mutating,
479
+ consequential: false,
480
+ asks: gate.asks && mutating && !gate.editsPreApproved
481
+ };
482
+ }
483
+ return {
484
+ descriptors,
485
+ hostTools,
486
+ gate,
487
+ runTool,
488
+ preview,
489
+ get disposed() {
490
+ return disposed;
491
+ },
492
+ dispose() {
493
+ if (disposed)
494
+ return;
495
+ disposed = true;
496
+ if (ownsGate)
497
+ gate.dispose();
498
+ }
499
+ };
500
+ }
@@ -16,6 +16,8 @@
16
16
  */
17
17
  import type { Command, UIAction } from '../commands/types.js';
18
18
  import type { NodeMetadata } from '../types/index.js';
19
+ import type { FlowDropInstance } from '../stores/instanceContainer.svelte.js';
20
+ import type { ApprovalGate } from './gate.js';
19
21
  import type { MessagesOverride } from '../messages/types.js';
20
22
  /** One property of a tool's input schema. */
21
23
  export interface ToolSchemaProperty {
@@ -250,6 +252,96 @@ export interface WebMCPOptions {
250
252
  export type WebMCPMountOptions = Omit<WebMCPOptions, 'nodeTypes' | 'onUIAction' | 'modelContext'> & {
251
253
  nodeTypes?: WebMCPOptions['nodeTypes'];
252
254
  };
255
+ /** The host hooks behind the `save`, `run` and `run_status` tools. */
256
+ export type HostHooks = Pick<WebMCPOptions, 'onSave' | 'onRun' | 'onRunStatus'>;
257
+ /**
258
+ * One host tool (`save`, `run`, `run_status`) as the runtime offers it. Like a
259
+ * {@link ToolDescriptor} but without `toCommands`: these tools run a hook,
260
+ * not commands.
261
+ */
262
+ export interface HostToolDescriptor {
263
+ verb: 'save' | 'run' | 'run_status';
264
+ description: string;
265
+ inputSchema: ToolInputSchema;
266
+ readOnly: boolean;
267
+ /** Never covered by "don't ask again for edits"; always asks. */
268
+ consequential: boolean;
269
+ }
270
+ /**
271
+ * What a tool call would do, before it runs — for a transcript or a dialog.
272
+ * Computed the way `runTool` will act: the layout opt-out is already applied
273
+ * and `asks` reflects the gate's current state, so a caller announcing the
274
+ * call announces what actually happens.
275
+ */
276
+ export interface ToolPreview {
277
+ /** The commands the call will run; empty for a host tool. */
278
+ commands: Command[];
279
+ /** Layout commands the opt-out will skip (`chatAllowLayoutChanges` off). */
280
+ skipped: Command[];
281
+ /** True when the call passes through the approval gate. */
282
+ mutating: boolean;
283
+ /** True for `save` and `run`. */
284
+ consequential: boolean;
285
+ /**
286
+ * True when the call will wait on the gate's decision — a mutating call
287
+ * the person has not pre-approved, or a consequential one — under a policy
288
+ * that asks at all (`approval: 'auto'` never does).
289
+ */
290
+ asks: boolean;
291
+ }
292
+ export interface ToolRuntimeOptions {
293
+ instance: FlowDropInstance;
294
+ /** See {@link WebMCPOptions.nodeTypes}. Defaults to the instance's list. */
295
+ nodeTypes?: NodeMetadata[] | (() => NodeMetadata[]);
296
+ /** See {@link WebMCPOptions.onUIAction}. Without it there is no `view` tool. */
297
+ onUIAction?: (action: UIAction) => void;
298
+ /** Host hooks; each present hook adds its tool. */
299
+ hooks?: HostHooks;
300
+ /**
301
+ * An existing gate to ask, e.g. the registration's. When omitted the
302
+ * runtime creates one from `approval`, `container`, `messages` and
303
+ * `rememberEdits` and disposes it with itself.
304
+ */
305
+ gate?: ApprovalGate;
306
+ approval?: WebMCPApproval;
307
+ container?: HTMLElement;
308
+ messages?: MessagesOverride | (() => MessagesOverride);
309
+ rememberEdits?: boolean;
310
+ /**
311
+ * The approval dialog's title for this runtime's calls, given the editor
312
+ * name — who is asking. Defaults to the gate's WebMCP wording. Lets two
313
+ * runtimes share one gate and still say which surface wants the change.
314
+ */
315
+ dialogTitle?: (editorName: string) => string;
316
+ }
317
+ /**
318
+ * The tool runtime: every editor tool and host tool of one editor instance
319
+ * behind a single `runTool(name, input)`. Built by `createToolRuntime`.
320
+ */
321
+ export interface ToolRuntime {
322
+ /** Editor tools (commands), in registration order. */
323
+ readonly descriptors: readonly ToolDescriptor[];
324
+ /** Host tools present for the supplied hooks, in registration order. */
325
+ readonly hostTools: readonly HostToolDescriptor[];
326
+ /** The gate mutating calls pass through. */
327
+ readonly gate: ApprovalGate;
328
+ /**
329
+ * Run a tool by its bare verb (`add_node`, `batch`, `save`, …): validate,
330
+ * map, gate, execute. Never throws for a bad call — argument errors, a
331
+ * rejected dialog, an unknown name all come back as an `isError` result the
332
+ * model can read. Throws only for a bug.
333
+ */
334
+ runTool(name: string, input: unknown): Promise<ToolResult>;
335
+ /**
336
+ * What `runTool(name, input)` would do, without doing it. `null` for an
337
+ * unknown tool or arguments the schema refuses.
338
+ */
339
+ preview(name: string, input: unknown): ToolPreview | null;
340
+ /** True after `dispose()`; every later call answers `DETACHED`. */
341
+ readonly disposed: boolean;
342
+ /** Dismiss any open dialog (as a rejection) and refuse further calls. */
343
+ dispose(): void;
344
+ }
253
345
  /** Returned by `attachWebMCP`. */
254
346
  export interface WebMCPHandle {
255
347
  /**
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.7.0",
6
+ "version": "2.8.0",
7
7
  "author": "Shibin Das (D34dMan)",
8
8
  "bugs": {
9
9
  "url": "https://github.com/flowdrop-io/flowdrop/issues"