115 lines
8.4 KiB
Markdown
115 lines
8.4 KiB
Markdown
# WebUI Fleet Bridge Planning Scratchpad
|
||
|
||
**Mode:** Task 0 docs-only decision PR authorized; Task 1 and all executable/runtime work remain blocked.
|
||
**Owner:** Velma
|
||
**Opened:** 2026-08-09
|
||
**Scope:** One enrolled Agent Host launching one native `mosaic claude` OAuth session and streaming it into `apps/web` through `apps/gateway`.
|
||
|
||
## Objective
|
||
|
||
Turn the approved direction in `jarvis-brain/docs/scratchpads/MOSAIC-WEBUI-FLEET-BRIDGE.md` into a test-first implementation plan while preserving Fred's harness-home/launcher contract and Scooby's greenfield safety findings.
|
||
|
||
## Source reconciliation
|
||
|
||
- Current `origin/main`: `b0f7d26dd9c14d91eaaefc35d6c9fd6618a0bd92`.
|
||
- Current `origin/next`: `4df478cdd150fdf8d52ea109f02ade5d85017acd`.
|
||
- Branches currently diverge (`main` has 11 unique commits; `next` has 13). `next` contains local-tier Redis fix #689; `main` contains later fleet/shell fixes.
|
||
- Fred's three-root harness-home design and promotion stack are not yet fully present on either baseline.
|
||
- Therefore neither current SHA is an acceptable implementation pin. Code may begin only from a Fred-certified reconciled SHA containing the required launcher/home contract and safe Gateway startup prerequisites.
|
||
- The deployed `mosaic.woltje.com` v0.0.20 UI remains reference-only.
|
||
|
||
## Verified seams
|
||
|
||
- Current browser chat uses an in-process Pi SDK session.
|
||
- `AgentRuntimeProvider` supports list/tree/stream/send/attach/detach/terminate, but not create/start.
|
||
- `InteractionController` enrolls an already-existing runtime session; it cannot launch one.
|
||
- Hermes is the only runtime provider registered in Gateway.
|
||
- Tmux streaming is explicitly unsupported and remains out of scope.
|
||
- `mosaic claude` is the authoritative launcher and accepts Claude's machine-facing stream-json flags.
|
||
- Installed discovery version: Claude Code 2.1.226. Target Distrobox version must be independently pinned and certified.
|
||
|
||
## Non-negotiable dependencies
|
||
|
||
1. Fred approves the machine-facing launcher/seat-home contract before code.
|
||
2. No WebUI/Gateway direct read of lease broker state, daemon socket, or state files (F-V3).
|
||
3. No provider OAuth token leaves the Agent Host.
|
||
4. No local Gateway/Web startup around the KBN/database hold.
|
||
5. Greenfield work runs in a Debian Distrobox with an isolated home.
|
||
6. The initial plan PR targets `next`; Fred binds D1–D15 on its exact head before issue/PRD/tracker completion or implementation work.
|
||
|
||
## Reproducible evidence
|
||
|
||
Run from a clean Stack clone:
|
||
|
||
```bash
|
||
git fetch origin main next
|
||
git rev-parse origin/main origin/next
|
||
git rev-list --left-right --count origin/main...origin/next
|
||
rg -n "interface AgentRuntimeProvider|createSession|streamEvents|terminate" \
|
||
packages/types/src/agent packages/agent/src apps/gateway/src/agent
|
||
rg -n "AgentService\.prompt|interaction_sessions|createRuntimeTerminationApproval" \
|
||
apps/gateway/src packages/db/src/schema.ts
|
||
```
|
||
|
||
Primary inspected source seams:
|
||
|
||
- `packages/types/src/agent/agent-runtime-provider.ts`
|
||
- `packages/agent/src/{runtime-provider-registry,hermes-runtime-provider,matrix-native-runtime-provider,tmux-fleet-runtime-provider}.ts`
|
||
- `apps/gateway/src/agent/{runtime-provider-registry.service,interaction.controller,durable-session.repository,durable-session.service}.ts`
|
||
- `apps/gateway/src/chat/chat.gateway.ts`
|
||
- `packages/mosaic/src/commands/{launch,interaction}.ts`
|
||
- `packages/mosaic/src/fleet/generated-env-boundary.ts`
|
||
- `packages/db/src/schema.ts`
|
||
- `apps/web/src/app/(dashboard)/chat/page.tsx`
|
||
|
||
Planning-only investigation transcripts are local and intentionally uncommitted:
|
||
|
||
- `/tmp/velma-plan-stack-surface.txt`
|
||
- `/tmp/velma-plan-structure.txt`
|
||
- `/tmp/velma-plan-scooby.txt`
|
||
- `/tmp/velma-plan-runtime-contract.txt`
|
||
|
||
## Source findings that constrain the design
|
||
|
||
- `interaction_sessions.id` is the stable primary key; there are no create/policy/enrollment/state columns.
|
||
- `interaction_outbox` has a unique `(session_id, idempotency_key)` index and only `pending | processing | delivered`.
|
||
- Baseline `DurableSessionRepository.create()` can replace provider/runtime identity for the same owner; M1 must remove that implicit mutation.
|
||
- Baseline termination approval is Redis-backed and currently consumes separately from PostgreSQL; M1 therefore needs durable authorization acceptance before destructive token deletion/dispatch.
|
||
- Existing interaction HTTP base is `/api/interaction/:agentName`; the plan extends it rather than inventing a second route family.
|
||
- Baseline `launch.ts`/lease launcher still use ambient lookup/literal interpreters. Section 4.1 is non-binding consumer input to Fred's W-F design; W-F's final resolved-launch contract must exist in the certified base before Velma can certify it.
|
||
- Root `pnpm test` is not KBN-safe: it includes PGlite migration and framework-shell/lease-broker suites.
|
||
|
||
## Independent draft review
|
||
|
||
Seven adversarial review rounds found and drove explicit fixes for:
|
||
|
||
- a candidate resolved-seat consumer descriptor and threat model, now explicitly non-binding input to Fred's W-F-owned launcher design;
|
||
- one active launch per stable conversation, exact pending/failed encodings, durable pre-dispatch reservation, CAS activation, and crash lookup without a migration;
|
||
- generation-bound enrollment, command/event revalidation, `SIGHUP` config epochs, and stale-epoch rejection;
|
||
- Redis/PostgreSQL exact-stop crash safety via non-destructive verify, durable authorization acceptance, atomic claim/`GETDEL`, and same-operation status reconciliation;
|
||
- sequence gaps/reorder limits, deterministic UUIDv5 completion, and Gateway restart fail-closed behavior;
|
||
- shared streaming redaction before host ring/transport and again before Gateway persistence/browser;
|
||
- D2/D12-selected path-free provenance and a separate safe browser DTO—never raw or hashed path strings;
|
||
- exact F-V3 boundary: bridge has no broker API, while Fred's sealed launcher may enforce broker policy internally;
|
||
- migration-free focused tests in Tasks 1–8, with live OAuth, repository transaction, Gateway/Web, and Playwright restricted to the Fred/Scooby-certified Task 9 path;
|
||
- candidate private/public commitment and artifact-binding mechanisms that W-F may accept, simplify, replace, or defer;
|
||
- JCS event-digest recomputation and equal/different duplicate handling in both accepted and future-buffer states;
|
||
- a safe browser presentation DTO for host/workspace/seat/persona labels, readiness, and connection state;
|
||
- explicit `OnApplicationBootstrap` create/stop recovery enumeration with no auto-launch;
|
||
- all POSIX/Windows/UNC/file/tilde path classes in the streaming redactor and definitive failed-stop response semantics;
|
||
- the full 14-column canonical task schema, fake-only Task 5 repository tests, migration-free certified Task 9 DB test, server-owned operation correlations/routes, and exact merged-SHA smoke;
|
||
- per-commit independent review, queue guards, exact-head PR review, squash merge, exact merged-next SHA/CI wait, worktree-bound smoke, issue-state readback, and reviewed tracker-closure PR with its own merged-next CI;
|
||
- a private DB URL loader captured/exported per session without recording or echoing the credential;
|
||
- an attached Task 9 implementation branch, provider-filtered exact issue-state readback, and machine-verified smoke JSON binding source/worktree/deployed SHA;
|
||
- a capped, duplicate-key-rejecting, exact-key/type smoke schema so report extensions or JSON boolean/float coercion cannot smuggle data or fake child-count evidence.
|
||
|
||
The plan remains deliberately **decision-PR-ready, not implementation-ready**. Fred authorized only Task 0's initial two-document PR on `next`. He must still return every Section 2 value, replace all `[FRED-GATE]` entries, certify storage/startup, and provide the W-F-dependent `IMPLEMENTATION_BASE_SHA` before Task 0 closes or Task 1 starts.
|
||
|
||
## Current status
|
||
|
||
- Gitea principal verified as `velma`; helper and API wrapper resolution are fail-closed and correct.
|
||
- Fred authorized the initial Task 0 docs-only PR in `comms/20260809T094952Z__from-fred__ec0e85.md` and confirmed its `next` lane/W-F descriptor corrections in `comms/20260809T095437Z__from-fred__4ee79d.md`.
|
||
- Provisional decisions: D1/D8/D9/D10/D13/D14 approved; D4 tool labels exactly `{Read, Grep, Glob}`; D5/D12 provisional; D11 remains a single-operator seam; D2/D3/D6/D7 and `IMPLEMENTATION_BASE_SHA` are `BLOCKED-ON-W-F`.
|
||
- Awaiting exact plan-PR-head review and Fred's complete D1–D15 binding contract.
|
||
- No source code, database, deployment, or live runtime changes made.
|