@mono-agent/session-web 0.4.1

package/README.md

@@ -0,0 +1,92 @@
+# @mono-agent/session-web
+
+Discovers local mono-agent instances and serves a read-only **web PWA** that
+visualises their runs in real time — the browser counterpart to the TUI. It is
+the single backend the browser talks to: it aggregates recorded-run history (from
+each instance's artifact dir) with live sub-run streams (from each running
+agent's operator-adapter live endpoint), and never drives an agent.
+
+## Category
+
+Category: `operator-surface`
+
+A drop-in operator surface, like `@mono-agent/tui`: launched separately, it
+discovers everything on the machine via the trace-source registry.
+
+## Responsibility
+
+- Discover instances (registry `listTraceSources`/`mergeTraceSources`), exposing
+  name, cwd, `artifactDir`, health, and the optional `live` SSE endpoint.
+- Read recorded runs per instance and map them to the UI `Session` model
+  (`mapRunToSession`, from `@mono-agent/observability`).
+- Watch artifact dirs (run-level) and connect to operator-adapter live SSE (sub-run);
+  fold both into one live session model.
+- Serve the built PWA (`express.static`), a JSON API, and a browser SSE stream.
+
+## Install / Usage
+
+```ts
+import { startSessionWebServer } from "@mono-agent/session-web";
+
+const server = await startSessionWebServer({
+  registryDirs: ["/Users/me/.mono-agent/trace-sources"],
+  host: "127.0.0.1",
+  port: 4599,
+  // Defaults to agent runs only. Uncomment to include memory-maintenance runs.
+  // includeMemory: true,
+});
+console.log(server.url);
+await server.stop();
+```
+
+The `mono-agent web` CLI command wraps this with registry resolution + browser open.
+Loopback on port `4599` is the default. Startup prints the exact URL to target
+from reverse proxies. A non-loopback bind requires `allowNonLoopback: true`
+and an `authToken`; `/api/*` and `/api/stream` require `Authorization: Bearer
+<token>` (or `?token=<token>` for browser `EventSource`).
+
+Run lists and the initial browser SSE snapshot are summary-only and step-less.
+Full run timelines are read lazily from `/api/sessions/:sourceId/:runId` when a
+detail view opens.
+`/api/sessions` supports `instance`, `limit`, and `offset` query parameters and
+returns page metadata (`total`, `offset`, `limit`, `hasMore`) so the browser can
+load older history without replaying already-loaded rows. Stale `running`
+summaries are projected as `stalled` in the web surface instead of being treated
+as live.
+Instance metadata includes the source timezone when it is discoverable; the PWA
+uses that timezone for per-instance run lists and details, and falls back to the
+viewer locale/timezone for mixed-instance views. Failure summaries preserve
+`failureKind`, error text, and provider failover attempts so failed runs are
+inspectable from the list and detail views.
+Memory-maintenance runs are hidden by default across disk history, watched
+updates, API responses, browser SSE frames, and live folds; pass
+`includeMemory: true` to opt them back in.
+
+## Public API
+
+- `startSessionWebServer(options)` → `{ url, stop() }` (`includeMemory` defaults
+  to `false`; `true` includes memory-maintenance runs in history/API/SSE/live
+  frames).
+- `discoverWebInstances(options)` and the `Session`/`SessionStep`/`WebInstance` types.
+
+## Dependency Boundary
+
+Depends only on `core` + `observability`: `@mono-agent/agent-contracts`,
+`@mono-agent/observability`. Plus `express`. It reaches
+operator-adapter live endpoints **over HTTP only** — it does not (and, per the
+architecture rule, may not) depend on that `communication` package. The browser
+SPA lives in the isolated `webapp/` sub-project (its own lockfile), built to
+`webapp/dist` and served statically.
+
+## What This Package Does Not Own
+
+- The agent-side broadcast tap or the `live` channel driver.
+- Turn-driving / any write path to an agent (read-only by construction).
+- The recorder, the trace-source registry writer, or run persistence.
+
+## Verification
+
+```sh
+pnpm --filter @mono-agent/session-web... run build
+pnpm --filter @mono-agent/session-web run test
+```

package/dist/aggregator.d.ts

@@ -0,0 +1,123 @@
+import type { SourceStampedSession } from "./history.js";
+import type { BrowserStreamFrame, WebInstance } from "./session-model.js";
+export interface SessionAggregatorLogger {
+    info?(message: string, metadata?: unknown): void;
+    warn?(message: string, metadata?: unknown): void;
+    error?(message: string, metadata?: unknown): void;
+}
+export interface SessionAggregatorOptions {
+    readonly registryDirs: readonly string[];
+    readonly maxRunsPerInstance: number;
+    readonly staleAfterMs?: number;
+    readonly env?: Record<string, string | undefined>;
+    readonly logger?: SessionAggregatorLogger;
+    /** Periodic registry reconcile interval (source of truth for membership). Default 5000. */
+    readonly reconcileIntervalMs?: number;
+    /** Debounce for `fs.watch`-triggered registry reconciles. Default 300. */
+    readonly registryDebounceMs?: number;
+    /** Debounce for `fs.watch`-triggered artifact re-reads (per run). Default 300. */
+    readonly artifactDebounceMs?: number;
+    /** Debounce for live-fold recomputes (per run). Default 150. */
+    readonly liveFoldDebounceMs?: number;
+    /** Coalescing window for `instances` frame emissions. Default 100. */
+    readonly instancesDebounceMs?: number;
+    /** Injectable fetch, threaded to the live client (tests point it at a local SSE server). */
+    readonly fetchImpl?: typeof fetch;
+    /** Include memory-maintenance runs in disk history and live frames. Default false. */
+    readonly includeMemory?: boolean;
+    /** Injectable clock for stale-running projection. Defaults to Date.now. */
+    readonly clock?: () => number;
+}
+export declare class SessionAggregator {
+    private readonly registryDirs;
+    private readonly maxRunsPerInstance;
+    private readonly staleAfterMs;
+    private readonly env;
+    private readonly logger;
+    private readonly reconcileIntervalMs;
+    private readonly registryDebounceMs;
+    private readonly artifactDebounceMs;
+    private readonly liveFoldDebounceMs;
+    private readonly instancesDebounceMs;
+    private readonly fetchImpl;
+    private readonly includeMemory;
+    private readonly clock;
+    private readonly states;
+    private readonly subscribers;
+    private readonly registryWatchers;
+    private reconcileTimer;
+    private reconcileDebounceTimer;
+    private instancesEmitTimer;
+    private lifecycleGeneration;
+    private stopped;
+    constructor(options: SessionAggregatorOptions);
+    /** Discover instances, seed history, open live connections, and start watching. */
+    start(): Promise<void>;
+    getInstances(): WebInstance[];
+    /** Sessions for one instance (by sourceId) or all ("all"), newest-first by `startTs`. */
+    getSessions(filter: string): SourceStampedSession[];
+    /** Step-less list projection for `/api/sessions` and browser SSE snapshots. */
+    getSessionSummaries(filter: string): SourceStampedSession[];
+    getSessionSummariesPage(filter: string, page: {
+        readonly offset: number;
+        readonly limit: number;
+    }): Promise<{
+        readonly sessions: readonly SourceStampedSession[];
+        readonly total: number;
+        readonly offset: number;
+        readonly limit: number;
+        readonly hasMore: boolean;
+    }>;
+    private collectSessions;
+    /** One session, reading it from disk on demand when it isn't already held. */
+    getSession(sourceId: string, runId: string): Promise<SourceStampedSession | undefined>;
+    /** Subscribe to the browser frame fan-out. Returns an unsubscribe function. */
+    subscribe(listener: (frame: BrowserStreamFrame) => void): () => void;
+    /** Close every live connection, watcher, and timer, and drop all subscribers. */
+    stop(): Promise<void>;
+    private discover;
+    private addInstance;
+    private connectLive;
+    private disconnectLive;
+    private handleLiveStatus;
+    private handleLiveFrame;
+    private scheduleLiveRecompute;
+    private recomputeLiveRun;
+    private insertDiskSession;
+    private insertDiskSummarySession;
+    private insertSession;
+    /**
+     * Bound `state.sessions` to the per-instance cap, evicting the oldest *completed*
+     * sessions by `startTs`. A still-running session is never evicted (its live fold
+     * is in flight); each drop emits a `session_removed` so browser subscribers stay
+     * in sync with the server-side map.
+     */
+    private evictSessionOverflow;
+    private watchArtifacts;
+    private watchMemoryArtifacts;
+    private scheduleArtifactReread;
+    private rereadArtifactSummaryFile;
+    private setupRegistryWatchers;
+    private scheduleReconcile;
+    private reconcile;
+    private updateInstance;
+    private removeInstance;
+    /** Close connections/watchers/timers for an instance without emitting any frames. */
+    private teardownState;
+    private scheduleInstancesEmit;
+    private emit;
+    private projectInstance;
+    private seedHistory;
+    private refreshDiskState;
+    private isActive;
+    private filteredStates;
+    private refreshStaleRunningSessions;
+    private refreshStaleRunningSessionsForState;
+    private countPagedSessions;
+    private now;
+    private isCurrentState;
+    private mapOptions;
+    private shouldDropMemoryLiveFrame;
+    private suppressMemoryLiveRun;
+}
+//# sourceMappingURL=aggregator.d.ts.map

package/dist/aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregator.d.ts","sourceRoot":"","sources":["../src/aggregator.ts"],"names":[],"mappings":"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"}