docs(relayflows): f.human is shipped — local answer/resume, Cloud delivery to Slack and GitHub

Merged
KH
1mo ago
+163-39

What

The relayflows docs still described f.human as unshipped (unsupported_verb, "lands in the release after 2.0.17", "use f.done('needs_human') instead"). It shipped in relayflows 2.0.18, and Cloud delivers the question to Slack / GitHub and takes the answer there as of today. This PR documents the shipped surface and drops every "not yet" that no longer holds. Follows the convention #96 set: TypeScript samples first (f.human has no YAML form, so no Language dropdown is needed).

Pages

  • introduction — rung 4 of the ladder: f.human parks the run until a person answers; only dispatch is still refused.
  • build — Ctx.human is Step<boolean> (a postfix .gate() attaches); the "neither runs" Note is now about dispatch only; new Human gates section: content-pipeline sample with to: 'slack:#marketing', the PARKED output, flows answer → flows resume, the human-N journal step (answeredBy, kernel at_ms, attribution: client_asserted), the four to forms, human_to_invalid (flows' current main, release after 2.0.19), and what is not enforced yet (timeout; local runs deliver nothing).
  • cloud — new Human approval on Cloud section: a pull_request-triggered release-notes sample with to: 'github:@khaliqgant' and its flows deploy, the needs_human / humanWait record, delivery table, how to answer (thread reply, ✅/❌, DM flat reply, @relay yes <code>), the bot's acknowledgements and refusals, REQUIRES / connect prompting, GET/POST …/runs/<runId>/answer and resume, and what is not yet (flows answer --cloud, reaction retraction). The listener Note no longer calls pull_request events and hosted schedules unshipped (--on github:events=pull_request is 2.0.17+, flows schedule is 2.0.18+).
  • cli — usage block is 2.0.18's verbatim (answer, schedule/schedules/unschedule, --no-connect); new Answer a human gate section; --json list updated.
  • reliability — exit 3 and the completion paragraph mention the f.human wait.
  • multi-agent — the ship-feature sample is a shipped f.human with a still-unshipped f.dispatch; the Note says only that.
  • flows gallery (web/app/flows/flow-examples.ts) — the five samples carrying "f.human is declared but not yet executed (flows#400)" drop that comment.

Verified against

  • flows origin/main: docs/SURFACE.md §5 Human gates, docs/CLOUD.md, packages/sdk/src/human-to.ts, packages/sdk/src/cli/answer.ts, authored-flow-executor.ts (f.dispatch still unsupportedVerb); tags: flows answer and the f.human lowering are in v2.0.18, the to forms / human_to_invalid (#472) are after v2.0.19.
  • cloud origin/main: lib/flows/human-gate-delivery.ts, human-gate-runtime.ts, human-gate-resume.ts, app/api/v1/workflows/runs/[runId]/answer/route.ts.
  • The three new TypeScript samples pass tsc --strict and flows check against the published @relayflows/surface@2.0.19 / relayflows@2.0.19 (RELAYFLOWS_SLACK_MOCK=1 / RELAYFLOWS_GITHUB_MOCK=1 for the helper mounts, as the docs already describe).
  • next build --webpack succeeds; every cross-link anchor (#human-gates, #human-approval-on-cloud, #answer-a-human-gate) resolves in the built HTML. vitest is unchanged: 145 pass, and the one failure (flow-workflows lockfile/bun test) fails identically on main in this environment.

🤖 Generated with Claude Code

[!NOTE]
Low Risk
Documentation and embedded example strings only; no runtime or auth logic changes.

Overview
Updates Relayflows docs and gallery samples to match 2.0.18, where f.human is runnable instead of unsupported_verb / “use f.done('needs_human')” workarounds.

Docs: Ctx.human is documented as Step<boolean> with a new Human gates section (flows answer → flows resume, human-N waits, to forms). CLI reflects 2.0.18 (flows answer, flows schedule, --no-connect) and adds Answer a human gate. Cloud adds Human approval on Cloud (Slack/GitHub delivery, answering, HTTP answer route) and notes PR listeners and hosted schedules. Introduction, multi-agent, and reliability now treat human approval as shipped; f.dispatch stays unshipped.

Gallery: Five flow-examples.ts snippets drop the “not yet executed (flows#400)” comment on f.human calls.

Reviewed by Cursor Bugbot for commit 80b87b59fda3da899717b7f322039cd3f69b1faf. Bugbot is set up for automated code reviews on this repo. Configure here.

Summary by cubic

Updates the relayflows docs to describe f.human as shipped: previously listed as an unshipped verb (unsupported_verb), it now parks a run until a person answers, with flows answer/flows resume continuing locally and Cloud delivering the question to Slack or GitHub. f.dispatch remains unshipped and still fails closed with unsupported_verb.

  • Adds a Human gates section to the build doc: Ctx.human now returns Step<boolean> instead of Promise<boolean>, and documents the human-N journal step and the four to forms.
  • Adds a Human approval on Cloud section covering the delivery table, how to answer (thread reply, ✅/❌ reaction, @relay yes <code>), and the runs/<runId>/answer HTTP route.
  • Adds an Answer a human gate section to the CLI doc and updates the usage block to 2.0.18's output (answer, schedule/schedules/unschedule, --no-connect).
  • Corrects related version claims: --on github:events=pull_request is 2.0.17+, flows schedule is 2.0.18+, and human_to_invalid lands in the release after 2.0.19.
  • Drops the "f.human is declared but not yet executed" comments from five samples in the flows gallery.

Agent Relay sessions

  • claude session a4f1feea · opened via gh pr create · last active 2026-09-18