@fleetless/sdk 3.0.2 → 3.1.0

package/dist/index.d.ts

@@ -2,6 +2,68 @@
 import { z } from 'zod';
 
 
+/**
+ * One exposure of a robot, as `robot_describe` and the console's per-role
+ * preview list it. Every exposure the role grants is listed —
+ * a missing `description` is shown as `null`, never used to hide the entry.
+ *
+ * `input_schema` is a JSON Schema document generated from an action's,
+ * service's or publisher's `parameters`; `null` for the other kinds. It is
+ * `unknown` for the same reason the retired `mcpToolPreview.input_schema`
+ * was: pinning it would mean maintaining a zod description of JSON Schema.
+ */
+declare const mcpExposure: z.ZodObject<{
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        datapoint: "datapoint";
+        action: "action";
+        service: "service";
+        publisher: "publisher";
+        camera: "camera";
+    }>;
+    description: z.ZodNullable<z.ZodString>;
+    unit: z.ZodNullable<z.ZodString>;
+    decimals: z.ZodNullable<z.ZodNumber>;
+    input_schema: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strip>;
+type McpExposure = z.infer<typeof mcpExposure>;
+/** The two role capabilities a robot tool can need beyond a slug grant. `presence` is a stream and has no tool. */
+declare const mcpCapabilities: z.ZodObject<{
+    action_history: z.ZodBoolean;
+    assets: z.ZodBoolean;
+}, z.core.$strip>;
+type McpCapabilities = z.infer<typeof mcpCapabilities>;
+/**
+ * What one caller may do on one robot — the answer to `robot_describe`, and
+ * since 1.1.0 to `GET /api/robots/:id/datasheet` as well. One schema for both
+ * surfaces on purpose: an app and an AI tool read the same description of the
+ * same grant. The `mcp` prefix is history, not scope.
+ */
+declare const mcpRobotDatasheet: z.ZodObject<{
+    robot_id: z.ZodUUID;
+    robot_name: z.ZodString;
+    capabilities: z.ZodObject<{
+        action_history: z.ZodBoolean;
+        assets: z.ZodBoolean;
+    }, z.core.$strip>;
+    exposures: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        kind: z.ZodEnum<{
+            datapoint: "datapoint";
+            action: "action";
+            service: "service";
+            publisher: "publisher";
+            camera: "camera";
+        }>;
+        description: z.ZodNullable<z.ZodString>;
+        unit: z.ZodNullable<z.ZodString>;
+        decimals: z.ZodNullable<z.ZodNumber>;
+        input_schema: z.ZodNullable<z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type McpRobotDatasheet = z.infer<typeof mcpRobotDatasheet>;
+
+
 /**
  * Jobs: one running unit of work on a robot — an action
  * goal or a service call — with an id both sides know, so bridge and cloud
@@ -116,6 +178,94 @@ declare const busyDetails: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 type BusyDetails = z.infer<typeof busyDetails>;
+/**
+ * One durable record of one invocation. One row per run, never one per event:
+ * the per-event timeline's write rate
+ * is set by the bridge, and a throttled log that cannot say it was throttled is
+ * an instrument that cannot say what it does not know. The live timeline is
+ * delivered in full by realtime, for as long as somebody is watching.
+ */
+declare const jobRun: z.ZodObject<{
+    id: z.ZodUUID;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        action: "action";
+        service: "service";
+    }>;
+    state: z.ZodEnum<{
+        failed: "failed";
+        running: "running";
+        succeeded: "succeeded";
+        cancelled: "cancelled";
+        lost: "lost";
+    }>;
+    started_at: z.ZodISODateTime;
+    ended_at: z.ZodNullable<z.ZodISODateTime>;
+    duration_ms: z.ZodNullable<z.ZodNumber>;
+    result: z.ZodNullable<z.ZodUnknown>;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+    actor: z.ZodObject<{
+        kind: z.ZodEnum<{
+            developer: "developer";
+            server_key: "server_key";
+            end_user: "end_user";
+            app_user: "app_user";
+        }>;
+        id: z.ZodUUID;
+        label: z.ZodString;
+    }, z.core.$strip>;
+    seq: z.ZodNumber;
+    progress: z.ZodNullable<z.ZodNumber>;
+    feedback: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strip>;
+type JobRun = z.infer<typeof jobRun>;
+declare const jobRunListResponse: z.ZodObject<{
+    runs: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        robot_id: z.ZodUUID;
+        slug: z.ZodString;
+        kind: z.ZodEnum<{
+            action: "action";
+            service: "service";
+        }>;
+        state: z.ZodEnum<{
+            failed: "failed";
+            running: "running";
+            succeeded: "succeeded";
+            cancelled: "cancelled";
+            lost: "lost";
+        }>;
+        started_at: z.ZodISODateTime;
+        ended_at: z.ZodNullable<z.ZodISODateTime>;
+        duration_ms: z.ZodNullable<z.ZodNumber>;
+        result: z.ZodNullable<z.ZodUnknown>;
+        error: z.ZodNullable<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>>;
+        actor: z.ZodObject<{
+            kind: z.ZodEnum<{
+                developer: "developer";
+                server_key: "server_key";
+                end_user: "end_user";
+                app_user: "app_user";
+            }>;
+            id: z.ZodUUID;
+            label: z.ZodString;
+        }, z.core.$strip>;
+        seq: z.ZodNumber;
+        progress: z.ZodNullable<z.ZodNumber>;
+        feedback: z.ZodNullable<z.ZodUnknown>;
+    }, z.core.$strip>>;
+    next_cursor: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+type JobRunListResponse = z.infer<typeof jobRunListResponse>;
 
 /**
  * The REST read of one datapoint. For bridge-captured data `timestamp_ms`
@@ -413,6 +563,29 @@ declare const clientIdentity: z.ZodObject<{
 type ClientIdentity = z.infer<typeof clientIdentity>;
 
 
+/**
+ * One robot as `GET /api/client/robots` lists it — the REST twin of the MCP
+ * tool `robots_list`, and the one robot question no robot-scoped route can
+ * answer: which robots may I name at all.
+ *
+ * Deliberately not `robotListItem`: that one carries `exposes`, the per-kind
+ * counts a developer's list shows, which are a configuration fact rather than
+ * something an app user's role grants. What an app user is entitled to is the
+ * robot, its bridge state, and whether anything is published on it yet.
+ */
+declare const clientRobotListItem: z.ZodObject<{
+    bridge_state: z.ZodObject<{
+        online: z.ZodBoolean;
+        latency_ms: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    published_version: z.ZodNullable<z.ZodNumber>;
+    id: z.ZodUUID;
+    name: z.ZodString;
+    created_at: z.ZodISODateTime;
+}, z.core.$strip>;
+type ClientRobotListItem = z.infer<typeof clientRobotListItem>;
+
+
 declare const asset: z.ZodObject<{
     id: z.ZodUUID;
     robot_id: z.ZodUUID;
@@ -555,10 +728,10 @@ type AssetListResponse = z.infer<typeof assetListResponse>;
  * console renders a third, and each is right in its own tests.
  *
  * `field` is the **flat key exactly as the caller sent it** — the same string
- * as the `parameterSpec.name` it violated. That is the entire justification
- * for the flat parameter form: a refusal has to name something the caller can
- * find in what they typed, and a console can attach the error to that one
- * input rather than to the form.
+ * as the `parameterSpec.name` it violated. That is why the parameter form
+ * stays flat: a refusal has to name something the caller can find in what
+ * they typed, and a console can attach the error to that one input rather
+ * than to the form.
  */
 declare const parameterViolation: z.ZodObject<{
     field: z.ZodString;
@@ -607,13 +780,13 @@ type ErrorCode = (typeof ERROR_CODES)[number];
  *   later on the same socket — nobody knows — but the caller cannot be made
  *   to wait forever for that.
  * - `command_outcome_unknown`: worse than a timeout, and told apart from it
- *   on purpose — the realtime connection that carried the command was
- *   replaced by a new one (a reconnect) before any reply arrived. A reply
- *   can now never come: the server, if it answered at all, answered a
- *   socket that no longer exists. The command may or may not have run.
- *   Never retried automatically — that could run an action twice — the
- *   caller recovers by reading the job (e.g. `actions.subscribe`), since
- *   state is observed by slug regardless of which connection asked for it.
+ *   on purpose — the connection that carried the command was replaced by a
+ *   new one (a reconnect) before any reply arrived. The server, if it
+ *   answered at all, answered a socket that no longer exists, so the
+ *   command may or may not have run. Never retried automatically — that
+ *   could run an action twice — the caller recovers by reading the job
+ *   (e.g. `actions.subscribe`), since state is observed by slug regardless
+ *   of which connection asked for it.
  * - `unexpected_response`: the server answered `ok:true` but left out
  *   something the command is defined to always return (e.g. no `job` on a
  *   successful `invoke`) — a contract violation the SDK noticed, not a
@@ -801,20 +974,19 @@ interface JobSubscriptionHandlers {
 interface JobSubscription {
     /**
      * Stops this subscription. The `unsubscribe` frame reaches the server only
-     * when this was the **last** holder of the robot and slug pair, and only if
-     * the channel is connected — subscriptions are reference-counted across
-     * kinds, so releasing this one while a second `actions.subscribe`, a
-     * `datapoints.subscribe` or an in-flight `services.call` still holds the
-     * same pair leaves that one's stream running untouched. Safe to call more
-     * than once.
+     * when this was the **last** holder of the robot/slug pair and the channel
+     * is connected — subscriptions are reference-counted across kinds, so a
+     * second `actions.subscribe`, `datapoints.subscribe` or in-flight
+     * `services.call` on the same pair keeps its stream running. Safe to call
+     * more than once.
      */
     unsubscribe(): void;
 }
 
 /**
  * Long-running work on a robot, reachable as `client.actions`. An action is
- * a ROS action the developer exposed under a slug: it is invoked, it runs
- * for as long as it runs, and it reports back while it does.
+ * a ROS action the developer exposed under a slug: it is invoked, runs as
+ * long as it runs, and reports back while it does.
  */
 interface ActionsApi {
     /**
@@ -822,7 +994,7 @@ interface ActionsApi {
      * — the job id is informative, not the result. Feedback, progress and the
      * eventual result arrive separately over `subscribe`. A second invoke of
      * the same slug while one is already running is refused `busy`, with
-     * `error.details.running` naming the job that is running.
+     * `error.details.running` naming the running job.
      *
      * `options.patienceMs` bounds goal *acceptance* only — once a goal
      * is accepted this call has already resolved; the job then runs as long
@@ -1106,7 +1278,7 @@ interface AssetsApi {
      * **Do not also install `createMeshLoader` on the same manager.** The two
      * consume different URDF sources — this method fetches the URDF's *raw*
      * bytes, `createMeshLoader` is meant to pair with `urdf()`'s
-     * cloud-rewritten text. **It is not that every mesh gets fetched twice.**
+     * cloud-rewritten text. **Not a double-fetch.**
      * What actually happens is asymmetric breakage,
      * whichever URDF text the combination ends up parsing: paired with
      * *this* method's raw text, `createMeshLoader` receives urdf-loader's
@@ -1236,7 +1408,7 @@ interface TokenStore {
 /** The default store: works out of the box, forgets the session on reload. */
 declare class InMemoryTokenStore implements TokenStore {
     #private;
-    /** Creates an empty store. Nothing is loaded from anywhere — a client built with it starts logged out. */
+    /** Nothing is loaded from anywhere — a client built with it starts logged out. */
     constructor();
     /** Returns the session held in memory, or `null` if there is none. */
     load(): StoredSession | null;
@@ -1680,8 +1852,8 @@ interface CameraLiveSession {
      * courteous fast path; the robot actually stops publishing once every
      * viewer's LiveKit `Room` has disconnected, which the SFU notices on its
      * own with no cooperation required. **Always pair this with disconnecting
-     * the `Room` you connected with `url`/`token`** — see the README's
-     * Cameras section for the paired cleanup pattern; a `release()` that ran
+     * the `Room` you connected with `url`/`token`** — see the Cameras
+     * section of the SDK reference for the paired cleanup pattern; a `release()` that ran
      * alone while the `Room` stayed connected would stop nothing.
      *
      * Safe to call more than once (only the first call does anything) and
@@ -1692,14 +1864,12 @@ interface CameraLiveSession {
      * from `beforeunload`, where a call that could throw would be a liability.
      *
      * **A failed DELETE here is not observable anywhere** — not as a
-     * rejection, not as a realtime event, not as a field on this object. This
-     * is a deliberate decision, not an oversight: the only
-     * consumer of that information would be code deciding whether to retry,
-     * and the backstop this comment already describes — the cloud's own
-     * LiveKit-participation reconciliation — makes a retry unnecessary for
-     * correctness. If a future caller needs to know "did my release actually
-     * reach the cloud" (telemetry, say), that is a new, additive signal to
-     * design, not a change to this method's contract.
+     * rejection, a realtime event, or a field on this object. Deliberate, not
+     * an oversight: the only consumer of that information would be code
+     * deciding whether to retry, and the reconciliation backstop described
+     * above already makes a retry unnecessary for correctness. A future need
+     * to know "did my release actually reach the cloud" (telemetry, say) is a
+     * new, additive signal to design, not a change to this method's contract.
      */
     release(): Promise<void>;
 }
@@ -1753,12 +1923,11 @@ interface DatapointSubscriptionHandlers {
 interface DatapointSubscription {
     /**
      * Stops this subscription. The `unsubscribe` frame reaches the server only
-     * when this was the **last** holder of the robot and slug pair, and only if
-     * the channel is connected — subscriptions are reference-counted across
-     * kinds, so releasing this one while a second `datapoints.subscribe`, an
-     * `actions.subscribe` or an in-flight `services.call` still holds the same
-     * pair leaves that one's stream running untouched. Safe to call more than
-     * once.
+     * when this was the **last** holder of the robot/slug pair and the channel
+     * is connected — subscriptions are reference-counted across kinds, so
+     * releasing this one while a `datapoints.subscribe`, `actions.subscribe` or
+     * in-flight `services.call` still holds the same pair leaves that one's
+     * stream running. Safe to call more than once.
      */
     unsubscribe(): void;
 }
@@ -1766,11 +1935,10 @@ interface DatapointSubscription {
  * Window aggregation for `datapoints.history`. `window` and `agg` always
  * travel together on the wire — the cloud refuses one without the other
  * rather than defaulting either, since a silently chosen aggregation is a
- * chart that lies quietly — so they live in one object here instead of two
- * independent optional fields a caller could set only one of. The same
- * reasoning as `cameraSource` being a discriminated union rather than
- * optional fields: make the impossible combination unrepresentable, not
- * merely rejected.
+ * chart that lies quietly — so they live in one object instead of two
+ * optional fields a caller could set only one of. Same reasoning as
+ * `cameraSource`'s discriminated union: make the impossible combination
+ * unrepresentable, not merely rejected.
  */
 interface HistoryAggregation {
     /** Bucket width, e.g. `10s`, `1m`. */
@@ -1781,9 +1949,8 @@ interface HistoryAggregation {
     field?: string;
 }
 /**
- * The window `datapoints.history` reads, and whether it comes back as raw
- * samples or as aggregated buckets. `aggregate` is what decides which of
- * the two responses you get.
+ * The window `datapoints.history` reads. `aggregate` decides whether the
+ * response is raw samples or aggregated buckets.
  */
 interface HistoryOptions {
     /**
@@ -1823,9 +1990,9 @@ interface DatapointsApi {
      * Reference-counted per `(robotId, slug)`: two subscriptions to the same
      * pair share one wire subscription. Unsubscribing one never affects the
      * other — the `unsubscribe` frame is sent only when the last subscriber
-     * on that pair goes away. This matters in practice: two widgets showing
-     * the same battery value, or a component mounted twice under React
-     * StrictMode, both subscribe to the same key. That count is shared with
+     * on that pair goes away. In practice: two widgets showing the same
+     * battery value, or a component mounted twice under React StrictMode,
+     * subscribe to the same key. That count is shared with
      * `actions.subscribe` and `services.call` — a slug is one namespace across
      * kinds, and so is its subscription.
      */
@@ -1838,10 +2005,9 @@ interface DatapointsApi {
      * reduced by `aggregate.agg`. Leave `aggregate` out and the other overload
      * gives you raw samples instead.
      *
-     * Two overloads rather than one union so a caller who already knows which
-     * they asked for isn't forced to narrow something they determined
-     * themselves. `kind` still carries the same information on both, so code
-     * holding the result dynamically can still branch on it.
+     * Two overloads rather than one union, so a caller who already knows which
+     * one they asked for isn't forced to narrow it. `kind` carries the same
+     * information either way, so dynamic code can still branch on it.
      *
      * **Rejects, does not silently empty out, two specific refusals** —
      * unlike `cameras.snapshot`'s absorption of `no_snapshot_yet` into a null
@@ -1875,26 +2041,42 @@ interface DatapointsApi {
 }
 
 /**
- * Robot-wide job reads, reachable as `client.jobs`. Everything here is
- * addressed by robot rather than by slug, which is what `actions` and
- * `services` cannot do.
+ * The filters `jobs.history` reads. Every field is optional; the wire names
+ * are snake_case and this SDK spells them the way its other options are
+ * spelt. `fromMs`/`toMs` are unix milliseconds, a half-open window
+ * `[from, to)` so adjacent windows never both contain the run on their
+ * boundary. `limit` above the platform's page cap is refused with
+ * `validation_error`, not quietly reduced.
+ */
+interface JobHistoryOptions {
+    slug?: string;
+    state?: JobState;
+    kind?: 'action' | 'service';
+    limit?: number;
+    /** The previous page's `next_cursor`. Send it back rather than computing one. */
+    beforeSeq?: number;
+    fromMs?: number;
+    toMs?: number;
+}
+/**
+ * Robot-wide job reads, reachable as `client.jobs` — addressed by robot,
+ * not slug, which `actions` and `services` cannot do.
  */
 interface JobsApi {
     /**
      * Every job the platform currently believes this robot has.
      *
-     * `actions.subscribe`/`services.call` and `GET /jobs/:slug` (the per-slug
-     * route those build on) all require already knowing the slug. That is not
-     * always true: a reconnecting bridge can name a job the cloud only
-     * *adopted*, and a configuration change can leave a job on a slug the
-     * published document no longer contains. Both are jobs no slug can name,
-     * which is exactly what this method is for — an app developer has no
-     * other way to reach them.
+     * `actions.subscribe`/`services.call` and `GET /jobs/:slug` — the per-slug
+     * route those build on — all require knowing the slug already. Two cases
+     * don't: a reconnecting bridge naming a job the cloud only *adopted*, and
+     * a config change leaving a job on a slug the published document no
+     * longer contains. Neither has a slug to give — this method is the only
+     * way an app developer reaches them.
      *
-     * At most one entry per slug: the current job there, exactly what a
-     * per-slug read would answer for that slug. Not a history endpoint.
+     * At most one entry per slug: the current job there, same as a per-slug
+     * read would answer. Not a history endpoint — that is `history` below.
      * Grant-filtered same as `cameras.list`/`datapoints` — an end user or
-     * server key sees only jobs on slugs their role grants; a developer
+     * server key sees only jobs on slugs their role grants, a developer
      * session sees every job on the robot. Never empty-vs-missing ambiguity:
      * a robot doing nothing resolves `[]`.
      *
@@ -1909,6 +2091,26 @@ interface JobsApi {
      * hour-long one was only just adopted.
      */
     list(robotId: string): Promise<Job[]>;
+    /**
+     * What *has* run on this robot: one row per run, newest first by the
+     * durable `seq`, with its actor, its outcome and its `duration_ms`, kept
+     * for 90 days. The durable counterpart of `list`.
+     *
+     * **Needs the `action_history` capability** on the caller's role, or it
+     * rejects `capability_required`. An app user sees only runs on the slugs
+     * their role grants; a developer session sees the whole robot.
+     *
+     * **Page until `next_cursor` is `null`, never until a page looks short.**
+     * The cloud applies the role's grants to the page it already read, so a
+     * page can come back thin — or empty — with a perfectly good non-null
+     * cursor behind it. `runs.length === 0` is not an end-of-data signal.
+     *
+     * It lags realtime by a moment, deliberately: a run watched to completion
+     * over `actions.subscribe` can still read `running` here for an instant.
+     * Render the outcome from the realtime job you already have; use this for
+     * what you were not watching.
+     */
+    history(robotId: string, options?: JobHistoryOptions): Promise<JobRunListResponse>;
 }
 
 /**
@@ -1920,16 +2122,15 @@ interface PublishersApi {
     /**
      * Publishes one message to a publisher.
      *
-     * This is a plain method call — there is deliberately no deadman switch,
-     * rate governor or "takt" helper here. The bridge's own
-     * `timeout_ms` failsafe is the platform's safety primitive: if messages
-     * stop arriving — including because this process crashed — the bridge
-     * publishes the configured failsafe message itself. That does **not**
-     * mean the SDK protects a caller who stops calling `publish` on purpose
-     * without stopping cleanly (e.g. no repeated call at a safe rate): the
-     * safety pattern for *how often* and *when* to publish belongs in the
-     * app, not here. See the README's "Publishers, and no teleop helpers"
-     * section before building a publisher-driven control loop.
+     * A plain method call — deliberately no deadman switch, rate governor or
+     * "takt" helper. The bridge's own `timeout_ms` failsafe is the platform's
+     * safety primitive: when messages stop arriving, crash included, the
+     * bridge publishes its configured failsafe message. That does **not**
+     * cover a caller who stops calling `publish` on purpose without stopping
+     * cleanly (e.g. no repeated call at a safe rate) — how often and when to
+     * publish is the app's pattern, not the SDK's. See the Publishers
+     * section of the SDK reference before building a
+     * publisher-driven control loop.
      *
      * Rejects `publisher_busy` while a different user is publishing and has
      * not been quiet for its configured quiet timeout yet — whoever publishes
@@ -1938,18 +2139,54 @@ interface PublishersApi {
     publish(robotId: string, slug: string, message: Record<string, unknown>, options?: SendCommandOptions): Promise<void>;
 }
 
+/**
+ * Discovery, reachable as `client.robots`: which robots may I name at all,
+ * and what may I do on one. The two calls every app screen starts from;
+ * every other namespace takes a `robotId` that came from here.
+ *
+ * The answers are the caller's role made visible — the same rows and the
+ * same datasheet the MCP tools `robots_list` and `robot_describe` answer,
+ * from the same code on the server. There is no client-side filtering to
+ * do and nothing to cache: a role change shows at the next call.
+ */
+interface RobotsApi {
+    /**
+     * The robots this caller reaches, in name order with the id as the tiebreak.
+     *
+     * An app user reaches the robots their app attaches on which their role
+     * grants at least one slug or capability; a server key reaches every robot
+     * its app attaches. A robot the role grants nothing on is absent rather
+     * than listed empty — reach is a grant, not an attachment — so a new app
+     * whose built-in roles grant nothing yet resolves `[]`, and that is the
+     * console's Roles tab talking, not a broken login.
+     */
+    list(): Promise<ClientRobotListItem[]>;
+    /**
+     * Everything the caller's role lets them do on one robot: every granted
+     * datapoint (with `unit` and `decimals`), action, service and publisher
+     * (with the parameter JSON Schema under `input_schema`) and camera, plus
+     * the two capabilities that gate whole features, `action_history` and
+     * `assets`. A robot with nothing published resolves an empty `exposures`
+     * list. One the caller does not reach rejects `not_found`, exactly as a
+     * robot that does not exist — never `forbidden`, which would say it exists.
+     *
+     * The type is `McpRobotDatasheet` because the MCP server answered it first;
+     * the prefix is history, not scope.
+     */
+    describe(robotId: string): Promise<McpRobotDatasheet>;
+}
+
 /**
  * Request/response calls to a robot, reachable as `client.services`. A
- * service answers once and is done, which is why this namespace has a
- * single method and nothing to subscribe to.
+ * service answers once and is done — one method, nothing to subscribe to.
  */
 interface ServicesApi {
     /**
      * Calls a service and resolves with its result. A service call is a job
      * underneath — the same `job_id` exchange and disconnect survival as an
      * action — but that is deliberately invisible here: the caller gets a
-     * plain `Promise<result>`, matching the REST `serviceCallResponse` shape's
-     * developer experience. There is nothing to subscribe to for a service —
+     * plain `Promise<result>`, matching the REST `serviceCallResponse` shape.
+     * There is nothing to subscribe to for a service —
      * no feedback, no progress, no cancel — so this call already waits for
      * the terminal state internally.
      *
@@ -1962,8 +2199,7 @@ interface ServicesApi {
      * call — the ack that a job was created, plus however much of the
      * budget is left for it to then reach a terminal state — not two
      * separate `timeoutMs`-length windows back to back. A caller who sets
-     * `timeoutMs: 5000` is bounding total latency at ~5s, not ~10s; the
-     * number means what it says, once, for the whole call.
+     * `timeoutMs: 5000` bounds total latency at ~5s, not ~10s.
      *
      * It is also **not independent** of `patienceMs`: left unset, it
      * is derived from `patienceMs` so this SDK's local clock cannot fire
@@ -1986,10 +2222,9 @@ interface FleetlessClientOptions {
     /** The app's identifier (the slug shown in the console), sent on every login. */
     appIdentifier: string;
     /**
-     * Where refresh/access tokens are kept between calls. Defaults to an
-     * in-memory store — pass your own (localStorage, a cookie, a native
-     * keystore) to persist a session across reloads. The SDK never assumes a
-     * browser exists.
+     * Where refresh/access tokens live between calls. Defaults to in-memory —
+     * pass your own (localStorage, a cookie, a native keystore) to persist a
+     * session across reloads. The SDK never assumes a browser exists.
      */
     tokenStore?: TokenStore;
     /**
@@ -2050,14 +2285,16 @@ interface FleetlessClient {
     readonly jobs: JobsApi;
     /** URDF and mesh reads — list/get/urdf, plus the `urdf-loader` mesh callback. */
     readonly assets: AssetsApi;
+    /** Which robots this caller reaches, and what their role lets them do on each — the calls every screen starts from. */
+    readonly robots: RobotsApi;
     /**
-     * Closes the realtime channel and stops it from reconnecting. Safe to
-     * call whether or not any subscription was ever made, and safe to call
-     * more than once. A Node script (the exact use case `serverKey` is for)
-     * that never calls this after subscribing will not exit on its own — an
-     * open WebSocket keeps the event loop alive. `auth.logout()` calls this
-     * automatically; call it yourself too if the process should exit without
-     * logging out (e.g. a server-side caller shutting down).
+     * Closes the realtime channel and stops it from reconnecting. Safe with
+     * no subscription ever made, and safe to call twice. A Node script (the
+     * exact use case `serverKey` is for) that never calls this after
+     * subscribing will not exit on its own — an open WebSocket keeps the
+     * event loop alive. `auth.logout()` calls this automatically; call it
+     * yourself if the process should exit without logging out (e.g. a
+     * server-side shutdown).
      */
     close(): void;
 }
@@ -2073,4 +2310,4 @@ interface FleetlessClient {
  */
 declare function createClient(options: FleetlessClientOptions): FleetlessClient;
 
-export { type AcceptInvitationOptions, type ActionsApi, type Asset, type AssetBytes, type AssetListResponse, type AssetsApi, type AuthApi, type BeginOidcLoginOptions, type BusyDetails, type CameraDescriptor, type CameraLiveSession, type CameraSnapshot, type CameraSnapshotMeta, type CamerasApi, type ClientIdentity, type ClientMcpInteraction, type ClientOidcErrorCode, type CompleteOidcLoginOptions, type CreateMeshLoaderOptions, type DatapointEvent, type DatapointSubscription, type DatapointSubscriptionHandlers, type DatapointValue, type DatapointsApi, type FleetlessClient, type FleetlessClientConfig, type FleetlessClientOptions, FleetlessError, type FleetlessErrorCode, type FleetlessErrorOptions, type HistoryAggregation, type HistoryBucketsResponse, type HistoryOptions, type HistorySamplesResponse, InMemoryTokenStore, type InvokeOptions, type Job, type JobEvent, type JobState, type JobSubscription, type JobSubscriptionHandlers, type JobsApi, type McpConsentGrant, type McpInteractionDecision, type MeshLoaderDelegate, type OidcLoginRequest, type ParameterInvalidDetails, type ParameterViolation, type PrepareUrdfSceneOptions, type ProviderButton, type PublishersApi, type RateLimitDetails, type RegisterOptions, SDK_ERROR_CODES, type SdkErrorCode, type SendCommandOptions, type ServicesApi, type StoredSession, type TokenStore, type UrdfCompleteness, type UrdfSceneManager, type UrdfSceneResources, createClient, parameterInvalidDetails };
+export { type AcceptInvitationOptions, type ActionsApi, type Asset, type AssetBytes, type AssetListResponse, type AssetsApi, type AuthApi, type BeginOidcLoginOptions, type BusyDetails, type CameraDescriptor, type CameraLiveSession, type CameraSnapshot, type CameraSnapshotMeta, type CamerasApi, type ClientIdentity, type ClientMcpInteraction, type ClientOidcErrorCode, type ClientRobotListItem, type CompleteOidcLoginOptions, type CreateMeshLoaderOptions, type DatapointEvent, type DatapointSubscription, type DatapointSubscriptionHandlers, type DatapointValue, type DatapointsApi, type FleetlessClient, type FleetlessClientConfig, type FleetlessClientOptions, FleetlessError, type FleetlessErrorCode, type FleetlessErrorOptions, type HistoryAggregation, type HistoryBucketsResponse, type HistoryOptions, type HistorySamplesResponse, InMemoryTokenStore, type InvokeOptions, type Job, type JobEvent, type JobHistoryOptions, type JobRun, type JobRunListResponse, type JobState, type JobSubscription, type JobSubscriptionHandlers, type JobsApi, type McpCapabilities, type McpConsentGrant, type McpExposure, type McpInteractionDecision, type McpRobotDatasheet, type MeshLoaderDelegate, type OidcLoginRequest, type ParameterInvalidDetails, type ParameterViolation, type PrepareUrdfSceneOptions, type ProviderButton, type PublishersApi, type RateLimitDetails, type RegisterOptions, type RobotsApi, SDK_ERROR_CODES, type SdkErrorCode, type SendCommandOptions, type ServicesApi, type StoredSession, type TokenStore, type UrdfCompleteness, type UrdfSceneManager, type UrdfSceneResources, createClient, parameterInvalidDetails };