# V3 Architecture

## Goals

1. Make task progress observable from CLI, Cockpit, Telegram, and app.99pages.uk.
2. Keep deterministic monitoring separate from AI reasoning.
3. Prevent provider sprawl by routing all model calls through AI Workforce.
4. Keep V1 commercial delivery stable while V3 evolves.
5. Make every application a CLI-addressable MCP capability before adding UI.

## Components

```text
Core CLI
  -> Run Store
  -> Event Stream
  -> Approval Gate
  -> AI Workforce Router
  -> MCP Tool Layer
  -> Shell / Browser / Computer Use / Virtual Desktop

Sentinel
  -> local deterministic checks
  -> conditional run creation

Cockpit
  -> subscribes to event stream
  -> shows runs, approvals, virtual desktop, artifacts
```

## Browser Layer Decision

Cockpit and app.99pages.uk use HTML5/PWA as the primary GUI layer.
This is a product constraint, not just an implementation preference.

The browser layer is a remote-control surface:

- Chat with Core CLI.
- Display run events, approvals, artifacts, and logs.
- Show a browser terminal for Core CLI conversation and status.
- Launch Mini Apps and project their SQLite-backed state.

The browser layer is not a bash editor and should not own execution logic.
Shell execution remains in Core CLI, SubCLI, PTY, SSH, and MCP modules.
On Windows, those CLI surfaces must use PowerShell with UTF-8 input/output so
Chinese input is reliable. `cmd.exe` is not the default shell surface.

Applications are not traditional frontend bundles by default. An app is a
manifest, tools, data contract, events, reports, approval policy, and optional
projection URL. app.99pages.uk projects those capabilities when visual operation
is worth maintaining.

```text
HTML5/PWA Cockpit
  -> HTTP/WebSocket bridge
  -> Core CLI daemon
  -> SubCLI / MCP / PTY / SSH / Keybox
  -> local SQLite stores
```

This keeps Windows, macOS, Linux, ChromeOS, and remote-control devices on the
same UI code path. GUI can degrade gracefully; Core CLI remains usable without
the browser.

## Remote Control Devices

A device used as remote control should not be forced to become the execution
device. app.99pages.uk and Cockpit can send commands, inspect state, and approve
actions, while a separate local machine or VPS performs the work.

Remote commands should become queued tasks by default. Forced intervention is a
separate action because it can interrupt a running agent.

## Mini App Builder

Mini Apps are lightweight by default and CLI/MCP first:

- Schema and database preparation are the first deliverables.
- Data import/write and update events matter more than screens.
- Final reports are required.
- HTML5/PWA UI is optional projection.
- Capability access goes through the same MCP/Skill/Plugin registry.

The builder should clone capability templates from installed MCPs rather than
generating isolated custom stacks for every app.

## Event Types

- `run.created`
- `agent.selected`
- `step.started`
- `tool.call`
- `tool.result`
- `approval.required`
- `artifact.created`
- `step.completed`
- `run.completed`
- `run.failed`
- `sentinel.tick`
- `sentinel.condition_matched`

## Commercial Policy

- Main agent is always `minimax-2.5`.
- Main agent uses the `private_assistant_default` profile and defaults to English.
- Module agents are assigned by `configs/model_policy.json`.
- No raw provider names are exposed to end users.
- Every event can be replayed.
- Every mutating action can request approval.
- Health Score uses the internal `health_score_fast` AI Workforce tier for
  speed and cost control. Cockpit must not show the underlying model or provider.
