Add optional facilities
The command path is useful by itself. Cheetah also supplies higher-level facilities for recurring application problems. Add one when it removes real product work, and treat its storage, policy, lifecycle, and operating boundary as part of the design.
Choose the facility from the problem
| Product need | Cheetah facility | Important boundary |
|---|---|---|
| return a screenshot, DOM snapshot, or parsed page evidence with an action | post-command capture and parser definitions | capture is locally authorized; full evidence lives in history |
| allocate a tab, window, or console flow for work | context registry and WorkerContextManager | this is an assignment pool, not a durable task queue |
| keep a current answer derived from retained messages | reducers, derived-view engine, and stores | the application owns scheduling, migrations, and domain truth |
| inspect connections, pending work, histories, contexts, and traces | inspectors and diagnostics routes | diagnostic data is sensitive and requires administrative auth |
| embed operational views in a repository React product | private, source-consumed @cheetah/ui components and composites | this is not currently a supported external package; the UI observes unless a separate control API is enabled |
| provide a ready operator workspace | DevConsole | build, hosting, access control, and write-capable routes remain explicit |
| connect server and client timing across a command | server tracing and client telemetry sinks | exporters, receiver endpoints, sampling, and redaction belong to the deployment |
| make local or cooperative sites reachable through sessions | site-relay facilities | session lookup is not by itself an outer user-authentication boundary |
| run repeatable browser evidence collection | browser capture runs | the current solution layer has its own worker, storage, and concurrency limits |
Capture and parsing
An application can attach a capture request to a command so the client collects supported evidence after the action. Parser definitions are registered and validated rather than sent as arbitrary executable code on every request. The browser still decides whether the target and evidence request are permitted locally.
Capture can partially succeed. Keep the structured capture status and individual artifact errors instead of treating a screenshot, DOM body, and parser output as one indivisible fact. Large payloads may be offloaded through configured token-signing and storage support; that storage needs its own access, retention, and cleanup policy.
Contexts and worker assignment
Clients report platform state as common execution-context snapshots. The application-side worker manager can find an idle context, assign a guarded task ID, address a command to it, renew the assignment, and release it. Browser-specific placement can also create tabs or worker windows when the required providers are configured.
The context registry is current coordination state. Store the product task separately. A worker disappearing does not decide whether the external task should be retried.
The worker-pool reference covers acquisition, guarded handles, selection, browser placement, capacity, protection, and multi-process limits.
Diagnostics, tracing, and UI
Read-only inspectors expose Cheetah's view of connections, correlation, histories, contexts, activity, and other supported domains. Mounted diagnostics routes make those inspectors available to the DevConsole or product UIs. The separate control route can issue real commands; enabling it changes an observer into an operator and requires stronger review.
Server roles emit structured tracing through ITracer. Client runtimes emit telemetry through a replaceable sink. Cheetah can carry trace relationships across the command, but the application supplies exporters, a protected client-telemetry receiver, backend retention, sampling, and redaction.
OpenTelemetryTracer(exporter=None) is intentionally silent; it does not install a console exporter. The process or host that creates an OpenTelemetry tracer owns its final shutdown() after every component set using it has stopped. A replaceable ITracer is not required to expose that method.
Derived state and solution layers
Reducers can turn ordered retained messages into a current view. Rebuild remains bounded by history retention, and the application owns reducer versions and store migrations. Capture runs and site relays compose several lower-level facilities into larger solutions; enabling them is an architectural choice, not a node preset flag.
Review the maturity and operational limits of each feature before depending on it. Optional means that the core works without it, not that the facility is cost-free or automatically safe in every deployment.
Prepare a browser client for parser capture