Skip to content

feat: add flow variables - #59

Merged
wavekat-eason merged 13 commits into
mainfrom
feat/flow-variables
Nov 2, 2026
Merged

wavekat-eason merged 13 commits into
mainfrom
feat/flow-variables

Conversation

@wavekat-eason

@wavekat-eason wavekat-eason commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

Adds flow schema v4: a flow can declare variables (each with a default) and use them as {{name}} in prompts and menu option labels, so one published flow can be reused with different text per call.

  • Schema v4: top-level variables (description, default required, max_len 1..500). Audio prompts can keep a template beside their pre-voiced default audio. {{#name}}…{{/name}} keeps text only when the value is non-empty.
  • Validation (Rust + TS twins, shared corpus): placeholder syntax, unknown/undeclared names, placeholders only in prompts/templates/option labels, name pattern, max_len range. v1–v3 treat {{ as plain text.
  • fill(flow, values) (Rust + TS): replaces placeholders (given value, else default), drops an option whose label is an empty variable (with its exit), keeps pre-voiced audio when defaults are kept. Values are inserted literally. Contract: validate the source flow first; the filled result isn't re-validated.
  • Trace: MenuChoice gains an optional label (omitted when absent; old JSON still reads). StepDetail now also derives Deserialize.

Breaking for Rust callers on 0.0.x: Prompt::Audio gained template, Variable is new, CURRENT_SCHEMA_VERSION is 4. Behavior change: in a v4 flow, {{ in a text field other than a prompt, prompt template or menu label (e.g. a transfer target, or the flow's id/name) is now an error (placeholder_not_allowed). Notes are never scanned.

The prettier pass in one commit also reflowed a few unrelated lines in validate.ts (no behavior change).

Consumers (the platform, wk, the engine and the skill) follow in separate PRs.

Tests: cargo test -p wavekat-flow, cargo test -p compat-old-readers, pnpm --filter @wavekat/flow-schema test (310), typecheck, clippy, fmt — all green locally.

Final-review fixes for schema v4 flow variables, in both languages:

- A `note` (flow or step) is a comment and is never scanned for
  placeholders (conformance v4/valid/placeholder-in-note).
- `fill` returns a plain v3 document: schema_version 4+ becomes 3, and
  the result passes validate_outbound and round-trips on its own. A
  filled prompt over the prompt limit is refused with `prompt_too_long`
  (Rust FillError::PromptTooLong { node }). Fill corpus outputs are now
  v3; new cases prompt-too-long, all-options-dropped, value-with-braces.
- `engine::run` fills a flow that still declares variables with its
  defaults before running it; a fill error ends the run as a defect.
- A variable default longer than its max_len is refused with
  `variable_default_too_long`.
- Schema, README and corpus wording describe the real v4 behaviour;
  module docs state that a blank value falls back to the default.
- compat-old-readers: the oldest reader refuses v4 documents with an
  error, not a panic.
After dropping options, fill removes every node no longer reachable from entry (both languages), so the filled v3 document validates on its own. Adds fill/dropped-option-only-path and fixes a typo in a v4 case description.
@wavekat-eason
wavekat-eason marked this pull request as ready for review November 2, 2026 05:32
@wavekat-eason
wavekat-eason merged commit ff58aef into main Nov 2, 2026
3 checks passed
@wavekat-eason
wavekat-eason deleted the feat/flow-variables branch November 2, 2026 05:32
@github-actions github-actions Bot mentioned this pull request Nov 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant