@rubytech/create-realagent 1.0.858 → 1.0.860

package/payload/platform/plugins/cloudflare/PLUGIN.md

@@ -49,6 +49,10 @@ The plugin registers no agent-facing MCP tools. Every Cloudflare operation is dr
 
 The agent loads these references on demand via `plugin-read` as the conversation requires. They are not auto-injected into the system prompt.
 
+### UI contract
+
+`cloudflare-setup-form` (rendered via `render-component`) invokes `useDeviceUrlActions().onShowVnc()` immediately after a successful POST to `/api/admin/cloudflare/setup`. This auto-surfaces the brand-VNC overlay before `ActionLogPanel` shows the OAuth URL inside it, so the operator never has to open the menu manually. The `[browser-viewer] event=mount surface="overlay"` line must appear within 5 s of `[cloudflare-setup] phase=action-launched`; absence is a regression.
+
 ## Identity model
 
 - **Product identity** (Maxy vs Real Agent) — known from `brand.json` (`productName`, `configDir`).

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

@@ -2,7 +2,7 @@
 
 Step-by-step recovery path for when the Maxy automation fails or is unavailable. Every command below is isolated in its own code block — nothing to parse from prose. Every path is brand-scoped so multiple brands can coexist on the same Linux user.
 
-Prerequisites: `cloudflared` installed; the brand's VNC running on its own X display + rfbport + websockify + CDP port (per `brand.json`'s `vncDisplay`/`rfbPort`/`websockifyPort`/`cdpPort` fields — Tasks 553 + 924; defaults Maxy=`:99`/`5900`/`6080`/`9222`, Real Agent=`:100`/`5901`/`6081`/`9223`, Maxy-2=`:101`/`5902`/`6082`/`9224`, Maxy-3=`:102`/`5903`/`6083`/`9225`, Maxy-4=`:103`/`5904`/`6084`/`9226`); SSH access to the device.
+Prerequisites: `cloudflared` installed; the brand's VNC running on its own X display + rfbport + websockify + CDP port (per `brand.json`'s `vncDisplay`/`rfbPort`/`websockifyPort`/`cdpPort` fields — Tasks 553 + 924; defaults Maxy=`:99`/`5900`/`6080`/`9222`, Real Agent=`:100`/`5901`/`6081`/`9223`, Maxy-2=`:101`/`5902`/`6082`/`9224`, Maxy-3=`:102`/`5903`/`6083`/`9225`, Maxy-4=`:103`/`5904`/`6084`/`9226`); SSH access to the device. The defaults table is historical — runtime readers (`paths.ts`, admin/MCP, `vnc.sh`, `test-laptop-vnc-boot.sh`) loud-fail with `reason=cdp-port-unresolved` if any of `rfbPort`/`websockifyPort`/`cdpPort` is missing from the live `brand.json`; the values above show what each brand's `brand.json` contains, not what the readers fall back to.
 
 ---
 

package/payload/platform/scripts/test-laptop-vnc-boot.sh

@@ -29,7 +29,14 @@ pass()   { echo "OK: $*"; }
 [ -r "$BRAND_JSON" ] || fail "${BRAND_JSON} unreadable"
 command -v jq >/dev/null 2>&1 || fail "jq not on PATH (apt install jq)"
 CONFIG_DIR=$(jq -r '.configDir // ".maxy"' "$BRAND_JSON")
-CDP_PORT=$(jq -r '.cdpPort // 9222' "$BRAND_JSON")
+# Task 959 — brand.json is the single source of truth for cdpPort at
+# runtime; a missing field is a doctrinal violation, not a fallback.
+if ! CDP_PORT=$(jq -er '.cdpPort' "$BRAND_JSON" 2>/dev/null); then
+  _keys=$(jq -r 'keys | join(",")' "$BRAND_JSON" 2>/dev/null || echo "unparseable")
+  _brand=$(echo "$CONFIG_DIR" | sed 's/^\.//')
+  echo "[test-laptop-vnc-boot] error reason=cdp-port-unresolved brand=$_brand path=$BRAND_JSON field=cdpPort json_keys=$_keys" >&2
+  exit 1
+fi
 PERSIST_DIR="${HOME}/${CONFIG_DIR}"
 VNC_LOG="${PERSIST_DIR}/logs/vnc-boot.log"
 

package/payload/platform/scripts/vnc.sh

@@ -41,36 +41,42 @@ set -uo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PLATFORM_ROOT="${MAXY_PLATFORM_ROOT:-$(dirname "$SCRIPT_DIR")}"
 BRAND_JSON="${PLATFORM_ROOT}/config/brand.json"
-CONFIG_DIR=".maxy"
-VNC_DISPLAY_NUM=99
-RFB_PORT=""
-WEBSOCKIFY_PORT=""
-CDP_PORT=""
-BRAND_HOSTNAME="maxy"
-if [ -f "$BRAND_JSON" ] && command -v jq >/dev/null 2>&1; then
-  _dir=$(jq -r '.configDir // empty' "$BRAND_JSON" 2>/dev/null) || true
-  [ -n "$_dir" ] && CONFIG_DIR="$_dir"
-  _vd=$(jq -r '.vncDisplay // empty' "$BRAND_JSON" 2>/dev/null) || true
-  if [ -n "$_vd" ] && [ "$_vd" -eq "$_vd" ] 2>/dev/null; then
-    VNC_DISPLAY_NUM="$_vd"
-  fi
-  _rfb=$(jq -r '.rfbPort // empty' "$BRAND_JSON" 2>/dev/null) || true
-  if [ -n "$_rfb" ] && [ "$_rfb" -eq "$_rfb" ] 2>/dev/null; then RFB_PORT="$_rfb"; fi
-  _wsp=$(jq -r '.websockifyPort // empty' "$BRAND_JSON" 2>/dev/null) || true
-  if [ -n "$_wsp" ] && [ "$_wsp" -eq "$_wsp" ] 2>/dev/null; then WEBSOCKIFY_PORT="$_wsp"; fi
-  _cdp=$(jq -r '.cdpPort // empty' "$BRAND_JSON" 2>/dev/null) || true
-  if [ -n "$_cdp" ] && [ "$_cdp" -eq "$_cdp" ] 2>/dev/null; then CDP_PORT="$_cdp"; fi
-  _hn=$(jq -r '.hostname // empty' "$BRAND_JSON" 2>/dev/null) || true
-  [ -n "$_hn" ] && BRAND_HOSTNAME="$_hn"
+
+# Task 959 — brand.json is the single source of truth at runtime; missing
+# fields loud-fail rather than silently substituting a vncDisplay-derived
+# offset (silent-fallback-masks-root-cause recurrence). The install-time
+# offset rule in packages/create-maxy/src/index.ts stamps every brand at
+# build time, so a correctly-installed device always has all five fields.
+if [ ! -f "$BRAND_JSON" ]; then
+  echo "[vnc.sh] error reason=brand-config-missing path=$BRAND_JSON" >&2
+  exit 1
+fi
+if ! command -v jq >/dev/null 2>&1; then
+  echo "[vnc.sh] error reason=brand-config-missing path=$BRAND_JSON detail=\"jq not on PATH\"" >&2
+  exit 1
 fi
 
-# Task 924 — deterministic fallback when brand.json omits any of the three
-# new port fields. Mirrors the rule in paths.ts so vnc.sh and the runtime
-# always agree on the port set even when only `vncDisplay` is stamped.
-_offset=$((VNC_DISPLAY_NUM - 99))
-[ -z "$RFB_PORT" ] && RFB_PORT=$((5900 + _offset))
-[ -z "$WEBSOCKIFY_PORT" ] && WEBSOCKIFY_PORT=$((6080 + _offset))
-[ -z "$CDP_PORT" ] && CDP_PORT=$((9222 + _offset))
+# `exit 1` inside a `$(…)` command substitution only kills the subshell, so
+# the loud-fail uses a parent-context `||` chain instead. Each field is read
+# with `jq -e` (exit non-zero on null/missing) and a parent-context error
+# helper invokes the script-level `exit 1`.
+_fail_brand_field() {
+  local field="$1"
+  local keys
+  keys=$(jq -r 'keys | join(",")' "$BRAND_JSON" 2>/dev/null || echo "unparseable")
+  local brand_label
+  brand_label=$(jq -r '.configDir // "unknown"' "$BRAND_JSON" 2>/dev/null | sed 's/^\.//')
+  echo "[vnc.sh] error reason=cdp-port-unresolved brand=$brand_label path=$BRAND_JSON field=$field json_keys=$keys" >&2
+  exit 1
+}
+
+CONFIG_DIR=$(jq -er '.configDir' "$BRAND_JSON" 2>/dev/null) || _fail_brand_field configDir
+VNC_DISPLAY_NUM=$(jq -er '.vncDisplay' "$BRAND_JSON" 2>/dev/null) || _fail_brand_field vncDisplay
+RFB_PORT=$(jq -er '.rfbPort' "$BRAND_JSON" 2>/dev/null) || _fail_brand_field rfbPort
+WEBSOCKIFY_PORT=$(jq -er '.websockifyPort' "$BRAND_JSON" 2>/dev/null) || _fail_brand_field websockifyPort
+CDP_PORT=$(jq -er '.cdpPort' "$BRAND_JSON" 2>/dev/null) || _fail_brand_field cdpPort
+BRAND_HOSTNAME=$(jq -r '.hostname // empty' "$BRAND_JSON" 2>/dev/null)
+[ -z "$BRAND_HOSTNAME" ] && BRAND_HOSTNAME="${CONFIG_DIR#.}"
 
 VNC_DISPLAY=":${VNC_DISPLAY_NUM}"
 MAXY_DIR="${HOME}/${CONFIG_DIR}"