@cool-ai/beach-inspect

Optional local-only development UI that reads the event router's stream and renders sessions, envelopes, and tool calls.

Home: cool-ai.org · Documentation: cool-ai.org/docs

Install

npm install --save-dev @cool-ai/beach-inspect

For Redis-backed stores, install the optional peer:

npm install ioredis

CLI usage

# Inspect a JSON missive store
npx beach-inspect --store ./data/missives.ndjson

# Inspect a Redis store
npx beach-inspect --store redis://localhost:6379

# Use a non-default port
npx beach-inspect --store ./data/missives.ndjson --port 9090

The CLI starts a local HTTP server and opens the browser. Press Ctrl+C to exit.

Programmatic use

import { InspectReader, createServer, ManifestEventStore } from '@cool-ai/beach-inspect';
import { ManifestRegistry } from '@cool-ai/beach-core';
import { JSONMissiveStore } from '@cool-ai/beach-missives/stores';

// Wire the manifest observer before creating the registry
const manifests = new ManifestEventStore();
const registry = new ManifestRegistry({ observer: manifests });

const store = new JSONMissiveStore('./data/missives.ndjson');
const reader = new InspectReader(store, {
  listAll: () => store.listAll(),  // enables session listing
  manifests,                        // enables Manifests tab in turn detail view
});
const server = createServer(reader);
server.listen(9090);

ManifestEventStore implements ManifestObserver from @cool-ai/beach-core. It subscribes to manifest lifecycle events in-process and surfaces them in two places:

• Manifests tab (turn detail view) — each manifest's status, slot fill state, delivery timestamps, and duration. Slots filled via the orphan queue are annotated (via orphan claim).
• Orphans tab (process-wide) — live orphan queue with TTL remaining, and a complete orphan event history (queued → claimed/evicted).

If manifests is not provided, both tabs return empty data rather than erroring.

wireInspect()

Zero-boilerplate helper that wires all eight observation callbacks in one call. Returns { routerOptions, managerOptions, turnOptions } to spread into constructors and runTurn().

import { wireInspect, ManifestEventStore } from '@cool-ai/beach-inspect';
import { EventRouter } from '@cool-ai/beach-core';
import { SessionTurnManager } from '@cool-ai/beach-session';

const manifests = new ManifestEventStore();
const registry = new ManifestRegistry({ observer: manifests });

const { routerOptions, managerOptions, turnOptions } = wireInspect(store, manifests);
const router  = new EventRouter({ ...routerOptions });
const manager = new SessionTurnManager({ router, manifestRegistry: registry, ...managerOptions });

// Per turn:
await manager.runTurn({ ..., ...turnOptions });

All eight signals are enabled by default: turns.started, turns.settled, turns.timeout, turns.cancelled, turns.toolCalls, router.routingDecisions, router.cascadeErrors, router.cascadeSuppressed.

To disable individual signals, pass a WireInspectOptions object:

wireInspect(store, manifests, {
  signals: { turns: { toolCalls: false }, router: { routingDecisions: false } },
});

A beach-inspect.config.example.json ships inside the package. Copy it from node_modules/@cool-ai/beach-inspect/beach-inspect.config.example.json, rename to beach-inspect.config.json, and pass the parsed contents to wireInspect(). Set any signal to false to disable it — no code changes needed.

Rationale

OpenTelemetry (BF-013) gives Beach consumers distributed tracing for production. For day-to-day development, having a local UI that reads the router's event log — without requiring an OTLP backend, Jaeger, or Honeycomb — dramatically improves the onboarding story. This is the role @cool-ai/beach-inspect plays: a minimal dev-time inspector, not a production observability platform.

Philosophically it is closest to Burr's built-in telemetry UI.

Process model — CLI (BCR-011)

@cool-ai/beach-inspect runs as a CLI that boots a transient local HTTP server. Developers run npx @cool-ai/beach-inspect (or pnpm dlx @cool-ai/beach-inspect); the CLI starts a server on a free local port (default: 9090), opens the default browser, and exits when the browser tab is closed or Ctrl+C is pressed.

This avoids:

• Middleware coupling — the tool is not a middleware mounted on the consumer's HTTP app, so it does not care whether the consumer uses Express, Hono, Fastify, or anything else.
• Long-running-process ops — no PM2/systemd config needed; the process lives for the debugging session only.

The CLI reads from the consumer's configured event store (Redis URL, SQLite path, etc.) via the same connection the agent itself uses. Configuration is discovered from the consumer's existing .env or passed as CLI flags.

Concern

@cool-ai/beach-inspect provides:

• A CLI entry point — @cool-ai/beach-inspect command that launches the transient server.
• Event log reader — consumes the router's event stream (same stream @cool-ai/beach-core emits). Read-only.
• Session view — shows a session's mailbox, turn history, active actor, envelope stream.
• Envelope view — shows the parts that made up a specific envelope, per originator, per delivery class.
• Tool call view — shows a tool call's arguments, approval state (if applicable), result. For specialist tools, shows the specialist_execution log records.
• Replay trigger — invoke @cool-ai/beach-session's replay on a specific turn, with a modified input if desired, and render the result alongside the original.

Not in this package

• Production observability — use OpenTelemetry exporters via @cool-ai/beach-core.
• Eval result management — use @cool-ai/beach-evals.
• Dataset management, regression dashboards, or cross-consumer analytics.

Target scope for v1

The v1 ambition is deliberately small:

• One page for "list of recent sessions."
• One page for "session detail" (events, mailbox, envelopes).
• One page for "envelope detail" (parts per originator).
• Server-side rendered (no SPA build).
• Reads from the same event store the router writes to (no separate persistence layer).

Consumers wanting more (filtering, search, session timeline visualisations, replay-with-tweaks, comparison views) can either:

• Build extensions on top of the core event-log-reader primitives Beach exposes.
• Integrate a proper observability backend (Honeycomb, Langfuse, Braintrust, custom Grafana).

Consumers

Developers working on any Beach-based agent. Not a runtime dependency; only used in development.

Related

• https://cool-ai.org/docs/design-principles — principle 3.6 (observability is design-time).
• ../core/ — where the event log originates.
• ../evals/ — for regression testing; @cool-ai/beach-inspect is complementary.