@mono-agent/web

The persistent browser console for mono-agent. It discovers every running local agent, keeps multiple independent conversations in owner-private SQLite state, and serves the assistant-ui PWA from one always-on process.

Category

Category: operator-surface

Responsibility

• Discover local agents through the shared trace-source registry and probe their loopback operator endpoints.
• Persist agents, threads, messages, structured reasoning/tool/telemetry parts, revisions, turns, attachments, and agent pin preferences under ~/.mono-agent/web.
• Keep an upstream turn running when a browser reloads or disconnects, and expose state invalidations over SSE so any connected browser can catch up.
• Accept browser-selected files through bounded staged uploads and forward the exact transport-neutral AgentAttachment contract used by Telegram.
• Serve the assistant-ui PWA and its versioned JSON/SSE API.

Install / Usage

The mono-agent web command owns normal lifecycle management. The embeddable server API is also available:

import { startWebServer } from "@mono-agent/web";

const server = await startWebServer(); // 0.0.0.0:5050
console.log(server.url);
await server.stop();

The interface is deliberately single-user and has no application login. Anyone who can reach port 5050 can inspect conversations and operate discovered agents; use host firewall/LAN policy and Tailscale ACLs as the access boundary. The server emits no CORS permission and rejects cross-origin mutations.

Private IP literals, localhost, the machine hostname, and its exact .local name are accepted as browser hosts. Set MONO_AGENT_WEB_ALLOWED_HOSTS to a comma-separated list of any additional exact DNS names (for example the node's Tailscale DNS name); suffix wildcards are intentionally not trusted. When a managed agent protects its loopback operator endpoint, discovery reads only MONO_AGENT_TUI_API_KEY from that agent's attested, owner-owned dotenv file.

On desktop, drag the agent rail's right edge to reveal full agent names. The resize separator is keyboard-operable, and its width is remembered by that browser so each device can keep an appropriate layout. Pin or unpin an agent with its star control in the desktop rail or mobile agent picker. Pins are stored by the web service rather than in browser storage, so the same favorites appear over localhost, LAN, and Tailscale; pinned agents sort before the remaining discovered agents.

The assistant-ui run-settings popover combines searchable model selection with the selected model's supported reasoning-effort choices and becomes a viewport-safe bottom sheet on narrow screens. Usage telemetry remains internal and is summarized through a context display that accumulates the conversation's newest per-turn snapshots; it reports a percentage only when the agent advertises a trustworthy context-window size. Structured reasoning is grouped into a stream-aware disclosure without reordering adjacent tool or answer parts. Typing / in an empty composer opens the available command triggers.

Public API

Every symbol exported by each public code entrypoint is listed below.

@mono-agent/web

CreateWebThreadInput
CreateWebUploadInput
DEFAULT_WEB_HOST
DEFAULT_WEB_PORT
DiscoverOperatorAgentsOptions
DiscoveredOperatorAgent
PatchWebAgentInput
PatchWebThreadInput
StartWebServerOptions
StartWebTurnInput
WEB_API_VERSION
WEB_MAX_ACTIVE_ATTACHMENT_TURN_BYTES
WEB_MAX_CONCURRENT_UPLOADS
WEB_MAX_FILES_PER_TURN
WEB_MAX_QUEUED_ATTACHMENT_TURNS
WEB_MAX_STAGED_UPLOADS
WEB_MAX_STAGED_UPLOAD_BYTES
WEB_MAX_TURN_ATTACHMENT_BYTES
WEB_STAGED_UPLOAD_TTL_MS
WebAgentStatus
WebAgentSummary
WebAttachment
WebBootstrap
WebConsoleError
WebEvent
WebEventType
WebMessage
WebMessagePart
WebMessageStatus
WebModelOption
WebRunState
WebRunStatus
WebServerHandle
WebStatePathOptions
WebStatePaths
WebThread
WebThreadDetail
defaultTraceRegistryDir
defaultWebStateDir
discoverOperatorAgents
isTrustedOperatorBaseUrl
operatorBaseUrlFromMetadata
prepareWebState
prepareWebStatePaths
resetWebState
resolveWebStatePaths
startWebServer

The primary exports are startWebServer, prepareWebState, resetWebState, defaultWebStateDir, the versioned Web* DTOs, API/upload limit constants, and the trace-registry discovery helpers. startWebServer() returns a handle with the actual bound address/port plus idempotent stop() and close() methods.

The browser API is rooted at /api/v1:

• GET /bootstrap, PATCH /agents/:id, and GET/PATCH /threads/:id
• POST /threads, /threads/:id/turns, and /threads/:id/cancel
• POST /uploads, PUT/GET /uploads/:id/content, and DELETE /uploads/:id
• GET /events (SSE)

GET /healthz is intentionally outside the versioned API for service probes.

Dependency Boundary

The server depends only on the core @mono-agent/agent-contracts and @mono-agent/config packages, the observability trace-source registry, and Express. Its compiled browser bundle additionally contains the production graph from the isolated webapp lockfile: assistant-ui, Base UI, cmdk, React, and Workbox plus their transitive dependencies. The repository advisory and license gates audit that nested production graph separately because it ships inside this package even though it is not part of the root pnpm workspace. Running agents are reached over their loopback HTTP operator endpoints; this package does not import a communication adapter or another operator surface.

What This Package Does Not Own

• Agent runtime/provider execution or conversation history inside an agent.
• The operator-adapter HTTP server published by each agent.
• CLI background-process, launchd, or conflict-safe Tailscale Serve lifecycle.
• Session Recorder history/replay, which remains in @mono-agent/session-web.
• Authentication. Network reachability is the intentional security boundary.
• Host filesystem browsing: attachments come only from the browser device's native file picker.

Verification

pnpm --filter @mono-agent/web run typecheck
pnpm --filter @mono-agent/web run test
pnpm --filter @mono-agent/web run build