Workstream: AiCliSupervisorManager

Status: Shipped · Extension planned: session-lifecycle orchestration · Component: Enable agentic swarms · Docs: project page

This is an aspirational vision and design-scope document, not a milestone plan. It is the fleet-admin console over AiCliHostSupervisor — the engine, and the durable home of the agent, that this observes and drives. It is the admin-facing sibling of MyLittleAgi: both are consoles over the same supervisor fleet, but where MyLittleAgi hides the infrastructure for end users who just want to talk to their agents, this console puts supervisor configuration, health, and placement front and center for operators running the fleet. (Autonomous swarms are SpawningPool's.) It describes elevating today's single-supervisor diagnostic web UI into a fleet-wide console backed by a durable url:// service.

North star

Turn the raw supervisor fleet into something an operator can see and drive at a glance. One console that, across every supervisor at once, shows every live conversation, lets you name and organize the supervisors and their threads, and jumps you straight into any running session — without hand-copying url:// addresses or driving one supervisor at a time.

Today the AiCliHostSupervisorDaemonWui can only point at one supervisor and drive its raw sessions; a supervisor operator running a fleet has no single pane over all of them. This workstream closes that gap.

What this is — and what it is not

It is the fleet-admin console for the supervisor fleet. It elevates the single-supervisor diagnostic WUI into a fleet-wide console (AiCliSupervisorManagerWui) backed by a new durable manager service (AiCliSupervisorManager). Its subject matter is the supervisors and everything running on them — with supervisor configuration, health, and placement in the foreground, the details MyLittleAgi keeps hidden.
It is the sibling of the end-user console, not a separate agent store. The end-user console is MyLittleAgi; autonomous swarms are SpawningPool's. All three are frontends over the same supervisors — where agents (definitions, capabilities, history, the inter-agent mailbox) actually live. This Manager is the operator's lens: it holds only light operator metadata (supervisor aliases/descriptions, human names for live threads) and a live aggregated view; it has no agent store of its own.
Its API diet defines the agents' API. The Manager consumes only the supervisors' public url:// surface — and that same surface is what agents themselves consume when they act as clients, notably monitor agents (AiCliHostSupervisor §12). Because the Manager manages supervisors directly, it necessarily exposes whatever the engine supports (including trigger-woken conversations — initiation policy is a per-console choice, and this console makes none); and anything the Manager can do through the API, a suitably-granted agent can do too. The API's sufficiency bar is that neither the console nor a monitor needs anything private.
It is not where the supervisors' durable state lives. As of the AiCliHostSupervisor redesign, supervisors are the durable home of the agent — each durably owns its homed agents in full (definitions, permissions, runtime configuration, conversation catalog active + paused/archived, transcript history, and mailbox). The Manager does not implement or hold that state: it sits above the fleet and owns only its own operator-facing metadata plus a cached, aggregated view of what the fleet is doing. Durable agent and session state belongs to the supervisor that homes the agent, not here.

Guiding principles

Stateless console, durable manager. Per the standard layered architecture, the HTTPS console persists nothing to disk — it is a presentation layer. All durable state lives behind url:// in the manager service (Api / Embedded / ServiceServer), so it survives a console redeploy or host move, which an ephemeral ContainerNursery container cannot guarantee for disk state.
One fleet, one list. However a supervisor became known — it announced itself, or an operator typed its URL — it is the same thing: a supervisor connected to the manager. There is no "registered" vs. "recent" split; registration provenance is at most a small label, never a separate view.
Verified membership, durable identity. The list shows only supervisors that have actually been reached at least once; ones long unseen drop out of the view. But their operator metadata (alias, description, first-seen, advertised catalog) is kept, so a supervisor that comes back reappears fully named and described. Only an explicit remove forgets a supervisor.
The manager aggregates; the console renders. A cross-fleet view is expensive — each supervisor is a cold-prone P2P round-trip, the same reason the single-supervisor dashboard already needs a bounded render. So the manager continuously maintains the fleet view and the console reads it; the console never fans out to the whole fleet on a page load.
Names are for humans, bound to reality. A supervisor carries an operator alias and description; a live thread can be given a name. A thread name is bound to the actual running session — it survives a native resume of that session and retires when the session ends. Persistent, cross-session agent and conversation identity lives on the home supervisor (AiCliHostSupervisor), not in this console layer.

The shape of the system

        +------------------------------+
        |          Operator            |
        +------------------------------+
                     |  HTTPS
                     v
        +------------------------------+     stateless — no disk state
        |   AiCliSupervisorManagerWui  |     (fleet home, settings, per-supervisor
        |  aiclisupervisor.wasmserver  |      console, thread terminal)
        +------------------------------+
                     |  url:// via UrlResolver
                     v
   +--------------------------------------------+   DURABLE state (operator-facing only):
   |         AiCliSupervisorManager             |   - fleet registry + operator metadata
   |   url://aiclisupervisormanager/ service    |   - thread names
   |   (Api / Embedded / ServiceServer)         |   - cached cross-fleet conversation snapshot
   +--------------------------------------------+     (aggregated from supervisor catalogs)
        |            |            |  polls + receives announcements
        v            v            v
   url://vpn.*.  url://vpn.*.  url://vpn.*.aiclisupervisor/   <- STATEFUL AiCliHostSupervisor daemons,
   (supervisor)  (supervisor)  (supervisor)                     one per host — each is the durable HOME
                                                                of its agents: definition, config,
                                                                catalog (active+paused/archived),
                                                                history, mailbox

Which data lives where

The manager owns the durable operator state only: the fleet registry (each supervisor's stable id, url:// address, operator alias, description, first-seen / last-seen-or-verified timestamps, advertised harness/model catalog, and how it was first added), thread names (keyed to a supervisor and its session), the spend-source registry (operator-declared cost records — today each supervisor's $200/month subscription — feeding the Resource Consumption Rate charts), and a cached snapshot aggregated from each supervisor's durable state — the agents it homes and their conversation catalogs (active + paused/archived) — with their stats.
The supervisors own the actual PTY sessions and their live state — and, per the AiCliHostSupervisor redesign, the durable agents themselves: definitions, permissions, runtime configuration, conversation catalog (with resume state), transcript history, and mailbox. The Manager reads and aggregates this; it does not own it.
The console owns nothing durable — it renders the manager's state and relays operator actions back to it.

How the fleet view stays fresh

The manager keeps a rolling snapshot of every supervisor's conversation catalog, refreshed by extending the supervisor's periodic self-announcement to carry a catalog summary and by manager-side polling of supervisors that do not push. That one loop does several jobs at once: it drives each supervisor's online/offline state, updates the last-seen/verified timestamp, and feeds the staleness filter that decides list membership. Because the manager holds the aggregate, the console's fleet-wide pages render immediately from cache rather than blocking on the slowest cold supervisor.

Scope note: with stateful supervisors, the summary now covers a supervisor's agents and their whole conversation catalog — active (currently-running PTY), paused, and archived — because those durable entries live on the supervisor and it can report them. What the Manager never owns durably is any agent state — transcript history, definitions, mailbox — all of which live on the home supervisor. The Manager aggregates the catalog of agents and conversations (and their live status) for the operator; it stores none of it.

The surfaces

A fleet home — every conversation across every supervisor, in one table: its name (editable in place), its owning supervisor (linked), its status (active / paused / archived, drawn from the supervisor's durable catalog), its model, when it started, and when it last saw a message. A new conversation is started from here by choosing a supervisor and a model from that supervisor's advertised catalog; a paused one can be resumed on its owning supervisor.
A fleet usage view — quota/usage reports at each of the four AiCli scopes (supervisor, model, agent, conversation), each quota a max quantity + current quantity (tokens, requests, or a percentage — e.g. the Codex 5-hour/weekly limits), rendered from a manager-cached aggregate polled from each supervisor's getUsageJson. (Planned addition, 2026-08-01:) on the supervisors page, alongside the quota-available chart, a second chart titled "Resource Consumption Rate" shows the resources consumed over time, measured in dollars. Today the only consumed resource is each supervisor's $200/month harness subscription (every supervisor runs on its own credentials), so the chart renders as a flat line at the summed subscription spend rate; the chart is designed to fold in additional spend sources as they become tracked (e.g. CI build costs). The same chart also appears on each per-supervisor console page (e.g. https://aiclisupervisor.wasmserver.com/supervisor?id=sup-…), scoped to that supervisor's spend.
- Spend sources (decided 2026-08-01). Spend sources are durable, operator-editable records in the Manager service — not hard-coded in the console — managed from the fleet settings surface. Each source carries a name, a kind (today: flat recurring rate; later: metered feeds such as CI build costs), a dollar amount and period, a start date (defaulting to the supervisor's first-seen timestamp), and a scope: pinned to one supervisor, or fleet-wide. Today's only source is the per-supervisor $200/month subscription, so the fleet chart shows the sum across supervisors and each per-supervisor chart shows that supervisor's own subscription line. Genuinely fleet-wide sources appear on the fleet chart directly and on per-supervisor pages as a visually distinct series labeled fleet-wide — never apportioned across supervisors by head-count or usage share, which would chart an invented number; the adjacent Token Consumption chart already shows each supervisor's real usage-based cost.
- Chart semantics (decided 2026-08-01). Both spend charts plot a rate, not a cumulative total, normalized to dollars per day: the $200/month subscription renders as a flat line at ~$6.58/day (labeled "$200/mo"), and Token Consumption sums each turn's dollar cost into daily UTC buckets keyed by turn timestamp. The default window is 30 days (daily buckets need range), sharing the quota chart's visual conventions but without its projection machinery in v1; a cumulative toggle is derivable later if wanted. The two charts plot different kinds of dollars, and say so: Resource Consumption Rate is actual money leaving; Token Consumption is a shadow cost — what the same usage would cost at API list prices, since subscription usage is not billed per token — and carries an explicit "at API pricing" label so the charts are never read as double-counting. Laying the two lines side by side answers "is the subscription paying for itself?" at a glance. Token Consumption renders as a stacked series by model (top few models + "other"), so an expensive model's contribution is visible rather than folded into one undifferentiated line.
- Spend-history aggregation (decided 2026-08-01). The Manager polls each supervisor's getSpendHistoryJson(sinceDay) (AiCliHostSupervisor) at a slow cadence — hourly, plus an on-demand refresh when an operator opens a page whose cache is stale — and durably stores the merged per-supervisor daily series, mirroring how it already durably records UsageHistorySample. Spend history therefore survives a supervisor being wiped or replaced, even though the source session files die with the supervisor. The console renders only from this store, never fanning out on page load (per "the manager aggregates; the console renders"); the subscription lines come straight from the Manager's own spend-source registry and never touch a supervisor.
A fleet settings surface — where supervisors are managed: add one by URL (verified as reachable on add), give it an alias and a description, see its timestamps, glance at a quick table of its open threads (and jump straight into one), and remove it.
A per-supervisor console — the powerful single-supervisor view (full status, the complete thread table, start-a-thread, and per-supervisor controls), addressed by the supervisor's stable id rather than its raw url:// address. It carries the same planned "Resource Consumption Rate" chart as the supervisors page, scoped to that supervisor. (Planned addition, 2026-08-01:) it also carries a "Token Consumption" chart — the supervisor's token usage over time, dollar-spend-adjusted according to API pricing. The supervisor computes these values itself (see AiCliHostSupervisor) by scanning the past conversations in its harness CLIs' local session directories (the claude and codex directories) and computing per-conversation token usage and spend as ClaudeSpendApi defines it — that library's scope expands from Claude-only to cover codex spend too, generalizing into the harness-neutral AiCliSpend* family (decisions recorded in AiCliHostSupervisor). Per-model pricing is fetched dynamically — from OpenRouter's public models endpoint, with cached and bundled-static fallbacks (see AiCliHostSupervisor for the decided design) — rather than hard-coded, so price adjustments and newly released models are reflected without a code change.
An attach-monitor flow (added 2026-08-03 with the engine's monitor-agent design — AiCliHostSupervisor §12) — the surface that makes creating a monitor trivial. On any conversation page or agent row, an "Attach monitor" action opens a single form: pick an existing monitor agent or create one inline (name, model/harness, persona pre-filled from a built-in advisor template whose system prompt does the heavy lifting), the trigger keywords with match mode (substring/word) and case flag, the target scope (this conversation vs. all of the agent's conversations), watch-only vs. advising (whether may-inject is delegated alongside may-observe), circuit-breaker thresholds (defaults pre-filled), and the monitor's home supervisor (defaulting to the target's own supervisor for locality, with any healthy supervisor from the fleet registry allowed — monitors work cross-supervisor). One submit relays create-agent → capability delegation → attach to the supervisors; per this console's rules, the Manager durably stores none of it. Monitor visibility rides the existing surfaces: a watched conversation shows a "watched by …" badge with click-through to the monitor's own conversation, injected advice renders in the thread terminal under its attribution prefix, and a tripped circuit breaker surfaces loudly on the fleet home — with the two paused conversations linked as forensic evidence — until a human inspects and explicitly re-arms it.
A thread terminal — the live PTY view for one conversation, as today. Structured sends from console surfaces use the supervisor's atomic sendMessage operation (a whole message delivered as one serialized unit, never interleaved with another sender's input — the same operation monitor agents use to inject); raw keystroke access remains for the interactive terminal itself, where a human genuinely is typing.

Session-lifecycle orchestration: pause and resume

(Extension adopted 2026-07-17, revised 2026-07-18 in lock-step with the AiCliHostSupervisor redesign that makes supervisors stateful. The original framing put durable resume records in the Manager; that custody now lives in the supervisor, and the Manager's role narrows to orchestration + aggregation.)

The Manager already defines the state of new sessions (start-a-thread lives on its fleet home) and its thread names already survive a native resume. This extension completes that role — but as the orchestrator of session lifecycle across the fleet, not the durable custodian of it. Durable custody belongs to the now-stateful supervisor.

Pause and terminate are user-driven Manager operations. Supervisors keep a conversation warm indefinitely; it is the Manager that relays the user's request to pause or terminate a session to the owning supervisor (AiCliHostSupervisor §8).
The supervisor holds the resume record; the Manager aggregates it. On pause — deliberate or forced (host pressure, maintenance, crash recovery) — the supervisor flips its own durable catalog entry to paused, recording the harness, the CLI's native session reference, and the durable home reference. It does not hand that record off and forget; it keeps it. The Manager is notified so its cached cross-fleet snapshot shows the conversation as paused, but the authoritative resume record lives on the supervisor. This is a deliberate change from the earlier design, which stored the resume record in the Manager. (Durable transcript history — like everything else about the agent — lives on the home supervisor throughout; neither console stores it.)
Resume is a Manager-orchestrated relaunch on the owning supervisor. Continuing a paused conversation means the Manager asks the supervisor that holds it to relaunch from its own catalog entry; the relaunched CLI restores its own context via its native resume against the durable home (AiCliHostSupervisor §9). Because the durable config + catalog are pinned to that supervisor, resume defaults to same-host; resuming on a different supervisor would require migrating that durable state, which the engine workstream defers (AiCliHostSupervisor §8).

Scope

In scope: a durable url:// manager service plus a stateless fleet console; a single verified-membership supervisor registry whose operator metadata (aliases, descriptions, first-seen/last-seen timestamps, catalogs) is durable even when a supervisor is currently offline; human names for live threads (bound to the running session, surviving native resume); a manager-maintained cached cross-fleet snapshot — aggregated from the supervisors' own durable conversation catalogs (active + paused/archived) — feeding a fleet-wide conversation home and per-supervisor consoles; renaming both supervisors and conversations from the console; fleet spend visibility — a "Resource Consumption Rate" chart of dollars consumed over time on the supervisors page and on each per-supervisor console page, starting with the flat $200/month subscription and extensible to further spend sources (e.g. CI build costs), plus a per-supervisor "Token Consumption" chart of dollar-adjusted token spend, computed on the supervisor from its harness session directories via ClaudeSpendApi (scope expanded to codex, generalizing into the AiCliSpend* family) with dynamically fetched per-model pricing; the attach-monitor flow — creating monitor agents from a built-in template and attaching them to watched agents/conversations in one submit (relayed to and durably stored on the supervisors), with watched-by badges, attributed injections in the thread terminal, and loud tripped-circuit-breaker surfacing until a human re-arms (AiCliHostSupervisor §12); and session-lifecycle orchestration — relaying user-driven pause/terminate/resume to the owning supervisor and aggregating the resulting state across the fleet (the extension above).

Explicit non-goals: implementing supervisor statefulness or being the durable owner of any agent or session state (supervisors are now the durable home of the agent — definitions, capabilities, history, mailbox, config, catalog, resume records — that is AiCliHostSupervisor's workstream; the Manager only orchestrates and aggregates, caching a view and never storing agent state); any disk state in the console; and being the end-user product surface (that is its sibling console MyLittleAgi, with autonomous farms in SpawningPool) — this console is deliberately the operator/admin lens over the same supervisors. This document also defers task and milestone breakdown.

Relationship to other workstreams

AiCliHostSupervisor — the stateful engine this workstream observes and drives. The Manager is the operator console over a fleet of those supervisors, and — per the session-lifecycle orchestration extension — the orchestrator of session lifecycle: supervisors keep sessions warm until the Manager relays the user's pause/terminate, and each supervisor holds its own durable resume records (the Manager aggregates them). Its fleet registry is also a natural substrate for the new-conversation discovery/placement that plan calls for (a scheduler could read the same registry the operator browses). And the supervisor API this console consumes is deliberately the same surface monitor agents consume (engine §12) — two clients, one API, with the attach-monitor flow above as the trivial creation path.
MyLittleAgi — the end-user console and this Manager's sibling: both are frontends over the same supervisor fleet, and neither stores agents (agents live on the supervisors). The split is audience and emphasis — MyLittleAgi hides the infrastructure so a person can just talk to their agents; the Manager foregrounds supervisor configuration, health, and placement for an operator running the fleet. SpawningPool is the third frontend, for autonomous farms. All ride the same engine.
UrlResolver — the P2P fabric the manager uses both to reach supervisors and to host its own url:// service.
Standard layered architecture — the manager follows Api / Embedded / ServiceServer with a stateless WUI on top, the same uniform shape every service on the platform uses.
Manager–Daemon Pairing — the general enrollment pattern the supervisor↔manager relationship follows: a supervisor launched with --register-with announces itself to the manager, and an operator can add a supervisor by URL from fleet settings — the two bootstrapping directions that pattern describes ("however a supervisor became known… it is the same thing").

Repositories

Shipped by this workstream:

AiCliSupervisorManagerApi / AiCliSupervisorManagerEmbedded / AiCliSupervisorManagerServiceServer — the durable manager service, deployed at url://aiclisupervisormanager/: the fleet registry, operator metadata, thread names, and the cached cross-fleet snapshot.
AiCliSupervisorManagerWui — the stateless fleet console, superseding AiCliHostSupervisorDaemonWui and serving aiclisupervisor.wasmserver.com.
AiCliHostSupervisorDaemonServiceServer (extension) — supervisor self-announcements now optionally carry a thread summary, so the manager refreshes its snapshot from announcements alone.

Graduation

Graduated (2026-07-05) — for the original console/registry scope. The session-lifecycle orchestration extension graduates separately, when a conversation paused through the Manager can be resumed on its owning supervisor from that supervisor's own durable catalog record via the CLI's native resume, with the Manager relaying the command and reflecting the state (exercised alongside the AiCliHostSupervisor graduation path; cross-supervisor resume is deferred with the engine's state-migration decision). The original criteria below are met: the manager service is live at url://aiclisupervisormanager/, the console at aiclisupervisor.wasmserver.com renders the cross-fleet live-conversation home from the cached snapshot, supervisors register through announcements and operator adds with durable aliases/descriptions/timestamps, and both supervisors and live threads can be named and jumped into. The project page lives in the Documentation Repository.

This workstream was defined to graduate from "vision" when the manager service is real and the console is built on it end-to-end: a single home page renders the live conversations across the whole fleet from the manager's cached snapshot; supervisors register however they connect and carry durable operator aliases, descriptions, and timestamps; and both supervisors and live threads can be named, organized, and jumped into. At that point it becomes a first-class project in the Documentation Repository. Milestones and sequencing are intentionally out of scope here.