MeshView

MeshView is the data model used by the terminal console and plain line stream. The class ships in @cotal-ai/workspace/view and lives in packages/workspace/src/view/mesh-view.ts. The web dashboard has a separate observer and HTTP and server-sent event APIs. It does not import MeshView.

This API belongs to the reference implementation. Its fields derive from the wire contract, but do not define it. The SPEC defines subjects, delivery modes, presence, and other wire requirements. Other clients can derive their own models.

The observerCopy Anchor Link

The console and stream use openObserver({ space, server, name, auth?, operator? }) from @cotal-ai/workspace/view. It returns an unstarted CotalEndpoint configured with consume: false, registerPresence: false, watchPresence: true, and no joined channels. operator: true adds the operator role and a lifecycle UID for endpoint service calls; broker grants still decide which calls it may make. The endpoint stays off the roster and creates no inbox, chat, or anycast durables. It reads through a live tap, history reads, and presence and membership watches. The web server creates its own endpoint with the same observer flags. Browsers read its HTTP APIs and event stream.

History reads can create temporary consumers. Stopping or rebinding a watch first disarms local delivery. If the presented credentials exclude consumer deletion, cleanup sends no delete and leaves broker expiry to reclaim it after five minutes. Permitted deletes reclaim immediately. SDK-internal ordered-consumer recovery is unchanged.

The console narrows its tap to chatWildcard(space) whenever it has credentials or a user bearer. That view exposes multicast traffic and hides DMs and anycast. An open-mesh console uses the whole-space tap. A space-wide subscription still requires broker permission. Authenticated admin grants cover the chat, inst, and svc planes individually, so the web server taps those three subjects separately.

On an open mesh, the interactive console starts a second, presence-only endpoint before the operator's first send. It shares the observer's card, so peers can address replies to the operator. The observer's whole-space tap displays those replies. A session that only watches stays invisible. The console provides no participant endpoint under auth. An authorized send there is one-way, and the console reports that limitation. The default authenticated console and user-mode admin view cannot send. An explicit --creds file enables the send path, subject to its broker grants. See Watch a mesh for operator behavior.

MeshView dataCopy Anchor Link

MeshView takes a not-yet-started endpoint and owns its lifecycle. The model contains plain data, with no ANSI, React, HTML, or color values. The console's useMesh hook consumes snapshots. The stream consumes individual entries and presence events.

const view = new MeshView(ep, { window: 300 });
view.on("entry", (entry: FeedEntry) => { /* one live feed row */ });
view.on("presence", (event: PresenceEvent) => { /* join, update, or offline */ });
view.on("warning", (error: Error) => { /* recoverable endpoint notice */ });
view.on("change", (snapshot: MeshSnapshot) => { /* batched model */ });
await view.start();
const snapshot = view.snapshot();
await view.stop();

start() starts the endpoint and tap, then launches history prefill, channel refresh, and membership reads without awaiting them. Its resolution does not mean that those reads have completed. A 75 ms timer emits change when the model is dirty. A one-second heartbeat marks the model dirty to refresh ages and rates. Channels refresh every two seconds. Membership watch notifications debounce for 150 ms before a new read. stop() clears timers, discards pending unicast bursts, stops the membership watch, and stops the endpoint.

spaceWildcard(space) and an omitted tapSubject select the whole space when the credential permits it. status.dmVisible is false only when tapSubject equals chatWildcard(ep.space). It describes that selection, not a separate permission check. Other custom tap subjects do not change this flag.

interface FeedEntry {
	id: string;
	ts: number;
	from: EndpointRef;
	delivery: "multicast" | "unicast" | "anycast";
	channel?: string;      // multicast target
	toService?: string;    // anycast target
	toIds?: string[];      // unicast target endpoint IDs
	toNames?: string[];    // corresponding roster display names
	count?: number;        // unicast burst target count, including repeats
	events?: boolean;      // multicast row on an agent's structured-event channel
	replyTo?: string;      // ID of the message this one answers
	mentions?: string[];   // lowercased peer names called out by the sender
	contextId?: string;    // sender-chosen thread or conversation correlation ID
	text: string;          // partsToText(msg.parts)
}

interface MeshSnapshot {
	agents: Presence[];    // card.kind === "agent"
	endpoints: Presence[]; // all other card kinds
	channels: { channel: string; messages: number; arrivals: number; deliveryClass: DeliveryClass }[];
	feed: FeedEntry[];
	membership: { snapshot?: MembershipSnapshot; unreadable?: string };
	rates: { msgsPerSec: number; activity: number[] };
	status: { connected: boolean; space: string; dmVisible: boolean; error?: string; warning?: string };
	signals: MeshSignals;
	nameOf: (id: string) => string;
}

The model applies these rules:

• deliveryOf(subject) classifies chat, unicast, and anycast. Chat becomes multicast in FeedEntry. Control, presence, and trace frames return null and do not enter the feed.
• Live multicast rows on structured-event channels carry events: true. Those channels do not appear in channel tabs or history prefill. Their live rows remain in the feed.
• replyTo, mentions, and contextId are retained on live feed rows and channel history. Fields are absent when the sender did not set them. The wire has no separate DM conversation ID: DM pairs use sender and recipient principals, and contextId is optional sender-chosen correlation.
• Unicast messages with the same sender ID, plain text, and thread fields share a 400 ms window, measured from the first arrival. The row appears when that window closes. Its id comes from the first message, and its ts is the earliest timestamp. toIds and toNames preserve parallel target lists. Repeated targets contribute to count.
• entry emits each live row after classification and coalescing. History prefill updates snapshots without emitting entry. The stream therefore does not print the initial backlog.
• The roster sorts by status, in the order working, waiting, idle, and offline, then by name. agents and endpoints split that roster by card kind.
• nameOf(id) reads the roster-derived name map. An unknown ID returns its first eight characters. Message payload names do not update that map.
• Channel rows sort by name. messages is the broker's retained count, which can stop growing at the retention cap. arrivals counts live rows seen by this viewer, independently of retained history. A channel's arrival count disappears when the channel leaves the next successful poll. deliveryClass is the channel's effective class from the registry cache.
• Startup prefill reads up to 50 messages per non-event channel. It deduplicates against the current feed by id, merges by timestamp, and applies window. Channel-list failures skip prefill. Individual history failures contribute no rows.
• When DMs are visible, prefill also requests up to 1,000 DM messages for the DM roll-up. Those messages do not enter feed. A refused DM history read leaves the roll-up with live traffic only.
• The feed retains at most window entries. Live tap arrivals, before coalescing, drive the rolling one-second msgsPerSec rate.
• rates.activity contains 15 four-second buckets, oldest first, with raw live-arrival counts over 60 seconds. The buckets decay even without new traffic. The console renders this series as a status-bar sparkline.

status.error and status.warning retain the latest endpoint error and warning messages. status.connected is true while the endpoint is bound and its NATS transport is connected. A broker outage marks it disconnected during automatic reconnection; transport recovery restores the connected state. A successful endpoint rebind clears the previous connection error.

Derived operator signalsCopy Anchor Link

interface MeshSignals {
	counts: { working: number; waiting: number; idle: number; offline: number };
	waiting: Presence[];
	stalestLiveTs?: number;
	dms: DmPeer[];
}

interface DmMessage {
	ts: number;
	from: string; // display name
	to: string;   // display name
	text: string;
}

interface DmThread {
	with: string;
	role?: string;
	status: PresenceStatus;
	lastTs: number;
	messages: DmMessage[];
}

interface DmPeer {
	name: string;
	role?: string;
	status: PresenceStatus;
	lastTs: number;
	conversations: DmThread[];
}

counts includes agent cards only. waiting includes agents whose status is waiting, sorted by name and then ID. Presence.ts is the last heartbeat, republished every two seconds by default. Presence.statusSince dates the current combination of status and activity. An activity change moves it too. Neither field establishes how long an agent has been blocked.

stalestLiveTs is the oldest heartbeat among agents whose status is not offline. It is absent when no agent is live. The fifth status tile displays its age as heartbeat freshness. Offline agents are excluded because their heartbeat ages continue to grow after departure.

dms groups retained raw DMs by endpoint ID into conversations between peers that exchanged messages. Self-addressed messages do not form conversations. The model resolves names, roles, and statuses from the roster by ID. An absent peer has status offline. Message lists sort oldest first. Conversations and peers sort by their latest message, newest first. The log retains at most 1,000 raw DMs. Startup history merges with live DMs by sender ID, recipient ID, and timestamp. A chat-only observer leaves dms empty. The console topology also uses endpoint IDs as keys and roster name/role labels for display, so equal names do not merge nodes.

Membership feedCopy Anchor Link

membership.snapshot is the last successful membership read. membership.unreadable records the most recent read or watch failure, while retaining the last snapshot. A successful read clears the failure. A watch that closes after startup reports through the same field. A missing feed bucket produces an empty snapshot with no asOf heartbeat. Membership failures do not set status.error.

The console topology checks the following states in order:

Feature to surface mapCopy Anchor Link

The console and stream use the model fields below. The web column describes equivalent browser features derived through its own APIs and client code. An empty cell means that the display has no corresponding feature.

The topology view switches with v or 1 to 3 between a swimlane sequence, an adjacency heat matrix, and a ring map. It derives traffic links from the feed and overlays the broker-authoritative membership feed from readMembership() and watchMembership(). Silent subscribers appear as nodes. Live subscriptions use faint solid spokes, and durable offline subscriptions use dashed spokes. Wide readers, with > or * subscriptions, have a ≫ badge. The map draws the subscription structure, the matrix uses ∘ and ◌ markers, and the sequence remains a traffic timeline.

Channel unread counts belong to the viewer. They count arrivals since the channel was last viewed. A deleted channel leaves the tab strip on the next successful channel poll, with its unread count removed. The console resolves harness tags from card.meta.connector, then from the manager launch record for a managed seat without that metadata. Examples include cc for Claude Code and oc for OpenCode. Agent detail computes its runs label from the connector and managed runtime mode. It also displays reported model metadata and card skills when available. The web dashboard does not use the console's manager-record enrichment.

Future workCopy Anchor Link

The web dashboard's ?demo scene includes static examples that its live renderer does not implement. These examples are not live capabilities or a delivery schedule.

PrinciplesCopy Anchor Link

The implementation keeps these distinctions:

• MeshView centralizes classification, coalescing, roster sorting, ID-to-name lookup, rates, feed limits, and operator signals for its console and stream consumers.
• Each renderer owns layout, color, keybindings, input, search, and selection. The console derives topology from the model. The web dashboard derives its browser model separately.
• Broker grants determine visibility. A model flag does not confer permission. Startup endpoint failures propagate, membership failures remain explicit, and history prefill is best effort as described above.
• Status uses both shape and color. The glyphs are ● for working, ◐ for waiting, ○ for idle, and ⨯ or ⊘ for offline.
• Displays distinguish reported data from absent data. The web model badge says "not reported" when a harness reports no model. A heartbeat age is not a blocked duration.
• attention: "open" and absent attention both mean normal reception. The web display gives neither a badge. It marks only dnd and focus.

The operator walkthrough is Watch a mesh.