@rubytech/create-realagent 1.0.623 → 1.0.624

package/payload/platform/config/cloudflared.yml

@@ -1,17 +0,0 @@
-# Cloudflare Tunnel configuration for Maxy Phase 0
-# This file is a template — actual tunnel UUID and credentials
-# are created during `cloudflared tunnel create` setup.
-#
-# See: platform/skills/cloudflare/references/setup-guide.md
-# See: docs/deployment.md
-
-tunnel: <TUNNEL_UUID>
-credentials-file: /root/.cloudflared/<TUNNEL_UUID>.json
-
-ingress:
-  - hostname: public.maxy.bot
-    service: http://localhost:19200
-  - hostname: admin.maxy.bot
-    service: http://localhost:19200
-  # Catch-all
-  - service: http_status:404

package/payload/platform/plugins/cloudflare/references/setup-guide.md

@@ -1,132 +0,0 @@
-# Cloudflare Tunnel Setup Guide
-
-This plugin talks to Cloudflare through one path only: the `cloudflared` binary, authenticated by a browser-based sign-in the operator completes themselves. Whatever the operator sees in their Cloudflare dashboard is authoritative; the agent's job is to explain what to click there and then run `cloudflared` against the signed-in session.
-
-## Prerequisites
-
-- A Cloudflare account (free at cloudflare.com)
-- A domain on the Cloudflare account (see "Getting a domain on Cloudflare" below)
-
-### Getting a domain on Cloudflare
-
-The tunnel needs a domain on the same Cloudflare account the laptop will sign into. Two paths, both happen in the operator's browser:
-
-**Option A: Buy a new domain through Cloudflare.** Navigate to cloudflare.com → Domains, and buy a domain. The dashboard sets everything up.
-
-**Option B: Add an existing domain.** In the dashboard: Websites → Add a site. Cloudflare reviews the existing DNS setup and imports it — the operator reviews the imported list to confirm the website and email entries are present. Cloudflare provides two nameservers; the operator replaces the registrar's nameservers with those. Propagation is usually minutes but can take up to 24 hours; the domain shows as Active when ready.
-
-Existing website traffic continues to work during and after the move. Only DNS resolution changes owners.
-
-## Setup Flow
-
-The operator drives the browser. The agent runs `cloudflared` commands and reports what happened. All decisions — which account, which domain, which sub-addresses — are confirmed by the operator in chat.
-
-### Sign-in
-
-The agent runs `tunnel-login`, which spawns `cloudflared tunnel login` on the device and returns a tool result containing a `maxy-device-url` fenced block with the Cloudflare auth URL. The chat UI renders that block as an "Open Cloudflare sign-in on device" button — clicking it drives the device's VNC browser (via CDP on 127.0.0.1:9222) to the auth page. This is device-bound because the OAuth callback round-trips to `cloudflared`'s local HTTP server on the laptop; the completion has to happen on the device that started login, not wherever the operator is viewing the chat from. The operator picks the Cloudflare account they want this laptop to talk to (the account name shows in the top-left of the Cloudflare page, next to the little orange cloud), clicks Authorize, and confirms. The agent runs `tunnel-login` a second time; it reports `Sign-in complete.` once cert.pem has landed.
-
-The `tunnel-login` tool reports one of three deterministic states on every call. Every non-terminal state emits a `maxy-device-url` fenced block so the chat UI renders the sign-in URL as a click-to-open-on-device button (Task 546):
-
-- **`Sign-in complete.`** — the laptop is signed in and bound to a Cloudflare account; the agent continues to the next step.
-- **`Sign-in in progress…`** — the cloudflared login process is still running and its OAuth callback is waiting. The tool result carries a `maxy-device-url` block for the sign-in URL; the operator clicks the button to open the page in the device's browser (or, if the VNC surface is unreachable, uses the inline copy-to-clipboard fallback). The agent calls `tunnel-login` again once they confirm. When cloudflared's own browser-launch subcommand failed (rare), a `[cloudflare:tunnel-login:browser-launch-failed]` log line is emitted for diagnostics — no operator-facing change, the device-URL button is still how they open the page.
-- **`Sign-in ended without saving the cert. Restarting.`** — the login process exited without writing cert.pem (crash, SIGKILL, abrupt shutdown). The tool respawns login and its result carries a fresh `maxy-device-url` block against the new auth URL.
-
-To switch Cloudflare accounts later, the agent runs `tunnel-login` with `force=true`. This signs the laptop out (deletes the local sign-in file) so a fresh sign-in can pick a different account.
-
-### Tunnel creation
-
-The agent runs `tunnel-create` with the domain and sub-address choices. `cloudflared` creates the tunnel and routes DNS for both addresses using the signed-in session. Two safety checks run inside the tool:
-
-- **Pre-flight, nameserver check.** Before asking `cloudflared` to route the address, the tool confirms the domain's registrable parent (e.g. `maxy.bot` for `admin.maxy.bot`) is on Cloudflare. When not, the tool refuses with `hostname-zone-not-routable` and tells the operator to add the domain in the dashboard first.
-- **Post-flight, FQDN check.** After `cloudflared` reports success, the tool checks that the address was created under the requested name. A mismatch means `cloudflared` fell through to a different domain on the signed-in account — almost always because the laptop is signed into the wrong Cloudflare account. The tool refuses with `post-flight-fqdn-mismatch` and tells the operator which dashboard account name they need to switch to.
-
-### Remote password
-
-Before the tunnel can be enabled, a remote password must be set. This protects the admin interface when accessed from the public internet. It is separate from the local PIN.
-
-Password requirements: at least 8 characters, must contain a number and a special character, no leading/trailing spaces.
-
-### Enabling the tunnel
-
-`tunnel-enable` starts the tunnel daemon and verifies the admin URL through Cloudflare. The tunnel runs with automatic health monitoring and restart on failure.
-
-After enabling, the agent fetches the admin URL via Cloudflare's edge; URLs are not reported as working until an end-to-end probe succeeds. If verification fails, the agent reports the failure and possible causes (DNS propagation delay, domain on a different account, etc.).
-
-When verified:
-- Admin interface is live at `https://admin.{domain}` (requires remote password)
-- Public chat is live at `https://public.{domain}`
-- Local network access continues to work with the PIN as before
-
-## After Setup
-
-`tunnel-status` reports the tunnel's full state, including an end-to-end probe of every configured address. Run it whenever something seems off.
-
-### Alias addresses
-
-An alias address (e.g. `maxy.chat`) serves the public chat directly — the URL stays as the alias in the browser bar, no redirect. The alias's domain must be on the same Cloudflare account the laptop is signed into.
-
-`tunnel-add-hostname` runs the same pre-flight and post-flight safety checks as `tunnel-create`. After it succeeds, DNS propagates over 1-5 minutes and the alias goes live.
-
-## Troubleshooting
-
-### Tunnel won't start
-
-Ask the agent to run `tunnel-status`. Common states:
-
-- **`bound: false`** — this laptop is not signed into Cloudflare, or the sign-in has drifted. Run `tunnel-login` (or `tunnel-login force=true` to sign out first and start fresh).
-- **`running: false, unhealthyReason: "not-running"`** — the tunnel process is not alive. Run `tunnel-enable` (or check `~/{configDir}/logs/cloudflared.log` for why it exited).
-
-### `tunnel-status` unhealthyReason mapping
-
-`tunnel-status` returns a structured `unhealthyReason` value on any failure. The tool's trailing text names the single prescribed recovery for each case — the agent relays it verbatim:
-
-| `unhealthyReason` | Recovery sentence |
-|---|---|
-| `bound-account-does-not-own-hostname` | "Sign in to Cloudflare at dash.cloudflare.com in the account that owns `<hostname>` — the account with the little orange cloud next to it in your browser tab — then tell me and I'll restart the tunnel login." |
-| `hostname-probes-failed` with `tunnel-not-matched` / `cname-points-elsewhere` | "DNS is pointing at a different tunnel. I'll re-point it." (agent calls `tunnel-add-hostname` for each configured hostname) |
-| `hostname-probes-failed` with `dns-missing` | "DNS is not set up yet. I'll create it." (agent calls `tunnel-add-hostname`) |
-| `hostname-probes-failed` with `edge-unreachable` | "The tunnel is not reachable through Cloudflare right now. This usually clears in a minute." |
-| `not-running` | "The tunnel process is not running. Ask the user if they want me to enable it." |
-| `no-tunnel-configured` | "No tunnel is configured on this laptop yet. Run tunnel-create to set one up." |
-
-### Refusal `hostname-zone-not-routable`
-
-The domain you tried to use is not on Cloudflare yet, or the laptop is signed into an account that does not own it. Open Cloudflare in the browser, check the account name in the top-left, and add the domain in Websites → Add a site under the account that should own it. Then ask the agent to retry.
-
-### Refusal `post-flight-fqdn-mismatch`
-
-The tunnel is running locally but `cloudflared` routed the address under a different domain — because the laptop is signed into a Cloudflare account that does not own the domain you configured. Open Cloudflare in the browser — the account name in the top-left is the account this laptop will talk to. When that is not the account that owns the domain, switch accounts using the dropdown, then ask the agent to run `tunnel-login force=true` to sign the laptop into the correct account.
-
-If `cloudflared` wrote a stray entry under the wrong domain (e.g. `admin.yourdomain.com.somebody-else.xyz`), delete it in the wrong-account dashboard — the agent cannot reach it.
-
-### DNS not resolving
-
-The #1 cause of "tunnel running but URLs dead" is wrong nameservers on the domain. The domain must use Cloudflare's nameservers, not the registrar's defaults. `tunnel-status` runs an end-to-end probe per address and reports the exact failure mode.
-
-Confirm in the dashboard: Websites → pick the domain → the status says Active (not Pending). If Pending, follow the dashboard's nameserver instructions and wait.
-
-Use `dns-lookup` for ad-hoc DNS checks — `dig` and `nslookup` are not available on the Pi.
-
-### Remote login issues
-
-- After 5 failed login attempts, there is a 15-minute lockout — wait for it to expire.
-- The remote password can be reset by asking the agent on the local network.
-
-### Changing domain
-
-- Ask the agent to disable the tunnel.
-- Ask the agent to run `tunnel-login force=true` so the sign-in is cleared and a different account can be picked when the new domain is on a different one.
-- Ask the agent to run `tunnel-create` with the new domain. Old entries stay in the dashboard for cleanup.
-
-## Agent Tools
-
-| Tool | Purpose |
-|------|---------|
-| `tunnel-login` | Browser sign-in with Cloudflare — the only auth path. Reports one of three deterministic states: `Sign-in complete.`, `Sign-in in progress…` (with optional one-line advisory when cloudflared couldn't open the browser itself), or `Sign-in ended without saving the cert. Restarting.`. `force=true` clears the local sign-in so a fresh one can pick a different account. |
-| `tunnel-status` | Full state including an end-to-end probe of every configured address. Trailing text is a single prescribed recovery sentence per `unhealthyReason` (see table above). `healthy: true` requires every address to probe `ok`; `boundAccountOwnsHostnames: false` means the laptop is running a tunnel that nothing from the internet is reaching. |
-| `tunnel-install` | Install the `cloudflared` binary. |
-| `tunnel-create` | Create a tunnel and route DNS for chosen sub-addresses. Refuses when the domain is not on the signed-in Cloudflare account. Idempotent. |
-| `tunnel-add-hostname` | Add an alias address to an existing tunnel. Refuses when the alias's domain is not on the signed-in account. Idempotent. |
-| `tunnel-enable` | Start the tunnel daemon with health monitoring. |
-| `tunnel-disable` | Stop the tunnel, preserve config for re-enabling. |
-| `dns-lookup` | Resolve DNS lookups without system binaries — `dig` and `nslookup` are not available on the Pi. |