Skip to content

feat: screened transfer in flow schema v3 - #57

Merged
wavekat-eason merged 4 commits into
mainfrom
feat/screened-transfer
Oct 31, 2026
Merged

wavekat-eason merged 4 commits into
mainfrom
feat/screened-transfer

Conversation

@wavekat-eason

Copy link
Copy Markdown
Contributor

Adds flow schema v3 with a screened transfer, and lets v3 outbound flows hand the call to a person.

What changes

  • Schema v3 (schema/flow.v3.schema.json): transfer gains optional whisper (a prompt) and timeout_secs (5–120). A transfer with a whisper is a screened transfer: the engine calls the target first, plays the whisper, and connects only when they accept; otherwise the step takes its no_answer exit. Without whisper it is the same blind transfer as before.
  • Validator (Rust + TS twins):
    • a screened transfer must wire no_answer and is not terminal; timeout_secs without whisper → timeout_without_whisper; out-of-range timeout → transfer_timeout_out_of_range
    • whisper / timeout_secs in a v1/v2 document → field_requires_newer_schema (old readers would silently blind-transfer)
    • outbound_kinds(version): v3 outbound flows may use ring and a screened transfer; a plain blind transfer is refused on outbound (outbound_blind_transfer); ring/screened-transfer no_answer count as silent exits for the unbounded-loop rule
    • OUTBOUND_KINDS is unchanged (the v2 list)
  • Engine: FlowEffects::screened_transfer(target, whisper, timeout) -> ScreenOutcome { Connected, NoAnswer, Failed }, with a default impl returning Failed, so existing implementors keep compiling and fall through to no_answer. New trace detail StepDetail::Screened { target, outcome }. DEFAULT_SCREEN_TIMEOUT_SECS = 25.
  • Corpus: new conformance/v3/ (valid, invalid, outbound) plus one new v2/invalid/v2-whisper-refused case and a canonical case. No existing v1/v2 case or schema file was edited.
  • Roadmap: v3 is taken by this change; assistant moves to v4.

Compatibility

  • Old readers refuse v3 documents (new old-reader test), so a screened transfer never runs as a blind one.
  • isTerminal in the TS package now takes a node (terminal-ness depends on whisper); it isn't exported from the barrel.

Checks

  • cargo test --workspace, clippy -D warnings, fmt --check: pass
  • pnpm --filter @wavekat/flow-schema test (237) and typecheck: pass; codegen drift clean
  • cargo package -p wavekat-flow: passes (all three schema copies included)

After merge, the release PR publishes wavekat-flow and @wavekat/flow-schema.

Version 3 adds optional whisper and timeout_secs to transfer. A reader
that ignored whisper would hand the call over blind, so it is a new
version rather than an additive field. assistant moves to version 4.
@wavekat-eason
wavekat-eason merged commit aad735a into main Oct 31, 2026
3 checks passed
@wavekat-eason
wavekat-eason deleted the feat/screened-transfer branch October 31, 2026 07:41
@github-actions github-actions Bot mentioned this pull request Oct 31, 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