Cheetah / Cheetah documentation

Actions and capabilities

An action belongs to the client composition that registers it. Capability advertisement tells the server what the runtime says it can execute; central and local policy still decide whether one invocation is allowed.

Actions present in every core runtime

The first five bypass ordinary local action authorization because they are bounded runtime queries. They remain available only through the authenticated Cheetah relationship. ping.timestamp is created by Date.now() in the client runtime that executes the probe. It confirms client execution but is not an authoritative application-server clock.

Browser control actions

The browser package can register:

• list_tabs and focus_tab;
• create_tab, navigate, and close_tab;
• create_worker_window and set_worker_window;
• browser download_files;
• set_worker_overlay.

Availability depends on the composed browser services and Chrome permissions. Targets belong under target; for example, navigate reads target.tab_id and params.url.

Page actions

Browser content-script and cooperative-web layers can supply:

• change: click, type, scroll, focus, blur;
• read: get_text, get_dom, get_page_info, get_element_info, query_selector_all, get_attribute;
• wait: wait_for_element, plus web-only wait_settled.

The extension path crosses the content-script bridge and is constrained by tab access and extension permissions. The web path acts on its own cooperative document. Identical action names do not give the two environments identical authority or every identical option.

Important page-action contracts include:

• type appends to an input or textarea when clear is omitted or false, and replaces the value when clear: true; it focuses the element and emits one bubbling input event then one bubbling change event, but does not support content-editable elements;
• browser scroll accepts optional selector, x, y, and absolute; with a selector it changes that element's own scroll position;
• page-side wait_for_element defaults to 5 seconds, while the extension bridge has its own 15-second deadline;
• selected-element get_text reads textContent; without a selector it returns at most 5,000 characters of body innerText;
• get_element_info returns tag, ID, class, truncated text, rectangle, and a positive-size visibility flag, not computed styles or a general attribute map.

Console actions

The console package can register:

• flows: list_flows, create_flow, close_flow;
• files: read_file, write_file, list_dir;
• process execution: exec;
• console download_files.

exec reports the Cheetah handler as applied when the program was launched and observed; the payload's exit_code records whether the program itself succeeded. File roots, shell access, downloads, and modules should be restricted by client-local policy.

Custom and native actions

Custom action contracts belong to the package or product that registers them. Provide a descriptor with matching name, summary, argument-check choice, schema, and non-sensitive metadata. Register it before startup.

The runtime execution context exposes normalized command data, progress, cancellation, and configured providers. A progress or result payload may be an object, explicit null, or absent; wrap arrays and primitives in a named object. Return stable errors. A native bridge must translate cancellation and lifecycle semantics explicitly; current mobile/native support does not yet have full browser/console parity.

Descriptor boundary

Built-in descriptors describe the registered action names, summaries, argument-check behavior, schemas, and safe metadata used for discovery and validation. They do not grant permission, replace client-local policy, or prove that the platform has a required resource or operating-system capability. Custom action authors must keep a descriptor and its handler contract aligned and test both schema validation and real platform behavior.

The current protocol advertises capabilities at startup and has no live capability-change message. Handler registration closes when startup begins, keeping get_actions, executable handlers, and the hello advertisement aligned. Build and start a fresh runtime to change its action composition.

Interpret outcomes by action contract

An applied handler result means the Cheetah action ran and produced its defined payload. Batch actions can report partial success. External systems can report their own success or failure inside that payload. Cancellation can suppress a late terminal result after abort or lease invalidation.

Do not infer exactly-once external effects from command IDs, ACKs, leases, or returned-message deduplication. Use product idempotency and reconciliation where the action requires it.

Continue to the action catalog