Cheetah / Cheetah documentation

Run a connected action

The connected console example is the smallest maintained proof that a command can leave application code, execute in a separately running client, return through ingestion, and be observed both by a waiter and in retained history.

Run the proof

From the repository root on Windows:

serverCheetah\venv\Scripts\python.exe cheetahClient\examples\console-client\connected_smoke.py

On macOS or Linux:

serverCheetah/venv/bin/python cheetahClient/examples/console-client/connected_smoke.py

The script selects temporary local ports, starts one in-memory Python host, launches the headless TypeScript console runtime, and waits for presence before sending work. Its final report has this shape:

{
  "status": "ok",
  "client_id": "console_minimal_smoke",
  "command_id": "<generated command id>",
  "result_kind": "result",
  "returned_params": {
    "probe": "minimal-connected"
  }
}

The command ID changes on every run. The useful evidence is the ok status, the expected logical client, a terminal result, and the original probe inside the retained payload.

Follow what happened

The Python host creates one shared development component set and attaches three roles to it. The WebSocket role owns the console connection. The application role addresses the logical client and submits example_info. The console dispatcher selects the handler registered by the example and passes it the normalized parameters.

The handler returns its received parameters and current working directory. The client posts that result to the host's returned-data endpoint. Ingestion authenticates and validates the message, applies its fences and deduplication rules, writes it to history, and signals the correlator. The waiting application code receives lightweight terminal metadata and then reads the full result from history by command ID.

This last distinction matters. A waiter is a timely signal for one caller. History is the retained application message. A successful wait does not turn its small resolution record into the durable result payload.

What a pass proves

A passing run proves that this prepared checkout can perform all of the following as one bounded exchange:

• authenticate and register a live console client;
• route a command to its current runtime instance;
• select and execute a product handler;
• return a terminal message through the authenticated HTTP edge;
• correlate the terminal message with the pending command;
• retain and read the full response;
• stop the runtime and release both listeners.

It does not prove production transport, external identity integration, persistence across a restart, multi-node coordination, or safety of arbitrary product handlers.

Diagnose the first failing boundary

If the script fails, begin with the earliest missing fact:

Do not change credentials, ports, handlers, and transport at the same time. Preserving one known-good boundary makes the next failure much easier to locate.

Replace the example action

The headless console runtime registers actions in cheetahClient/examples/console-client/shared.ts. A product action should accept a defined parameter shape, perform one bounded responsibility, and return a structured value or a structured error. It should also obey cancellation and local authority decisions supplied by the runtime.

When adding the first real action, keep the same finish line: assert over the returned result, not only over connection or send acceptance. If the handler can cause a non-repeatable external effect, give the product an idempotency or reconciliation strategy before enabling automatic retries.

Grow the first proof into an application