@widgetic/workflows 0.2.15 → 0.2.17

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 (108) hide show
  1. package/README.md +117 -3
  2. package/dist/api/types.d.ts +17 -0
  3. package/dist/api/workflowsApi.d.ts +12 -1
  4. package/dist/api/workflowsApi.js +37 -0
  5. package/dist/assistant/assistantEvents.d.ts +44 -2
  6. package/dist/assistant/assistantEvents.js +58 -2
  7. package/dist/assistant/assistantReferences.d.ts +66 -0
  8. package/dist/assistant/assistantReferences.js +109 -0
  9. package/dist/assistant/assistantSaveMode.d.ts +15 -3
  10. package/dist/assistant/assistantSaveMode.js +16 -2
  11. package/dist/assistant/assistantSeed.d.ts +55 -0
  12. package/dist/assistant/assistantSeed.js +90 -0
  13. package/dist/assistant/assistantStream.js +81 -3
  14. package/dist/assistant/assistantSuggest.d.ts +18 -0
  15. package/dist/assistant/assistantSuggest.js +21 -0
  16. package/dist/assistant/assistantTurns.d.ts +75 -0
  17. package/dist/assistant/assistantTurns.js +56 -0
  18. package/dist/assistant/attachmentUploads.d.ts +42 -0
  19. package/dist/assistant/attachmentUploads.js +69 -0
  20. package/dist/assistant/canvasLink.d.ts +30 -0
  21. package/dist/assistant/canvasLink.js +51 -0
  22. package/dist/assistant/compositionMention.d.ts +18 -0
  23. package/dist/assistant/compositionMention.js +47 -0
  24. package/dist/assistant/liveData.d.ts +150 -0
  25. package/dist/assistant/liveData.js +286 -0
  26. package/dist/assistant/mcpMention.d.ts +20 -0
  27. package/dist/assistant/mcpMention.js +30 -0
  28. package/dist/assistant/mentionEntries.d.ts +39 -0
  29. package/dist/assistant/mentionEntries.js +69 -0
  30. package/dist/assistant/planFlow.d.ts +26 -0
  31. package/dist/assistant/planFlow.js +57 -0
  32. package/dist/assistant/templateDestinations.d.ts +37 -0
  33. package/dist/assistant/templateDestinations.js +64 -0
  34. package/dist/assistant/types.d.ts +99 -2
  35. package/dist/assistant/workflowPlanViewModel.d.ts +13 -2
  36. package/dist/assistant/workflowPlanViewModel.js +9 -1
  37. package/dist/components/Workflows.svelte +7 -1
  38. package/dist/components/WorkflowsEmptyState.svelte +8 -3
  39. package/dist/components/WorkflowsWorkspace.svelte +29 -1
  40. package/dist/components/WorkflowsWorkspace.svelte.d.ts +3 -0
  41. package/dist/components/assistant/AssistantPlanStepRow.svelte +56 -0
  42. package/dist/components/assistant/AssistantPlanStepRow.svelte.d.ts +9 -0
  43. package/dist/components/assistant/CompositionMentionMenu.svelte +135 -0
  44. package/dist/components/assistant/CompositionMentionMenu.svelte.d.ts +9 -0
  45. package/dist/components/assistant/DataPreviewCard.svelte +108 -0
  46. package/dist/components/assistant/DataPreviewCard.svelte.d.ts +7 -0
  47. package/dist/components/assistant/PlanBindingsBlock.svelte +200 -0
  48. package/dist/components/assistant/PlanBindingsBlock.svelte.d.ts +14 -0
  49. package/dist/components/assistant/TemplateProjectCard.svelte +81 -0
  50. package/dist/components/assistant/TemplateProjectCard.svelte.d.ts +14 -0
  51. package/dist/components/assistant/WorkflowAssistantPanel.svelte +1045 -147
  52. package/dist/components/assistant/WorkflowAssistantPanel.svelte.d.ts +5 -0
  53. package/dist/components/canvas/CanvasContextMenu.svelte +199 -0
  54. package/dist/components/canvas/CanvasContextMenu.svelte.d.ts +16 -0
  55. package/dist/components/canvas/CompositionNodeView.svelte +7 -2
  56. package/dist/components/canvas/ConditionNodeView.svelte +5 -1
  57. package/dist/components/canvas/HandlePoint.svelte +25 -3
  58. package/dist/components/canvas/WorkflowCanvas.svelte +351 -12
  59. package/dist/components/canvas/WorkflowCanvas.svelte.d.ts +12 -1
  60. package/dist/components/canvas/altDragDuplicateController.d.ts +29 -0
  61. package/dist/components/canvas/altDragDuplicateController.js +92 -0
  62. package/dist/components/canvas/connectionSnapController.d.ts +29 -0
  63. package/dist/components/canvas/connectionSnapController.js +182 -0
  64. package/dist/components/canvas/spacePanController.d.ts +16 -0
  65. package/dist/components/canvas/spacePanController.js +103 -0
  66. package/dist/components/editor/EditorCanvasArea.svelte +98 -4
  67. package/dist/components/editor/EditorCanvasArea.svelte.d.ts +5 -0
  68. package/dist/components/editor/EditorTopBar.svelte +53 -42
  69. package/dist/components/editor/WorkflowEditor.svelte +74 -41
  70. package/dist/components/editor/WorkflowEditor.svelte.d.ts +5 -0
  71. package/dist/components/editor/WorkflowNameControl.svelte +9 -8
  72. package/dist/components/editor/WorkflowNameControl.svelte.d.ts +3 -1
  73. package/dist/components/list/WorkflowList.svelte +50 -26
  74. package/dist/components/list/WorkflowList.svelte.d.ts +5 -0
  75. package/dist/components/panel/CompositionForm.svelte +3 -2
  76. package/dist/components/panel/CompositionPicker.svelte +15 -20
  77. package/dist/components/panel/CompositionPicker.svelte.d.ts +2 -2
  78. package/dist/components/panel/CompositionSelect.svelte +4 -4
  79. package/dist/components/panel/CompositionSelect.svelte.d.ts +2 -2
  80. package/dist/components/ui/icons.d.ts +8 -0
  81. package/dist/components/ui/icons.js +24 -1
  82. package/dist/editor/autoLayout.d.ts +38 -0
  83. package/dist/editor/autoLayout.js +403 -0
  84. package/dist/editor/blockClipboard.svelte.d.ts +9 -0
  85. package/dist/editor/blockClipboard.svelte.js +24 -0
  86. package/dist/editor/blockCopy.d.ts +39 -0
  87. package/dist/editor/blockCopy.js +137 -0
  88. package/dist/editor/canvasMenu.d.ts +45 -0
  89. package/dist/editor/canvasMenu.js +68 -0
  90. package/dist/editor/connectionSnap.d.ts +90 -0
  91. package/dist/editor/connectionSnap.js +98 -0
  92. package/dist/editor/editorState.svelte.d.ts +122 -13
  93. package/dist/editor/editorState.svelte.js +262 -22
  94. package/dist/editor/graphIssues.d.ts +5 -0
  95. package/dist/editor/graphIssues.js +18 -0
  96. package/dist/editor/graphModel.d.ts +6 -1
  97. package/dist/editor/graphModel.js +8 -1
  98. package/dist/editor/keyHints.d.ts +21 -0
  99. package/dist/editor/keyHints.js +30 -0
  100. package/dist/editor/listState.svelte.d.ts +4 -4
  101. package/dist/editor/staleGuard.d.ts +111 -0
  102. package/dist/editor/staleGuard.js +279 -0
  103. package/dist/i18n/language.d.ts +3 -3
  104. package/dist/i18n/messages.d.ts +84 -1
  105. package/dist/i18n/messages.js +97 -4
  106. package/dist/index.d.ts +1 -0
  107. package/dist/types/index.d.ts +19 -2
  108. package/package.json +10 -10
package/README.md CHANGED
@@ -70,11 +70,13 @@ How the three fit together, and the order they are released in: [`__docs/package
70
70
  ## Install
71
71
 
72
72
  ```bash
73
- npm install @widgetic/workflows @widgetic/design-system svelte
73
+ npm install @widgetic/workflows @widgetic/design-system @widgetic/chat @widgetic/brand svelte
74
74
  ```
75
75
 
76
- `@widgetic/design-system` and `svelte` are peer dependencies. The host brings them, so there is one copy of each on the
77
- page. The package needs Svelte 5.
76
+ `@widgetic/design-system`, `@widgetic/chat`, `@widgetic/brand` and `svelte` are peer dependencies. The host brings them, so
77
+ there is one copy of each on the page. The package needs Svelte 5. The chat and the brand are for the assistant panel (it is
78
+ drawn with the chat's turns and the brand's mascot; see [The assistant](#the-assistant)); `@widgetic/brand` has `three` as
79
+ its own peer, which it loads only when a mascot is drawn.
78
80
 
79
81
  **Styles.** The components are styled with Tailwind classes and ship no stylesheet of their own, so the host's Tailwind
80
82
  has to read the package, or the screen is drawn without its classes. The classes themselves (`bg-background`,
@@ -135,6 +137,8 @@ the screen needs, the screen scrolls inside it; it never spills over what the pa
135
137
  | `dir` | `'ltr' \| 'rtl'` | the screen around it | Which way the screen is read. You decide it; it is not worked out from `locale`. |
136
138
  | `class` | `string` | `''` | Extra classes on the root element. |
137
139
  | `onError` | `(error: WorkflowsError) => void` | none | Called once for each failure. |
140
+ | `assistant` | `WorkflowAssistantConfig \| null` | no panel | The assistant panel of the open workflow: its endpoints, how a file is uploaded, and whether it is drawn as the mascot (below). Left out, there is no panel. |
141
+ | `assistantSeed` | `WorkflowAssistantSeed \| null` | none | A first message that waits in the composer of one workflow's assistant, not sent; `onAssistantSeedApplied(workflowId)` tells the page it was used (below). |
138
142
  | `fetchImplementation` | `typeof fetch` | the page's `fetch` | For tests and previews: the `fetch` the screen asks the API with. |
139
143
 
140
144
  `WorkflowsError` is `{ message: string; code: 'RENDER_FAILED' | 'REQUEST_FAILED' | 'SESSION_ENDED'; fatal: boolean }`.
@@ -166,6 +170,116 @@ own other window is not a teammate and gets no badge. A look that fails (offline
166
170
  badges as they were and the next looks come further apart; an API that says there is no presence here, or a token that may
167
171
  not ask, ends the looking and the list goes on without badges. A badge never shuts anything: the row opens as always.
168
172
 
173
+ ## The assistant
174
+
175
+ With `assistant` given (and `enabled: true`), the open workflow has a panel where the person describes the workflow they
176
+ want: the assistant answers, asks a question when it needs one, shows a plan, and builds the widgets of the plan once the
177
+ person approves it. The page gives the wiring; the screen holds no key.
178
+
179
+ | Field | Type | What it does |
180
+ | --------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
181
+ | `enabled` | `boolean` | `false` leaves the panel out. |
182
+ | `streamUrl` | `string` | Where the person's message goes; the assistant answers as a stream. |
183
+ | `approveUrl` | `string` | Where an approved plan goes; the widgets are built as a stream. |
184
+ | `getAuthHeaders` | `Record<string, string> \| (() => Promise<Record<string, string>>)` | The headers of both calls (the person's token). |
185
+ | `uploadFileToLibrary` | `(file: File) => Promise<{ mediaId: string; fileName: string }>` | Puts a file the person attached into their file library. |
186
+ | `suggestUrl` | `string` (optional) | Where the box asks how to go on: grey words after what the person typed (see below). Left out, the box suggests none. |
187
+ | `outcomeUrl` | `string` (optional) | Where the counts of what happened to the suggestions go: shown, taken, sent away. Counts only, never a word typed. |
188
+ | `agentMascot` | `boolean` (default `true`) | `false` draws the chat's plain round avatar instead of the mascot, and never loads the mascot's Three.js (see below). |
189
+
190
+ **The assistant's face** is the Scribble Mascot (`@widgetic/brand`), the one it has in the chat of the Widgetic creator, and
191
+ it moves the way it does there: it thinks (large) while the person waits for the first word, writes (small) while the
192
+ assistant answers or builds the plan, and settles to a happy or a worried face (large) when the run ends. Beside a question
193
+ or the plan waiting for an answer it stays small, which is the one place the panel differs from the chat: the panel is
194
+ narrow, and a large avatar would leave the card two thirds of it. Only the newest turn moves; the turns above it are still
195
+ pictures. The panel asks the chat for these looks (`liveAgentLook`, `settledAgentLook` of `@widgetic/chat`), so the two
196
+ follow one set of rules. The first mascot is warmed up when the panel opens, so it appears without a pause.
197
+
198
+ A page that does not want the mascot sets `agentMascot: false`. The face is then the chat's plain round avatar, with the same
199
+ turns and the same layout, and nothing of the mascot is started. There are no faces of the people of a team in this panel,
200
+ so a page has nothing else to switch off.
201
+
202
+ **Suggestions in the box.** With `suggestUrl` given, the box where the person writes shows grey words after what they have
203
+ typed, a way to go on in this panel (a journey of the playbook, a widget template or preset, "reuse my widget …"). `Tab` takes
204
+ them, typing on or `Esc` sends them away, and `Enter` is never involved: the box has no Enter handler, and a message still goes
205
+ only when the person presses Send. The box asks the gateway with the language of the page and with how many steps the open
206
+ workflow holds (a number, never a name or a word of the workflow), so an empty canvas is offered ways to begin and a full one
207
+ ways to go on. The requests carry the headers of `getAuthHeaders` (a token refreshed on demand is waited for) and never a
208
+ cookie, and the box keeps working while the assistant answers. A box that is not given a route has no suggestions, and that
209
+ is the only difference: without `suggestUrl` nothing is asked of the network. `outcomeUrl` is where the counts go (how many
210
+ suggestions were shown, taken, sent away), grouped, so the ranking can learn which ones helped; leave it out and nothing is
211
+ reported. The grey words are set in the box's own font, only grey. While a suggestion shows, a line under the box says what Tab does, **until the
212
+ person has taken one suggestion** (after the first Tab the line is gone for good in that browser, and leaves no gap); the words of that line
213
+ (`workflows.assistant.suggestionTabKey`, `suggestionTabHint`) and the sentence a screen reader hears, which always says how to take the
214
+ suggestion (`suggestionAnnouncement`), are in the catalog like every other word of the panel. The engine is
215
+ `@widgetic/design-system/inline-completion`, so the box needs the design system version that ships it.
216
+
217
+ **Naming an attached file with a `#`.** With files attached to the draft, typing `#` after a space (or at the start of the box)
218
+ opens a list of them, each with its thumbnail (a picture is drawn from the file in the person's hands, nothing is fetched; any
219
+ other kind of file shows a file icon). Choosing one puts a badge in the text (the thumbnail, the file's name and an X that takes
220
+ it out again), so a person can say "use #hero_banner as the header and #logo in the footer"; a `#hero_banner` typed by hand
221
+ names the file the same way. The word of a file is made from its name when it is attached (`hero-banner.png` is `hero_banner`),
222
+ a name that says nothing (`IMG_4021.jpg`, a screenshot) becomes `Image_1`, `Image_2`, and no two files of a draft have the
223
+ same one. It lives in the draft only: it is not stored, and a chat started over starts its numbers over. A badge or a row of
224
+ the list that the pointer is on rings the chip of the same file above the box. The panel gives nothing to configure: it is on
225
+ for every box, and with no file attached the `#` does nothing.
226
+
227
+ What is sent is what the person wrote: the room a badge takes in the box is not part of the message or of the transcript, so
228
+ the assistant reads "use #hero_banner as the header". Beside `attachmentMediaIds` the request carries `attachmentReferences`
229
+ (`[{ id, label }]`, the id being the file's `mediaId`), only when the message names a file that has gone up, once per file and
230
+ at most twenty; a message that names no file has no such key, and a file still uploading or that failed is left to the words.
231
+ The panel posts its stream with `fetch` and not through the generated SDK, so the field leaves with the first build that has this
232
+ code, and a gateway that does not read it yet ignores it (the message still goes). A label is made from a file's name, so the
233
+ suggestions of the box never see one: in what a suggestion service is asked, each reference is the neutral word `#file`. The
234
+ words (`workflows.assistant.referenceHint`, `referenceMenuLabel`, `referenceRemove`) are in the catalog like every other word of
235
+ the panel. The list, the badges and the labels are `@widgetic/design-system/prompt-references`, so the box needs the design
236
+ system version that ships it. A reference opens no file: it only tells the assistant which of the attached files a sentence is about.
237
+
238
+ ### Opening the assistant with a message
239
+
240
+ A page that sends a person here with something in mind (an idea from an email, a template, a link) gives `assistantSeed`: the
241
+ first message, waiting in the composer of the assistant of one workflow. The person reads it, changes it if they want to and
242
+ presses Send. The screen never sends it for them.
243
+
244
+ ```svelte
245
+ <Workflows
246
+ {apiUrl}
247
+ {getAccessToken}
248
+ {workspaceId}
249
+ workflowId={draftId}
250
+ {assistant}
251
+ assistantSeed={{
252
+ workflowId: draftId,
253
+ message: 'When someone finishes @Spring launch quiz, send them to @Thank you page.',
254
+ compositionReferences: [
255
+ { id: '3f1c0e7a-5b1d-4c53-9e55-0d9d1f6a4b21', name: 'Spring launch quiz' },
256
+ { id: '9a7c4d02-1e5f-4a8b-b0c1-6e3f7d2a8c90', name: 'Thank you page' }
257
+ ]
258
+ }}
259
+ onAssistantSeedApplied={() => (assistantSeed = null)}
260
+ />
261
+ ```
262
+
263
+ | Field | Type | What it does |
264
+ | ----------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
265
+ | `workflowId` | `string` | The workflow the seed is for. A seed for another workflow than the open one is not used. |
266
+ | `message` | `string` | The text for the composer. A mention of a composition is written `@Name`. |
267
+ | `compositionReferences` | `{ id: string; name: string }[]` (optional) | The compositions the message names. Each goes along with the message when it is sent, so the assistant knows which one is meant. |
268
+
269
+ - **Read once.** The seed is read when the workflow is opened, and not watched afterwards: hand it over no later than the
270
+ `workflowId` that opens that workflow. A seed that arrives later, or one the page replaces, is not used. It is written
271
+ when the assistant of that workflow is first drawn, and coming back to the Editor tab does not write it again.
272
+ - **Only into an empty composer, and only for a workflow with no conversation yet.** A person who is already typing, or a
273
+ workflow whose conversation with the assistant has begun, keeps what it has. Either way
274
+ `onAssistantSeedApplied(workflowId)` is called once, so the page can drop the seed.
275
+ - **The mentions go with the message for as long as they are in it.** A composition is sent along with the message only
276
+ while its `@Name` is still in the text: a person who takes a mention out stops pointing at that composition. The
277
+ assistant accepts at most 10 per message, each with a UUID and a name of at most 200 characters; an entry that would be
278
+ refused (and a second entry for the same id) is left out, so a message is never refused because of one. A name the page
279
+ had to cut short ends with `…` and is matched by its beginning.
280
+ - **A chip is not a send of the seed.** The composer is emptied after a message only when it still holds that message, so
281
+ a click on one of the welcome chips leaves the seed where it was.
282
+
169
283
  ## Look and feel
170
284
 
171
285
  The screen is drawn with the Widgetic design system, the one in the Figma file "Dashboard": its colours, type, corners and
@@ -154,6 +154,23 @@ export interface CompositionOptionList {
154
154
  limit: number;
155
155
  offset: number;
156
156
  }
157
+ /** How the gateway says one of the person's Open MCPs stands: what the last look at the server, or the sign-in, found. */
158
+ export type OpenMcpStatus = 'pending' | 'connected' | 'needs_sign_in' | 'error';
159
+ /**
160
+ * One of the person's own Open MCPs in this workspace (a server they connected under the workspace settings), as the `@` menu of
161
+ * the assistant offers it. Nothing here is a credential: the gateway never sends the address of a server (only its host), a
162
+ * token or a header, and never lists a colleague's.
163
+ */
164
+ export interface OpenMcpOption {
165
+ id: string;
166
+ /** What the person called it. */
167
+ name: string;
168
+ /** The host of the server's address, to tell two servers of the same name apart. */
169
+ host: string;
170
+ status: OpenMcpStatus;
171
+ /** How many of its tools the person switched on (the assistant may use only those). */
172
+ enabledToolCount: number;
173
+ }
157
174
  /** A widget a preset shows: what a card of the preset draws for it. */
158
175
  export interface WorkflowPresetWidget {
159
176
  name: string;
@@ -1,5 +1,5 @@
1
1
  import type { IssueCode, ValidationIssue, WorkflowGraph } from '@widgetic/workflows-engine';
2
- import { type AccessTokenFunction, type CompositionOption, type CompositionOptionList, type CompositionOptionsQuery, type EditLeaseAnswer, type EditLeasePeekAnswer, type WorkflowDetail, type WorkflowList, type WorkflowListItem, type WorkflowListQuery, type WorkflowPreset, type WorkflowPublishResult, type WorkflowStateAction, type WorkflowStats, type WorkflowStatsQuery, type WorkflowVersion, type WorkflowVersionDetail } from './types.js';
2
+ import { type AccessTokenFunction, type CompositionOption, type CompositionOptionList, type CompositionOptionsQuery, type OpenMcpOption, type EditLeaseAnswer, type EditLeasePeekAnswer, type WorkflowDetail, type WorkflowList, type WorkflowListItem, type WorkflowListQuery, type WorkflowPreset, type WorkflowPublishResult, type WorkflowStateAction, type WorkflowStats, type WorkflowStatsQuery, type WorkflowVersion, type WorkflowVersionDetail } from './types.js';
3
3
  /** How long a request may take before it is given up: the reads, and the writes (a publish reads every composition). */
4
4
  export declare const READ_TIMEOUT_MS = 15000;
5
5
  export declare const WRITE_TIMEOUT_MS = 30000;
@@ -108,6 +108,12 @@ export interface WorkflowsApi {
108
108
  changeState(workflowId: string, action: WorkflowStateAction, options?: RequestOptions): Promise<WorkflowListItem>;
109
109
  getStats(workflowId: string, query?: WorkflowStatsQuery, options?: RequestOptions): Promise<WorkflowStats>;
110
110
  listCompositionOptions(query?: CompositionOptionsQuery, options?: RequestOptions): Promise<CompositionOptionList>;
111
+ /**
112
+ * The Open MCPs the person connected to this workspace, for the `@` menu of the assistant: their own servers, never a
113
+ * colleague's, oldest first. A workspace where Open MCPs are off, or a plan that does not include them, answers with an error
114
+ * (the menu then has no such group), and nothing in the answer is a credential.
115
+ */
116
+ listMcpOptions(options?: RequestOptions): Promise<OpenMcpOption[]>;
111
117
  /** The presets this workspace can start a workflow from, in the order their offerer set (an empty list when none is offered). */
112
118
  listPresets(options?: RequestOptions): Promise<WorkflowPreset[]>;
113
119
  /**
@@ -150,6 +156,11 @@ export declare function usableImageUrl(value: unknown): string | null;
150
156
  * capability model is the API's, and an answer that left a part out is treated as "this composition cannot do that".
151
157
  */
152
158
  export declare function readCompositionOption(data: unknown): CompositionOption;
159
+ /**
160
+ * One Open MCP the menu can offer. Its id, name and host are what a row cannot do without, so an answer that lacks one is refused;
161
+ * a status this screen does not know reads as `error` (the row then says it cannot be reached, never that it is fine).
162
+ */
163
+ export declare function readOpenMcpOption(data: unknown): OpenMcpOption;
153
164
  /**
154
165
  * One preset a workflow can be started from. The key and the title are what a card and a start cannot do without; the
155
166
  * description may be missing (a preset its offerer wrote nothing about), and a count that is not a number is refused.
@@ -408,6 +408,35 @@ function readCompositionOptionList(data) {
408
408
  offset: readWholeNumber(data, 'offset', 'the compositions')
409
409
  };
410
410
  }
411
+ const OPEN_MCP_STATUSES = [
412
+ 'pending',
413
+ 'connected',
414
+ 'needs_sign_in',
415
+ 'error'
416
+ ];
417
+ /**
418
+ * One Open MCP the menu can offer. Its id, name and host are what a row cannot do without, so an answer that lacks one is refused;
419
+ * a status this screen does not know reads as `error` (the row then says it cannot be reached, never that it is fine).
420
+ */
421
+ export function readOpenMcpOption(data) {
422
+ if (!isRecord(data))
423
+ throw invalidResponse('an Open MCP');
424
+ const status = data.status;
425
+ return {
426
+ id: readText(data, 'id', 'an Open MCP'),
427
+ name: readText(data, 'name', 'an Open MCP'),
428
+ host: readText(data, 'urlHost', 'an Open MCP'),
429
+ status: typeof status === 'string' && OPEN_MCP_STATUSES.includes(status)
430
+ ? status
431
+ : 'error',
432
+ enabledToolCount: readWholeNumber(data, 'enabledToolCount', 'an Open MCP')
433
+ };
434
+ }
435
+ function readOpenMcpOptionList(data) {
436
+ if (!Array.isArray(data))
437
+ throw invalidResponse('the Open MCPs');
438
+ return data.map(readOpenMcpOption);
439
+ }
411
440
  /** A widget a preset shows. A name that is not text is not a widget a card can say anything about, so the answer is refused. */
412
441
  function readPresetWidget(data) {
413
442
  if (!isRecord(data))
@@ -626,6 +655,8 @@ function startAttempt(outer, timeoutMs) {
626
655
  export function createWorkflowsApi(options) {
627
656
  const apiBase = `${options.apiUrl.replace(/\/+$/, '')}/v1`;
628
657
  const workspaceBase = `/workspaces/${encodeURIComponent(options.workspaceId)}/workflows`;
658
+ // The Open MCPs a person connected to this workspace are not under `/workflows`: they belong to the workspace's settings.
659
+ const openMcpBase = `/workspaces/${encodeURIComponent(options.workspaceId)}/open-mcps`;
629
660
  const readTimeoutMs = options.readTimeoutMs ?? READ_TIMEOUT_MS;
630
661
  const writeTimeoutMs = options.writeTimeoutMs ?? WRITE_TIMEOUT_MS;
631
662
  const startFromPresetTimeoutMs = options.startFromPresetTimeoutMs ?? START_FROM_PRESET_TIMEOUT_MS;
@@ -846,6 +877,12 @@ export function createWorkflowsApi(options) {
846
877
  timeoutMs: readTimeoutMs
847
878
  }));
848
879
  },
880
+ async listMcpOptions(requestOptions = {}) {
881
+ return readOpenMcpOptionList(await request('GET', openMcpBase, {
882
+ signal: requestOptions.signal,
883
+ timeoutMs: readTimeoutMs
884
+ }));
885
+ },
849
886
  async listPresets(requestOptions = {}) {
850
887
  return readWorkflowPresetList(await request('GET', `${workspaceBase}/presets`, {
851
888
  signal: requestOptions.signal,
@@ -1,8 +1,17 @@
1
+ import { type WorkflowAssistantSaveMode } from './assistantSaveMode.js';
2
+ import type { CompositionReference } from './compositionMention.js';
3
+ import { type AssistantDataPreview, type PlanBindingStatus } from './liveData.js';
4
+ import type { McpReference } from './mcpMention.js';
1
5
  import type { AssistantPlanCardState, AssistantQuestionCardState, AssistantTranscriptMessage } from './types.js';
2
6
  export interface AssistantUiState {
3
7
  readonly messages: readonly AssistantTranscriptMessage[];
4
8
  readonly questionCard: AssistantQuestionCardState | null;
5
9
  readonly planCard: AssistantPlanCardState | null;
10
+ /**
11
+ * What the assistant's calls of the person's Open MCPs would show, for the person to check (the newest few). Never written to the
12
+ * transcript that is kept in the browser: they hold the person's data, and a reload starts without them.
13
+ */
14
+ readonly dataPreviews: readonly AssistantDataPreview[];
6
15
  readonly isStreaming: boolean;
7
16
  readonly completionMessage: string | null;
8
17
  readonly savedWorkflowId: string | null;
@@ -14,28 +23,61 @@ export type AssistantUiAction = {
14
23
  type: 'user_message';
15
24
  id: string;
16
25
  text: string;
26
+ compositionReferences?: readonly CompositionReference[];
27
+ mcpReferences?: readonly McpReference[];
17
28
  } | {
18
29
  type: 'streaming';
19
30
  value: boolean;
20
- } | {
31
+ }
32
+ /** `failed`: the words are a failure's (the server's error, not a reply), so the assistant's face can look worried. */
33
+ | {
21
34
  type: 'assistant_text';
22
35
  id: string;
23
36
  text: string;
37
+ failed?: boolean;
24
38
  } | {
25
39
  type: 'question_card';
26
40
  card: AssistantQuestionCardState;
27
41
  } | {
28
42
  type: 'plan_card';
29
43
  card: AssistantPlanCardState;
44
+ } | {
45
+ type: 'data_preview';
46
+ preview: AssistantDataPreview;
30
47
  } | {
31
48
  type: 'plan_step';
32
49
  stepId: string;
33
50
  status: 'waiting' | 'creating' | 'done' | 'failed';
34
51
  detail?: string;
52
+ }
53
+ /**
54
+ * The build of a step's widget has started, and this is the canvas it is built on: the card then offers a link that opens it, so the
55
+ * person watches the build (and can take it over) in a tab of its own.
56
+ */
57
+ | {
58
+ type: 'plan_step_canvas';
59
+ stepId: string;
60
+ canvasId: string;
61
+ } | {
62
+ type: 'binding_status';
63
+ bindingId: string;
64
+ status: PlanBindingStatus;
65
+ detail?: string;
66
+ rows?: number;
35
67
  } | {
36
68
  type: 'workflow_ready';
37
69
  workflowId: string;
38
- mode: 'filled_empty' | 'created_new';
70
+ mode: WorkflowAssistantSaveMode;
71
+ }
72
+ /**
73
+ * The assistant changed the draft of a workflow while it was working (the chat's own tools saved it). The chat has nothing to
74
+ * add to its transcript: the editor shows the change, which is what this is for. `revision` is the draft's revision after the
75
+ * save, or `null` when the event did not say (the editor then always looks).
76
+ */
77
+ | {
78
+ type: 'workflow_updated';
79
+ workflowId: string;
80
+ revision: number | null;
39
81
  } | {
40
82
  type: 'done';
41
83
  };
@@ -1,9 +1,11 @@
1
1
  import { WORKFLOWS_MESSAGES } from '../i18n/messages.js';
2
2
  import { completionMessageKeyForSaveMode } from './assistantSaveMode.js';
3
+ import { liveDataIsReady, rememberDataPreview, withBindingStatus, } from './liveData.js';
3
4
  export const emptyAssistantUiState = {
4
5
  messages: [],
5
6
  questionCard: null,
6
7
  planCard: null,
8
+ dataPreviews: [],
7
9
  isStreaming: false,
8
10
  completionMessage: null,
9
11
  savedWorkflowId: null,
@@ -15,7 +17,18 @@ export function reduceAssistantUiState(state, action) {
15
17
  case 'user_message':
16
18
  return {
17
19
  ...state,
18
- messages: [...state.messages, { id: action.id, role: 'user', text: action.text }],
20
+ messages: [
21
+ ...state.messages,
22
+ {
23
+ id: action.id,
24
+ role: 'user',
25
+ text: action.text,
26
+ ...(action.compositionReferences?.length
27
+ ? { compositionReferences: action.compositionReferences }
28
+ : {}),
29
+ ...(action.mcpReferences?.length ? { mcpReferences: action.mcpReferences } : {}),
30
+ },
31
+ ],
19
32
  };
20
33
  case 'streaming':
21
34
  return { ...state, isStreaming: action.value };
@@ -32,6 +45,28 @@ export function reduceAssistantUiState(state, action) {
32
45
  planCard: {
33
46
  ...action.card,
34
47
  steps: action.card.steps.map((step) => ({ ...step, status: 'waiting' })),
48
+ // A card of a plan with no live data stays without the key, as it always was.
49
+ ...(action.card.bindings
50
+ ? {
51
+ bindings: action.card.bindings.map((binding) => ({
52
+ ...binding,
53
+ status: 'waiting',
54
+ detail: undefined,
55
+ })),
56
+ }
57
+ : {}),
58
+ },
59
+ };
60
+ case 'data_preview':
61
+ return { ...state, dataPreviews: rememberDataPreview(state.dataPreviews, action.preview) };
62
+ case 'binding_status':
63
+ if (!state.planCard?.bindings)
64
+ return state;
65
+ return {
66
+ ...state,
67
+ planCard: {
68
+ ...state.planCard,
69
+ bindings: withBindingStatus(state.planCard.bindings, action.bindingId, action.status, action.detail, action.rows),
35
70
  },
36
71
  };
37
72
  case 'plan_step':
@@ -46,6 +81,16 @@ export function reduceAssistantUiState(state, action) {
46
81
  : step),
47
82
  },
48
83
  };
84
+ case 'plan_step_canvas':
85
+ if (!state.planCard)
86
+ return state;
87
+ return {
88
+ ...state,
89
+ planCard: {
90
+ ...state.planCard,
91
+ steps: state.planCard.steps.map((step) => step.id === action.stepId ? { ...step, canvasId: action.canvasId } : step),
92
+ },
93
+ };
49
94
  case 'workflow_ready':
50
95
  return {
51
96
  ...state,
@@ -53,8 +98,19 @@ export function reduceAssistantUiState(state, action) {
53
98
  completionMessage: WORKFLOWS_MESSAGES[completionMessageKeyForSaveMode(action.mode)],
54
99
  isStreaming: false,
55
100
  };
101
+ case 'workflow_updated':
102
+ // Nothing to say in the chat: the editor draws the change.
103
+ return state;
56
104
  case 'done':
57
- return { ...state, isStreaming: false };
105
+ return {
106
+ ...state,
107
+ isStreaming: false,
108
+ // A plan that only turned live data on saves no workflow, so no `workflow_saved` ever says it is over: `done`, after
109
+ // every binding is done, is the one sign (a binding that failed leaves the card as it is, for another press).
110
+ ...(state.completionMessage === null && state.planCard && liveDataIsReady(state.planCard)
111
+ ? { completionMessage: WORKFLOWS_MESSAGES['workflows.assistant.liveDataReady'] }
112
+ : {}),
113
+ };
58
114
  default:
59
115
  return state;
60
116
  }
@@ -0,0 +1,66 @@
1
+ /**
2
+ * The files a person names with a `#` in the box of the assistant ("use #hero_banner as the header"): what the menu offers, which
3
+ * files a message may name, and what the request carries of them. The label of each file and the reading of the text are the design
4
+ * system's (`@widgetic/design-system/prompt-references`, used by the panel); what is here needs no browser, so a test in Node runs it.
5
+ *
6
+ * Plain TypeScript with no Svelte and no design-system import.
7
+ */
8
+ /** The most files a message names: the gateway reads that many, and a message carries no more files (`attachmentMediaIds`). */
9
+ export declare const ASSISTANT_MAX_REFERENCES = 20;
10
+ /** A file of the draft as the panel keeps it (`AssistantAttachmentChip`), said by the fields this module reads. */
11
+ export interface ReferenceableChip {
12
+ readonly mediaId: string;
13
+ readonly fileName: string;
14
+ readonly state: 'uploading' | 'ready' | 'error';
15
+ /** The word that names the file after a `#`. A chip without one cannot be named. */
16
+ readonly label?: string;
17
+ /** A picture of the file, an address the browser made for it. Pictures only. */
18
+ readonly previewUrl?: string;
19
+ }
20
+ /** A file in the menu of the `#`: the design system's `ReferenceItem`, written out so that this module imports nothing. */
21
+ export interface AssistantReferenceItem {
22
+ id: string;
23
+ label: string;
24
+ number: number;
25
+ fileName: string;
26
+ previewUrl?: string;
27
+ }
28
+ /** A file a message names, as the request says it: the id of the stored file and the word that named it. */
29
+ export interface AssistantReference {
30
+ id: string;
31
+ label: string;
32
+ }
33
+ /** What the request carries of the references: a key only when the message names a file. */
34
+ export interface AssistantReferenceFields {
35
+ attachmentReferences?: AssistantReference[];
36
+ }
37
+ /** Whether a file is a picture the browser can draw a thumbnail of (pictures only: another kind of file is a file icon). */
38
+ export declare function isPictureFile(file: {
39
+ type?: string | null;
40
+ } | null | undefined): boolean;
41
+ /**
42
+ * The labels of every file of the draft, a file whose upload failed included. They are what a new file's label must not repeat, and
43
+ * what is kept out of a suggestion request: a label is made from a file's name, and a hand-typed `#label` names a file as well.
44
+ */
45
+ export declare function referenceLabelsOfChips(chips: readonly ReferenceableChip[]): string[];
46
+ /**
47
+ * The files the menu of the `#` offers, in the order of the draft: the ones that have a label and did not fail. A file still
48
+ * uploading is offered, since it may be named while it goes up (the request names it only if it has gone up by the send).
49
+ * `number` counts from 1 among the files offered, so `#2` offers the second. `id` is the stored file's id once it has one and its
50
+ * label until then (a label never has a dash, an id of a file always does, so the two never meet).
51
+ */
52
+ export declare function referenceItemsOfChips(chips: readonly ReferenceableChip[]): AssistantReferenceItem[];
53
+ /**
54
+ * The files a message can name when it is sent: stored (`ready`, with the id the gateway knows), and labelled. A file that is still
55
+ * going up or that failed is left to the text as plain words, and the request does not carry it either.
56
+ */
57
+ export declare function referenceTargetsOfChips(chips: readonly ReferenceableChip[]): AssistantReference[];
58
+ /** The ids of the stored files the message carries (`attachmentMediaIds`): every file of the draft that went up. */
59
+ export declare function readyMediaIdsOfChips(chips: readonly ReferenceableChip[]): string[];
60
+ /**
61
+ * The `attachmentReferences` of the request: only the references the gateway would read. A reference to a file the request does not
62
+ * carry, a label the gateway cannot read, an id it cannot read, a file or a word named twice, and any beyond the bound are left out
63
+ * (the gateway ignores most of these and refuses a malformed one outright, and a refused message loses the whole turn). The key is
64
+ * not there at all when nothing is left, the way a field with nothing to say is never sent as `null`.
65
+ */
66
+ export declare function attachmentReferenceFields(references: readonly AssistantReference[] | null | undefined, sentMediaIds: readonly string[] | null | undefined, max?: number): AssistantReferenceFields;
@@ -0,0 +1,109 @@
1
+ /**
2
+ * The files a person names with a `#` in the box of the assistant ("use #hero_banner as the header"): what the menu offers, which
3
+ * files a message may name, and what the request carries of them. The label of each file and the reading of the text are the design
4
+ * system's (`@widgetic/design-system/prompt-references`, used by the panel); what is here needs no browser, so a test in Node runs it.
5
+ *
6
+ * Plain TypeScript with no Svelte and no design-system import.
7
+ */
8
+ /** The most files a message names: the gateway reads that many, and a message carries no more files (`attachmentMediaIds`). */
9
+ export const ASSISTANT_MAX_REFERENCES = 20;
10
+ /** The longest id of a stored file the gateway reads in a reference. */
11
+ const MAX_REFERENCE_ID_LENGTH = 64;
12
+ /**
13
+ * What a label is, as the gateway reads it: one to 24 letters, digits and underscores of any script (counted in characters, not
14
+ * in code units). The gateway has no pattern for it in its spec, so the rule is written here, the same as the design system's.
15
+ */
16
+ const REFERENCE_LABEL_RULE = /^[\p{L}\p{M}\p{N}_]{1,24}$/u;
17
+ /** Whether a file is a picture the browser can draw a thumbnail of (pictures only: another kind of file is a file icon). */
18
+ export function isPictureFile(file) {
19
+ return typeof file?.type === 'string' && file.type.toLowerCase().startsWith('image/');
20
+ }
21
+ /**
22
+ * The labels of every file of the draft, a file whose upload failed included. They are what a new file's label must not repeat, and
23
+ * what is kept out of a suggestion request: a label is made from a file's name, and a hand-typed `#label` names a file as well.
24
+ */
25
+ export function referenceLabelsOfChips(chips) {
26
+ const labels = [];
27
+ for (const chip of chips) {
28
+ if (typeof chip.label === 'string' && chip.label !== '')
29
+ labels.push(chip.label);
30
+ }
31
+ return labels;
32
+ }
33
+ /**
34
+ * The files the menu of the `#` offers, in the order of the draft: the ones that have a label and did not fail. A file still
35
+ * uploading is offered, since it may be named while it goes up (the request names it only if it has gone up by the send).
36
+ * `number` counts from 1 among the files offered, so `#2` offers the second. `id` is the stored file's id once it has one and its
37
+ * label until then (a label never has a dash, an id of a file always does, so the two never meet).
38
+ */
39
+ export function referenceItemsOfChips(chips) {
40
+ const items = [];
41
+ for (const chip of chips) {
42
+ if (chip.state === 'error' || typeof chip.label !== 'string' || chip.label === '')
43
+ continue;
44
+ const item = {
45
+ id: chip.mediaId !== '' ? chip.mediaId : chip.label,
46
+ label: chip.label,
47
+ number: items.length + 1,
48
+ fileName: chip.fileName
49
+ };
50
+ if (typeof chip.previewUrl === 'string' && chip.previewUrl !== '')
51
+ item.previewUrl = chip.previewUrl;
52
+ items.push(item);
53
+ }
54
+ return items;
55
+ }
56
+ /**
57
+ * The files a message can name when it is sent: stored (`ready`, with the id the gateway knows), and labelled. A file that is still
58
+ * going up or that failed is left to the text as plain words, and the request does not carry it either.
59
+ */
60
+ export function referenceTargetsOfChips(chips) {
61
+ const targets = [];
62
+ for (const chip of chips) {
63
+ if (chip.state !== 'ready' || chip.mediaId === '')
64
+ continue;
65
+ if (typeof chip.label !== 'string' || chip.label === '')
66
+ continue;
67
+ targets.push({ id: chip.mediaId, label: chip.label });
68
+ }
69
+ return targets;
70
+ }
71
+ /** The ids of the stored files the message carries (`attachmentMediaIds`): every file of the draft that went up. */
72
+ export function readyMediaIdsOfChips(chips) {
73
+ return chips.filter((chip) => chip.state === 'ready').map((chip) => chip.mediaId);
74
+ }
75
+ /**
76
+ * The `attachmentReferences` of the request: only the references the gateway would read. A reference to a file the request does not
77
+ * carry, a label the gateway cannot read, an id it cannot read, a file or a word named twice, and any beyond the bound are left out
78
+ * (the gateway ignores most of these and refuses a malformed one outright, and a refused message loses the whole turn). The key is
79
+ * not there at all when nothing is left, the way a field with nothing to say is never sent as `null`.
80
+ */
81
+ export function attachmentReferenceFields(references, sentMediaIds, max = ASSISTANT_MAX_REFERENCES) {
82
+ if (!references || references.length === 0 || !sentMediaIds || sentMediaIds.length === 0)
83
+ return {};
84
+ const bound = Number.isFinite(max) ? Math.max(0, Math.floor(max)) : ASSISTANT_MAX_REFERENCES;
85
+ const sent = new Set(sentMediaIds);
86
+ const seenIds = new Set();
87
+ const seenLabels = new Set();
88
+ const kept = [];
89
+ for (const reference of references) {
90
+ if (kept.length >= bound)
91
+ break;
92
+ const id = reference?.id;
93
+ const label = reference?.label;
94
+ if (typeof id !== 'string' || id.length === 0 || id.length > MAX_REFERENCE_ID_LENGTH)
95
+ continue;
96
+ if (typeof label !== 'string' || !REFERENCE_LABEL_RULE.test(label))
97
+ continue;
98
+ if (!sent.has(id))
99
+ continue;
100
+ const labelKey = label.toLowerCase();
101
+ if (seenIds.has(id) || seenLabels.has(labelKey))
102
+ continue;
103
+ seenIds.add(id);
104
+ seenLabels.add(labelKey);
105
+ // A copy with the two fields only, so nothing else the caller's objects carry reaches the request
106
+ kept.push({ id, label });
107
+ }
108
+ return kept.length > 0 ? { attachmentReferences: kept } : {};
109
+ }
@@ -1,5 +1,17 @@
1
- export type WorkflowAssistantSaveMode = 'filled_empty' | 'created_new';
1
+ /**
2
+ * Where the assistant put what the person approved:
3
+ * - `filled_empty`: into the open workflow, which had nothing in it;
4
+ * - `updated_open`: into the open workflow too, next to the blocks that were already there (they are kept);
5
+ * - `created_new`: into a new workflow, so the open one stays as it was.
6
+ */
7
+ export type WorkflowAssistantSaveMode = 'filled_empty' | 'updated_open' | 'created_new';
8
+ /**
9
+ * Reads the `mode` of a `workflow_saved` event. A mode this version does not know is read as the open workflow having been
10
+ * filled: that is what an older screen did with every mode but `created_new`, and it shows the person the workflow they have
11
+ * open, which is never wrong.
12
+ */
13
+ export declare function saveModeFromWire(mode: unknown): WorkflowAssistantSaveMode;
2
14
  /** Catalog message key for the completion line after approve. */
3
- export declare function completionMessageKeyForSaveMode(mode: WorkflowAssistantSaveMode): 'workflows.assistant.ready' | 'workflows.assistant.createdNew';
4
- /** Whether approving should reload the open workflow or navigate to a new one. */
15
+ export declare function completionMessageKeyForSaveMode(mode: WorkflowAssistantSaveMode): 'workflows.assistant.ready' | 'workflows.assistant.updatedOpen' | 'workflows.assistant.createdNew';
16
+ /** Whether approving should show the open workflow's new draft or navigate to a new one. */
5
17
  export declare function editorActionForSaveMode(mode: WorkflowAssistantSaveMode): 'reload_open' | 'open_new';