diff --git a/.planning/phases/02-ui-performance/02-AIUI-D14.md b/.planning/phases/02-ui-performance/02-AIUI-D14.md new file mode 100644 index 00000000..cb724f93 --- /dev/null +++ b/.planning/phases/02-ui-performance/02-AIUI-D14.md @@ -0,0 +1,140 @@ +# AIUI D-14 Embed Contract + +**Written:** 2026-07-30 (Phase 02 Plan 07, Task 1) +**Purpose:** Record where AIUI's source lives, what its embed parameter contract is today, +which side implements each of D-14's two UX defaults, and what deploying the AIUI half +would require — so Task 2 (and any future agent) does not re-run this search. + +## Source Location + +AIUI's source is **not present on this machine and not reachable via the noted build +server at this time.** Search performed and exhausted: + +1. **Sibling-repo checks** (the two places `neode-ui`'s own tooling expects it): + - `neode-ui/package.json`'s `dev:mock` script: `cd ../../AIUI && pnpm dev` (relative to + `neode-ui/`, i.e. `/AIUI`) — degrades to + `echo '[AIUI] Not found at ../../AIUI — chat will show placeholder'` when absent. + - `scripts/setup-aiui-server.sh`: `AIUI_DIST="$PROJECT_DIR/../AIUI/packages/app/dist"` + (relative to the `archy` repo root, i.e. the same sibling directory), with a + documented prerequisite: "AIUI must be built locally first: + `cd AIUI/packages/app && VITE_BASE_PATH=/aiui/ npx vite build`". + - Checked directly: `/home/archipelago/Projects/AIUI` does **not** exist. + `ls /home/archipelago/Projects/` shows only `archy` and various `archy-*` + worktree/backup checkouts, `botfights`, and two unrelated Indeehub projects — no + `AIUI` directory. + +2. **Broader filesystem search** for any directory literally named `AIUI` (case-insensitive) + containing AIUI's own `package.json`: `find / -maxdepth 6 -iname "AIUI" -type d` returned + only deployed **build output** directories — `/opt/archipelago/web-ui*/aiui` (dozens of + timestamped backup copies), `/opt/archipelago/apps/aiui` (this repo's manifest dir, no + source), `archy`'s own `apps/aiui` and `demo/aiui` (built static assets, mirrors of the + deployed bundle), and installer-ISO copies under `image-recipe/`. None of these are + AIUI's source repository — they are prebuilt `dist/` output, deployed or bundled. + +3. **ThinkPad build server reachability** (project memory notes `.116` as the primary build + server, where AIUI may live if not here): both ping and SSH to `192.168.1.116` failed — + `ping` returned "Destination Host Unreachable" from the local gateway (`192.168.1.66`), + and `ssh -o BatchMode=yes -o ConnectTimeout=3` timed out after 3s with "Connection timed + out" on port 22. The build server is not reachable from this execution environment right + now (machine likely off or off this network segment). + +**Conclusion:** The search is exhausted for this session. AIUI's source cannot be read from +`archy` alone, confirming RESEARCH.md's Open Question 1. Task 2's `` — which +requires this section to name a reachable checkout — is **not met**; this plan halts before +any code targeting the AIUI side is written, per the plan's own instruction not to invent a +parameter and ship it. + +## Embed Parameter Contract + +`neode-ui/src/views/Chat.vue`'s `aiuiUrl` computed (lines ~74-82) constructs the iframe URL +today with: +- `embedded=true` — always present when a URL is built. +- `hideClose=true` — always present when a URL is built. +- `&mockArchy=1&seed=1` — only appended when `IS_DEMO` is true. + +Because AIUI's own source could not be inspected, the exact file/line where each parameter +is *parsed inside AIUI* cannot be recorded from source, per the instruction not to invent +what wasn't verified. As a diligence step (not a substitute for source access), the +currently-**deployed** AIUI build's static JS bundle was inspected instead — this is a +built artifact, not source, so variable/function names are minified and the full parsing +logic cannot be confirmed with certainty from it. Findings, treated as supporting evidence +only: + +- Bundle inspected: `/opt/archipelago/web-ui/aiui/assets/index-Lh5NfTCq.js` (byte-identical + copy also present in this repo at `demo/aiui/assets/index-Lh5NfTCq.js` and + `web/dist/neode-ui/../aiui`-style deploy mirrors — same build hash everywhere checked). +- `embedded` — read via `new URLSearchParams(window.location.search).has("embedded")`, + stored as `window.__AIUI_EMBEDDED__`. This is a **presence-only** check (any value, + including none, counts as embedded=true). Confirmed present in the bundle. +- `mockArchy` — read via `.has("mockArchy")`, but only takes effect when the embedded flag + is *false* (`&&!embedded` in the minified logic). This does not match how `Chat.vue`'s + demo mode currently sends both `embedded=true` and `mockArchy=1` together — flagging as + an existing inconsistency in the deployed build, unrelated to D-14 and out of this plan's + scope to investigate or fix. +- `hideClose` — **zero** occurrences of the literal string anywhere in this build's JS. No + evidence this deployed build reads or honors it at all. +- `seed` — not exhaustively searched this pass; irrelevant to D-14, not pursued further. + +No parameter resembling an expanded-state or mobile-initial-view control (see D-14a/D-14b +below) was found anywhere in this bundle. + +## D-14a + +**Default:** the AIUI chat should start EXPANDED rather than requiring the user to expand it. + +- **Status: needs a new AIUI-side parameter** (or a postMessage control, per the plan's + fallback path). No string resembling `expandedState`, `chatExpanded`, `expandChat`, or + similar chat-UI-state control was found in the deployed bundle. The one `expanded` hit in + the bundle is inside a third-party media-player library's ARIA `aria-expanded` attribute + code — unrelated to chat panel state. +- **Which side implements it:** AIUI (the receiving half must read the flag and render + itself in the expanded state on load). neode-ui's half — appending the agreed flag name + to the iframe URL — is inert and forward-compatible even before AIUI reads it, but cannot + usefully ship without the AIUI-side change, and the AIUI-side change itself is blocked: + its source is unreachable this session (see Source Location above). + +## D-14b + +**Default:** on a mobile viewport, AIUI should open on its CHAT view rather than its +context view. + +- **Status: needs a new AIUI-side parameter** (or a postMessage control). No string + resembling `mobileView`, `initialView`, `view=chat`, `view=context`, or similar was found + in the deployed bundle. +- **Which side implements it:** AIUI (it owns the chat-view/context-view routing and would + need to read an initial-view flag or a fixed mobile-view-preference flag on load). + Same blocked status as D-14a — the AIUI-side change cannot be made without source access. + +## Deployment Impact + +`apps/aiui/manifest.yml` declares: +```yaml +container: + image: localhost/archipelago-aiui:latest + pull_policy: always +``` + +AIUI ships as a **prebuilt container image**, not as neode-ui-bundled static assets served +alongside the rest of the dashboard. Shipping any AIUI-side source change requires, in +order: + +1. Access to the AIUI source repository (currently unreachable — see Source Location). +2. Rebuilding AIUI's production bundle, per the documented prerequisite in + `scripts/setup-aiui-server.sh`: `cd AIUI/packages/app && VITE_BASE_PATH=/aiui/ npx vite build`. +3. Rebuilding the `localhost/archipelago-aiui:latest` container image from that fresh build + output (the manifest names a `localhost`-scoped image tag, implying a local/on-node + build or push into each target node's local image store — not a registry pull from + outside the fleet). +4. Redeploying/restarting the `aiui` app container on the target node(s) so + `pull_policy: always` picks up the new local image tag. + +Per D-15, this phase restricts deployment to the **dev pair only, with no OTA** — so even +once source access becomes available, an AIUI-side D-14 change would be built and deployed +only to the designated dev nodes (per plan 02-08, which owns the deploy step), not pushed +through the normal fleet release train. + +**Bottom line:** until AIUI source access is available (e.g. the ThinkPad build server at +`.116` comes back online and is confirmed to hold the AIUI checkout, or the repository is +otherwise made reachable), the AIUI half of D-14 cannot be implemented, built, or deployed +at all. This is a genuine blocking external dependency, not a scope reduction — D-14 is not +dropped, it is blocked pending a fact only the developer can supply.