Cheetah / Cheetah documentation

Core and custom actions

Every core runtime registers a small set of framework actions. They test the runtime boundary, describe its executable surface, and optionally write through a configured cache. Platform and product actions use the same handler and descriptor interfaces.

Core actions

The five framework probes bypass ordinary local action authorization because they are bounded runtime inspection operations. They are not unauthenticated network endpoints: the server still has to establish the Cheetah relationship and deliver a valid command.

The timestamp returned by ping comes from Date.now() in the client that executed it. It is useful as proof of client-side execution and for rough diagnostics, not as an authoritative or synchronized application clock. echo is a transport and serialization probe; do not put secrets into it merely because the server is trusted.

get_config depends on the configured provider's filterOutboundConfig() implementation. Without a provider it reports that configuration is unavailable. get_policy similarly reports an inactive policy when no local policy source exists. get_actions reports the frozen pre-start registration set because registration closes when startup begins.

cache_data

cache_data requires string key and string data. encoding defaults to utf-8; the cache provider decides how supported encodings and metadata are persisted. With no cache provider the action fails with no_cache. Core's default composition has no cache provider, while the console runtime supplies a filesystem-backed one.

Caching is a local convenience, not durable application history. Providers may evict data, share a device with another process, or disappear with the client. Do not infer server acceptance, transactional durability, or secure secret storage from an applied cache result.

Register a product action before startup

A handler names one command type and returns one terminal CommandResult or null. A matching ActionDescriptor makes that operation discoverable and enables basic argument validation.

import type {
  ActionDescriptor,
  CommandContext,
  ICommandHandler,
} from '@cheetah/core';

const descriptor: ActionDescriptor = {
  name: 'read_temperature',
  version: '1.0',
  summary: 'Read one registered sensor',
  requiresArgCheck: true,
  argSchema: {
    sensor_id: { type: 'string', required: true },
  },
};

const handler: ICommandHandler = {
  commandType: 'read_temperature',
  async execute(ctx: CommandContext) {
    if (ctx.abortSignal.aborted || !ctx.isLeaseValid()) return null;

    const sensorId = String(ctx.command.params?.sensor_id);
    const celsius = await sensors.read(sensorId);
    return { status: 'applied', payload: { sensor_id: sensorId, celsius } };
  },
};

runtime.registerHandler(handler, descriptor);
await runtime.start();

The handler's commandType and descriptor name must describe the same public operation. Registration must finish before start(); a later registration raises RuntimeHandlerRegistrationClosedError. To change the action set, create and start a fresh runtime.

Descriptors support discovery, not full schema validation

ActionDescriptor can contain name, summary, description, version, whether argument checks are required, an argument schema, and non-sensitive metadata. The v1 argument validator runs only when requiresArgCheck is true and an argSchema exists. It checks required presence and the five basic types string, number, boolean, array, and non-array object.

It does not enforce nested schemas, string formats, enum values, numeric ranges, relationships between fields, or rejection of undeclared fields. Unknown type names are currently skipped. Handlers must validate semantic rules themselves, preferably through shared product validators that can also be exercised outside the transport path.

Descriptor metadata is advertised and can be shown to operators, applications, or model-driven tools. Do not put credentials, private host paths, tokens, or mutable security decisions in it. A descriptor says what code was registered; it neither grants permission nor proves the device can satisfy an invocation at that moment.

Handler context and progress

CommandContext supplies the normalized command, an optional lease, an abort signal, isLeaseValid(), and progress(). Before any side effect, a handler should check both cancellation and lease validity. Long operations should check again at safe interruption points.

progress() publishes an intermediate message. Progress can enter history and wake readers, but it does not complete an RPC. The handler should still return a terminal result or error unless cancellation or lease loss requires it to return null and suppress late output.

Progress and terminal payloads must be a JSON object, explicit null, or absent. Wrap an array or primitive in a named object:

await ctx.progress({ completed: 20, total: 100 });
return { status: 'applied', payload: { values: [1, 2, 3] } };

Use stable machine-readable error codes and clear human messages. An action that successfully observes a failed child process or a rejected remote job may still be applied with that external outcome in its payload. Reserve the Cheetah failed status for failure of the action's own contract.

Authority remains layered

The server's central decision, client-local policy, optional approval, constraint evaluators, resource lease, platform permissions, and handler validation are distinct checks. A central allow cannot override an explicit client-local deny. Approval permits one invocation; it does not rewrite policy. A valid lease coordinates Cheetah work on the target but cannot grant operating-system or browser authority.

Design custom actions with a precise success boundary and idempotency strategy. ACK proves receipt into the client dispatch path, not handler entry or effect completion. A returned result is stronger evidence, but only for what that action contract says it observed.

Continue to browser control actions