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

[khaliqgant]

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 80b87b5. 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.

^{Written for commit 80b87b5. Summary will update on new commits.}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 7555dc46-5ccd-48e3-9ead-13ad1cf9d3a5

📥 Commits

Reviewing files that changed from the base of the PR and between a09d7ed and 80b87b5.

📒 Files selected for processing (7)

• web/app/flows/flow-examples.ts
• web/content/docs/relayflows/build.mdx
• web/content/docs/relayflows/cli.mdx
• web/content/docs/relayflows/cloud.mdx
• web/content/docs/relayflows/introduction.mdx
• web/content/docs/relayflows/multi-agent.mdx
• web/content/docs/relayflows/reliability.mdx

 ________________________________________________________________________
< Brb...inventing the time machine to fix your code before you wrote it. >
 ------------------------------------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[github-actions]

Preview deployed!

Environment	URL
Web	https://b4365904-agentrelay-web.agent-workforce.workers.dev

This is a Cloudflare Workers preview version of this PR's build.