@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.
@@ -36,7 +36,8 @@ export interface SetConfigCommand {
36
36
  export interface GetConfigCommand {
37
37
  type: 'get_config';
38
38
  nodeId: string;
39
- key: string;
39
+ /** One key; omit to read every value together with the node's config schema. */
40
+ key?: string;
40
41
  }
41
42
  export interface ConnectCommand {
42
43
  type: 'connect';
@@ -65,6 +66,16 @@ export interface ListEdgesCommand {
65
66
  export interface ListTypesCommand {
66
67
  type: 'list_types';
67
68
  }
69
+ /** Describe one node type — ports, config schema, defaults — before adding it. */
70
+ export interface DescribeTypeCommand {
71
+ type: 'describe_type';
72
+ nodeTypeId: string;
73
+ }
74
+ /** Find node types by a case-insensitive substring of id, name, description or tags. */
75
+ export interface SearchTypesCommand {
76
+ type: 'search_types';
77
+ query: string;
78
+ }
68
79
  export interface InfoCommand {
69
80
  type: 'info';
70
81
  nodeId: string;
@@ -136,7 +147,7 @@ export interface CanvasResetViewCommand {
136
147
  type: 'canvas_reset_view';
137
148
  }
138
149
  /** Discriminated union of all commands */
139
- export type Command = AddNodeCommand | DeleteNodeCommand | RenameNodeCommand | SetConfigCommand | GetConfigCommand | ConnectCommand | DisconnectPortsCommand | DisconnectNodeCommand | ListNodesCommand | ListEdgesCommand | ListTypesCommand | InfoCommand | UndoCommand | RedoCommand | ConfigOpenCommand | SelectNodeCommand | HelpCommand | ClearCommand | SwapNodeCommand | MoveNodeCommand | AutoLayoutCommand | BeautifyLayoutCommand | CanvasFitViewCommand | CanvasZoomInCommand | CanvasZoomOutCommand | CanvasZoomToCommand | CanvasPanToCommand | CanvasResetViewCommand;
150
+ export type Command = AddNodeCommand | DeleteNodeCommand | RenameNodeCommand | SetConfigCommand | GetConfigCommand | ConnectCommand | DisconnectPortsCommand | DisconnectNodeCommand | ListNodesCommand | ListEdgesCommand | ListTypesCommand | DescribeTypeCommand | SearchTypesCommand | InfoCommand | UndoCommand | RedoCommand | ConfigOpenCommand | SelectNodeCommand | HelpCommand | ClearCommand | SwapNodeCommand | MoveNodeCommand | AutoLayoutCommand | BeautifyLayoutCommand | CanvasFitViewCommand | CanvasZoomInCommand | CanvasZoomOutCommand | CanvasZoomToCommand | CanvasPanToCommand | CanvasResetViewCommand;
140
151
  export type ParseResult = {
141
152
  ok: true;
142
153
  command: Command;
@@ -145,7 +156,9 @@ export type ParseResult = {
145
156
  error: string;
146
157
  input: string;
147
158
  };
148
- export type CommandErrorCode = 'NODE_NOT_FOUND' | 'NODE_TYPE_NOT_FOUND' | 'PORT_NOT_FOUND' | 'EDGE_NOT_FOUND' | 'INVALID_CONNECTION' | 'CYCLE_DETECTED' | 'NO_WORKFLOW' | 'PARSE_ERROR' | 'UNKNOWN_COMMAND' | 'CONFIG_KEY_NOT_FOUND' | 'CONFIG_VALIDATION_ERROR' | 'UNDO_UNAVAILABLE' | 'REDO_UNAVAILABLE';
159
+ export type CommandErrorCode = 'NODE_NOT_FOUND' | 'NODE_TYPE_NOT_FOUND' | 'PORT_NOT_FOUND' | 'EDGE_NOT_FOUND' | 'INVALID_CONNECTION' | 'CYCLE_DETECTED' | 'NO_WORKFLOW' | 'PARSE_ERROR' | 'UNKNOWN_COMMAND' | 'CONFIG_KEY_NOT_FOUND'
160
+ /** search_types with a blank query — use list_types for the whole catalog. */
161
+ | 'EMPTY_QUERY' | 'CONFIG_VALIDATION_ERROR' | 'UNDO_UNAVAILABLE' | 'REDO_UNAVAILABLE';
149
162
  /** Result data for add_node — nodeId is DSL-format short ID (e.g. "llm_node.1") */
150
163
  export interface AddNodeResultData {
151
164
  nodeId: string;
@@ -174,13 +187,54 @@ export interface ListEdgesResultData {
174
187
  targetPort: string;
175
188
  }>;
176
189
  }
190
+ /** One row of list_types / search_types — `typeId` is the short id add_node accepts. */
191
+ export interface TypeSummary {
192
+ typeId: string;
193
+ name: string;
194
+ category: string;
195
+ description?: string;
196
+ tags?: string[];
197
+ }
177
198
  /** Result data for list_types — type IDs are short names usable with add command */
178
199
  export interface ListTypesResultData {
179
- types: Array<{
180
- typeId: string;
181
- name: string;
182
- category: string;
183
- }>;
200
+ types: TypeSummary[];
201
+ }
202
+ /** Result data for search_types — the matching rows, in catalog order */
203
+ export interface SearchTypesResultData {
204
+ query: string;
205
+ types: TypeSummary[];
206
+ }
207
+ /** One config key as described by describe_type / get_config */
208
+ export interface ConfigKeyDescription {
209
+ key: string;
210
+ /** JSON Schema type — a literal, or a list when the schema declares several. */
211
+ type?: string | string[];
212
+ title?: string;
213
+ description?: string;
214
+ enum?: unknown[];
215
+ default?: unknown;
216
+ required?: boolean;
217
+ }
218
+ /** One port as described by describe_type */
219
+ export interface PortDescription {
220
+ portId: string;
221
+ name: string;
222
+ dataType: string;
223
+ required?: boolean;
224
+ description?: string;
225
+ }
226
+ /**
227
+ * Result data for describe_type — everything an agent needs to know about a
228
+ * node type before adding one. `confirmation`, `can` and `agent` are passed
229
+ * through from the host's payload untouched when present.
230
+ */
231
+ export interface DescribeTypeResultData extends TypeSummary {
232
+ inputs: PortDescription[];
233
+ outputs: PortDescription[];
234
+ config: ConfigKeyDescription[];
235
+ confirmation?: NodeMetadata['confirmation'];
236
+ can?: NodeMetadata['can'];
237
+ agent?: NodeMetadata['agent'];
184
238
  }
185
239
  /** Result data for info command — all IDs are DSL-format short IDs */
186
240
  export interface InfoResultData {
@@ -210,12 +264,21 @@ export interface InfoResultData {
210
264
  localPort: string;
211
265
  }>;
212
266
  }
213
- /** Result data for get_config command */
214
- export interface GetConfigResultData {
267
+ /** get_config with a key: that key's value and its schema entry, if declared. */
268
+ export interface GetConfigKeyResultData {
215
269
  nodeId: string;
216
270
  key: string;
217
271
  value: unknown;
272
+ schema?: ConfigKeyDescription;
273
+ }
274
+ /** get_config without a key: every current value and the whole config schema. */
275
+ export interface GetConfigAllResultData {
276
+ nodeId: string;
277
+ values: Record<string, unknown>;
278
+ schema: ConfigKeyDescription[];
218
279
  }
280
+ /** Result data for get_config — narrow on `'key' in data`. */
281
+ export type GetConfigResultData = GetConfigKeyResultData | GetConfigAllResultData;
219
282
  /** Result data for help command */
220
283
  export interface HelpResultData {
221
284
  commands: Array<{
@@ -231,11 +294,13 @@ export interface SetConfigResultData {
231
294
  value: unknown;
232
295
  /** Validation warnings (non-blocking unless strict mode) */
233
296
  warnings?: Array<{
234
- type: 'enum' | 'type_mismatch';
297
+ type: 'enum' | 'type_mismatch' | 'unknown_key';
235
298
  message: string;
236
299
  allowedValues?: unknown[];
237
300
  expectedType?: string;
238
301
  actualType?: string;
302
+ /** For `unknown_key`: the keys the node's config schema does declare. */
303
+ knownKeys?: string[];
239
304
  }>;
240
305
  }
241
306
  /** Result data for swap_node command */
@@ -252,7 +317,7 @@ export interface SwapNodeResultData {
252
317
  configReset: string[];
253
318
  }
254
319
  /** Result data types union for typed access */
255
- export type CommandResultData = AddNodeResultData | ListNodesResultData | ListEdgesResultData | ListTypesResultData | InfoResultData | GetConfigResultData | SetConfigResultData | HelpResultData | SwapNodeResultData;
320
+ export type CommandResultData = AddNodeResultData | ListNodesResultData | ListEdgesResultData | ListTypesResultData | SearchTypesResultData | DescribeTypeResultData | InfoResultData | GetConfigResultData | SetConfigResultData | HelpResultData | SwapNodeResultData;
256
321
  /** Successful command result */
257
322
  export interface CommandResultOk {
258
323
  ok: true;
@@ -16,6 +16,8 @@
16
16
  type ListNodesResultData,
17
17
  type ListEdgesResultData,
18
18
  type ListTypesResultData,
19
+ type SearchTypesResultData,
20
+ type DescribeTypeResultData,
19
21
  type InfoResultData,
20
22
  type HelpResultData
21
23
  } from '../../commands/index.js';
@@ -29,6 +31,8 @@
29
31
  formatListNodes,
30
32
  formatListEdges,
31
33
  formatListTypes,
34
+ formatSearchTypes,
35
+ formatDescribeType,
32
36
  formatInfo,
33
37
  formatHelp
34
38
  } from './formatters.js';
@@ -65,6 +69,10 @@
65
69
  return formatListEdges(result.data as ListEdgesResultData);
66
70
  case 'list_types':
67
71
  return formatListTypes(result.data as ListTypesResultData);
72
+ case 'search_types':
73
+ return formatSearchTypes(result.data as SearchTypesResultData);
74
+ case 'describe_type':
75
+ return formatDescribeType(result.data as DescribeTypeResultData);
68
76
  case 'info':
69
77
  return formatInfo(result.data as InfoResultData);
70
78
  case 'help':
@@ -2,7 +2,7 @@
2
2
  * Pure formatting functions for rich command result display.
3
3
  * Converts CommandResult data into aligned table strings for console output.
4
4
  */
5
- import type { ListNodesResultData, ListEdgesResultData, ListTypesResultData, InfoResultData, HelpResultData } from '../../commands/types.js';
5
+ import type { ListNodesResultData, ListEdgesResultData, ListTypesResultData, SearchTypesResultData, DescribeTypeResultData, InfoResultData, HelpResultData } from '../../commands/types.js';
6
6
  /**
7
7
  * Formats list nodes result as an aligned table: ID, Label, Type.
8
8
  */
@@ -15,6 +15,14 @@ export declare function formatListEdges(data: ListEdgesResultData): string;
15
15
  * Formats list types result as a table: Type ID, Name, Category.
16
16
  */
17
17
  export declare function formatListTypes(data: ListTypesResultData): string;
18
+ /**
19
+ * Formats search types result: the same table as list types, or a hint.
20
+ */
21
+ export declare function formatSearchTypes(data: SearchTypesResultData): string;
22
+ /**
23
+ * Formats describe type result: header, ports and config schema sections.
24
+ */
25
+ export declare function formatDescribeType(data: DescribeTypeResultData): string;
18
26
  /**
19
27
  * Formats info result as structured output with header fields,
20
28
  * config section, ports section, and edges section.
@@ -51,6 +51,60 @@ export function formatListTypes(data) {
51
51
  const rows = data.types.map((t) => [t.typeId, t.name, t.category]);
52
52
  return formatTable(['Type ID', 'Name', 'Category'], rows);
53
53
  }
54
+ /**
55
+ * Formats search types result: the same table as list types, or a hint.
56
+ */
57
+ export function formatSearchTypes(data) {
58
+ if (data.types.length === 0) {
59
+ return `No node type matches "${data.query}"`;
60
+ }
61
+ return formatListTypes({ types: data.types });
62
+ }
63
+ /**
64
+ * Formats describe type result: header, ports and config schema sections.
65
+ */
66
+ export function formatDescribeType(data) {
67
+ const lines = [];
68
+ lines.push(`Type: ${data.typeId}`);
69
+ lines.push(`Name: ${data.name}`);
70
+ lines.push(`Category: ${data.category}`);
71
+ if (data.description)
72
+ lines.push(`Description: ${data.description}`);
73
+ if (data.tags && data.tags.length > 0)
74
+ lines.push(`Tags: ${data.tags.join(', ')}`);
75
+ if (data.confirmation)
76
+ lines.push(`Confirmation: ${data.confirmation.policy}`);
77
+ lines.push('');
78
+ lines.push('Inputs:');
79
+ if (data.inputs.length === 0)
80
+ lines.push(' (none)');
81
+ for (const p of data.inputs) {
82
+ lines.push(` ${p.portId} (${p.dataType})${p.required ? ' required' : ''}${p.description ? ` — ${p.description}` : ''}`);
83
+ }
84
+ lines.push('');
85
+ lines.push('Outputs:');
86
+ if (data.outputs.length === 0)
87
+ lines.push(' (none)');
88
+ for (const p of data.outputs) {
89
+ lines.push(` ${p.portId} (${p.dataType})${p.description ? ` — ${p.description}` : ''}`);
90
+ }
91
+ lines.push('');
92
+ lines.push('Config:');
93
+ if (data.config.length === 0)
94
+ lines.push(' (none)');
95
+ for (const c of data.config) {
96
+ const type = Array.isArray(c.type) ? c.type.join('|') : (c.type ?? 'any');
97
+ const parts = [` ${c.key} (${type})`];
98
+ if (c.required)
99
+ parts.push('required');
100
+ if (c.enum)
101
+ parts.push(`one of ${c.enum.map((v) => JSON.stringify(v)).join(', ')}`);
102
+ if (c.default !== undefined)
103
+ parts.push(`default ${JSON.stringify(c.default)}`);
104
+ lines.push(parts.join(' ') + (c.description ? ` — ${c.description}` : ''));
105
+ }
106
+ return lines.join('\n');
107
+ }
54
108
  /**
55
109
  * Formats info result as structured output with header fields,
56
110
  * config section, ports section, and edges section.
@@ -50,7 +50,7 @@ export { resolveScopeToKey, keyToScope, generateDefaultUISchema, collectReferenc
50
50
  export { DEFAULT_PORT_CONFIG } from '../config/defaultPortConfig.js';
51
51
  export { defaultEndpointConfig, createEndpointConfig } from '../config/endpoints.js';
52
52
  export { generateNodeId, extractConfigDefaults } from '../utils/nodeIds.js';
53
- export type { AddNodeCommand, DeleteNodeCommand, RenameNodeCommand, SetConfigCommand, GetConfigCommand, ConnectCommand, DisconnectPortsCommand, DisconnectNodeCommand, ListNodesCommand, ListEdgesCommand, ListTypesCommand, InfoCommand, UndoCommand, RedoCommand, ConfigOpenCommand, SelectNodeCommand, HelpCommand, ClearCommand, SwapNodeCommand, MoveNodeCommand, AutoLayoutCommand, Command, ParseResult, CommandErrorCode, AddNodeResultData, ListNodesResultData, ListEdgesResultData, ListTypesResultData, InfoResultData, GetConfigResultData, SetConfigResultData, HelpResultData, CommandResultData, CommandResultOk, CommandResultError, CommandResult, BatchResult, UIAction, CommandDispatch, CommandContext } from '../commands/index.js';
53
+ export type { AddNodeCommand, DeleteNodeCommand, RenameNodeCommand, SetConfigCommand, GetConfigCommand, ConnectCommand, DisconnectPortsCommand, DisconnectNodeCommand, ListNodesCommand, ListEdgesCommand, ListTypesCommand, DescribeTypeCommand, SearchTypesCommand, InfoCommand, UndoCommand, RedoCommand, ConfigOpenCommand, SelectNodeCommand, HelpCommand, ClearCommand, SwapNodeCommand, MoveNodeCommand, AutoLayoutCommand, Command, ParseResult, CommandErrorCode, AddNodeResultData, ListNodesResultData, ListEdgesResultData, ListTypesResultData, SearchTypesResultData, DescribeTypeResultData, TypeSummary, ConfigKeyDescription, PortDescription, InfoResultData, GetConfigResultData, GetConfigKeyResultData, GetConfigAllResultData, SetConfigResultData, HelpResultData, CommandResultData, CommandResultOk, CommandResultError, CommandResult, BatchResult, UIAction, CommandDispatch, CommandContext } from '../commands/index.js';
54
54
  export { buildTypeMap, parseCommand, executeCommand, toShortId, toShortTypeId, resolveNode, executeBatch, computeAutoPosition } from '../commands/index.js';
55
55
  export { WorkflowAdapter } from '../adapters/WorkflowAdapter.js';
56
56
  export type { StandardNode, StandardEdge, StandardWorkflow, WorkflowExecutionResult, WorkflowValidationResult } from '../adapters/WorkflowAdapter.js';
@@ -601,5 +601,38 @@ export declare const defaultMessages: {
601
601
  }) => string;
602
602
  readonly reject: "Reject";
603
603
  readonly apply: "Apply";
604
+ readonly saveLine: ({ name }: {
605
+ name: string;
606
+ }) => string;
607
+ readonly saveHint: "Writes the workflow to the server. This cannot be undone from the editor.";
608
+ readonly runLine: ({ name }: {
609
+ name: string;
610
+ }) => string;
611
+ readonly runHint: "Starts a run of the saved workflow. Unsaved changes are not part of it.";
612
+ /** One clause per kind of change; joined into the batch summary. */
613
+ readonly summaryAdds: ({ count }: {
614
+ count: number;
615
+ }) => string;
616
+ readonly summaryDeletes: ({ count }: {
617
+ count: number;
618
+ }) => string;
619
+ readonly summaryConnects: ({ count }: {
620
+ count: number;
621
+ }) => string;
622
+ readonly summaryDisconnects: ({ count }: {
623
+ count: number;
624
+ }) => string;
625
+ readonly summaryConfigs: ({ count }: {
626
+ count: number;
627
+ }) => string;
628
+ readonly summaryOther: ({ count }: {
629
+ count: number;
630
+ }) => string;
631
+ /** `{count} changes — adds 2 nodes, connects 1 edge. Applied together, undone together.` */
632
+ readonly batchSummary: ({ count, parts }: {
633
+ count: number;
634
+ parts: string;
635
+ }) => string;
636
+ readonly rememberEdits: "Apply further edits from any agent on this page without asking, until this page is closed";
604
637
  };
605
638
  };
@@ -502,6 +502,20 @@ export const defaultMessages = {
502
502
  confirmTitle: ({ name }) => `A browser agent wants to change “${name}”`,
503
503
  confirmCount: ({ count }) => `${count === 1 ? '1 change' : `${count} changes`} — applied together, undone together.`,
504
504
  reject: 'Reject',
505
- apply: 'Apply'
505
+ apply: 'Apply',
506
+ saveLine: ({ name }) => `Save “${name}” to the server`,
507
+ saveHint: 'Writes the workflow to the server. This cannot be undone from the editor.',
508
+ runLine: ({ name }) => `Run “${name}” on the server`,
509
+ runHint: 'Starts a run of the saved workflow. Unsaved changes are not part of it.',
510
+ /** One clause per kind of change; joined into the batch summary. */
511
+ summaryAdds: ({ count }) => `adds ${count} ${count === 1 ? 'node' : 'nodes'}`,
512
+ summaryDeletes: ({ count }) => `deletes ${count} ${count === 1 ? 'node' : 'nodes'}`,
513
+ summaryConnects: ({ count }) => `connects ${count} ${count === 1 ? 'edge' : 'edges'}`,
514
+ summaryDisconnects: ({ count }) => `removes ${count} ${count === 1 ? 'edge' : 'edges'}`,
515
+ summaryConfigs: ({ count }) => `sets ${count} config ${count === 1 ? 'key' : 'keys'}`,
516
+ summaryOther: ({ count }) => `${count} other ${count === 1 ? 'change' : 'changes'}`,
517
+ /** `{count} changes — adds 2 nodes, connects 1 edge. Applied together, undone together.` */
518
+ batchSummary: ({ count, parts }) => `${count} changes — ${parts}. Applied together, undone together.`,
519
+ rememberEdits: 'Apply further edits from any agent on this page without asking, until this page is closed'
506
520
  }
507
521
  };
@@ -65,7 +65,13 @@ export interface GlobalExportOptions {
65
65
  * 6. Call onMarkAsSaved / onAfterSave hooks
66
66
  * 7. Show toast notifications (respecting features.showToasts)
67
67
  */
68
- export declare function globalSaveWorkflow(options?: GlobalSaveOptions): Promise<void>;
68
+ /**
69
+ * Resolves `true` when the workflow was written, `false` when nothing was
70
+ * saved because there was no workflow or `onBeforeSave` cancelled. A failed
71
+ * request throws. Callers that relay the outcome (the WebMCP `save` tool)
72
+ * must not read a quiet return as a save.
73
+ */
74
+ export declare function globalSaveWorkflow(options?: GlobalSaveOptions): Promise<boolean>;
69
75
  /**
70
76
  * Export the current workflow as a downloadable JSON file.
71
77
  *
@@ -73,6 +73,12 @@ async function flushPendingFormChanges() {
73
73
  * 6. Call onMarkAsSaved / onAfterSave hooks
74
74
  * 7. Show toast notifications (respecting features.showToasts)
75
75
  */
76
+ /**
77
+ * Resolves `true` when the workflow was written, `false` when nothing was
78
+ * saved because there was no workflow or `onBeforeSave` cancelled. A failed
79
+ * request throws. Callers that relay the outcome (the WebMCP `save` tool)
80
+ * must not read a quiet return as a save.
81
+ */
76
82
  export async function globalSaveWorkflow(options = {}) {
77
83
  const { eventHandlers, onMarkAsSaved, onSaved } = options;
78
84
  const features = { ...DEFAULT_FEATURES, ...options.features };
@@ -87,13 +93,13 @@ export async function globalSaveWorkflow(options = {}) {
87
93
  if (features.showToasts) {
88
94
  apiToasts.error('Save workflow', 'No workflow to save');
89
95
  }
90
- return;
96
+ return false;
91
97
  }
92
98
  // Step 2 — Allow the parent to cancel the save
93
99
  if (eventHandlers?.onBeforeSave) {
94
100
  const shouldContinue = await eventHandlers.onBeforeSave(currentWorkflow);
95
101
  if (shouldContinue === false) {
96
- return;
102
+ return false;
97
103
  }
98
104
  }
99
105
  const loadingToast = features.showToasts ? apiToasts.loading('Saving workflow') : null;
@@ -124,7 +130,10 @@ export async function globalSaveWorkflow(options = {}) {
124
130
  // Explicit key list, so every contract field must be named here:
125
131
  // omitting `interface` silently strips the declared contract on save
126
132
  // (absent means "declares no interface" to the server).
127
- ...(currentWorkflow.interface !== undefined && { interface: currentWorkflow.interface })
133
+ ...(currentWorkflow.interface !== undefined && { interface: currentWorkflow.interface }),
134
+ // The revision the editor loaded, so a server that checks it can refuse
135
+ // a stale write (409 CONFLICT) instead of letting the last write win.
136
+ ...(currentWorkflow.revision !== undefined && { revision: currentWorkflow.revision })
128
137
  };
129
138
  // Step 4 — Persist via this instance's API client.
130
139
  // id-presence (computed above) decides update vs create — never UUID-regex.
@@ -144,6 +153,10 @@ export async function globalSaveWorkflow(options = {}) {
144
153
  }
145
154
  });
146
155
  }
156
+ // Step 5b — The save minted a new revision (and may have refreshed what the
157
+ // user may do); take the server's word so the next save sends the current
158
+ // stamp rather than the one this save just superseded.
159
+ fd.workflow.acknowledgeServer({ revision: savedWorkflow.revision, can: savedWorkflow.can });
147
160
  // Step 6a — Mark dirty state as clean
148
161
  if (onMarkAsSaved) {
149
162
  onMarkAsSaved();
@@ -165,6 +178,7 @@ export async function globalSaveWorkflow(options = {}) {
165
178
  if (eventHandlers?.onAfterSave) {
166
179
  await eventHandlers.onAfterSave(savedWorkflow);
167
180
  }
181
+ return true;
168
182
  }
169
183
  catch (error) {
170
184
  if (loadingToast)
@@ -180,6 +180,16 @@ export declare class WorkflowStore {
180
180
  * Call this after a successful backend save.
181
181
  */
182
182
  markAsSaved(): void;
183
+ /**
184
+ * Take the server's word on the workflow's revision and permissions after a
185
+ * save (the load path sets them with the payload). Bookkeeping only: no history entry, no dirty flag, no
186
+ * change notification — the document the user edits is unchanged. Keys the
187
+ * server did not send are left as they were.
188
+ */
189
+ acknowledgeServer(state: {
190
+ revision?: Workflow['revision'];
191
+ can?: Workflow['can'];
192
+ }): void;
183
193
  /**
184
194
  * Set the restoring from history flag.
185
195
  *
@@ -324,6 +324,21 @@ export class WorkflowStore {
324
324
  this.#onDirtyStateChange(false);
325
325
  }
326
326
  }
327
+ /**
328
+ * Take the server's word on the workflow's revision and permissions after a
329
+ * save (the load path sets them with the payload). Bookkeeping only: no history entry, no dirty flag, no
330
+ * change notification — the document the user edits is unchanged. Keys the
331
+ * server did not send are left as they were.
332
+ */
333
+ acknowledgeServer(state) {
334
+ if (!this.#workflow)
335
+ return;
336
+ this.#workflow = {
337
+ ...this.#workflow,
338
+ ...(state.revision !== undefined && { revision: state.revision }),
339
+ ...(state.can !== undefined && { can: state.can })
340
+ };
341
+ }
327
342
  /**
328
343
  * Set the restoring from history flag.
329
344
  *
@@ -282,6 +282,12 @@
282
282
  --fd-leading-relaxed: 1.6; /* @public */
283
283
 
284
284
  /* ----- FONT FAMILIES ----- */
285
+ /* The editor inherits the host page's font. This stack is for UI the
286
+ library mounts outside the editor's subtree (the WebMCP confirm dialog
287
+ on document.body), where "inherit" means whatever the host's body has —
288
+ on Drupal admin themes, the browser's serif fallback. */
289
+ --fd-font-sans:
290
+ system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; /* @public */
285
291
  --fd-font-mono:
286
292
  ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace; /* @public */
287
293
 
@@ -171,9 +171,11 @@ export interface MountedFlowDropApp {
171
171
  */
172
172
  getWorkflow: () => Workflow | null;
173
173
  /**
174
- * Trigger save operation
174
+ * Trigger save operation. Resolves `true` when the workflow was written,
175
+ * `false` when the save was cancelled (`onBeforeSave`) or there was nothing
176
+ * to save; rejects when the request failed.
175
177
  */
176
- save: () => Promise<void>;
178
+ save: () => Promise<boolean>;
177
179
  /**
178
180
  * Trigger export operation (downloads JSON)
179
181
  */
@@ -281,18 +281,10 @@ export async function mountFlowDropApp(container, options = {}) {
281
281
  eventHandlers: eventHandlers ?? null,
282
282
  unsubscribeDraftSettings
283
283
  };
284
- // WebMCP editor tools, opt-in. Attaches in the background — mounting does
285
- // not wait for it — and detaches with the mount.
284
+ // WebMCP editor tools, opt-in. Attached below, once `mountedApp` exists —
285
+ // its default `onSave` is `mountedApp.save()`.
286
286
  let webmcpHandle;
287
287
  let destroyed = false;
288
- if (webmcp) {
289
- void attachWebMCPToMount(fd, webmcp === true ? {} : webmcp, () => destroyed).then((handle) => {
290
- if (destroyed)
291
- handle?.detach();
292
- else
293
- webmcpHandle = handle;
294
- });
295
- }
296
288
  // Create the mounted app interface
297
289
  const mountedApp = {
298
290
  instance: fd,
@@ -351,7 +343,7 @@ export async function mountFlowDropApp(container, options = {}) {
351
343
  },
352
344
  getWorkflow: () => fd.workflow.current,
353
345
  save: async () => {
354
- await globalSaveWorkflow({
346
+ return globalSaveWorkflow({
355
347
  instance: fd,
356
348
  onSaved: (saved) => {
357
349
  // globalSaveWorkflow does not write the server-assigned ID back to the
@@ -379,6 +371,28 @@ export async function mountFlowDropApp(container, options = {}) {
379
371
  return removed;
380
372
  }
381
373
  };
374
+ // WebMCP editor tools, opt-in. Attaches in the background — mounting does
375
+ // not wait for it — and detaches with the mount. Defaults `onSave` to the
376
+ // mount's own Save so a browser agent's `save` tool persists exactly like
377
+ // clicking Save does; a host that supplies its own `onSave` overrides it.
378
+ if (webmcp) {
379
+ const webmcpOptions = {
380
+ onSave: async () => (await mountedApp.save())
381
+ ? undefined
382
+ : {
383
+ ok: false,
384
+ code: 'UNAVAILABLE',
385
+ message: 'Nothing was saved: the host cancelled the save or no workflow is loaded.'
386
+ },
387
+ ...(webmcp === true ? {} : webmcp)
388
+ };
389
+ void attachWebMCPToMount(fd, webmcpOptions, () => destroyed).then((handle) => {
390
+ if (destroyed)
391
+ handle?.detach();
392
+ else
393
+ webmcpHandle = handle;
394
+ });
395
+ }
382
396
  return mountedApp;
383
397
  }
384
398
  /**
@@ -428,7 +442,7 @@ export async function mountWorkflowEditor(container, options = {}) {
428
442
  markAsSaved: () => fd.workflow.markAsSaved(),
429
443
  getWorkflow: () => fd.workflow.current,
430
444
  save: async () => {
431
- await globalSaveWorkflow({ instance: fd });
445
+ return globalSaveWorkflow({ instance: fd });
432
446
  },
433
447
  export: () => {
434
448
  globalExportWorkflow({ instance: fd });
@@ -761,6 +761,43 @@ export interface NodeMetadata {
761
761
  * Allows storing additional configuration and UI state data at the node type level
762
762
  */
763
763
  extensions?: NodeExtensions;
764
+ /**
765
+ * The host's confirmation policy for instances of this type, when the host
766
+ * publishes one: whether a run pauses for a person before this node acts.
767
+ * Surfaced to browser agents by `describe_type`; the library never reads it.
768
+ */
769
+ confirmation?: NodeConfirmation;
770
+ /**
771
+ * What the current user may do with this type, computed by the host and
772
+ * passed through untouched. `add: false` means `add_node` will be refused
773
+ * server-side; the tools pre-empt with `FORBIDDEN`.
774
+ */
775
+ can?: Record<string, boolean>;
776
+ /**
777
+ * Guidance the host writes for agents reading this type — usage notes,
778
+ * example configurations, types it is usually wired to. Surfaced verbatim by
779
+ * `describe_type`; the library never interprets it.
780
+ */
781
+ agent?: NodeAgentGuidance;
782
+ }
783
+ /**
784
+ * A host's confirmation policy for a node type (see `NodeMetadata.confirmation`).
785
+ */
786
+ export interface NodeConfirmation {
787
+ /** `ask` — a run pauses for approval before the node acts; `skip` — it does not. */
788
+ policy: 'ask' | 'skip';
789
+ /** Where the policy came from: set on the type, or derived from the plugin. */
790
+ source?: 'policy' | 'plugin' | string;
791
+ /** Controls the instance author may exercise (e.g. `waive`, `require`). */
792
+ authorControls?: string[];
793
+ /** Controls a runtime input may exercise. */
794
+ dynamicControls?: string[];
795
+ }
796
+ /** Host-written guidance for agents (see `NodeMetadata.agent`). */
797
+ export interface NodeAgentGuidance {
798
+ usage?: string;
799
+ examples?: string[];
800
+ pairsWith?: string[];
764
801
  }
765
802
  /**
766
803
  * Common base interface for all schema properties
@@ -1373,6 +1410,18 @@ export interface Workflow {
1373
1410
  config?: Record<string, unknown>;
1374
1411
  /** Public contract for callers. Absent = the workflow declares no interface. */
1375
1412
  interface?: WorkflowInterface;
1413
+ /**
1414
+ * What the current user may do with this workflow, computed by the host and
1415
+ * passed through untouched (`save`, `run`, …). The browser-agent tools
1416
+ * pre-empt with `FORBIDDEN` when a key is `false`; the server stays the
1417
+ * authority either way.
1418
+ */
1419
+ can?: Record<string, boolean>;
1420
+ /**
1421
+ * The revision the editor loaded, as the host stamps it. Sent back on save
1422
+ * so the server can refuse a stale write with `CONFLICT`.
1423
+ */
1424
+ revision?: string | number;
1376
1425
  }
1377
1426
  /**
1378
1427
  * API response types