@fleetless/sdk 3.1.1 → 4.0.0

package/dist/index.js

@@ -236,7 +236,6 @@ function isRenderKind(kind) {
     case "texture":
       return true;
     case "urdf":
-    case "other":
       return false;
     default: {
       const exhaustive = kind;
@@ -411,7 +410,7 @@ function createAssetsApi(http) {
   };
 }
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/common.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/common.js
 import { z } from "zod";
 var SLUG_RULE = "A name is lower-case: it starts with a letter, continues with letters and digits, and joins further words with a single underscore \u2014 `battery_voltage`. Capitals, dashes, dots, spaces, a leading digit and a doubled or trailing underscore are all refused.";
 var slug = z.string().min(2).max(63).regex(/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/, SLUG_RULE);
@@ -426,7 +425,14 @@ var wireTimestampMs = z.union([z.string().regex(/^\d{1,15}$/), z.number().int()]
   const year = new Date(ms).getUTCFullYear();
   return Number.isFinite(year) && year >= 1 && year <= 9999;
 }, "must fall within years 1..9999"));
-var applyErrorKind = z.enum(["datapoint", "action", "service", "publisher", "camera"]);
+var applyErrorKind = z.enum([
+  "datapoint",
+  "action",
+  "service",
+  "publisher",
+  "camera",
+  "low_bandwidth"
+]);
 var applyError = z.object({
   slug: z.string(),
   kind: applyErrorKind,
@@ -435,7 +441,7 @@ var applyError = z.object({
   details: z.record(z.string(), z.unknown()).optional()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/mcp.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/mcp.js
 import { z as z2 } from "zod";
 function mcpAppEndpointPath(appIdentifier2) {
   return `/mcp/${appIdentifier2}`;
@@ -484,17 +490,17 @@ var mcpRolePreviewResponse = z2.object({
 });
 var MCP_ASSET_LINK_TTL_MS = 15 * 60 * 1e3;
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/protocol.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/protocol.js
 import { z as z8 } from "zod";
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/assets.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/assets.js
 import { z as z3 } from "zod";
-var assetKind = z3.enum(["urdf", "mesh", "texture", "other"]);
+var assetKind = z3.enum(["urdf", "mesh", "texture"]);
 var asset = z3.object({
   id: z3.uuid().meta({ description: "The asset's id in the store." }),
   robot_id: z3.uuid().meta({ description: "The robot this asset belongs to." }),
   kind: assetKind.meta({
-    description: "What the file is: the `urdf` itself, a `mesh` it references, a `texture` a mesh or the URDF paints with, or `other`. A renderer decides from this alone, before fetching anything, what to pre-fetch."
+    description: "What the file is: the `urdf` itself, a `mesh` it references, or a `texture` a mesh or the URDF paints with. A renderer decides from this alone, before fetching anything, what to pre-fetch."
   }),
   /**
    * What the robot called it — for a mesh, the `package://` URI the URDF
@@ -593,16 +599,18 @@ var assetSyncResponse = z3.object({
     description: "The sync that has just started. A sync is long-running, so the answer is something to watch rather than a status that was true at the moment of asking."
   })
 });
-var ASSET_UPLOAD_MAX_BYTES = 64 * 1024 * 1024;
-var assetTooLargeDetails = z3.object({
-  limit_bytes: z3.number().int().positive().meta({
-    description: "The upload ceiling, in bytes."
+var assetStoreRefusedDetails = z3.object({
+  store_bytes: z3.number().int().positive().meta({
+    description: "The robot's store, in bytes."
+  }),
+  used_bytes: z3.number().int().nonnegative().meta({
+    description: "Bytes the robot's assets occupy before this upload."
   }),
   size_bytes: z3.number().int().positive().meta({
-    description: 'How large the refused file is, in bytes. With `limit_bytes` beside it a developer can tell whether to shrink the mesh or raise the limit; "too large" alone answers neither.'
+    description: "The refused upload, in bytes."
   })
 });
-var assetFailureKind = z3.enum(["unresolvable", "upload_failed", "refused", "too_large"]);
+var assetFailureKind = z3.enum(["unresolvable", "upload_failed", "refused"]);
 var assetFailure = z3.object({
   /**
    * What could not be provided, verbatim — the same string `asset.name` would
@@ -615,33 +623,28 @@ var assetFailure = z3.object({
     description: "What could not be provided, verbatim \u2014 the same string the asset would have been stored under, so a developer can match it against their own workspace by eye. For a failed URDF upload it is `robot_description`, which is **not** a mesh URI: a consumer must not assume every entry is one."
   }),
   kind: assetFailureKind.meta({
-    description: "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** \u2014 the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, `refused` means it was never attempted because a producer-side ceiling was hit, and `too_large` means it exceeds the upload limit and carries both numbers in `details`."
+    description: "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** \u2014 the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, and `refused` means it was never attempted, either because the robot's asset store had no room \u2014 then `details` carries the three numbers \u2014 or because a producer-side ceiling was hit."
   }),
   /**
-   * **The two numbers, and why `too_large` is a kind of its own.**
+   * **The three numbers behind a full store.**
    *
-   * `refused` means *never attempted, because a producer-side ceiling was
-   * hit*. That fits a file skipped for its size **and** the single collective
-   * entry a sync emits when it stops naming individual failures. Filing both
-   * under one kind puts two facts on one key, each overwriting the other.
+   * A reason without numbers is not one a caller can act on. *"Refused"* does
+   * not answer whether to delete an old sync or shrink the mesh;
+   * `store_bytes`, `used_bytes` and `size_bytes` do.
    *
-   * A reason without numbers is not one a caller can act on. *"Too large"*
-   * does not answer whether to shrink the mesh or raise the limit;
-   * `limit_bytes` and `size_bytes` do.
-   *
-   * Absent for every other kind — a forced `details: null` on every
-   * `unresolvable` buys nothing. The pairing is **enforced** below, not merely
-   * described: a field whose rule lives only in a comment is a request.
+   * **Present only on `refused`, and not on every `refused`.** The other half
+   * of that kind is the single collective entry a sync emits when it stops
+   * naming individual failures, and no store number describes it — requiring
+   * details there would mean inventing them. So the enforcement below is the
+   * half that can be enforced: details belong to `refused` and to nothing
+   * else. A forced `details: null` on every `unresolvable` buys nothing.
    */
-  details: assetTooLargeDetails.nullish().meta({
-    description: "The two numbers behind a `too_large` failure, and absent for every other kind \u2014 a forced `null` on every `unresolvable` entry buys nothing. The pairing is enforced, not merely described."
+  details: assetStoreRefusedDetails.nullish().meta({
+    description: "The three numbers behind a `refused` entry the robot's store had no room for, and absent for every other kind \u2014 a forced `null` on every `unresolvable` entry buys nothing. A `refused` entry may also carry no details: the producer's own ceiling is the other half of that kind, and no store number describes it."
   })
 }).superRefine((f, ctx) => {
-  if (f.kind === "too_large" && f.details == null) {
-    ctx.addIssue({ code: "custom", path: ["details"], message: "`too_large` without limit_bytes/size_bytes says nothing a developer can act on" });
-  }
-  if (f.kind !== "too_large" && f.details != null) {
-    ctx.addIssue({ code: "custom", path: ["details"], message: "size details belong to `too_large` only" });
+  if (f.kind !== "refused" && f.details != null) {
+    ctx.addIssue({ code: "custom", path: ["details"], message: "store details belong to `refused` only" });
   }
 });
 var assetSyncState = z3.enum(["running", "succeeded", "failed"]);
@@ -687,6 +690,36 @@ var assetSyncStatus = z3.object({
   reason: z3.string().min(1).nullable().meta({
     description: "Why the sync ended as it did, when that is not a per-reference fact. `null` when `failed` already says everything there is to say."
   }),
+  /**
+   * **What the receiver counted, next to what the producer claimed.**
+   *
+   * `state` is the bridge's own terminal frame and nothing else. A dev stack
+   * with no object store answered `500` to every upload and the sync still
+   * read `succeeded` — the producer had genuinely sent every file, and no
+   * one had asked the store. These two numbers are the cloud's own count,
+   * taken after the terminal frame: how many of the announced files
+   * (`assets_available`'s URDF and mesh list) its store actually holds.
+   *
+   * They are a pair because neither alone answers anything. `stored` without
+   * `announced` cannot say whether four files is all of them or a tenth of
+   * them, and `announced` alone is what the producer said it had, which is
+   * the claim under examination.
+   *
+   * A partial store is still `succeeded`: some meshes were never going to
+   * resolve, and the per-reference `failed` entries say which. An empty one
+   * under a `succeeded` frame is `failed`, because no transport succeeds at
+   * nothing.
+   *
+   * **`stored` is `null` while the sync is still running.** The count is
+   * taken once, after the robot's terminal frame; a `0` before then would
+   * say the store is empty when nobody has looked.
+   */
+  stored: z3.number().int().nonnegative().nullable().meta({
+    description: "How many of the announced files the cloud's store actually holds. Counted once, after the robot reports the sync done, and `null` until then \u2014 nobody has looked yet. Read it against `announced`: `state` is what the robot reported, this is what arrived."
+  }),
+  announced: z3.number().int().nonnegative().meta({
+    description: "How many files the robot announced for this sync \u2014 the URDF, if it has one, plus every mesh URI its description references. `0` when the robot announced nothing, and also `0` until it has answered at all: read it beside `stored`, which stays `null` until the terminal frame."
+  }),
   started_at: z3.iso.datetime().meta({
     description: "When the sync started, as an ISO 8601 timestamp."
   }),
@@ -730,6 +763,43 @@ var assetListResponse = z3.object({
    */
   urdf_available: z3.boolean().nullable().meta({
     description: 'What the connected bridge says it *could* transfer \u2014 deliberately separate from what has been transferred. `null` when no bridge is connected, distinct from `false`: "no robot is online to ask" and "the robot has no URDF" send a developer to different places. After a publisher is killed rather than shut down this can read `true` for some seconds, on the underlying DDS liveliness timeout rather than on any check made here.'
+  }),
+  /**
+   * **How full this robot's store is, on the list that already names what is
+   * in it.** A page showing assets is the page where "will the next sync fit"
+   * is asked, and a second round trip to some quota endpoint would answer it
+   * about the organisation instead — which is a different number about a
+   * different thing.
+   */
+  store: z3.object({
+    bytes: z3.number().int().positive().meta({
+      description: "The robot's asset store, `ROBOT_ASSET_STORE_BYTES`."
+    }),
+    used_bytes: z3.number().int().nonnegative().meta({
+      description: "Bytes its assets occupy."
+    })
+  }).meta({ description: "How full this robot's store is." }),
+  /**
+   * The datapoint that moves the joints in a renderer, chosen by a developer
+   * and stored on the robot. It rides on this list because a client that has
+   * just fetched the URDF and the meshes needs exactly one more thing to
+   * animate them, and asking a second endpoint for one slug is a round trip
+   * that buys nothing.
+   *
+   * `null` is an ordinary answer: none was ever chosen, or a publish removed
+   * the datapoint it named and the cloud cleared the mapping rather than
+   * leave it pointing at something that no longer qualifies.
+   */
+  joint_state_slug: slug.nullable().meta({
+    description: "The whole-message `sensor_msgs/msg/JointState` datapoint that drives the console's URDF viewer; null when none is chosen or a publish removed it. Set through `PUT /api/robots/:id/urdf/joint-state`."
+  })
+});
+var assetsClearResponse = z3.object({
+  deleted: z3.number().int().nonnegative().meta({
+    description: "How many assets \u2014 URDF, meshes and textures together \u2014 were removed."
+  }),
+  bytes_freed: z3.number().int().nonnegative().meta({
+    description: "The bytes the robot's store got back."
   })
 });
 var missingAssetQuery = z3.object({
@@ -743,10 +813,10 @@ var assetSyncBusyDetails = z3.object({
   started_at_ms: z3.number().int().nonnegative()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/config.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/config.js
 import { z as z5 } from "zod";
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/alerts.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/alerts.js
 import { z as z4 } from "zod";
 var alertRowCondition = z4.discriminatedUnion("kind", [
   z4.strictObject({
@@ -816,7 +886,7 @@ var putDatapointDisplayRequest = z4.object({
   y_max: z4.number().finite().nullable()
 }).strict();
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/config.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/config.js
 var RTSP_URL_RULE = "The URL has to begin with `rtsp://` or `rtsps://` \u2014 `rtsp://cam-1.plant.local/stream1`. No other scheme is accepted: the bridge opens this with a library that would equally honour `file:`.";
 var MJPEG_URL_RULE = "The URL has to begin with `http://` or `https://` \u2014 `http://cam-1.plant.local/video.mjpg`. No other scheme is accepted: the bridge opens this with a library that would equally serve `file:`.";
 var DEVICE_PATH_RULE = "A capture device is a path under `/dev/`, and the character straight after it is a letter or a digit \u2014 `/dev/video0`, or a stable `/dev/v4l/by-id/...` symlink. Nothing outside `/dev/` is accepted: the string reaches OpenCV, which would as happily open an ordinary file.";
@@ -1207,6 +1277,9 @@ var datapointConfig = strictObject({
     description: "A ceiling on how often this datapoint is sent, in hertz. Omitted or `0` means no throttling. It is **a ceiling, not a clock**: a slow topic stays slow, a value is never repeated to manufacture a rate, and within a window the newest value wins. The bridge enforces it, so the robot's bandwidth is genuinely saved.",
     examples: [2, 0.5]
   }).optional(),
+  low_bandwidth: z5.literal("keep").optional().meta({
+    description: "`keep` exempts this datapoint from the low-bandwidth rate cap; its backfill still pauses."
+  }),
   description: serviceDescription.meta({
     description: "Prose about what this value is, for whoever meets it in the console. It changes nothing the robot does, so a publish that touches only it pushes no configuration at all \u2014 but it is carried verbatim into `robot_describe`, where a model that has never seen this robot reads it. The datapoint is offered whenever the role grants it; without one it is offered with `description: null` and the model has less to go on, as for actions, services, publishers and cameras. Omission is the only way to say nothing; an empty string is refused, here and on all five.",
     /**
@@ -1804,6 +1877,34 @@ var cameraConfig = strictObject({
   /** The value position of one entry — `front: ▮` under `cameras:`. */
   defaultSnippets: [CAMERA_SNIPPET]
 });
+var lowBandwidthMode = z5.enum(["auto", "on", "off"]);
+var lowBandwidthCamera = z5.enum(["reduce", "stop"]);
+var lowBandwidthSection = strictObject({
+  mode: lowBandwidthMode.optional().meta({
+    description: "`auto` decides from the measured lag; `on` and `off` force the mode, for tests and for an operator who knows the link.",
+    enumDescriptions: describeValues(lowBandwidthMode.options, {
+      auto: "The bridge enters and leaves the mode on its own, from the lag the cloud reports and the dwell it measures in its own send queue. The setting to leave alone.",
+      on: "The mode is held on, whatever the link is doing. For a robot on a link known to be poor, and for a test that would otherwise have to wait for a real one.",
+      off: "The mode never engages, whatever the link is doing. The robot then sends at its configured rates over a link that cannot carry them, which is a choice and not a default."
+    })
+  }),
+  enter_lag_ms: z5.number().int().min(100).optional().meta({ description: "Lag or queue dwell above this enters the mode. Checked against exit_lag_ms only when both are in this document; a lone key composes with the bridge's parameter or the default on the robot, and a crossed pair is refused there when the configuration is applied, so name both when you change either." }),
+  enter_after_s: z5.number().int().min(1).optional().meta({ description: "The entry condition must hold this long." }),
+  exit_lag_ms: z5.number().int().min(0).optional().meta({ description: "Lag and dwell both at or below this leave the mode. Must be at or below enter_lag_ms: a crossed pair is a mode that leaves as it arrives. Checked here only when both keys are present; a lone key is checked on the robot against the parameter or default it composes with." }),
+  exit_after_s: z5.number().int().min(1).optional().meta({ description: "The exit condition must hold this long." }),
+  datapoint_max_hz: z5.number().gt(0).max(20).optional().meta({ description: "The long-run rate for every datapoint in the mode, unless the datapoint says `low_bandwidth: keep`. It is an average, not a minimum gap: after a quiet spell two samples may go out close together, and over any longer window the rate holds." }),
+  camera: lowBandwidthCamera.optional().meta({
+    description: "What happens to a running stream in the mode. New streams are refused either way.",
+    enumDescriptions: describeValues(lowBandwidthCamera.options, {
+      reduce: "A running stream is re-encoded at `camera_bitrate_kbps` and keeps running. A viewer sees a worse picture rather than none.",
+      stop: "A running stream ends and the viewer is told why. The uplink is then free for datapoints, which is the right trade where video is the nice-to-have."
+    })
+  }),
+  camera_bitrate_kbps: z5.number().int().min(50).max(2e4).optional().meta({ description: "Bitrate applied to running streams under `reduce`." })
+}).superRefine((s, ctx) => {
+  if (s.enter_lag_ms !== void 0 && s.exit_lag_ms !== void 0 && s.exit_lag_ms > s.enter_lag_ms)
+    ctx.addIssue({ code: "custom", path: ["exit_lag_ms"], message: "low_bandwidth.exit_lag_ms must be at or below enter_lag_ms" });
+});
 var FLEETLESS_FORMAT_VERSION = 1;
 var capped = (entry, max, what) => slugKeyed(entry).refine((m) => Object.keys(m).length <= max, { message: `at most ${max} ${what}` });
 var robotConfigDoc = strictObject({
@@ -1815,28 +1916,42 @@ var robotConfigDoc = strictObject({
     defaultSnippets: [underSlug("${1:drive}", SHARED_MESSAGE_SNIPPET)]
   }).optional(),
   datapoints: capped(datapointConfig, 200, "datapoints").meta({
-    description: "Values the robot publishes, each one field of one topic or a whole topic, and **never several topics**. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET \u2026/jobs/history` would shadow an action of that name; all four are refused when the document is validated.",
+    description: "Values the robot publishes, each one field of one topic or a whole topic, and **never several topics**. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET \u2026/jobs/history` would shadow an action of that name; all three are refused when the document is validated.",
     defaultSnippets: [
       underSlug("${1:battery_voltage}", DATAPOINT_SNIPPET),
       underSlug("${1:battery}", NUMERIC_DATAPOINT_SNIPPET)
     ]
   }).optional(),
   actions: capped(actionConfig, 200, "actions").meta({
-    description: "Things the robot does on request that take time, each reported as a job with progress. **At most one job runs per action slug**: a second call is refused `busy`, and every observer of that slug watches the same job. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET \u2026/jobs/history` would shadow an action of that name; all four are refused when the document is validated.",
+    description: "Things the robot does on request that take time, each reported as a job with progress. **At most one job runs per action slug**: a second call is refused `busy`, and every observer of that slug watches the same job. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET \u2026/jobs/history` would shadow an action of that name; all three are refused when the document is validated.",
     defaultSnippets: [underSlug("${1:navigate}", ACTION_SNIPPET)]
   }).optional(),
   services: capped(serviceConfig, 200, "services").meta({
-    description: "ROS service calls the robot answers \u2014 one request, one reply. Unlike an action a service reports **no progress** and the call returns with its result already on the job, so there is nothing left to observe; a second concurrent call is still refused `busy`, exactly as for an action. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET \u2026/jobs/history` would shadow an action of that name; all four are refused when the document is validated.",
+    description: "ROS service calls the robot answers \u2014 one request, one reply. Unlike an action a service reports **no progress** and the call returns with its result already on the job, so there is nothing left to observe; a second concurrent call is still refused `busy`, exactly as for an action. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET \u2026/jobs/history` would shadow an action of that name; all three are refused when the document is validated.",
     defaultSnippets: [underSlug("${1:reset_odometry}", SERVICE_SNIPPET)]
   }).optional(),
   publishers: capped(publisherConfig, 200, "publishers").meta({
-    description: "Topics clients may send to, and where the format's whole safety story lives. The `message` template fixes every value a caller cannot change, and **`failsafe` is required**: once a client falls silent the bridge sends the failsafe message itself, so an operator whose window closed does not leave a robot driving. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET \u2026/jobs/history` would shadow an action of that name; all four are refused when the document is validated.",
+    description: "Topics clients may send to, and where the format's whole safety story lives. The `message` template fixes every value a caller cannot change, and **`failsafe` is required**: once a client falls silent the bridge sends the failsafe message itself, so an operator whose window closed does not leave a robot driving. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET \u2026/jobs/history` would shadow an action of that name; all three are refused when the document is validated.",
     defaultSnippets: [underSlug("${1:drive}", PUBLISHER_SNIPPET)]
   }).optional(),
   cameras: capped(cameraConfig, 50, "cameras").meta({
-    description: "Video the robot streams, and the still frames the cloud serves from it. `width`, `height`, `fps` and `bitrate_kbps` are what **the bridge produces before sending**, not what the camera captures \u2014 they live in the configuration rather than in a viewer's request precisely so that no viewer can make a robot send more. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET \u2026/jobs/history` would shadow an action of that name; all four are refused when the document is validated.",
+    description: "Video the robot streams, and the still frames the cloud serves from it. `width`, `height`, `fps` and `bitrate_kbps` are what **the bridge produces before sending**, not what the camera captures \u2014 they live in the configuration rather than in a viewer's request precisely so that no viewer can make a robot send more. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET \u2026/jobs/history` would shadow an action of that name; all three are refused when the document is validated.",
     defaultSnippets: [underSlug("${1:front}", CAMERA_SNIPPET)]
-  }).optional()
+  }).optional(),
+  low_bandwidth: lowBandwidthSection.optional().meta({
+    description: "Overrides for the bridge's low-bandwidth mode; see the section schema.",
+    /**
+     * The body is the three keys a developer actually reaches for — when the
+     * mode engages, how hard it caps, and what it does to video. The five
+     * timing keys stay out: they exist to be tuned once against a measured
+     * link, and a skeleton that pre-fills them reads as a recommendation.
+     */
+    defaultSnippets: [{
+      label: "low-bandwidth mode, tuned",
+      description: "Enters after ten seconds above two seconds of lag, caps every datapoint to 1 Hz and lets running streams continue at a reduced bitrate.",
+      body: { enter_lag_ms: 2e3, datapoint_max_hz: 1, camera: "reduce" }
+    }]
+  })
 });
 var validationIssue = z5.object({
   path: z5.string().min(1),
@@ -1863,7 +1978,7 @@ var configState = z5.object({
   applied_errors: z5.array(applyError).nullable()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/introspection.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/introspection.js
 import { z as z6 } from "zod";
 var rosGraphEntry = z6.object({
   name: rosName,
@@ -1902,7 +2017,7 @@ var typeDefinition = z6.discriminatedUnion("kind", [
   })
 ]);
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/jobs.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/jobs.js
 import { z as z7 } from "zod";
 var jobState = z7.enum(["running", "succeeded", "failed", "cancelled", "lost"]);
 var job = z7.object({
@@ -2120,7 +2235,8 @@ var jobRunSummary = z7.object({
   since_ms: z7.number().int().nonnegative()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/protocol.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/protocol.js
+var DAY_MS = 24 * 60 * 60 * 1e3;
 var MAX_PATIENCE_MS = 12e4;
 var MIN_PATIENCE_MS = 1e3;
 var activeJob = z8.object({
@@ -2156,7 +2272,20 @@ var bridgeHello = z8.object({
 });
 var cloudHelloOk = z8.object({
   type: z8.literal("hello_ok"),
-  robot_id: z8.uuid()
+  robot_id: z8.uuid(),
+  protocol: z8.object({
+    status: z8.enum(["current", "deprecated"]).meta({
+      description: "`current` or `deprecated` \u2014 never `unsupported`, which is a `hello_error`."
+    }),
+    sunset_at: z8.iso.date().nullable().meta({
+      description: "ISO date a deprecated version stops being served; `null` when current."
+    })
+  }).optional().meta({ description: "The cloud's verdict on the announced protocol version; absent from an older cloud." }),
+  bridge: z8.object({
+    latest_version: z8.string().min(1).meta({
+      description: "The newest published fleetless-bridge package version, for the bridge's own upgrade hint."
+    })
+  }).optional().meta({ description: "What the cloud knows about bridge packages; absent from an older cloud." })
 });
 var cloudHelloError = z8.object({
   type: z8.literal("hello_error"),
@@ -2167,16 +2296,25 @@ var datapointFrame = z8.object({
   type: z8.literal("datapoint"),
   slug,
   value: z8.unknown(),
-  timestamp_ms: z8.number().int().nonnegative()
+  timestamp_ms: z8.number().int().nonnegative(),
+  backfill: z8.boolean().optional().meta({ description: "true when the sample was captured while the bridge was disconnected and is being replayed after the reconnect. The cloud keeps such a sample out of its lag measure; absent means live." })
 });
 var cloudPing = z8.object({
   type: z8.literal("ping"),
-  ts_ms: z8.number().int().nonnegative()
+  ts_ms: z8.number().int().nonnegative(),
+  latency_ms: z8.number().nonnegative().nullable().meta({ description: "Round trip of the last pong in milliseconds; null before the first." }),
+  lag_ms: z8.number().nonnegative().nullable().meta({ description: "Datapoint lag over the link: median of the last five seconds minus the ten-minute minimum, in milliseconds; null until a sample exists, and null again whenever no live sample arrived in the last five seconds, because a stale median would be a lie." })
 });
 var bridgePong = z8.object({
   type: z8.literal("pong"),
   ts_ms: z8.number().int().nonnegative()
 });
+var bridgeLinkMode = z8.object({
+  type: z8.literal("link_mode"),
+  low_bandwidth: z8.boolean().meta({ description: "Whether the mode is active after this transition." }),
+  reason: z8.enum(["lag", "dwell", "forced", "recovered"]).meta({ description: "`lag`: the cloud-measured lag crossed the threshold; `dwell`: the bridge-measured queue dwell did; `forced`: `mode: on` or `off`; `recovered`: both measures stayed at or below the exit threshold." }),
+  at_ms: z8.number().int().nonnegative().meta({ description: "Bridge time of the transition, epoch milliseconds." })
+});
 var cloudConfig = z8.object({
   type: z8.literal("config"),
   version: z8.number().int().nonnegative(),
@@ -2286,75 +2424,8 @@ var bridgeTypeDefinitions = z8.object({
 });
 var bridgeState = z8.object({
   online: z8.boolean(),
-  latency_ms: z8.number().nonnegative().nullable()
-});
-var bridgePressureTier = z8.object({
-  sent: z8.number().int().nonnegative(),
-  bytes: z8.number().int().nonnegative(),
-  drops: z8.number().int().nonnegative(),
-  high_water: z8.number().int().nonnegative()
-});
-var bridgePressure = z8.object({
-  link: z8.object({
-    /** bytes/s the socket demonstrably drains, from sends >= 64 KiB
-     *  only; null until the first large send of the session. */
-    rate_bps: z8.number().nonnegative().nullable(),
-    /**
-     * the byte target snapshots are currently encoded to fit.
-     *
-     * `.nonnegative()`, not `.positive()`: the target is derived from
-     * `rate_bps`, and a link measured below 0.5 B/s floors to 0 here. A
-     * schema that rejects 0 does not prevent that link — it only makes the
-     * frame reporting it unparseable, and a console that cannot parse a
-     * pressure frame shows "no feed", i.e. reports a struggling robot as an
-     * *old* one. Zero is a legitimate reading and says something true.
-     */
-    snapshot_max_bytes: z8.number().int().nonnegative()
-  }),
-  /**
-   * String keys "0".."5" because JSON has no integer keys. Counters are
-   * cumulative per session and reset on reconnect; clients window by
-   * differencing two samples.
-   *
-   * **What this schema does not decide:** it does not guarantee all six
-   * keys are present (`z.record` over the six literals is exhaustive in
-   * zod 4 — tested here, it required every key and rejected none, the
-   * opposite of what a partial sample needs — so this is a
-   * `.strictObject().partial()` over the same six literal keys instead, a
-   * deliberate deviation from the originally sketched `z.record` shape with
-   * the same runtime behaviour). A missing tier key reads as zeros; the
-   * schema names what it cannot decide rather than implying a completeness
-   * it cannot check.
-   */
-  tiers: z8.strictObject({
-    "0": bridgePressureTier,
-    "1": bridgePressureTier,
-    "2": bridgePressureTier,
-    "3": bridgePressureTier,
-    "4": bridgePressureTier,
-    "5": bridgePressureTier
-  }).partial(),
-  video: z8.object({
-    active_streams: z8.number().int().nonnegative(),
-    bitrate_sum_kbps: z8.number().int().nonnegative(),
-    /**
-     * The uplink budget the bridge was configured with
-     * (`FLEETLESS_UPLINK_KBPS`), or `null` when none was set.
-     *
-     * `.nonnegative()`, not `.positive()`: `FLEETLESS_UPLINK_KBPS=0` is a
-     * documented setting meaning "no video budget at all", and the bridge
-     * emits that 0 verbatim. `.positive()` made every frame from such a
-     * robot fail the console's `safeParse`, which renders an unparseable
-     * frame as "no pressure feed" — so the one robot that had *deliberately*
-     * turned video off was the one diagnosed as running a bridge too old to
-     * report pressure. A value the producer legitimately sends must parse;
-     * `null` is the only "not set" this field has.
-     */
-    uplink_kbps: z8.number().int().nonnegative().nullable(),
-    override_kbps: z8.number().int().nonnegative().nullable(),
-    video_budget_kbps: z8.number().int().nonnegative().nullable(),
-    reserve_kbps: z8.number().int().nonnegative()
-  })
+  latency_ms: z8.number().nonnegative().nullable(),
+  low_bandwidth: z8.boolean().meta({ description: "Whether the bridge is in its low-bandwidth mode: datapoints capped, cameras reduced or stopped. Bridge-reported." })
 });
 var snapshotHeader = z8.object({
   type: z8.literal("snapshot"),
@@ -2518,11 +2589,11 @@ var bridgeCameraState = z8.object({
   request_id: z8.string().min(1).max(64).nullable()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/config-issues.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/config-issues.js
 var EXPOSURE_SECTIONS = ["datapoints", "actions", "services", "publishers", "cameras"];
 var EXPOSURE_SECTION_NAMES = new Set(EXPOSURE_SECTIONS);
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/rest.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/rest.js
 import { z as z9 } from "zod";
 var robot = z9.object({
   id: z9.uuid().meta({
@@ -2548,6 +2619,21 @@ var createRobotResponse = z9.object({
   robot,
   token: robotToken
 });
+var robotTokenRotateResponse = z9.object({
+  token: robotToken.meta({
+    description: "The robot's new bridge token. Returned exactly once; the previous token stops working at the bridge's next hello."
+  })
+});
+var jointStatePutRequest = z9.object({
+  slug: slug.nullable().meta({
+    description: "The datapoint to read joint positions from, or `null` to choose none. It must name a whole-message `sensor_msgs/msg/JointState` datapoint of the published configuration; anything else is a `validation_error` naming the rule."
+  })
+});
+var jointStatePutResponse = z9.object({
+  joint_state_slug: slug.nullable().meta({
+    description: "The stored mapping after the call, `null` when none is chosen. The same value `assetListResponse.joint_state_slug` carries."
+  })
+});
 var exposureCounts = z9.object({
   datapoints: z9.number().int().nonnegative(),
   actions: z9.number().int().nonnegative(),
@@ -2555,11 +2641,15 @@ var exposureCounts = z9.object({
   publishers: z9.number().int().nonnegative(),
   cameras: z9.number().int().nonnegative()
 });
+var protocolStatusValue = z9.enum(["current", "deprecated", "refused"]);
 var robotListItem = z9.object({
   ...robot.shape,
   bridge_state: bridgeState,
   /** Required, not optional: "we did not look" and "it exposes nothing" must not render the same. */
-  exposes: exposureCounts
+  exposes: exposureCounts,
+  protocol_status: protocolStatusValue.optional().meta({
+    description: "Where this robot's bridge stands against the protocol window: `current`, `deprecated` (still served, sunset date on the detail), or `refused` (its last hello was refused for its version; offline until upgraded). Absent from a cloud older than 0.21.0; read absence as `current`."
+  })
 });
 var robotListResponse = z9.object({
   robots: z9.array(robotListItem)
@@ -2576,6 +2666,15 @@ var datapointValue = z9.object({
 var robotDetailResponse = z9.object({
   ...robotListItem.shape,
   bridge_version: z9.string().min(1).nullable(),
+  protocol_version: z9.number().int().positive().nullable().optional().meta({
+    description: "The protocol version the bridge announced in its last accepted hello; `null` before the first. Absent from a cloud older than 0.21.0."
+  }),
+  protocol: z9.object({
+    status: protocolStatusValue.meta({ description: "Same values as `protocol_status`." }),
+    sunset_at: z9.iso.date().nullable().meta({
+      description: "ISO date the announced version stops being served; `null` when current or unknown."
+    })
+  }).optional().meta({ description: "The window verdict for `protocol_version`." }),
   /**
    * Cleared (set back to null) by the next successful hello from this
    * robot's bridge — a warning that outlives the condition it warns
@@ -2629,7 +2728,7 @@ var fetchTypesResponse = z9.object({
 var datapointDescriptor = z9.object({
   slug: slug.meta({ description: "The name a client reads this datapoint by." }),
   builtin: z9.boolean().meta({
-    description: "`true` for the datapoints every robot has \u2014 `bridge_state`, `robot_details` and `bridge_pressure` \u2014 and `false` for everything the published configuration adds."
+    description: "`true` for the datapoints every robot has \u2014 `bridge_state` and `robot_details` \u2014 and `false` for everything the published configuration adds."
   }),
   unit: z9.string().nullable().meta({
     description: "The unit the value carries **after** any scale and offset, shown beside the number so nobody has to guess whether `15` means percent, volts or minutes. `null` when the configuration names none."
@@ -2647,7 +2746,7 @@ var datapointDescriptor = z9.object({
 });
 var datapointListResponse = z9.object({
   datapoints: z9.array(datapointDescriptor).meta({
-    description: "Everything a client may read on this robot: the three built-ins, plus every datapoint the published configuration exposes and the caller's role grants."
+    description: "Everything a client may read on this robot: the two built-ins, plus every datapoint the published configuration exposes and the caller's role grants."
   })
 });
 var robotDetailsDoc = z9.record(z9.string().regex(/^[a-z][a-z0-9_-]{0,63}$/), z9.union([z9.string().max(4096), z9.number(), z9.boolean(), z9.array(z9.unknown()), z9.record(z9.string(), z9.unknown())]));
@@ -3001,22 +3100,25 @@ var robotDeletionSummary = z9.object({
   bytes_freed: z9.number().int().nonnegative(),
   cameras: z9.array(slug),
   /**
-   * Assets destroyed with the robot, and **`asset_bytes_freed` is what
-   * this org actually gets back** — not the sum of the assets' sizes.
+   * Assets destroyed with the robot, and **`asset_bytes_freed` is what the
+   * robot's own store gives back** — every distinct mesh or texture blob it
+   * holds, counted once, URDF excluded.
    *
-   * Storage is content-addressed, so a mesh two robots share survives the
-   * deletion of one of them and frees nothing. Reporting the total would tell
-   * a developer they are about to recover 400 MB and hand back 4, on the one
-   * screen whose entire justification is naming what an irreversible click
-   * destroys. Same reasoning that keeps `cameras` out of `slug_count`: this
-   * summary is read aloud to a human, and a number that is nearly right is
-   * worse here than an absent one.
+   * Storage is content-addressed, but the store and its 1 GB ceiling are now
+   * per robot: a blob another robot also references stays in the object
+   * store but is still credited here, because each robot's counter carries
+   * it regardless of what else points at the same bytes. Same reasoning that
+   * keeps `cameras` out of `slug_count`: this summary is read aloud to a
+   * human, and a number that is nearly right is worse here than an absent
+   * one.
    *
    * `asset_count` is the plain count of the robot's asset rows, all of which
    * do go away.
    */
   asset_count: z9.number().int().nonnegative(),
-  asset_bytes_freed: z9.number().int().nonnegative(),
+  asset_bytes_freed: z9.number().int().nonnegative().meta({
+    description: "What the robot's store gives back: every distinct mesh or texture blob it holds, counted once, URDF excluded; a blob another robot also references stays in the object store but is still credited here, because each robot's counter carries it."
+  }),
   /**
    * How many rows of run history go with the robot — every recorded
    * invocation of one of its actions or services, up to
@@ -3155,39 +3257,13 @@ var orgQuotas = z9.object({
   max_end_users: z9.number().int().positive(),
   max_retention_bytes: z9.number().int().nonnegative(),
   max_retention_writes_per_minute: z9.number().int().nonnegative(),
-  max_realtime_connections: z9.number().int().positive(),
-  /**
-   * Asset storage — **its own dial, not part of `max_retention_bytes`.** A
-   * sync grows storage in jumps and time series grow steadily; one dial would
-   * let the first crowd out the second, and the org that hit its limit would be
-   * told to look at the wrong thing.
-   *
-   * **Counted per distinct blob *this org references* — not per asset row, and
-   * not per object the platform stores on its behalf.** The two readings are
-   * indistinguishable from the number alone and a customer is entitled to know
-   * which one they are being charged for.
-   *
-   * Within an org, sharing is free: two robots referencing the same mesh cost
-   * one copy, which is what dedup means to a customer, and anything else
-   * charges an org twice for a fleet of identical robots — the normal case.
-   *
-   * **Across orgs, sharing is not free.** Storage stays globally
-   * content-addressed (one object per sha256; that efficiency is real), but
-   * accounting is per-org: an org is charged for each distinct blob it
-   * references and credited when its own last reference goes, whether or not
-   * the blob survives for somebody else. Global refcounting would make the
-   * first org to sync a blob pay for it forever while every later org stored it
-   * free — a quota evadable by anyone whose mesh someone else had already
-   * uploaded, and an org's own number would depend on who got there first.
-   */
-  max_asset_storage_bytes: z9.number().int().nonnegative()
+  max_realtime_connections: z9.number().int().positive()
 });
 var orgQuotaUsageCounts = z9.object({
   max_robots: z9.number().int().nonnegative(),
   max_apps: z9.number().int().nonnegative(),
   max_end_users: z9.number().int().nonnegative(),
   max_retention_bytes: z9.number().int().nonnegative(),
-  max_asset_storage_bytes: z9.number().int().nonnegative(),
   max_retention_writes_per_minute: z9.number().int().nonnegative(),
   max_realtime_connections: z9.number().int().nonnegative()
 }).partial();
@@ -3282,13 +3358,13 @@ var slugUsageResponse = z9.object({
   alert_count: z9.number().int().nonnegative()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/realtime.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/realtime.js
 import { z as z14 } from "zod";
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/client-auth.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/client-auth.js
 import { z as z13 } from "zod";
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/apps.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/apps.js
 import { z as z10 } from "zod";
 var appIdentifier = slug;
 var app = z10.object({
@@ -3470,10 +3546,10 @@ var rolePermissions = z10.object({
   })
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/app-users.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/app-users.js
 import { z as z12 } from "zod";
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/identity.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/identity.js
 import { z as z11 } from "zod";
 var password = z11.string().min(12).max(256);
 var USER_DISPLAY_NAME_MAX = 120;
@@ -3635,7 +3711,7 @@ var authMeResponse = z11.object({ org, user: fleetlessUser });
 var patchOrgRequest = z11.object({ name: z11.string().min(1).max(120) }).strict();
 var patchAuthMeRequest = z11.object({ display_name: z11.string().min(1).max(USER_DISPLAY_NAME_MAX).nullable() }).strict();
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/app-users.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/app-users.js
 var APP_USER_DISPLAY_NAME_MAX = 120;
 var providerSlug = z12.string().max(40).regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/, "must be lowercase and hyphen-separated, starting with a letter");
 var appUserStatus = z12.enum(["pending_verification", "active", "blocked"]);
@@ -3886,7 +3962,7 @@ var mailOutcome = z12.object({
   })
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/client-auth.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/client-auth.js
 var clientLoginRequest = z13.object({
   app_identifier: appIdentifier.meta({
     description: "The app being logged in to: its globally unique, lowercase, underscore-separated identifier, chosen by the developer at creation. There is no organisation context at login, so this is what decides which app the credentials are checked for."
@@ -4075,7 +4151,7 @@ var clientIdentity = z13.object({
   })
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/realtime.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/realtime.js
 var clientAuth = z14.object({
   type: z14.literal("auth"),
   token: z14.string().min(1)
@@ -4353,7 +4429,7 @@ var orgEventDropped = z14.object({
   dropped: z14.number().int().positive()
 }).strict();
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/client-robots.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/client-robots.js
 import { z as z15 } from "zod";
 var clientRobotListItem = z15.object({
   ...robot.shape,
@@ -4370,7 +4446,7 @@ var clientRobotListResponse = z15.object({
   })
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/audit.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/audit.js
 import { z as z16 } from "zod";
 var auditActor = z16.object({
   kind: z16.enum(["developer", "end_user", "app_user", "server_key", "bridge"]),
@@ -4500,7 +4576,7 @@ var auditListResponse = z16.object({
   next_cursor: z16.number().int().positive().nullable()
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/errors.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/errors.js
 import { z as z17 } from "zod";
 var apiError = z17.object({
   code: z17.string().min(1),
@@ -4517,7 +4593,7 @@ var parameterInvalidDetails = z17.object({
   violations: z17.array(parameterViolation).min(1)
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/oauth.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/oauth.js
 import { z as z18 } from "zod";
 var oauthErrorCode = z18.enum([
   "invalid_request",
@@ -4584,7 +4660,7 @@ var dynamicClientRegistrationRequest = z18.object({
     description: "`none`, RFC 7591's value for a public client, and the only value either server registers. Any other value is **refused rather than silently downgraded**: a client that believes it holds a secret and does not has a wrong mental model of its own security. There is no client secret to hold \u2014 mandatory PKCE (`S256`) is the defence."
   }),
   grant_types: z18.array(z18.enum(["authorization_code", "refresh_token"])).optional().meta({
-    description: "Accepted for conformance with RFC 7591 and then **ignored**. What comes back is what was actually granted, which \xA73.2.1 permits a server to substitute: `authorization_code` and nothing else, so a client that asks for `refresh_token` is registered and told plainly that it did not get one."
+    description: "Accepted for conformance with RFC 7591 and then **ignored**: both MCP authorization servers grant `authorization_code` and `refresh_token` to every registration, and the answer states what was granted (\xA73.2.1) rather than what was asked."
   }),
   response_types: z18.array(z18.enum(["code"])).optional().meta({
     description: "Accepted for conformance and then **ignored**; the response names `code`, which is the only response type OAuth 2.1 leaves, the implicit grant having been removed."
@@ -4606,7 +4682,7 @@ var dynamicClientRegistrationResponse = z18.object({
     description: "The redirect URIs this registration was accepted for. A code is returned to one of these and nowhere else."
   }),
   grant_types: z18.array(z18.string()).meta({
-    description: 'The grants this client may use. Always exactly `["authorization_code"]` \u2014 a client that asked for `refresh_token` is registered and told here that it did not get one, which is the substitution RFC 7591 \xA73.2.1 permits.'
+    description: 'The grants this client may use. Always exactly `["authorization_code", "refresh_token"]` \u2014 an exchange mints a refresh token and the token endpoint rotates it.'
   }),
   response_types: z18.array(z18.string()).meta({
     description: "The response types this client may ask for: `code`."
@@ -4621,9 +4697,9 @@ var dynamicClientRegistrationResponse = z18.object({
     description: "Always `0`, which is RFC 7591's way of saying the client secret never expires \u2014 there is none. The **registration** itself does expire: a self-registered client that never completes a flow is an unauthenticated write somebody left behind."
   })
 });
-var oauthTokenRequest = z18.object({
+var oauthCodeTokenRequest = z18.object({
   grant_type: z18.literal("authorization_code").meta({
-    description: "Always `authorization_code`: this request exchanges the code from the authorize redirect for tokens. Any other value \u2014 `refresh_token` included \u2014 is `unsupported_grant_type`, refused before the code is looked up."
+    description: "`authorization_code`: this request exchanges the code from the authorize redirect for an access token and a refresh token."
   }),
   code: z18.string().min(1).max(500).meta({
     description: "The authorization code from the redirect. It may be exchanged once; a second presentation is `invalid_grant`, the same answer a fabricated code gets."
@@ -4643,6 +4719,25 @@ var oauthTokenRequest = z18.object({
 }).meta({
   description: "RFC 6749 \xA74.1.3's authorization-code exchange with PKCE, as either MCP authorization server reads it. Sent as `application/x-www-form-urlencoded`, per \xA74.1.3, though the server accepts a JSON body too."
 });
+var oauthRefreshTokenRequest = z18.object({
+  grant_type: z18.literal("refresh_token").meta({
+    description: "`refresh_token`: this request rotates a refresh token into a new access token and a new refresh token. The presented token is consumed; presenting it again revokes the whole session."
+  }),
+  refresh_token: z18.string().min(1).max(500).meta({
+    description: "The refresh token from the last token response. Bound to the client that received it and to one identity space: presented by another client, or at the other MCP server, it is `invalid_grant` and stays unconsumed."
+  }),
+  client_id: z18.string().min(1).max(200).meta({
+    description: "The client the refresh token was issued to, as registered. A refresh token is not transferable between clients."
+  }),
+  resource: z18.url().optional().meta({
+    description: "The resource the new token is for, per RFC 8707. Optional; when named it must be the audience the session was issued for, or the answer is `invalid_target` and the refresh token is left untouched. The successor carries the same audience either way."
+  })
+}).meta({
+  description: "RFC 6749 \xA76's refresh, as either MCP authorization server reads it. Every use rotates: the answer carries a new refresh token and the presented one is dead."
+});
+var oauthTokenRequest = z18.discriminatedUnion("grant_type", [oauthCodeTokenRequest, oauthRefreshTokenRequest]).meta({
+  description: "What an MCP token endpoint accepts: the authorization-code exchange, or a refresh. Any other `grant_type` is `unsupported_grant_type`, refused before a lookup happens."
+});
 var oauthTokenResponse = z18.object({
   access_token: z18.string().min(1).meta({
     description: "The bearer token. It is the same token the client login mints \u2014 only the envelope differs, because an RFC-compliant client parses this one and knows nothing about Fleetless."
@@ -4654,7 +4749,7 @@ var oauthTokenResponse = z18.object({
     description: "How long the access token is valid, in **seconds**, per RFC 6749 \xA75.1. Not a timestamp, and not milliseconds."
   }),
   refresh_token: z18.string().min(1).optional().meta({
-    description: "The refresh token, when one was issued. It rotates on every use."
+    description: "The refresh token. Both MCP token endpoints issue one on every exchange and every refresh; it rotates on every use, lives ninety days from its last use, and dies with the account's sessions \u2014 a block, a password change, a withdrawn consent. The console's own OAuth portal issues none."
   }),
   scope: z18.string().max(500).optional().meta({
     description: "The scopes the issued token actually carries, space-separated."
@@ -4677,7 +4772,7 @@ var authorizationServerMetadata = z18.object({
     description: "The response types this server offers: `code` only, the implicit grant being gone with OAuth 2.1."
   }),
   grant_types_supported: z18.array(z18.enum(["authorization_code", "refresh_token"])).meta({
-    description: "The grants this server offers. OAuth 2.1 removes the implicit and password grants, so neither appears here."
+    description: "The grants this server offers: `authorization_code` and `refresh_token`. OAuth 2.1 removes the implicit and password grants, so neither appears here."
   }),
   code_challenge_methods_supported: z18.array(codeChallengeMethod).meta({
     description: "The PKCE challenge methods accepted: `S256` only. `plain` is not offered \u2014 a challenge equal to its verifier defends against nothing, and offering it would make a downgrade negotiable."
@@ -4738,7 +4833,7 @@ var oauthAuthorizeQuery = z18.object({
   description: "The authorization request an MCP client sends, per RFC 6749 \xA74.1.1 with mandatory PKCE. The handler reads it parameter by parameter rather than through one parse, because the answers differ: `client_id` and `redirect_uri` are refused flat, with no redirect, since until both are confirmed there is no trusted target to bounce a browser to, and everything after them is reported to the client's own callback as query parameters."
 });
 
-// node_modules/.pnpm/@fleetless+contracts@1.1.0/node_modules/@fleetless/contracts/dist/routes.js
+// node_modules/.pnpm/@fleetless+contracts@2.0.0/node_modules/@fleetless/contracts/dist/routes.js
 var MCP_APP = MCP_APP_PATHS(":appIdentifier");
 var APP_IDENTIFIER = {
   name: "appIdentifier",
@@ -6011,7 +6106,7 @@ var ROUTES = [
     response: dynamicClientRegistrationResponse,
     errors: ["rate_limited"],
     transport: "http",
-    notes: "RFC 7591. **The request schema is what this endpoint accepts, not what it parses**: the handler reads the body field by field, because \xA73.2.2 distinguishes `invalid_redirect_uri` from `invalid_client_metadata` and one `safeParse` failure cannot say which of the two a caller earned. The shape is deliberately **not** strict, which is the schema agreeing with \xA73.1 rather than a gap in it \u2014 a conforming client sends `client_uri`, `logo_uri` and `software_id`, and both the schema and the server ignore them. `client_name` and `redirect_uris` are the two fields read; `grant_types`, `response_types` and `scope` are accepted and ignored. What comes back is what was actually granted, which \xA73.2.1 allows a server to substitute \u2014 this authorization server issues `authorization_code` only, so a client that asked for `refresh_token` is registered and told plainly that it did not get one. The registration carries a TTL. Refusals are `oauthError`; the rate limiter answers `apiError`."
+    notes: "RFC 7591. **The request schema is what this endpoint accepts, not what it parses**: the handler reads the body field by field, because \xA73.2.2 distinguishes `invalid_redirect_uri` from `invalid_client_metadata` and one `safeParse` failure cannot say which of the two a caller earned. The shape is deliberately **not** strict, which is the schema agreeing with \xA73.1 rather than a gap in it \u2014 a conforming client sends `client_uri`, `logo_uri` and `software_id`, and both the schema and the server ignore them. `client_name` and `redirect_uris` are the two fields read; `grant_types`, `response_types` and `scope` are accepted and ignored. What comes back is what was actually granted, which \xA73.2.1 allows a server to substitute \u2014 this authorization server grants `authorization_code` and `refresh_token` to every registration. The registration carries a TTL. Refusals are `oauthError`; the rate limiter answers `apiError`."
   },
   {
     method: "GET",
@@ -6137,7 +6232,7 @@ var ROUTES = [
     response: oauthTokenResponse,
     errors: [],
     transport: "http",
-    notes: "Only `authorization_code` is supported \u2014 there is no refresh grant here, so a session ends when its token expires and the client signs in again. Refusals are RFC 6749 \xA75.2's `oauthError`, so this route emits none of the codes in this reference. The response carries no `refresh_token`; the shape is the same `oauthTokenResponse` the app flow answers, whose refresh field is optional. The code is single-use, PKCE-verified, and its `resource` must match the audience it was authorized for."
+    notes: "`authorization_code` mints an `mcp_session` access token bound to the central resource and a refresh token; `refresh_token` rotates that pair, and the presented refresh token is consumed \u2014 a second presentation revokes the session, as on `/api/auth/refresh`. The refresh token lives ninety days from its last use and is bound to the `client_id` it was issued to. A refresh re-reads the Fleetless user, so a removed account cannot refresh. Refusals are RFC 6749 \xA75.2's `oauthError`, so this route emits none of the codes in this reference. The code is single-use, PKCE-verified, and its `resource` must match the audience it was authorized for; a `resource` on a refresh must match the session's audience, and is checked before the token is consumed."
   },
   /* ------------------------------- developer auth (the console\'s OAuth portal) */
   {
@@ -6428,7 +6523,7 @@ var ROUTES = [
     response: dynamicClientRegistrationResponse,
     errors: ["rate_limited", "not_found"],
     transport: "http",
-    notes: "RFC 7591, the same wire and the same handler as `POST /mcp/oauth/register` \u2014 one implementation, because a second answer to \"is this redirect URI acceptable\" would agree with the first only by luck. The request schema is what the endpoint accepts rather than what it parses, for the reason that row gives: \xA73.2.2 needs two distinguishable refusals and one `safeParse` failure offers one. `client_name` and `redirect_uris` are read; `grant_types`, `response_types` and `scope` are accepted and ignored, and what comes back is what was actually granted, which \xA73.2.1 allows \u2014 `authorization_code` only, so a client that asked for `refresh_token` is registered and told plainly that it did not get one. The registration carries a TTL. \n\n**The registration is scoped to this app.** A `client_id` minted here authorizes at this app's endpoint and nowhere else, so a client registered against one app cannot walk into another's authorize with it, and a developer who switches MCP off is not left with strangers' registrations valid somewhere adjacent. \n\nRefusals are `oauthError`; the rate limiter and `404 not_found` answer `apiError`. That `404` covers an unknown identifier **and** an app with the switch off, mirroring the two metadata documents this endpoint is discovered from \u2014 a client that could not read those has no business registering here, and giving it a third distinct answer would only tell it something the documents deliberately do not."
+    notes: "RFC 7591, the same wire and the same handler as `POST /mcp/oauth/register` \u2014 one implementation, because a second answer to \"is this redirect URI acceptable\" would agree with the first only by luck. The request schema is what the endpoint accepts rather than what it parses, for the reason that row gives: \xA73.2.2 needs two distinguishable refusals and one `safeParse` failure offers one. `client_name` and `redirect_uris` are read; `grant_types`, `response_types` and `scope` are accepted and ignored, and what comes back is what was actually granted, which \xA73.2.1 allows \u2014 this authorization server grants `authorization_code` and `refresh_token` to every registration. The registration carries a TTL. \n\n**The registration is scoped to this app.** A `client_id` minted here authorizes at this app's endpoint and nowhere else, so a client registered against one app cannot walk into another's authorize with it, and a developer who switches MCP off is not left with strangers' registrations valid somewhere adjacent. \n\nRefusals are `oauthError`; the rate limiter and `404 not_found` answer `apiError`. That `404` covers an unknown identifier **and** an app with the switch off, mirroring the two metadata documents this endpoint is discovered from \u2014 a client that could not read those has no business registering here, and giving it a third distinct answer would only tell it something the documents deliberately do not."
   },
   {
     method: "GET",
@@ -6464,7 +6559,7 @@ var ROUTES = [
     response: oauthTokenResponse,
     errors: [],
     transport: "http",
-    notes: "Only `authorization_code`, PKCE-verified and single-use. There is no refresh grant here either, so a session ends when its token expires and the client signs in again; the shape is the same `oauthTokenResponse` the central endpoint answers, whose refresh field is optional and stays empty. **The `aud` is this app's endpoint URL on the canonical public base**, and the code's `resource` must match it \u2014 that is the whole of what stops a token minted for one app being spent at another's endpoint. \n\n**Every refusal is RFC 6749 \xA75.2's `oauthError`, so this route emits none of the codes in this reference \u2014 including the ones about the app.** An unknown identifier and a switched-off app are `invalid_client` here, not the `404` and `403` the authorize route beside it answers. The difference is who reads the answer: authorize is walked by a browser and its refusal is read by a person, while this endpoint is called by a client's own code in the middle of a flow, and handing that code an envelope its OAuth library cannot parse turns a clean refusal into an unexplained crash."
+    notes: "`authorization_code`, PKCE-verified and single-use, and `refresh_token`, which rotates the pair the exchange minted; the refresh token lives ninety days from its last use, is bound to its client and to this app, and a refresh re-reads the app user's status and their standing consent to the client, so a block or a withdrawn consent ends the session at its next refresh at the latest. **The `aud` is this app's endpoint URL on the canonical public base**, and the code's `resource` must match it \u2014 that is the whole of what stops a token minted for one app being spent at another's endpoint. \n\n**Every refusal is RFC 6749 \xA75.2's `oauthError`, so this route emits none of the codes in this reference \u2014 including the ones about the app.** An unknown identifier and a switched-off app are `invalid_client` here, not the `404` and `403` the authorize route beside it answers. The difference is who reads the answer: authorize is walked by a browser and its refusal is read by a person, while this endpoint is called by a client's own code in the middle of a flow, and handing that code an envelope its OAuth library cannot parse turns a clean refusal into an unexplained crash."
   },
   /* -------------------------------------------------- app-user (client) auth */
   {
@@ -6849,6 +6944,42 @@ var ROUTES = [
     transport: "http",
     notes: "`token` is the only moment the raw bridge token exists outside the caller's hands \u2014 the cloud stores a hash, so nothing can read it back and a caller who loses it rotates rather than recovers. Audited: this mints a credential that can speak for the org from anywhere, and the event carries no `details`, because the one interesting value here is the token. `max_robots` is checked before anything is created, which is only safe because robot deletion exists."
   },
+  {
+    method: "POST",
+    path: "/api/robots/:id/token/rotate",
+    section: "robots",
+    summary: "Mints a new bridge token for the robot and invalidates the old one.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: true,
+    status: 201,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: robotTokenRotateResponse,
+    errors: [...DEVELOPER_GUARD, "tier_required", "invalid_uuid", "not_found"],
+    transport: "http",
+    notes: "Owner tier, behind the org-scoped lookup, so a developer-tier admin sees the `404` a stranger would for a robot outside their org rather than a tier refusal that confirms the id exists. `token` is the only moment the new secret exists outside the caller's hands \u2014 the cloud stores a hash \u2014 so a caller who loses it rotates again. Audited as `robot.token_rotated`, with no `details`: the one interesting value here is the token. \n\n**It stops the bridge that is connected right now.** The old secret is gone the instant the hash is replaced, so the cloud closes that socket with `CLOSE_TOKEN_ROTATED` rather than leaving a bridge speaking on a credential nothing would accept again. A bridge that does not know the code reconnects and is refused at hello as `invalid_token`, which is the honest answer and ends the same way. **The robot is offline until somebody puts the new token on it** \u2014 this is a deliberate interruption, not a background rekey, and a fleet cannot be rotated without a visit to each robot."
+  },
+  {
+    method: "PUT",
+    path: "/api/robots/:id/urdf/joint-state",
+    section: "robots",
+    summary: "Chooses the datapoint whose joint positions move the robot's URDF, or clears it.",
+    audience: "developer",
+    auth: "developer",
+    rateLimited: false,
+    ownerTier: false,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: jointStatePutRequest,
+    response: jointStatePutResponse,
+    errors: [...DEVELOPER_GUARD, "invalid_uuid", "not_found", "validation_error"],
+    transport: "http",
+    notes: '**What qualifies**: a datapoint of the **published** configuration whose ROS type is `sensor_msgs/msg/JointState` and which carries no `field` \u2014 the whole message, because positions and names arrive together and a single extracted field is half of a pose. Anything else is a `validation_error` naming that rule rather than a stored mapping that renders a battery reading as a robot. `{ "slug": null }` clears it, which is why the field is required and nullable rather than optional. \n\n**The mapping cannot outlive what it points at.** Every successful publish re-checks it against the new document and clears it when it no longer qualifies, recording `robot.joint_state_cleared` with the version that did it; a slug rename rewrites it like every other reference the editor already rewrites; deleting the robot takes it along. Every write through this route \u2014 a slug or `null` \u2014 is on the record too, as `robot.joint_state_set` with the actor and the slug, so a clear a person made is never mistaken for one a publish made. The stored value reads back on `GET /api/robots/:id/assets` as `joint_state_slug`, so a renderer fetches the URDF, the meshes and the mapping from one place.'
+  },
   {
     method: "GET",
     path: "/api/robots",
@@ -7734,6 +7865,24 @@ var ROUTES = [
     transport: "http",
     notes: "Developer sessions only, like starting a sync: the guard admits three caller kinds and the handler answers `401 unauthorized` to the other two. A sync belonging to another robot reads exactly like one that never existed, which is why the robot is resolved first."
   },
+  {
+    method: "DELETE",
+    path: "/api/robots/:id/assets",
+    section: "assets",
+    summary: "Empties a robot's asset store: every URDF, mesh and texture, gone at once.",
+    audience: "client",
+    auth: "developer_or_client",
+    rateLimited: false,
+    ownerTier: true,
+    status: 200,
+    params: [{ name: "id", description: "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`." }],
+    query: null,
+    request: null,
+    response: assetsClearResponse,
+    errors: [...CLIENT_GUARD, "tier_required", "invalid_uuid", "not_found", "busy"],
+    transport: "http",
+    notes: "The store's escape hatch: a full store is never a dead end, and this is the blunt third of the three answers to it \u2014 the URDF upload is exempt from the gate, reconcile after a sync already frees what the new URDF stopped referencing, and this route lets an Owner clear the robot outright. Owner tier, unconditionally, like starting a sync. Removes every asset of the robot and resets its store to `0`; the next sync fills it again. It does not touch the bridge's availability report \u2014 `urdf_available` still answers from the connected robot, unrelated to what this cloud happens to have stored. A clear while a sync is running is `409 busy` naming that sync's details, the same refusal starting a second sync gets, because deleting under a running upload would leave the store counter wrong."
+  },
   /* ------------------------------------------------ org (quotas and fleet reads) */
   {
     method: "GET",
@@ -7858,9 +8007,9 @@ var ROUTES = [
     query: null,
     request: null,
     response: asset,
-    errors: ["unauthorized", "rate_limited", "asset_too_large", "validation_error", "not_found", "quota_exceeded", "bad_request"],
+    errors: ["unauthorized", "rate_limited", "validation_error", "not_found", "quota_exceeded", "bad_request"],
     transport: "http",
-    notes: "The body is the **raw file bytes**, not JSON, so it has no request schema; everything about the file \u2014 its kind, its name, its sync id and its announced size \u2014 rides in the `x-fleetless-asset-*` headers `ASSET_UPLOAD_HEADERS` names. The credential is a short-lived upload token minted by `POST /api/robots/:id/assets/sync`, verified in a `preParsing` hook so a refusal precedes the work rather than following it: a `preHandler` would already have buffered the whole file. The announced size is refused there too, before a single byte is read \u2014 it is an announcement and not a proof, so it only ever rejects early and never accepts early, and a body that lies small is still caught by the real length check. Past both, the server's own body limit answers a bare `413 bad_request` with neither ceiling nor size in it. Rate limited per robot inside that same hook, which is why `rateLimited` is `false`: there is no rate-limiting preHandler registered on this route."
+    notes: "The body is the **raw file bytes**, not JSON, so it has no request schema; everything about the file \u2014 its kind, its name, its sync id and its announced size \u2014 rides in the `x-fleetless-asset-*` headers `ASSET_UPLOAD_HEADERS` names. The credential is a short-lived upload token minted by `POST /api/robots/:id/assets/sync`, verified in a `preParsing` hook so a refusal precedes the work rather than following it: a `preHandler` would already have buffered the whole file. **Nothing is refused for its own size** \u2014 the robot's asset store is the only limit, so the announced size is checked there against `ROBOT_ASSET_STORE_BYTES` and a file with no room left answers `409 quota_exceeded` carrying `store_bytes`, `used_bytes` and `size_bytes`, while the sync carries on with the next file. Past that, the server's own body limit answers a bare `413 bad_request` with none of those numbers in it. Rate limited per robot inside that same hook, which is why `rateLimited` is `false`: there is no rate-limiting preHandler registered on this route. The URDF itself is never refused for the store; only meshes and textures are charged against it."
   },
   /* ------------------------------------ realtime and bridge transports */
   {
@@ -8135,13 +8284,16 @@ function oidcErrorFromCallbackParams(params) {
     `The federated sign-in ended without a session (${known.data}). See ClientOidcErrorCode in @fleetless/contracts for what each code means, and branch on error.code rather than on this message.`
   );
 }
-function serverKeyRefusal(method, needs) {
+function sessionlessRefusal(option, method, needs) {
   throw new FleetlessError(
     "invalid_option",
-    `auth.${method} is not available on a client constructed with a serverKey \u2014 ${needs}. Build a client with a tokenStore (an app user's own session) for this call.`
+    `auth.${method} is not available on a client constructed with ${option === "serverKey" ? "a serverKey" : "a credentials source"} \u2014 ${needs}. Build a client with a tokenStore (an app user's own session) for this call.`
   );
 }
-function createServerKeyAuth(http, appIdentifier2) {
+function createServerKeyAuth(http, appIdentifier2, option = "serverKey") {
+  const serverKeyRefusal = (method, needs) => sessionlessRefusal(option, method, needs);
+  const subject = option === "serverKey" ? "a server key" : "a supplied credential";
+  const holder = option === "serverKey" ? "a server-key client" : "a client with a supplied credential";
   return {
     // **`register`, `resendVerification` and `requestPasswordReset` are
     // allowed here** — see `createPublicAuthCalls`. They are public routes
@@ -8150,25 +8302,25 @@ function createServerKeyAuth(http, appIdentifier2) {
     // already has.
     ...createPublicAuthCalls(http, appIdentifier2),
     async verifyEmail() {
-      serverKeyRefusal("verifyEmail", "the route answers a session and a server-key client has nowhere to store it, so the session would be silently discarded");
+      serverKeyRefusal("verifyEmail", `the route answers a session and ${holder} has nowhere to store it, so the session would be silently discarded`);
     },
     async login() {
-      serverKeyRefusal("login", "a server key IS the credential; there is nothing to exchange");
+      serverKeyRefusal("login", `${subject} IS the credential; there is nothing to exchange`);
     },
     async logout() {
-      serverKeyRefusal("logout", "a server key holds no session to end");
+      serverKeyRefusal("logout", `${subject} holds no session to end`);
     },
     async me() {
       return http.request("/api/client/me", {});
     },
     async changePassword() {
-      serverKeyRefusal("changePassword", "a server key has no password; rotate the key in the console instead");
+      serverKeyRefusal("changePassword", `${subject} has no password${option === "serverKey" ? "; rotate the key in the console instead" : ""}`);
     },
     async confirmPasswordReset() {
-      serverKeyRefusal("confirmPasswordReset", "the route answers a session and a server-key client has nowhere to store it, so the session would be silently discarded");
+      serverKeyRefusal("confirmPasswordReset", `the route answers a session and ${holder} has nowhere to store it, so the session would be silently discarded`);
     },
     async acceptInvitation() {
-      serverKeyRefusal("acceptInvitation", "the route answers a session and a server-key client has nowhere to store it, so the session would be silently discarded");
+      serverKeyRefusal("acceptInvitation", `the route answers a session and ${holder} has nowhere to store it, so the session would be silently discarded`);
     },
     async listProviders() {
       const query = new URLSearchParams({ app_identifier: appIdentifier2 });
@@ -8188,16 +8340,16 @@ function createServerKeyAuth(http, appIdentifier2) {
       return http.request(`/api/client/mcp/interactions/${pathSegment(id)}`, {});
     },
     async approveMcpInteraction() {
-      serverKeyRefusal("approveMcpInteraction", "a consent is a person's decision, and a server key is not a person");
+      serverKeyRefusal("approveMcpInteraction", `a consent is a person's decision, and ${subject} is not a person`);
     },
     async denyMcpInteraction() {
-      serverKeyRefusal("denyMcpInteraction", "a consent is a person's decision, and a server key is not a person");
+      serverKeyRefusal("denyMcpInteraction", `a consent is a person's decision, and ${subject} is not a person`);
     },
     async listMcpGrants() {
-      serverKeyRefusal("listMcpGrants", "a server key never went through a consent screen, so it has no grants of its own");
+      serverKeyRefusal("listMcpGrants", `${subject} never went through a consent screen, so it has no grants of its own`);
     },
     async revokeMcpGrant() {
-      serverKeyRefusal("revokeMcpGrant", "a server key never went through a consent screen, so it has no grants of its own");
+      serverKeyRefusal("revokeMcpGrant", `${subject} never went through a consent screen, so it has no grants of its own`);
     }
   };
 }
@@ -8937,9 +9089,10 @@ var InMemoryTokenStore = class {
 
 // src/client.ts
 function createClient(options) {
-  if (options.serverKey !== void 0 && options.tokenStore !== void 0) {
+  const chosen = ["tokenStore", "serverKey", "credentials"].filter((name) => options[name] !== void 0);
+  if (chosen.length > 1) {
     throw new Error(
-      "createClient: pass either `tokenStore` (end-user login) or `serverKey` (a server-side caller), not both."
+      `createClient: pass exactly one of \`tokenStore\` (end-user login), \`serverKey\` (a server-side caller) or \`credentials\` (a bearer the caller owns) \u2014 got ${chosen.join(" and ")}.`
     );
   }
   const config = Object.freeze({
@@ -8955,7 +9108,11 @@ function createClient(options) {
   let auth;
   let http;
   let credentials;
-  if (options.serverKey !== void 0) {
+  if (options.credentials !== void 0) {
+    credentials = options.credentials;
+    http = new HttpClient({ baseUrl: config.apiUrl, fetch: fetchImpl, credentials });
+    auth = createServerKeyAuth(http, config.appIdentifier, "credentials");
+  } else if (options.serverKey !== void 0) {
     credentials = new ServerKeyCredentials(options.serverKey);
     http = new HttpClient({ baseUrl: config.apiUrl, fetch: fetchImpl, credentials });
     auth = createServerKeyAuth(http, config.appIdentifier);
@@ -8978,7 +9135,7 @@ function createClient(options) {
   const jobs = createJobsApi(http);
   const assets = createAssetsApi(http);
   const robots = createRobotsApi(http);
-  if (options.serverKey === void 0) {
+  if (options.serverKey === void 0 && options.credentials === void 0) {
     const baseLogout = auth.logout.bind(auth);
     auth = {
       ...auth,