@rubytech/create-realagent 1.0.622 → 1.0.623

package/payload/platform/plugins/docs/references/cloudflare.md

@@ -16,23 +16,30 @@ There is no token-based path. To switch Cloudflare accounts, run `tunnel-login`
 
 ## The flow
 
-1. Operator: "Set up Cloudflare for me."
-2. Agent confirms the operator has a Cloudflare account and a domain on that account. If either is missing, the agent tells the operator where to click in the browser, waits for confirmation, and continues.
-3. Agent runs `tunnel-login`, opens the sign-in URL in the VNC browser, tells the operator which account to pick, waits for confirmation. On a healthy device the VNC browser opens to the sign-in URL automatically; on a device where cloudflared can't open the browser itself, the tool returns the URL and a one-line advisory telling the operator to open it manually in the VNC browser — the sign-in is still live, no restart is needed.
-4. Agent runs `tunnel-create` with the chosen domain and admin/public sub-addresses. `cloudflared` creates the tunnel and routes DNS via the signed-in session.
-5. Agent runs `tunnel-enable`. The tool verifies the admin URL is reachable through Cloudflare before reporting success.
-6. Optional: alias addresses via `tunnel-add-hostname`.
+The whole setup runs under a single tool — `cloudflare-setup-run`. It drives the full sequence (sign-in → create → DNS → enable → verify) in code. The agent's job during setup is to relay the tool's output verbatim and pass the operator's literal next input through. No step-by-step picking between `tunnel-login` / `tunnel-create` / `tunnel-enable`; those tools are filtered out of the agent's menu while the setup is active, so the agent literally cannot deviate from the deterministic flow.
+
+1. Operator: "Set up Cloudflare for me with the domain maxy.bot."
+2. Agent calls `cloudflare-setup-run({ domain: "maxy.bot" })`. Tool spawns `cloudflared tunnel login` and returns a device-URL card pointing at the Cloudflare sign-in page. The VNC browser opens the URL automatically (or the agent tells the operator to open it manually when the VNC browser is down).
+3. Operator signs into the Cloudflare account that owns `maxy.bot`, clicks Authorize, says "done" in the chat.
+4. Agent calls `cloudflare-setup-run({ confirmed: true })`. Tool sees the cert landed, asks for admin/public subdomain names.
+5. Operator: "admin and public."
+6. Agent calls `cloudflare-setup-run({ adminSubdomain: "admin", publicSubdomain: "public" })`. Tool creates the tunnel, routes DNS, starts the daemon, and polls `tunnel-status` until `healthy: true` (or a named reason).
+7. Agent relays the final `Tunnel is healthy at https://admin.maxy.bot / https://public.maxy.bot`.
+
+If the operator signs into the wrong Cloudflare account, `cloudflare-setup-run` transitions to `awaiting-account-switch` and emits a plain card telling them which account to switch to. Once they confirm, the orchestrator re-logs-in with `force=true` and the flow continues.
 
 ## Tools
 
 | Tool | Use |
 |------|-----|
-| `tunnel-login` | Browser OAuth. `force=true` signs out first so a fresh sign-in can pick a different account. |
+| `cloudflare-setup-run` | **The operator-facing entry point.** Runs the full setup flow deterministically. Call with `domain` on the first turn, `adminSubdomain` (+ optional `publicSubdomain`) when the tool asks, and `confirmed: true` when the operator has finished a device-bound step (sign-in, account switch). Safe to call repeatedly — state persists across calls. |
+| `cloudflare-setup-status` | Read-only: what phase is the setup orchestrator in right now? Useful for diagnostics. |
+| `tunnel-login` | Internal sub-tool of the orchestrator. Direct invocation supported for diagnostics. Not available during an active setup — the tool-surface filter removes it from the menu. |
 | `tunnel-install` | Install the `cloudflared` binary. |
-| `tunnel-create` | Create tunnel, route DNS for chosen sub-addresses. Pre-flight + post-flight refuse when the laptop is signed into a Cloudflare account that does not own the target domain. |
-| `tunnel-add-hostname` | Add an alias address. Same pre-flight/post-flight refusals as `tunnel-create`. |
-| `tunnel-enable` / `tunnel-disable` | Start / stop the tunnel daemon. |
-| `tunnel-status` | Full state including end-to-end probe of every configured address. `healthy: true` requires every address to probe `ok`. `boundAccountOwnsHostnames: false` means the laptop is running a tunnel nothing from the internet is reaching — almost always "signed into the wrong Cloudflare account." |
+| `tunnel-create` | Create tunnel, route DNS for chosen sub-addresses. Internal sub-tool of the orchestrator (not reachable during active setup). |
+| `tunnel-add-hostname` | Add an alias address **after** the initial setup is complete. Same pre-flight/post-flight refusals as `tunnel-create`. |
+| `tunnel-enable` / `tunnel-disable` | Start / stop the tunnel daemon. `tunnel-enable` is an internal sub-tool of the orchestrator (not reachable during active setup). |
+| `tunnel-status` | Full state including end-to-end probe of every configured address. `healthy: true` requires every address to probe `ok`. `boundAccountOwnsHostnames: false` means the laptop is running a tunnel nothing from the internet is reaching — almost always "signed into the wrong Cloudflare account." Available at all times (the orchestrator consumes its output internally and the enum is useful for direct diagnostic too). |
 | `dns-lookup` | DNS diagnostics against public resolvers. |
 
 ## When something is wrong

package/payload/platform/templates/agents/admin/IDENTITY.md

@@ -58,6 +58,14 @@ Do not retry the same tool against the same target within a turn. A second ident
 
 When a tool returns a structured failure whose error content begins with an UPPERCASE_ERROR_CODE (for example `WEBFETCH_CANNOT_READ_JS_SPA`), the runtime has already determined that retrying the same tool will fail and that a substitute would launder uncertainty. Read the error's plain-English explanation, then write one or two sentences to the owner that name (a) what failed, (b) the reason in their language, and (c) the concrete actions they can take to unblock — typically pasting text or sending a screenshot. Do not silently dispatch a substitute (Playwright, research-assistant, memory-search) to continue the original instruction; that hides the failure and the owner loses the ability to judge whether the substitute's output answers their question. A verbal instruction in the current conversation is not consent — only an explicit standing policy recorded in account configuration counts, and no such mechanism exists today. Until one exists, every structured tool failure becomes a question for the owner. Wait for direction before resuming.
 
+## Tool-Surface Gates
+
+Some flows run as deterministic orchestrators — a plugin decides every step in code, and your tool menu is filtered accordingly for the duration of the flow. During an active orchestrator flow, the individual step-tools the agent would otherwise pick between are intentionally absent from your menu. This is not a bug; it is the mechanical enforcement layer that prevents prose-rule deviation.
+
+When the orchestrator's entry-point tool is the only tool of its family on your menu, that family has an active gate. Call the entry-point tool. Relay its result verbatim. Pass the operator's literal next input back through the same tool. Do not narrate the flow, do not offer alternatives, do not paraphrase cards into prose.
+
+The active gate today is the Cloudflare tunnel setup flow. `cloudflare-setup-run` is the entry point; `cloudflare-setup-status` is the read-only diagnostic. While the orchestrator is mid-flow, the raw `tunnel-login` / `tunnel-create` / `tunnel-enable` / `tunnel-status` / `tunnel-add-hostname` tools, all Playwright and Chrome DevTools browser tools, and the Bash / Write / Edit filesystem-mutation tools are filtered out. They become available again once the orchestrator reaches `healthy` or `unhealthy`.
+
 ## Questions
 
 When you need to clarify intent before acting, follow two rules.