@flowrunner/cli 0.1.9 → 0.1.10

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 (70) hide show
  1. package/README.md +8 -8
  2. package/ai-docs/instructions/service-code-format/01-service-structure.md +3 -2
  3. package/ai-docs/instructions/service-code-format/02-zod-types.md +8 -0
  4. package/ai-docs/instructions/service-code-format/03-parameters.md +181 -10
  5. package/ai-docs/instructions/service-code-format/04-http-requests.md +2 -2
  6. package/ai-docs/instructions/service-code-format/05-dictionaries.md +14 -0
  7. package/ai-docs/instructions/service-code-format/07-actions.md +5 -4
  8. package/ai-docs/instructions/service-code-format/11-output-model.md +42 -6
  9. package/ai-docs/instructions/service-code-format/12-service-readme.md +1 -1
  10. package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +4 -1
  11. package/ai-docs/instructions/service-code-format/15-unit-tests.md +2 -1
  12. package/ai-docs/instructions/service-code-format/16-gotchas.md +39 -1
  13. package/ai-docs/instructions/service-code-format/README.md +1 -1
  14. package/ai-docs/providers/claude/agents/flowrunner-service-test-engineer.md +1 -1
  15. package/dist/cli.js +276 -42
  16. package/dist/cli.js.map +3 -3
  17. package/dist/index.js +275 -41
  18. package/dist/index.js.map +3 -3
  19. package/dist/types/flow-extension-runner/src/v2/actions/action-method.d.ts +13 -9
  20. package/dist/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +52 -7
  21. package/dist/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +4 -6
  22. package/dist/types/flow-extension-runner/src/v2/model/model-types.d.ts +2 -0
  23. package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +2 -2
  24. package/dist/types/flow-extension-runner/src/v2/params/json/encode.d.ts +10 -2
  25. package/dist/types/flow-extension-runner/src/v2/params/json/types.d.ts +1 -0
  26. package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +29 -0
  27. package/dist/types/flow-extension-runner/src/v2/types.d.ts +20 -8
  28. package/dist/types/shared/src/constants/activity-log.d.ts +1496 -0
  29. package/dist/types/shared/src/constants/docs.d.ts +2 -0
  30. package/dist/types/shared/src/constants/notification-types.d.ts +9 -3
  31. package/dist/types/shared/src/scheme/activity-log-base.d.ts +35 -0
  32. package/dist/types/shared/src/scheme/data-types/java.dto.d.ts +2 -3
  33. package/dist/types/shared/src/scheme/flowrunner/custom-elements.d.ts +20 -0
  34. package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -0
  35. package/dist/types/shared/src/scheme/shared-extensions/base.d.ts +5 -0
  36. package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +147 -0
  37. package/dist/types/shared/src/scheme/shared-extensions/extension.d.ts +20 -0
  38. package/dist/types/shared/src/scheme/shared-extensions/methods.d.ts +33 -1
  39. package/dist/types/shared/src/scheme/shared-extensions/params-schema.d.ts +1 -0
  40. package/dist/types/shared/src/scheme/shared-extensions/resolve.d.ts +15 -0
  41. package/dist/types/shared/src/scheme/shared-extensions/search.d.ts +10 -0
  42. package/package.json +1 -1
  43. package/runtime/index.js +275 -41
  44. package/runtime/index.js.map +3 -3
  45. package/runtime/types/flow-extension-runner/src/v2/actions/action-method.d.ts +13 -9
  46. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +52 -7
  47. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +4 -6
  48. package/runtime/types/flow-extension-runner/src/v2/model/model-types.d.ts +2 -0
  49. package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +2 -2
  50. package/runtime/types/flow-extension-runner/src/v2/params/json/encode.d.ts +10 -2
  51. package/runtime/types/flow-extension-runner/src/v2/params/json/types.d.ts +1 -0
  52. package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +29 -0
  53. package/runtime/types/flow-extension-runner/src/v2/types.d.ts +20 -8
  54. package/runtime/types/shared/src/constants/activity-log.d.ts +1496 -0
  55. package/runtime/types/shared/src/constants/docs.d.ts +2 -0
  56. package/runtime/types/shared/src/constants/notification-types.d.ts +9 -3
  57. package/runtime/types/shared/src/scheme/activity-log-base.d.ts +35 -0
  58. package/runtime/types/shared/src/scheme/data-types/java.dto.d.ts +2 -3
  59. package/runtime/types/shared/src/scheme/flowrunner/custom-elements.d.ts +20 -0
  60. package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -0
  61. package/runtime/types/shared/src/scheme/shared-extensions/base.d.ts +5 -0
  62. package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +147 -0
  63. package/runtime/types/shared/src/scheme/shared-extensions/extension.d.ts +20 -0
  64. package/runtime/types/shared/src/scheme/shared-extensions/methods.d.ts +33 -1
  65. package/runtime/types/shared/src/scheme/shared-extensions/params-schema.d.ts +1 -0
  66. package/runtime/types/shared/src/scheme/shared-extensions/resolve.d.ts +15 -0
  67. package/runtime/types/shared/src/scheme/shared-extensions/search.d.ts +10 -0
  68. package/templates/demo-todo-list/files/src/index.js +6 -6
  69. package/templates/qa-test/files/README.md +23 -8
  70. package/templates/qa-test/files/src/index.js +368 -37
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # flowrunner-cli
1
+ # @flowrunner/cli
2
2
 
3
3
  **[FlowRunner](https://flowrunner.ai/)** is the orchestration layer for AI agents in production. Model
4
4
  providers and tools arrive as verified connectors, flows are built no-code or in code, and an agent facing a
@@ -17,9 +17,9 @@ server never has to execute extension code to model it.
17
17
  first one:
18
18
 
19
19
  ```bash
20
- npx flowrunner-cli init # set up the project in the current directory
21
- npx flowrunner-cli init -d my-extensions # ...or in ./my-extensions, creating it if needed
22
- npx flowrunner-cli init blank # ...and scaffold a first service from a template
20
+ npx @flowrunner/cli init # set up the project in the current directory
21
+ npx @flowrunner/cli init -d my-extensions # ...or in ./my-extensions, creating it if needed
22
+ npx @flowrunner/cli init blank # ...and scaffold a first service from a template
23
23
  ```
24
24
 
25
25
  Then work inside the project, where `flowrunner` is already available:
@@ -34,7 +34,7 @@ flowrunner --help
34
34
  Add the CLI to a repository you already have, then set it up in place:
35
35
 
36
36
  ```bash
37
- npm install --save-dev flowrunner-cli
37
+ npm install --save-dev @flowrunner/cli
38
38
  flowrunner init
39
39
  ```
40
40
 
@@ -44,7 +44,7 @@ repository is the same operation as starting from nothing, minus the files that
44
44
  ## Quick start
45
45
 
46
46
  ```bash
47
- npx flowrunner-cli init -d my-extensions blank # project + first service, npm install, git repo
47
+ npx @flowrunner/cli init -d my-extensions blank # project + first service, npm install, git repo
48
48
  cd my-extensions
49
49
  flowrunner login # browser authorization → .flowrunner/token
50
50
  flowrunner deploy # discover → model → hash → zip → upload
@@ -100,12 +100,12 @@ The harness is **copied** into the project, not linked, so it is yours to edit
100
100
  it. Running `flowrunner init` again in an existing project is how a project created before the harness
101
101
  existed gets one. `--no-tests` skips it.
102
102
 
103
- The full guide is in `node_modules/flowrunner-cli/ai-docs/instructions/service-code-format/15-unit-tests.md`.
103
+ The full guide is in `node_modules/@flowrunner/cli/ai-docs/instructions/service-code-format/15-unit-tests.md`.
104
104
 
105
105
  ## Writing services with an AI agent
106
106
 
107
107
  This package ships the authoring reference itself, under
108
- `node_modules/flowrunner-cli/ai-docs/instructions/service-code-format/`. That location is the point: the
108
+ `node_modules/@flowrunner/cli/ai-docs/instructions/service-code-format/`. That location is the point: the
109
109
  instructions your agent reads are pinned to the CLI version your project installed, so they describe the
110
110
  format this CLI actually deploys rather than whatever a model remembers about it.
111
111
 
@@ -85,8 +85,9 @@ const ext = Flowrunner.createExtension({
85
85
  service display label only; per-item human text is `label`.
86
86
  - **Ids must be unique across *all* kinds**, not just within one — an action and a dictionary cannot share
87
87
  an id, and registration fails with `FR_EXT_DUPLICATE_ITEM_ID` if they do. Generated loader names count
88
- too: an action `foo` with a loader `result` claims `foo_SampleResultLoader`, and `dynamicParams` claims
89
- `foo_DynamicParams`, so don't register anything under those names by hand.
88
+ too: an action `foo` with a loader `result` claims `foo_SampleResultLoader`, `dynamicParams` claims
89
+ `foo_DynamicParams`, and each param declared with `.dynamicProps()` claims `foo_<param>_DynamicProps`, so
90
+ don't register anything under those names by hand.
90
91
  - **A dictionary `id` starts with `get` and ends with `Dictionary`** — `getChatsDictionary`,
91
92
  `getBoardsDictionary`. Name the const holding the ref the same as the id, so the declaration and every
92
93
  `.dictionary(ref)` read alike.
@@ -18,6 +18,7 @@ and behaviors.
18
18
  | `z.union([...])` | the **first** branch's widget — see below | | | | |
19
19
  | `z.filesUploadOptions([...])`, `z.filesListOptions([...])`, `z.filesGetOptions([...])`, `z.filesDeleteOptions([...])` | nested form — the platform's own file-storage options, one group per Files call (see [03-parameters.md](03-parameters.md)) | | | | |
20
20
  | | | | `.secret()` | `z.string()` config field | Masks the input, with a reveal toggle. **Display only** — see below |
21
+ | | | | `.dynamicProps({ dependsOn, execute })` | top-level **action** param: `z.looseObject()` or `z.array(z.looseObject())` | the object's inner fields are loaded at design time from other params (see [03-parameters.md](03-parameters.md)) |
21
22
 
22
23
  Notes:
23
24
 
@@ -40,6 +41,13 @@ Notes:
40
41
  trigger param, whose value lives in the flow definition and is readable through the API — masking that
41
42
  input would suggest a protection that is not there. Put credentials in a `z.string()` config item.
42
43
  - `.dictionary(ref)` binds a param to a dictionary for dynamic options and auto-derives its `dependsOn`.
44
+ - `.dynamicProps({ dependsOn, execute })` loads the **inner fields** of an object param at design time, from
45
+ the values of the sibling params named in `dependsOn`. It is allowed on **top-level action params only**
46
+ (not on trigger params, config items, dictionary `criteria`, nested fields or an array's element), and the
47
+ field must be a **loose object** — `z.looseObject({...})`, or `z.array(z.looseObject({...}))` for a list
48
+ of objects — because the loaded keys are not in the declared schema and a plain `z.object()` would strip
49
+ them. Both are checked when the service loads. Not combinable with `.dictionary()` on the same field.
50
+ Details in [03-parameters.md](03-parameters.md#dynamic-properties--dynamicprops).
43
51
  - `.labels({ value: 'Label' })` gives each declared VALUE a display name. The dropdown shows the label, the
44
52
  flow element stores the value, and your handler receives the value — so **renaming a label never breaks a
45
53
  saved flow**. `.default(v)` takes a value, not a label.
@@ -54,8 +54,9 @@ item and the slot:
54
54
  received z.string(); omit `params` entirely if there is nothing to declare
55
55
  ```
56
56
 
57
- The same rule applies to every schema slot: `configItems`, a dictionary's `criteria`,
58
- `dynamicParams.criteria`, and the object `dynamicParams.resolve()` returns.
57
+ The same rule applies to every schema slot: `configItems` and a dictionary's `criteria`. What a params
58
+ loader's `execute()` returns — for `.dynamicProps()` and `dynamicParams` — is held to it too, but may also be a
59
+ plain shape of zod fields (see [Dynamic properties](#dynamic-properties--dynamicprops)).
59
60
 
60
61
  ## Shared param schemas — one plugin call per line
61
62
 
@@ -176,18 +177,188 @@ non-negotiable, and one before it is silently overridable.
176
177
 
177
178
  See [10-files-api.md](10-files-api.md) for what each option does.
178
179
 
180
+ ## Dynamic properties — `.dynamicProps()`
181
+
182
+ An object param whose **inner fields** are only known at design time — the columns of the table the user
183
+ picked, the custom fields of an account — declares them with `.dynamicProps()`. While a flow author configures
184
+ the block, the runtime calls your `execute`, and the fields it returns are drawn inside that param.
185
+
186
+ ```js
187
+ ext.addAction({
188
+ category : 'Records',
189
+ id : 'saveRecord',
190
+ label : 'Save Record',
191
+ description: 'Saves a record with the columns of the chosen table.',
192
+ params : z.object({
193
+ appId : z.string().label('App').dictionary(getAppsDictionary),
194
+ tableName: z.string().label('Table'),
195
+ fields : z.looseObject({ id: z.string().optional().label('ID') })
196
+ .label('Record Fields')
197
+ .optional()
198
+ .dynamicProps({
199
+ dependsOn: ['appId', 'tableName'],
200
+ execute : async ({ criteria, context, apiRequest }) => {
201
+ const columns = await apiRequest({ url: `/apps/${ criteria.appId }/tables/${ criteria.tableName }/columns`, context })
202
+
203
+ return Object.fromEntries(columns.map(column => [
204
+ column.name,
205
+ (column.type === 'number' ? z.number() : z.string()).optional().label(column.title),
206
+ ]))
207
+ },
208
+ }),
209
+ }),
210
+ result : { saved: {} },
211
+ execute: async ({ params }) => {
212
+ // params.fields = { id, …every loaded field the user filled in }
213
+ },
214
+ })
215
+ ```
216
+
217
+ | Property | Type | Description |
218
+ |---|---|---|
219
+ | `dependsOn` | `string[]` | Names of **sibling params** of the same `params` object whose values the loader needs. Optional — omit it (or pass `[]`) when the fields depend on nothing: the loader then runs once when the block's inputs open, and again when the connection changes. Each name must exist and may not be the field itself. |
220
+ | `execute` | fn | `({ criteria, config, context, helpers, apiRequest, oauth, files, filesScope, logger }) => shape \| z.object({...})` — the loaded fields. |
221
+
222
+ **`criteria` holds exactly the `dependsOn` values** — nothing else from the block — each validated and
223
+ coerced by that sibling's own schema, so a number arrives as a number, the same as in the action's handler.
224
+ A required sibling the user has not filled in yet fails with `FR_EXT_INVALID_CRITERIA` (the console shows the
225
+ dependency as missing instead of loading). The loader is re-run when one of the `dependsOn` values changes,
226
+ so a value your `execute` needs **must** be listed — one you read from outside `dependsOn` is never in
227
+ `criteria`.
228
+
229
+ **What `execute` returns** is a plain shape (`{ name: z.string().label('Name') }`, wrapped in `z.object()` for
230
+ you) or a `z.object({ … })`. It is held to the same rules as any params object — the same supported types and
231
+ plugins (see [02-zod-types.md](02-zod-types.md)), so `.label()`, `.optional()`, `.min()`,
232
+ `.dictionary(ref)` and the rest all work on a loaded field. Two things are refused: `.dynamicProps()` inside
233
+ the returned fields, and a key that repeats one the field already declares statically. Anything that is not a
234
+ shape or a `z.object` fails with `FR_EXT_INVALID_SCHEMA` when the loader runs — the one check that cannot
235
+ happen while the service loads, because the schema does not exist until `execute` runs.
236
+
237
+ **Static keys are kept.** Fields you declare inside the `z.looseObject({ … })` stay, validated as usual,
238
+ and are shown **first**; the loaded fields follow them.
239
+
240
+ **The field must be a loose object.** The loaded keys are not part of the declared schema, so a plain
241
+ `z.object()` would strip them before your handler sees them. `z.looseObject()` keeps them. For a **list of
242
+ objects**, put `.dynamicProps()` on the **array** and a loose object inside it:
243
+
244
+ ```js
245
+ rows: z.array(z.looseObject({})).label('Rows').dynamicProps(recordColumns)
246
+ ```
247
+
248
+ Not on the element — that is refused. Every item of the list uses the same loaded fields.
249
+
250
+ **Reuse a definition.** Hold `{ dependsOn, execute }` in a `const` and pass it to each field's
251
+ `.dynamicProps()`. The runtime generates one loader method per use and never changes the definition.
252
+
253
+ Placement and shape are checked when the service loads, so `flowrunner deploy` fails before uploading:
254
+
255
+ | Mistake | Error |
256
+ |---|---|
257
+ | Anywhere but a top-level **action** param (a nested field, an array's element, a trigger param, a config item, a dictionary's `criteria`) | `…uses \`.dynamicProps()\`, which is supported on top-level action params only.` |
258
+ | A field that is not a loose object | `…\`.dynamicProps()\` needs a loose object …` |
259
+ | `execute` missing or not a function | `…needs an \`execute\` function that returns the loaded fields.` |
260
+ | `dependsOn` not an array of strings | `…\`dependsOn\` must be an array of param names.` |
261
+ | `dependsOn` names a param that is not a sibling, or the field itself | `…depends on "x", which is not another param of this action.` |
262
+ | `.dynamicProps()` and `.dictionary()` on one field | `…declares both \`.dynamicProps()\` and \`.dictionary()\`.` |
263
+
264
+ All of them are `FR_EXT_INVALID_SCHEMA`; see [16-gotchas.md](16-gotchas.md).
265
+
266
+ ### What the flow author sees
267
+
268
+ The loaded fields render inside the param in the Flow Builder, as the fields of a dynamic schema do.
269
+
270
+ - **When they load.** Once every **required** param in `dependsOn` has a value; an optional one may stay
271
+ empty. Until then the param says which ones to fill in first. Only a value typed or picked in the block
272
+ counts: a dependency bound to an earlier step's output has no value at design time, so it counts as empty —
273
+ a required one keeps the param waiting ("Fill in … first"), an optional one is left out of `criteria`.
274
+ - **When a dependency changes**, the fields load again, and the values the author already entered are **kept
275
+ for every field the new list still returns**. A value whose field is no longer returned stays saved in the
276
+ param — it is not shown, but it still reaches your handler until the param is edited — so do not treat every
277
+ key in the object as one the current loader returned.
278
+ - **When the load fails**, the error is shown in place of the fields and nothing entered is removed.
279
+
280
+ On an **AI Agent tool** that calls your action, the model is offered the loaded fields too. When the agent
281
+ runs, the tool calls your loaders with the values set by hand in the tool's panel as `criteria`, and adds what
282
+ they return to the tool's input: the fields inside a `.dynamicProps()` param, and the extra params of
283
+ `dynamicParams`, with their labels. Fields set by hand stay fixed — inside a `.dynamicProps()` param they are
284
+ merged key by key with what the model fills in, so pinning one field leaves the others to the model. Without a
285
+ hand-set value for a required dependency nothing is loaded, and if a loader fails the tool is offered only the
286
+ declared params.
287
+
288
+ > **Loaded fields are not validated at run time.** The loaders run only while the inputs are being
289
+ > configured. When the action executes, your handler receives the loaded keys as the flow supplied them:
290
+ > a `required` loaded field the author left empty is **not** rejected, and a loaded field's `.min()` or enum
291
+ > is not re-checked. Validate in `execute` anything your handler cannot do without. Static keys — those
292
+ > declared in the `z.looseObject({ … })` — are validated as usual.
293
+ >
294
+ > **A loaded field's `.default()` is not applied at run time either.** A loaded field the author left empty
295
+ > reaches your handler absent or empty, not as its default. Apply the fallback in `execute`.
296
+
179
297
  ## Dynamic params — `dynamicParams`
180
298
 
181
- Generate additional top-level param fields at runtime (e.g. fields that depend on a chosen resource):
299
+ Where `.dynamicProps()` loads the fields **inside one param**, `dynamicParams` loads **extra top-level params of
300
+ the action** — fields that sit next to the static ones and depend on a chosen resource.
301
+
302
+ ```js
303
+ ext.addAction({
304
+ category: 'Records',
305
+ id : 'addRow',
306
+ // …
307
+ params : z.object({
308
+ tableName: z.string().label('Table'),
309
+ }),
310
+ dynamicParams: {
311
+ dependsOn: ['tableName'],
312
+ execute : async ({ criteria, context, apiRequest }) => {
313
+ const columns = await apiRequest({ url: `/tables/${ criteria.tableName }/columns`, context })
314
+
315
+ return Object.fromEntries(columns.map(column => [column.name, z.string().optional().label(column.title)]))
316
+ },
317
+ },
318
+ // …
319
+ })
320
+ ```
182
321
 
183
322
  | Property | Type | Description |
184
323
  |---|---|---|
185
- | `criteria` | `z.object` | Dependency inputs → become `dependsOn`. |
186
- | `resolve` | fn | `({ criteria, context, apiRequest }) => z.object({...})` — extra params merged into `params`. |
324
+ | `dependsOn` | `string[]` | Names of the action's **declared** `params` the loaded fields depend on. Optional; each name must exist in `params`. |
325
+ | `execute` | fn | `({ criteria, config, context, helpers, apiRequest, oauth, files, filesScope, logger }) => shape \| z.object({...})` — extra params merged into `params`. |
326
+
327
+ `criteria` follows the same rules as for `.dynamicProps()`: exactly the `dependsOn` values, coerced by the
328
+ declared schemas, `FR_EXT_INVALID_CRITERIA` when a required one is missing. `execute` may return a plain shape
329
+ or a `z.object`. A loaded field **may not share a name with a declared param** — it would shadow it — and
330
+ fails with `FR_EXT_INVALID_SCHEMA` when the loader runs.
331
+
332
+ The loaded fields reach your handler next to the static ones: an action with `dynamicParams` keeps the input
333
+ keys its static `params` do not declare. They are **not validated** at run time, as for `.dynamicProps()`.
334
+
335
+ The old shape `dynamicParams: { criteria, resolve }` is no longer accepted. The service fails to load with an
336
+ error naming the replacement — `criteria` becomes `dependsOn` (a list of names), `resolve` becomes `execute`,
337
+ and it returns a shape or a `z.object`.
338
+
339
+ ### The loader's response
340
+
341
+ Both loaders answer with the loaded fields twice, built from the same schema so they cannot disagree:
342
+
343
+ ```json
344
+ {
345
+ "paramsSchema": { "v": 1, "fields": [ { "name": "name", "type": "string", "meta": { "title": "Name" } } ] },
346
+ "params": [ { "name": "name", "required": true, "description": "", "type": "STRING", "label": "Name" } ]
347
+ }
348
+ ```
349
+
350
+ `paramsSchema` is the same encoded zod an action publishes for its own params; `params` is the field list with
351
+ the display metadata (label, widget, dictionary) inline. The loader's registered method is generated for you —
352
+ `<actionId>_DynamicParams` and `<actionId>_<param>_DynamicProps`, see
353
+ [01-service-structure.md](01-service-structure.md) — and is never listed in the service README.
354
+
355
+ ### Which one to use
187
356
 
188
- The `resolve` function returns a `z.object(...)` whose fields are merged into the static `params`. The
189
- declared `criteria` inputs become the `dependsOn` set that triggers re-resolution when they change.
357
+ | You want | Use |
358
+ |---|---|
359
+ | A fixed set of top-level params, some with a list of choices | static `params`; `.dictionary(ref)` for the choices |
360
+ | One object (or list of objects) whose inner fields depend on other params | `.dynamicProps()` on that param |
361
+ | Extra top-level params that appear next to the static ones | `dynamicParams` |
190
362
 
191
- `resolve` must return a `z.object` — anything else fails with `FR_EXT_INVALID_SCHEMA` when the console calls
192
- it. This is the one slot that cannot be checked while the service loads, since the schema does not exist
193
- until the resolver runs.
363
+ `.dictionary()` offers **values** for one field; `.dynamicProps()` and `dynamicParams` define **fields**. See
364
+ [05-dictionaries.md](05-dictionaries.md).
@@ -276,8 +276,8 @@ A non-2xx **rejects** with a `ResponseError`:
276
276
  | `message` | the response body when there is one — **so it is not always a string** — else `Status Code <status> (<statusText>)`. A 502 is `No connection with server`. |
277
277
 
278
278
  Because `message` is the raw body for most JSON APIs, reading it as a string used to produce an unreadable
279
- `[object Object]`. The platform now renders an unhandled failure as the provider's response body — the
280
- Execute tab, a Run Block result and a flow's error exit all show that body rather than `[object Object]` —
279
+ `[object Object]`. The platform now renders an unhandled failure as the provider's response body — a method
280
+ run from the console, a Run Block result and a flow's error exit all show that body rather than `[object Object]` —
281
281
  so a service that does nothing still fails legibly.
282
282
 
283
283
  Normalising it yourself in `apiRequest` is still worth doing, and is still the main reason `apiRequest`
@@ -120,3 +120,17 @@ the parsed criteria (defaults applied, unknown fields dropped).
120
120
  `search` + `cursor` (+ a nested `criteria` object when `criteria` is declared) and puts the `"Payload"`
121
121
  label in `metaInfo.args`. You do **not** declare `search`/`cursor` yourself. See
122
122
  [11-output-model.md](11-output-model.md).
123
+
124
+ ## Dictionary or dynamic props?
125
+
126
+ Both react to other params, but they answer different questions:
127
+
128
+ | | `.dictionary(ref)` | `.dynamicProps()` / `dynamicParams` |
129
+ |---|---|---|
130
+ | Decides | the **values** one field may take (a dropdown's options) | which **fields** exist (the inner fields of an object, or extra params) |
131
+ | Runs | when the user opens the dropdown, with the typed `search` | when the block's inputs open and when a `dependsOn` value changes |
132
+ | Returns | `{ items: [{ label, value }], cursor }` | a shape or `z.object` of zod fields |
133
+
134
+ They are not combined on one field: `.dynamicProps()` and `.dictionary()` on the same param fails when the
135
+ service loads. A loaded field can itself carry `.dictionary(ref)`. See
136
+ [03-parameters.md](03-parameters.md#dynamic-properties--dynamicprops).
@@ -9,7 +9,7 @@ Actions are the primary operations a service exposes. Register one with `ext.add
9
9
  | `label` | string | ✓ | Display name. |
10
10
  | `description` | string | ✓ | Description. |
11
11
  | `params` | `z.object` | – | Input params — omit if it takes none (see [03-parameters.md](03-parameters.md)). |
12
- | `dynamicParams` | object | – | Runtime-generated params (see [03-parameters.md](03-parameters.md)). |
12
+ | `dynamicParams` | `{ dependsOn, execute }` | – | Extra top-level params loaded at design time (see [03-parameters.md](03-parameters.md#dynamic-params--dynamicparams)). An object param's inner fields are loaded with `.dynamicProps()` instead. |
13
13
  | `result` | sample object | ✓ | A literal sample of what `execute` returns — see below. |
14
14
  | `logo` / `appearanceColors` | – | – | Default to the extension's. |
15
15
  | `oauth2Scopes` | string[] | – | Extra OAuth scopes (unioned). |
@@ -19,7 +19,7 @@ Actions are the primary operations a service exposes. Register one with `ext.add
19
19
 
20
20
  The runtime parses the incoming input against `params` **before** `execute` runs, so a handler can trust
21
21
  what it receives: defaults are applied, values are coerced by the schema, and unknown fields are stripped
22
- (an action with `dynamicParams` keeps them — its generated fields aren't in the static schema). A violation
22
+ (an action with `dynamicParams` keeps them — its generated fields aren't in the static schema; a `z.looseObject()` keeps the keys it does not declare, which is how a `.dynamicProps()` field keeps its loaded fields). A violation
23
23
  rejects the call with `FR_EXT_INVALID_METHOD_INPUT` and the offending param paths; don't re-check required
24
24
  params by hand inside `execute`. Declare optionality honestly — a `z.string()` that the flow may legitimately
25
25
  leave empty must be `.optional()`.
@@ -29,9 +29,10 @@ declare:
29
29
 
30
30
  | Slot | Required fields | Unknown fields |
31
31
  |---|---|---|
32
- | Action `params`, SYSTEM invocations | enforced — `FR_EXT_INVALID_METHOD_INPUT` | stripped (kept with `dynamicParams`) |
32
+ | Action `params`, SYSTEM invocations | enforced — `FR_EXT_INVALID_METHOD_INPUT` | stripped (kept with `dynamicParams`; kept inside a `z.looseObject()`) |
33
33
  | Dictionary `criteria` | enforced — `FR_EXT_INVALID_CRITERIA` | dropped |
34
- | Sample-result / dynamic-params loader `criteria` | enforced — `FR_EXT_INVALID_CRITERIA` | ride through — the node's other params come along |
34
+ | Sample-result loader `criteria` | enforced — `FR_EXT_INVALID_CRITERIA` | ride through — the node's other params come along |
35
+ | `.dynamicProps()` / `dynamicParams` loader `criteria` | enforced — `FR_EXT_INVALID_CRITERIA` | dropped — `criteria` holds exactly the `dependsOn` params, validated by their own schemas |
35
36
  | Polling trigger `params` | enforced — `FR_EXT_INVALID_METHOD_INPUT`, target `triggerData` | ride through |
36
37
 
37
38
  So a sample-result loader resolves only once its owner's required params are filled.
@@ -15,6 +15,7 @@ your declarations have to satisfy.
15
15
  | `result` (value/schema/loader) | `metaInfo.sampleResult` / `sampleResultLoader` |
16
16
  | `scope` (realtime) | `integrationTriggersScope` |
17
17
  | `handleTrigger*` | SYSTEM methods (runtime-generated) |
18
+ | `.dynamicProps()` on a param / `dynamicParams` | a generated `PARAM_SCHEMA_DEFINITION` method each, plus `args[].schemaLoader` / `metaInfo.dynamicParams` on the action — see [Dynamic fields](#dynamic-fields--dynamicprops-and-dynamicparams) |
18
19
 
19
20
  Platform-side identity fields are added downstream — you never author them.
20
21
 
@@ -115,14 +116,14 @@ It does not change how a handler reads the value, and a custom install has no gl
115
116
 
116
117
  ## Helper-route & SYSTEM methods carry a wrapper-param `metaInfo.args`
117
118
 
118
- Dictionaries, sample-result / dynamic-params loaders, and the trigger/polling/OAuth SYSTEM methods take a
119
+ Dictionaries, sample-result / dynamic-params / dynamic-props loaders, and the trigger/polling/OAuth SYSTEM methods take a
119
120
  **single wrapper param** (never per-field params). The model describes that wrapper so `metaInfo.args` is
120
121
  never empty — consumers (UI, AI tools) need the label:
121
122
 
122
123
  | Method kind | `bodyParams` | `metaInfo.args` |
123
124
  |---|---|---|
124
125
  | Trigger / polling / OAuth SYSTEM | `[{ invocation }]` / `[{ callbackObject }]` / `[{ refreshToken }]` | labelled from that param (e.g. `{ invocation: { label: 'invocation' } }`) |
125
- | Loaders (`*_SampleResultLoader` / `*_DynamicParams`) | `[{ payload: OBJECT }]` | `{ payload: { label: 'payload' } }` |
126
+ | Loaders (`*_SampleResultLoader` / `*_DynamicParams` / `*_<param>_DynamicProps`) | `[{ payload: OBJECT }]` | `{ payload: { label: 'payload' } }` |
126
127
  | Dictionary | synthesized `payload` OBJECT with nested `search` + `cursor` (+ `criteria` when declared) | `{ payload: { label: 'Payload' } }` |
127
128
 
128
129
  You never author these params — the runtime emits them. Dictionaries keep the extension's **service colors**
@@ -136,8 +137,43 @@ and default to `OBJECT` `returnType`.
136
137
  - **The custom type** is `z.text()` → `uiComponent: MULTI_LINE_TEXT`, `STRING`-typed — see the type table
137
138
  above.
138
139
 
139
- ## Open items
140
+ ## Dynamic fields — `.dynamicProps()` and `dynamicParams`
140
141
 
141
- - The client-side render contract for **top-level** `dynamicParams` fields. The runtime emits and serves the
142
- `PARAM_SCHEMA_DEFINITION` method today, so the authoring side works; `metaInfo.dynamicParams` is marked
143
- provisional in the model.
142
+ Both are published as a loader method the console calls while a flow author configures the block. The loader
143
+ function itself never ships; only its name does.
144
+
145
+ | Authored | Published on the action | Loader method |
146
+ |---|---|---|
147
+ | `field.dynamicProps({ dependsOn, execute })` | `metaInfo.args[field].schemaLoader` = the loader's name, `metaInfo.args[field].dependsOn` = `dependsOn` (`[]` when omitted); in `paramsSchema`, the field's `meta.frDynamicProps` = `{ id, dependsOn }` and the object carries `loose: true` | `<actionId>_<field>_DynamicProps` |
148
+ | `dynamicParams: { dependsOn, execute }` | `metaInfo.dynamicParams` = `{ methodName, dependsOn }` | `<actionId>_DynamicParams` |
149
+
150
+ - `schemaLoader` is the key a legacy (class-based) service uses for the same purpose, so a consumer reads both
151
+ the same way. The field's own `bodyParams` entry and `paramsSchema` entry stay as declared.
152
+ - `frDynamicProps` in `paramsSchema` is the plain ref `{ id, dependsOn }`, written next to the other `fr*`
153
+ meta keys (`frDictionary`, `frLabels`, …).
154
+ - `loose: true` marks an object that keeps the keys it does not declare (`z.looseObject()`); without it a
155
+ consumer rebuilding zod from `paramsSchema` would strip the loaded fields.
156
+ - Both loaders are `PARAM_SCHEMA_DEFINITION` methods with `returnType: OBJECT`, taking the same single
157
+ `payload` wrapper as the other loaders: `{ payload: { criteria } }`, where `criteria` holds exactly the
158
+ `dependsOn` values.
159
+
160
+ ### The loader response
161
+
162
+ ```json
163
+ {
164
+ "paramsSchema": { "v": 1, "fields": [ … ] },
165
+ "params": [ { "name": "price", "required": false, "description": "", "type": "NUMBER", "label": "Price", "uiComponent": { "type": "NUMERIC_STEPPER" } } ]
166
+ }
167
+ ```
168
+
169
+ | Key | Holds |
170
+ |---|---|
171
+ | `paramsSchema` | The loaded fields as encoded zod — the same encoding an action publishes for its own `params`. Console forms build their widgets and validation from it. |
172
+ | `params` | The same fields as a param list with display metadata (`label`, `uiComponent`, `dictionary`, `dependsOn`) **inline** on each entry. The Flow Builder draws the fields from it. |
173
+
174
+ Both are built from the one schema `execute` returned, so they cannot disagree. For `.dynamicProps()`, the
175
+ field's own static keys come **first** in both. A loaded field that carries `.dictionary(ref)` publishes the
176
+ dictionary on its `params` entry.
177
+
178
+ A legacy loader differs: it answers with a plain list of param definitions, not this object. Consumers accept
179
+ both.
@@ -28,7 +28,7 @@ service's `src/index.js` (the single source of truth).
28
28
  may read nothing like the current behaviour. `label` is the human text the console shows, so it is what
29
29
  belongs in a README.
30
30
  - **Exclude** everything that is not a user-facing action or trigger: `ext.dictionary(...)` registrations,
31
- `dynamicParams`, `result` loader functions, `initContext`, `apiRequest`, `helpers`, and
31
+ `dynamicParams`, `.dynamicProps()` loaders, `result` loader functions, `initContext`, `apiRequest`, `helpers`, and
32
32
  `ext.setupOauth2` / `ext.setupRealtimeTriggers` setup calls. These are internal support declarations, and
33
33
  the SYSTEM methods generated from them are never documented.
34
34
  - **The exclusion is about declarations, not consequences.** It keeps the plumbing out; it does not silence
@@ -172,8 +172,11 @@ Driving these methods from a *suite* rather than a scratch script is the same ca
172
172
  | Action `execute` params | ✓ |
173
173
  | Dictionary `criteria` | ✓ |
174
174
  | Realtime trigger `match` params — object **and** function form | ✗ |
175
+ | Fields loaded by `.dynamicProps()` / `dynamicParams` | ✗ |
175
176
 
176
- An action's params are parsed, so `execute` sees defaults filled in. A trigger's `match` receives the
177
+ An action's params are parsed, so `execute` sees defaults filled in — except fields loaded by
178
+ `.dynamicProps()` or `dynamicParams`, which exist only while the inputs are configured and are passed through
179
+ as the flow supplied them. A trigger's `match` receives the
177
180
  **persisted instance config verbatim**: no defaults.
178
181
 
179
182
  `.labels()` needs no path at all — it is display metadata, so the value the element stored is already the
@@ -82,7 +82,8 @@ The rest of `executionContext` is filled with stable `test-*` values you can ass
82
82
  | `POLLING_TRIGGER` | `ext.addPollingTrigger(...)` | `Polling Triggers` |
83
83
  | `REALTIME_TRIGGER` | `ext.addRealtimeTrigger(...)` | `RealTime Triggers` |
84
84
  | `SAMPLE_RESULT_LOADER` | a `result` declared as a function | `DynamicResults` |
85
- | `PARAM_SCHEMA_DEFINITION` | `dynamicParams` | `DynamicParams` |
85
+ | `PARAM_SCHEMA_DEFINITION` | `dynamicParams` — the method is `<actionId>_DynamicParams` | `DynamicParams` |
86
+ | `PARAM_SCHEMA_DEFINITION` | `.dynamicProps()` on a param — the method is `<actionId>_<param>_DynamicProps` | `DynamicProps` |
86
87
  | `SYSTEM` | the runtime — trigger and OAuth seams | **no group of its own** — see below |
87
88
 
88
89
  **A SYSTEM method never gets its own `describe`.** `handleTriggerResolveEvents`,
@@ -194,6 +194,43 @@ and **the runtime's contract**:
194
194
  Either way the hedge is still the wrong answer: write the one branch that is true, and get the fact added
195
195
  to 13, which is the fix that stops the next service repeating it.
196
196
 
197
+ ## Dynamic fields load at design time, and are not validated at run time
198
+
199
+ `.dynamicProps()` and `dynamicParams` load fields while a flow author configures the block (see
200
+ [03-parameters.md](03-parameters.md#dynamic-properties--dynamicprops)). The traps:
201
+
202
+ - **A loaded field is not checked when the action runs.** The loaders run only at design time, so a
203
+ `required` loaded field the author left empty reaches your handler as absent, and a loaded `.min()` or
204
+ enum is not re-checked. Validate inside `execute` whatever the handler cannot do without. Static keys
205
+ declared in the `z.looseObject({ … })` are validated as usual.
206
+ - **The field must be a loose object.** `.dynamicProps()` on `z.object({ … })` fails when the service loads,
207
+ because a plain object would strip the loaded keys. Use `z.looseObject({ … })`, or
208
+ `z.array(z.looseObject({ … }))` for a list of objects.
209
+ - **Put it on the array, not on its element.** `z.array(z.looseObject({}).dynamicProps(…))` is refused;
210
+ `z.array(z.looseObject({})).dynamicProps(…)` is right.
211
+ - **`dependsOn` names siblings only, and `criteria` holds only those.** A value `execute` reads that is not
212
+ in `dependsOn` is never in `criteria`, and the loader is not re-run when it changes. A name that is not a
213
+ sibling param — or is the field itself — fails when the service loads.
214
+ - **`.dynamicProps()` and `.dictionary()` do not share a field.** A dictionary offers the values of one
215
+ field; dynamic props define the fields inside an object.
216
+ - **Top-level action params only.** Not on a trigger's params, a config item, a dictionary's `criteria`, a
217
+ nested field, or inside the fields a loader returns.
218
+ - **A loaded field may not repeat a declared one.** A `.dynamicProps()` loader that returns a key the object
219
+ already declares, or a `dynamicParams` loader that returns the name of a declared param, fails with
220
+ `FR_EXT_INVALID_SCHEMA` when the loader runs.
221
+ - **A loaded field's `.default()` is not applied when the action runs.** A loaded field left empty reaches
222
+ the handler absent or empty. Apply the fallback in `execute`.
223
+ - **A `.dynamicProps()` object may hold keys the loader no longer returns.** When a dependency changes, values
224
+ of fields that are gone stay saved in the param until it is edited, and reach the handler. Read the keys you
225
+ expect rather than iterating all of them.
226
+ - **A dependency bound to an earlier step's output counts as empty.** It has no value while the block is
227
+ configured: a required one keeps the fields from loading (the param asks for it first), an optional one is
228
+ left out of `criteria`.
229
+ - **`dynamicProps` is not `dynamicParams`.** `.dynamicProps()` is a method on one param and loads the fields
230
+ *inside* it; `dynamicParams` is an action property and loads extra *top-level* params.
231
+ - **`dynamicParams: { criteria, resolve }` is gone.** It fails when the service loads, naming
232
+ `{ dependsOn, execute }`.
233
+
197
234
  ## Where a fact already lives
198
235
 
199
236
  Do not restate these here; they are covered where they belong.
@@ -210,4 +247,5 @@ Do not restate these here; they are covered where they belong.
210
247
  | `rawBody` is **absent**, not empty, when there is nothing to verify — hashing `''` looks like a bad signature | [09-realtime-triggers.md](09-realtime-triggers.md) |
211
248
  | `FLOW`/`EXECUTION` file scopes fail in a method that runs outside a flow execution | [10-files-api.md](10-files-api.md) |
212
249
  | Unresolvable dictionary *input* is an empty list, not an error | [05-dictionaries.md](05-dictionaries.md) |
213
- | `dynamicParams.resolve()` must return a `z.object` — checked when the loader runs, not at load | [03-parameters.md](03-parameters.md) |
250
+ | A params loader's `execute()` must return a shape or a `z.object` — checked when the loader runs, not at load | [03-parameters.md](03-parameters.md) |
251
+ | `.dynamicProps()` needs a loose object, on a top-level action param; loaded fields are not validated at run time | [Dynamic fields](#dynamic-fields-load-at-design-time-and-are-not-validated-at-run-time) |
@@ -58,7 +58,7 @@ conditional groups that apply, together.
58
58
  |---|----------|--------|
59
59
  | 1 | [01-service-structure.md](01-service-structure.md) | `Flowrunner.createExtension(props)`: id/name/logo/colors, `usesFileStorage`, `configItems`, `initContext`, `apiRequest`, `helpers`; folder layout |
60
60
  | 2 | [02-zod-types.md](02-zod-types.md) | zod types & plugins — widget derived from type; `.label`/`.describe`/`.example`/`.optional`/`.default`/`.shared`/`.dictionary`/`.map` |
61
- | 3 | [03-parameters.md](03-parameters.md) | `params` (all body params), the platform's own file-options groups — one per Files call — and `dynamicParams` (runtime-generated fields) |
61
+ | 3 | [03-parameters.md](03-parameters.md) | `params` (all body params), the platform's own file-options groups — one per Files call — `.dynamicProps()` (an object param's inner fields, loaded at design time) and `dynamicParams` (extra top-level params, loaded the same way) |
62
62
  | 4 | [04-http-requests.md](04-http-requests.md) | the shared `apiRequest` helper, and the `Flowrunner.Request` client under it — sending model, methods, query, headers, bodies, multipart, responses, `ResponseError` |
63
63
  | 5 | [05-dictionaries.md](05-dictionaries.md) | `ext.dictionary(props)` — dynamic param options; `label` (→ `operationName`, always set it), `criteria` → auto `dependsOn`, optional `result` sample |
64
64
  | 6 | [07-actions.md](07-actions.md) | `ext.addAction(props)`, the shared `execute` context bag, and input validation |
@@ -62,7 +62,7 @@ Requirements, not preferences. A suite that breaks one is wrong even when it is
62
62
  `global.Flowrunner`, never reach for an internal. Behaviour unreachable through a method call is not the
63
63
  service's contract and not yours to test.
64
64
  2. **Group by `registerAs`.** Top-level groups are exactly `Actions`, `Dictionaries`, `OAuth`,
65
- `Polling Triggers`, `RealTime Triggers`, `DynamicResults`, `DynamicParams`. A method's group comes from
65
+ `Polling Triggers`, `RealTime Triggers`, `DynamicResults`, `DynamicParams`, `DynamicProps`. A method's group comes from
66
66
  its registration, never its subject matter — `sendPhoto` and `getChannel` are both `Actions`. Never
67
67
  invent a group (`Media`, `Messaging`…). **SYSTEM trigger methods are the one kind with no group and no
68
68
  `describe` of their own** — see rule 10.