@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.
- package/CHANGELOG.md +26 -0
- package/dist/chat/commandClassifier.d.ts +2 -1
- package/dist/chat/commandClassifier.js +4 -1
- package/dist/commands/executor.js +270 -37
- package/dist/commands/index.d.ts +1 -1
- package/dist/commands/parser.js +20 -0
- package/dist/commands/types.d.ts +77 -12
- package/dist/components/console/CommandConsole.svelte +8 -0
- package/dist/components/console/formatters.d.ts +9 -1
- package/dist/components/console/formatters.js +54 -0
- package/dist/core/index.d.ts +1 -1
- package/dist/messages/defaults.d.ts +33 -0
- package/dist/messages/defaults.js +15 -1
- package/dist/services/globalSave.d.ts +7 -1
- package/dist/services/globalSave.js +17 -3
- package/dist/stores/workflowStore.svelte.d.ts +10 -0
- package/dist/stores/workflowStore.svelte.js +15 -0
- package/dist/styles/tokens.css +6 -0
- package/dist/svelte-app.d.ts +4 -2
- package/dist/svelte-app.js +26 -12
- package/dist/types/index.d.ts +49 -0
- package/dist/webmcp/WebMCPConfirm.svelte +56 -10
- package/dist/webmcp/WebMCPConfirm.svelte.d.ts +12 -2
- package/dist/webmcp/bridge.d.ts +63 -0
- package/dist/webmcp/bridge.js +106 -0
- package/dist/webmcp/descriptors.d.ts +1 -1
- package/dist/webmcp/descriptors.js +57 -17
- package/dist/webmcp/gate.d.ts +39 -3
- package/dist/webmcp/gate.js +104 -8
- package/dist/webmcp/index.d.ts +3 -1
- package/dist/webmcp/index.js +1 -0
- package/dist/webmcp/register.js +253 -16
- package/dist/webmcp/types.d.ts +104 -2
- package/package.json +1 -1
package/dist/webmcp/gate.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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;
|
package/dist/webmcp/index.d.ts
CHANGED
|
@@ -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
|
|
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';
|
package/dist/webmcp/index.js
CHANGED
|
@@ -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';
|
package/dist/webmcp/register.js
CHANGED
|
@@ -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
|
|
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(
|
|
471
|
+
const ready = Promise.all(toolRegistrations).then(() => undefined);
|
|
235
472
|
// ---- detach -------------------------------------------------------------
|
|
236
473
|
function detach() {
|
|
237
474
|
if (!attached)
|
package/dist/webmcp/types.d.ts
CHANGED
|
@@ -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
|
|
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
|
+
"version": "2.7.0",
|
|
7
7
|
"author": "Shibin Das (D34dMan)",
|
|
8
8
|
"bugs": {
|
|
9
9
|
"url": "https://github.com/flowdrop-io/flowdrop/issues"
|