@flowrunner/cli 0.1.9-dev.2 → 0.1.10-dev.1

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 (27) hide show
  1. package/ai-docs/instructions/service-code-format/03-parameters.md +22 -7
  2. package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +4 -1
  3. package/ai-docs/instructions/service-code-format/16-gotchas.md +8 -0
  4. package/dist/cli.js +10398 -32
  5. package/dist/cli.js.map +4 -4
  6. package/dist/index.js +10367 -25
  7. package/dist/index.js.map +4 -4
  8. package/dist/types/shared/src/constants/shared-extensions.d.ts +12 -0
  9. package/dist/types/shared/src/scheme/access-keys/dto.d.ts +101 -0
  10. package/dist/types/shared/src/scheme/access-keys/index.d.ts +2 -0
  11. package/dist/types/shared/src/scheme/index.d.ts +1 -0
  12. package/dist/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -5
  13. package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +1 -1
  14. package/dist/types/shared/src/scheme/shared-extensions/index.d.ts +1 -0
  15. package/dist/types/shared/src/scheme/shared-extensions/list.d.ts +209 -0
  16. package/package.json +1 -4
  17. package/runtime/index.js +10356 -4
  18. package/runtime/index.js.map +4 -4
  19. package/runtime/types/shared/src/constants/shared-extensions.d.ts +12 -0
  20. package/runtime/types/shared/src/scheme/access-keys/dto.d.ts +101 -0
  21. package/runtime/types/shared/src/scheme/access-keys/index.d.ts +2 -0
  22. package/runtime/types/shared/src/scheme/index.d.ts +1 -0
  23. package/runtime/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -5
  24. package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +1 -1
  25. package/runtime/types/shared/src/scheme/shared-extensions/index.d.ts +1 -0
  26. package/runtime/types/shared/src/scheme/shared-extensions/list.d.ts +209 -0
  27. package/templates/qa-test/files/src/index.js +7 -5
@@ -265,19 +265,34 @@ All of them are `FR_EXT_INVALID_SCHEMA`; see [16-gotchas.md](16-gotchas.md).
265
265
 
266
266
  ### What the flow author sees
267
267
 
268
- The loaded fields render inside the param in the Flow Builder, as the fields of a dynamic schema do. When one
269
- of the `dependsOn` values changes the fields are loaded again, and the values the author already entered are
270
- **kept for every field the new list still returns**; only values whose field is no longer returned are
271
- dropped, and only after the load succeeds — a failed load removes nothing.
272
-
273
- On an **AI Agent tool** that calls your action, the loaded fields can be set by hand in the tool's panel to
274
- pin some values; the model fills in the rest, as it does for any other param.
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.
275
287
 
276
288
  > **Loaded fields are not validated at run time.** The loaders run only while the inputs are being
277
289
  > configured. When the action executes, your handler receives the loaded keys as the flow supplied them:
278
290
  > a `required` loaded field the author left empty is **not** rejected, and a loaded field's `.min()` or enum
279
291
  > is not re-checked. Validate in `execute` anything your handler cannot do without. Static keys — those
280
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`.
281
296
 
282
297
  ## Dynamic params — `dynamicParams`
283
298
 
@@ -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
@@ -218,6 +218,14 @@ to 13, which is the fix that stops the next service repeating it.
218
218
  - **A loaded field may not repeat a declared one.** A `.dynamicProps()` loader that returns a key the object
219
219
  already declares, or a `dynamicParams` loader that returns the name of a declared param, fails with
220
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`.
221
229
  - **`dynamicProps` is not `dynamicParams`.** `.dynamicProps()` is a method on one param and loads the fields
222
230
  *inside* it; `dynamicParams` is an action property and loads extra *top-level* params.
223
231
  - **`dynamicParams: { criteria, resolve }` is gone.** It fails when the service loads, naming