Skip to content

docs: define canonical local and managed T4 architecture #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
iarbpairs merged 6 commits into from
Jul 21, 2026
Merged

docs: define canonical local and managed T4 architecture #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
de88cab
docs: define T4 Hub architecture
iarbpairs Jul 20, 2026
8de5a51
docs: maintain T4 Hub plan as HTML
iarbpairs Jul 20, 2026
1a78e47
docs: sequence T4 Hub delivery gates
iarbpairs Jul 20, 2026
b10b1ee
docs: prerender architecture flows
iarbpairs Jul 20, 2026
3efda2b
docs: make architecture plan self-contained
iarbpairs Jul 20, 2026
bf4821c
docs: consolidate local and managed architecture
iarbpairs Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 44 additions & 58 deletions PRODUCT_BRIEF.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,70 +2,56 @@

## Product

A desktop, web, and mobile workspace for OMP. Preserve OMP as the agent runtime; make projects, concurrent sessions, live streaming, tools, terminal activity, subagents, reviews, files, settings, and remote hosts easier to see and operate.

## Primary reference

T3 Code at `reference/t3code` is the primary presentation, interaction, desktop-shell, and implementation reference. Its MIT license permits copying and modification with attribution. Use direct adaptation where it accelerates quality; do not reimplement equivalent primitives without a reason.
T4 Code is a Flutter desktop, mobile, and web workspace for official Oh My Pi (OMP). It makes
projects, concurrent sessions, live streaming, tools, terminal activity, task agents, reviews, files,
settings, and local or remote execution easier to operate without reimplementing OMP behavior.

## Experience target

- Presentation and perceived performance are product-critical.
- Keyboard-first, dense when useful, calm by default.
- Fast project/session switching with preserved scroll, composer, panel, and draft state.
- Center session stream remains the primary surface.
- Optional right pane extends the T3 pattern with five calm surface families: Agents, Activity (including events), Review, Files, and Agent Terminals. The user terminal remains a bottom drawer. Context is a popover/dialog, not a permanent tab.
- Browser/app preview is available through the focused host Preview and the separate native desktop Browser workspace rather than becoming a sixth permanent right-pane family.
- Keyboard shortcuts, Quick Open, the workspace menu, and transcript tool links use one shared action registry so the same operation has one availability rule and one implementation.
- Quick Open searches filenames across the active project through a bounded desktop-host operation. OMP supplies the trusted session root; the renderer never receives or chooses an absolute path. Older or limited hosts fall back honestly to files already loaded in the inspector.
- A visible text-file preview can be deliberately staged as bounded, reviewed context for the next new prompt. It is temporary renderer state compiled into ordinary prompt text; it does not create a second runtime authority.
- Light and dark themes use neutral surfaces. Accent use is minimal and semantic.
- OMP identity uses the existing pi/connector mark from the upstream Oh My Pi repository and the Pi Pink `#e83174` accent.
- No SVG turbulence, paper-grain, noise texture, or equivalent decorative overlay is imported from T3.

## Runtime boundary

- OMP remains authoritative for prompt acceptance, transcript truth, models, tools, sessions, task agents, memory, skills, settings, credentials, and execution.
- T4 clients consume the versioned T4 Host protocol. The T4 Host consumes the narrower OMP authority bridge; clients do not parse terminal pixels as their primary data source or reimplement OMP behavior.
- A persistent T4 Host runs beside OMP, speaks to the pinned OMP authority bridge, supports local desktop attachment, and supports authenticated remote attachment across the user's Tailscale tailnet.
- Remote control must preserve exact session identity, reconnect/replay semantics, capability authorization, and explicit destructive-action boundaries.

## Hub direction
- Fast project/session switching preserves scroll, composer, panel, and draft state.
- The center session stream remains the primary surface.
- Optional right-pane surfaces cover Agents, Activity, Review, Files, and Agent Terminals. The user
terminal remains a bottom drawer; Context is a popover or dialog.
- Browser and app preview remains a focused workspace rather than a permanent sixth pane.
- Keyboard shortcuts, Quick Open, workspace menus, and transcript links use one action registry so
availability and behavior do not diverge.
- Quick Open searches through bounded authorized operations. Flutter never receives or chooses an
absolute path it does not already own.
- A visible text preview may be staged as reviewed context for a prompt. It does not become a second
runtime authority.
- Light and dark themes use neutral surfaces with minimal semantic accent.
- OMP identity uses the existing pi/connector mark and Pi Pink `#e83174` accent.

## Product modes

T4 Code presents one client experience across four execution profiles:

- **T4 Local:** native execution on this macOS or Linux computer.
- **Personal Hub:** a managed installation on one Linux machine.
- **HA Hub:** a managed installation across tested Linux failure domains.
- **Workstation Runner:** native macOS or Linux execution registered with an existing Hub.

The client reports the selected profile and its capabilities truthfully. It never presents local
sessions as portable, terminal-only behavior as remotely executable, or unavailable features as
working.

## Runtime principle

OMP remains authoritative for prompt acceptance, transcript truth, models, tools, sessions, task
agents, memory, skills, settings, credentials, and execution. T4 operates through public OMP seams,
does not parse terminal pixels as its primary data source, and does not grow a permanent private OMP
distribution.

T4 is preparing a central Hub for users who coordinate several personal dev boxes, team machines,
or managed worker pools. The Hub will coordinate identity, durable commands, ownership, and events;
OMP will continue to own prompt acceptance, transcript truth, tools, and agent execution. The
released local T4 Host path remains supported while the Hub matures through the development
checkpoints in [`ADR-016`](docs/adr/016-hub-collaboration-foundation.md). Shared work is tracked in
[`docs/T4_HUB_TRACKER.md`](docs/T4_HUB_TRACKER.md).

The Hub contracts are independent of the client framework and deployment scheduler. A normal remote
dev box does not require Kubernetes or shared cluster storage merely to participate.

The local T4 Host and future T4 Nodes should converge on one shared OMP runtime adapter that operates
official pinned OMP through public RPC, SDK, and extension seams. The currently released Lycaon
authority bridge remains supported while that path is proven, but T4 does not plan to grow separate
local and distributed OMP integrations. Capabilities unavailable through official OMP are reported
honestly, supplied by an optional narrow T4 plugin when public extension APIs allow it, or proposed
as small generic upstream seams.

## Planned package boundaries
## Proof standard

- `apps/desktop`: Electron main/preload, packaging, updates, OS integration.
- `apps/web`: T3-derived React renderer and desktop/web client shell.
- `apps/mobile`: the current native Android wrapper around the web client.
- `packages/host-wire`: T4-owned, dependency-free `omp-app/1` wire schema.
- `packages/host-service`: persistent host service, projections, bounded indexes, workspaces, policy, replay, files, PTY, audit, and OMP authority-bridge supervision.
- `packages/host-daemon`: standalone T4 Host executable.
- `packages/protocol`: consumes the workspace-owned host wire schema and adds desktop-only IPC schemas.
- `packages/client`: connection, replay, cache, optimistic-state rules, host/session stores, and strictly decoded host-search coordinators.
- `packages/remote`: remote target discovery, identity pinning, pairing, and transport helpers.
- `packages/service-manager`: desktop-side T4 Host installation and lifecycle support.
- future `packages/omp-runtime-adapter`: shared official-OMP lifecycle, capability, and translation boundary for local T4 Hosts and T4 Nodes.
- `packages/ui`: T3-derived design primitives, tokens, icons, motion, virtualization.
- `packages/fixture-server`: deterministic seeded sessions, faults, and load scenarios.
- OMP authority bridge: versioned runtime boundary for session persistence, project roots, locks, workers, configuration, credentials, tools, and execution.
Behavior is proven with executable contracts, deterministic failure scenarios, physical client
slices, measured latency and resource overhead, and platform-specific runtime proof. Product claims
follow observed behavior rather than compilation, healthy infrastructure, or optimistic capability
reporting.

## Proof standard
## Canonical architecture

Behavior is proven with deterministic contract tests, concurrency and reconnect stress, seeded visual states, screenshot comparison, interaction/motion checks, Linux runtime proof, macOS runtime proof, and a real two-host Tailscale smoke before remote functionality is called complete.
[`docs/T4_ARCHITECTURE.html`](docs/T4_ARCHITECTURE.html) is the sole specification for execution
profiles, authority, transport, storage, recovery, deployment, performance, and delivery gates.
105 changes: 43 additions & 62 deletions docs/OWNERSHIP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,67 +1,48 @@
# Ownership and handoffs

These boundaries describe the released T4 repository and reserve low-conflict lanes for the Hub
work. Assign people to roles in the relevant tracker or pull request; the role names are not
permanent team titles. A primary owner is a coordination default, not an exclusive write lock.
Cross a boundary when that is the fastest coherent change, and tell the other active owner when the
same files are in flight.
These boundaries coordinate changes across the released repository and planned architecture paths.
They are defaults, not permanent titles or exclusive locks. When active work overlaps, name an
integration owner or land the smaller shared contract first.

## Current repository paths

| Path | Primary owner |
|---|---|
| `packages/host-wire/**`, network-frame changes in `packages/protocol/**` | Protocol owner |
| `packages/host-service/**`, `packages/host-daemon/**` | Host systems owner |
| `packages/client/**`, `packages/fixture-server/**` | Client data and fixtures owner |
| `packages/remote/**`, `packages/service-manager/**` | Remote connection and service-lifecycle owner |
| `apps/web/**`, `packages/ui/**`, visible copy/assets/screenshots | Client experience owner |
| `apps/desktop/**` | Desktop systems owner; coordinate visible UI changes with the client owner |
| `apps/mobile/**` | Mobile packaging owner; shared web behavior stays in `apps/web` |
| Root manifests, workspace configuration, and `pnpm-lock.yaml` | Integration owner |
| `docs/adr/**`, architecture, licenses, notices, and provenance | Architecture/provenance owner |

OMP owns the authority bridge and runtime behavior described in ADR-013. T4 owns the generic host,
wire contract, remote policy, projections, and client experience. A published T4 release still pins
one exact compatible OMP artifact.

The migration target is one T4-owned OMP runtime-adapter boundary reused by the local T4 Host and
future T4 Nodes. It operates official pinned OMP through public RPC, SDK, and extension seams and may
load an optional separately versioned T4 plugin. The released Lycaon bridge remains a compatibility
implementation while that path is proven, not a reason for local and Node integrations to diverge.

## Planned Hub paths

| Lane | Reserved scope | Boundary |
|---|---|---|
| Hub | Future `apps/hub/**` and `packages/hub-*/**` | Owns durable product state and Hub Wire; does not write workspaces directly. |
| Node/runtime | Future `apps/node/**`, `packages/runtime-wire/**`, and shared `packages/omp-runtime-adapter/**` | Owns the official OMP seam, capability reporting, optional T4-plugin loading, lifecycle, and workspace operations for local Hosts and Nodes; does not connect to the Hub database or reimplement OMP behavior. |
| Client | A provider boundary selected during contract work | Consumes Hub Wire; does not consume Runtime Wire or reconstruct OMP truth. |
| Infrastructure | Future deployment path selected as experiments mature | Packages behavior without quietly redefining command or ownership semantics. |

These names reserve collaboration lanes, not mandatory package scaffolding. The contract phase may
reuse an existing package when that creates a clearer boundary.

## Shared-file handoffs

When active branches overlap on protocol schemas, generated bindings, database migrations, root
manifests, the lockfile, CI workflows, or final wiring, use a temporary integration owner or land the
smaller shared edit first. Early Hub schemas and databases may be reset while there are no live
users. Add compatibility migrations when an external environment actually needs continuity.

Contract changes can land with their first consumer when that is the fastest clear patch. Split the
contract into its own PR when several active branches already depend on it or the combined diff
becomes difficult to review.

Backend-to-client handoff includes protocol version, capabilities, golden fixtures, stable IDs and
revisions, and loading, empty, stale, reconnecting, denied, indeterminate, and old-owner states. The
client does not create a shadow schema or present unavailable capabilities as working.

Runtime-to-Hub handoff includes the pinned OMP version, acceptance and replay behavior, checkpoint
contents, cancellation behavior, failure ambiguity, executable contract fixtures, command execution
surfaces, plugin reach, plan/goal API availability, settings and lock authority, and the disposition
of every required fork patch. The Hub does not infer acceptance from dispatch alone. Clients do not
present a recognized terminal-only command as executable or send it to the model as ordinary text.

Every T3-derived port keeps its import record. Security-sensitive logs and fixtures remain bounded
and redacted. The active Hub work and evidence links live in
[`T4_HUB_TRACKER.md`](T4_HUB_TRACKER.md).
| Path | Primary owner |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `apps/flutter/**` | Flutter client and provider owner |
| `packages/host-wire/**`, network-frame changes in `packages/protocol/**` | Protocol owner |
| `packages/host-service/**`, `packages/host-daemon/**` | T4 Local systems owner |
| `packages/client/**`, `packages/fixture-server/**` | Client data and fixtures owner |
| `packages/remote/**`, `packages/service-manager/**` | Pairing, remote connection, and native service-lifecycle owner |
| `apps/web/**`, `packages/ui/**`, visible copy/assets/screenshots | Compatibility client experience owner |
| `apps/desktop/**` | Compatibility desktop systems owner; coordinate visible UI changes with the client owner |
| Root manifests, workspace configuration, and `pnpm-lock.yaml` | Integration owner |
| `docs/adr/**`, architecture, licenses, notices, and provenance | Architecture/provenance owner |

## Planned path reservations

These paths reserve ownership without requiring premature scaffolding:

| Path | Primary owner |
| -------------------------------------------------------------------- | ------------------------- |
| Future `apps/hub/**`, `packages/hub-*/**` | Hub systems owner |
| Future `packages/hub-wire/**`, shared capability and client schemas | Protocol owner |
| Future `packages/omp-runtime-adapter/**`, `packages/runtime-wire/**` | Runtime integration owner |
| Future operator, release, and managed deployment paths | Managed platform owner |
| Future native Workstation Runner package | Workstation systems owner |

## Handoffs

- OMP remains authoritative for runtime behavior. A published T4 release pins one exact compatible
official OMP artifact.
- Changes to shared client, Hub Wire, Runtime Wire, capability, identifier, or error schemas require
executable fixtures before consumers enable the behavior.
- Root manifests, workspace configuration, lockfiles, migration identifiers, CI workflows, OCI
builds, operator APIs, and deployment manifests require an integration owner when lanes overlap.
- Client owners consume normalized capabilities and state; they do not reconstruct OMP behavior or
backend authority.
- Security-sensitive logs, fixtures, and support data remain bounded and redacted.

## Canonical architecture

[`T4_ARCHITECTURE.html`](T4_ARCHITECTURE.html) is the sole specification for product profiles,
authority, transport, storage, recovery, deployment, performance, and delivery gates.
Loading
Loading