Clients and execution environments
Cheetah clients share a protocol and execution model, but they do not have the same authority, lifetime, or capabilities. The common runtime exists to preserve the meanings that should remain stable. Platform packages exist to preserve the differences that should not be hidden.
Every client combines the shared contract with a platform layer. The browser receives more space because its useful resources and lifecycle are unusually fragmented, not because Cheetah is browser-only.
What the shared core provides
@cheetah/core is the common TypeScript client foundation. It establishes the connection and negotiated server configuration, carries a stable client identity and current runtime instance identity, registers named actions, validates commands, combines central and local authority, invokes optional approval, manages leases and cooperative cancellation, executes handlers, publishes progress and terminal outcomes, reports state, and exposes telemetry hooks.
This does not mean every client enables every stage. Payload-reference resolution, encryption support, approval providers, capture, parsers, state reporters, and other facilities depend on runtime composition. The shared core defines where they fit and what their results mean.
A product handler remains the boundary where application or platform work happens. The runtime can validate inputs and govern the invocation, but only the handler or its adapter knows how to read a particular page, run a particular tool, or interact with a particular device.
Stable client, current instance, and platform context
One identifier cannot describe all client lifetimes safely.
The client_id identifies a stable installation within an authenticated principal's scope. A browser extension or configured console agent can reconnect as that logical client after its process or socket changes. The identifier is a routing identity inside a trusted scope, not a credential by itself.
The instance_id identifies one running runtime lifetime. It remains the same across an ordinary transport reconnect by that runtime and changes when a replacement runtime starts. The server uses this distinction to fence pending correlation and returned messages. A late message from an old browser worker should not satisfy work registered for its replacement.
Contexts identify resources inside the client, such as a browser tab, window, or console flow. They are observed platform state, not independent authentication principals or guarantees that a resource will still exist when a command arrives.
Browser extension
The browser package is a primary Cheetah surface because browsers contain valuable execution context that a backend normally cannot possess: signed-in pages, active tabs, user-granted permissions, content scripts, and browser APIs.
The same browser is also a small distributed system. A Chrome MV3 extension can include a service worker, content scripts in several pages, optional offscreen processing, tracked worker tabs and windows, and stored identity or recovery metadata. Chrome may stop the service worker while pages continue to exist. The user may navigate, close, or replace a page independently of the runtime connection.
The browser layer therefore supplies Chrome-backed identity persistence, lifecycle-aware runtime composition, tab and window handlers, content-script bridging, capture and parsing, worker resource tracking, and browser state reporting. These mechanisms reconstruct supported framework state; they cannot preserve arbitrary in-memory product state or stop a user from changing the environment.
Local authority is especially important here. A capability advertisement means that the runtime has a handler for an action. It does not prove that the current page, permissions, local policy, or user approval allow the action now.
Console process
The console package applies the same command model to a longer-lived Node.js environment. It adds WebSocket transport adaptation and console-oriented handlers for files, processes, flows, downloads, and modules. An application can use it as a controlled local agent or as another connected execution environment alongside browser clients.
Console and browser clients share identity, command, authority, progress, outcome, and state concepts. They should not share an assumption that tabs and files are interchangeable resources. Their platform layers expose different handlers and carry different security consequences.
Cooperative web page
The web package embeds a Cheetah runtime inside a page. It can report page state and execute supported DOM actions within that page's own origin and lifetime. It is not equivalent to a browser extension: it does not gain extension-level access to arbitrary tabs or privileged Chrome APIs.
Current web support is implemented with limits and is younger than the browser and console paths. Same-origin storage and page lifecycle need deliberate treatment when several pages participate.
Native bridge and custom clients
The mobile/native package provides an experimental route for embedding the shared runtime in a native JavaScript host. It should be evaluated as an earlier-maturity bridge, not described as an equally supported peer of the browser or console packages.
A custom client can reuse the TypeScript core or implement the wire contract independently. In either case, compatibility requires more than accepting a JSON command. The client must preserve negotiation, identity lifetimes, authority decisions, progress and terminal outcomes, state meanings, and failure behavior. Later build and reference sections will define the conformance path and protocol fixtures for this work.
Choosing a client boundary
Choose the client type based on where the required authority and resources genuinely live.
| Required environment | Natural client boundary | Important limit |
|---|---|---|
| Signed-in pages, tabs, windows, extension APIs | Browser extension | Volatile MV3 and page lifetimes; local permissions remain decisive. |
| Files, processes, tools, or long-lived local flows | Console process | Machine-level effects require strict product and local policy. |
| A first-party page cooperating from inside its own DOM | Web client | Page and origin scope; not extension authority. |
| Embedded engine or another device/runtime | Native bridge or custom client | Experimental or implementation-specific; protocol conformance must be demonstrated. |
An application may use several client types and several client installations at once. That does not require merging their resources into one undifferentiated capability set. Product code addresses the logical client and, when relevant, a platform context; the runtime and platform layer determine what can honestly happen there.