Client packages and runtimes
The TypeScript workspace separates shared command machinery from platform integrations. Start with the highest-level runtime that matches the environment; use the core factory directly only when building a new platform or intentionally replacing its boundaries.
Package map
| Package | Purpose |
|---|---|
@cheetah/core | protocol transport, identity interfaces, dispatch, policy, approval, validation, leases, results, state and telemetry hooks |
@cheetah/browser | Chrome MV3 identity and lifecycle, tabs, windows, content scripts, capture, parsing, downloads, browser handlers |
@cheetah/console | Node WebSocket transport, file-backed identity, machine handlers, flows, files, processes, downloads, modules |
@cheetah/console-tui | optional interactive terminal UI over a console runtime |
@cheetah/web | cooperative runtime embedded in one web page with direct DOM actions |
@cheetah/mobile | embedded-engine/native bridge with an earlier maturity level than browser and console |
@cheetah/ui | private, source-consumed React diagnostics and operator components; not a supported external package or execution client |
Supported core imports come from package exports. Do not import source or dist internals.
Core factory
import { createCoreRuntime } from '@cheetah/core';
const runtime = await createCoreRuntime({
serverUrl,
restEndpoint,
authToken,
protocolVersion: '1.0',
identityProvider,
webSocketFactory,
responseSink,
stateReporter,
clientType: 'my-platform',
localPolicySource,
});
runtime.registerHandler(handler, descriptor);
await runtime.start();serverUrl and authToken are required. The REST endpoint may be supplied up front or learned from the accepted handshake. Factory construction is asynchronous because identity may need storage; it does not connect until start().
protocolVersion defaults to the core package version. An explicit value must be a non-empty trimmed string and must exactly match one of the server's supported protocol versions; the handshake does not negotiate a nearest or fallback version. The browser runtime passes the same option through to core.
Transport defaults to strict. Core's default WebSocket factory targets browser-like environments. A Node process should normally use createConsoleRuntime(), which supplies the Node adapter and file-backed identity.
Identity and lifecycle
Without an identity provider, core generates IDs for that runtime construction. A recoverable client supplies platform storage so its stable client_id survives runtime replacement while each fresh execution lifetime receives a new instance_id.
A socket reconnect normally preserves both IDs. Reconstructing a destroyed runtime preserves the client ID and changes the instance ID. Register handlers before startup because the hello capability advertisement is a startup snapshot retained for reconnect.
On shutdown, stop state reporters and optional providers, close transport, flush telemetry as supported, and release platform resources. Browser service-worker restarts must reconstruct the runtime and current context truth rather than assuming old in-memory state survives.
Core defaults
| Setting | Default |
|---|---|
| dispatcher timeout without command or runtime override | 20 seconds |
| lease TTL | 30 seconds |
| capture provider | null provider |
| telemetry | console sink when logging is enabled, otherwise null sink |
| local policy | no source; application actions locally allowed unless a platform supplies one |
| approval | no provider |
| payload reference resolution | disabled unless resolver and opt-in are supplied |
| encrypted payload resolution | disabled unless encryptor and opt-in are supplied |
These are client execution defaults. They are separate from the server's observation timeout and from product-level cancellation, idempotency, or reconciliation.
cache_data is registered in every core runtime, but without a cache provider it returns no_cache. Parser preflight uses a supplied parser-definition cache. Configuration negotiation and state reporting are separate opt-ins.
Platform boundaries
The browser factory does not grant Chrome permissions or inject product content scripts. The extension manifest, service-worker bootstrap, offscreen resources, and application policy remain extension-owned.
The console runtime can expose powerful machine actions. File roots, process execution, network access, and modules require local policy appropriate to the host.
The web runtime controls only its cooperative page and does not inherit extension privileges. Mobile/native integration requires a host bridge and does not yet have feature and validation parity with the browser and console surfaces.
@cheetah/ui is currently private workspace material consumed from source by repository products, not a supported installable external package. It consumes diagnostics APIs. Enabling a separate control API can let an operator issue commands, but rendering a Cheetah component does not itself create a client runtime.