@jxsuite/protocol 2.4.0 → 2.6.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Kevin Shenk
+Copyright (c) 2026 Avunu LLC and Jx Suite contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -17,7 +17,7 @@ A backend is free to change the transport and path prefix; the **sub-path, metho
 
 ## Core vs optional
 
-Optional routes back optional `StudioPlatform` members. Omitting one is not an error. Studio degrades exactly as each entry's `degradation` describes (the starter picker empties, the Projects catalogue hides, the Publish panel explains git-push publishing, and so on). `coreRouteNames()` / `optionalRouteNames()` split the table programmatically; a conformance test for a new backend can iterate `STUDIO_ROUTES` and assert every core route is served.
+Optional routes back optional `StudioPlatform` members, or, like `filesRead`, back no member and let an adapter serve one it already has more cheaply (their `degradation` names the route they stand in for). Omitting one is not an error. Studio degrades exactly as each entry's `degradation` describes (the starter picker empties, the Projects catalogue hides, the Publish panel explains git-push publishing, and so on). `coreRouteNames()` / `optionalRouteNames()` split the table programmatically; a conformance test for a new backend can iterate `STUDIO_ROUTES` and assert every core route is served.
 
 Highlights an implementer should know:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/protocol",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "The Studio Backend Protocol — wire types and the canonical route table every Jx Studio backend implements",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -1,7 +1,6 @@
 /**
- * The Studio Backend Protocol package: wire types plus the canonical route
- * table every Jx Studio backend implements. See README.md for the implementer
- * guide.
+ * The Studio Backend Protocol package: wire types plus the canonical route table every Jx Studio
+ * backend implements. See README.md for the implementer guide.
  *
  * @license MIT
  */
@@ -10,3 +9,5 @@ export * from "./problem";
 export * from "./problems";
 export * from "./routes";
 export type * from "./types";
+// The one runtime value types.ts carries: the batch-read limit a backend and a client both size to.
+export { READ_FILES_MAX_PATHS } from "./types";

package/src/problems.ts

@@ -6,7 +6,7 @@
  * declared once, exported as data, rendered into the docs by the same generator, and checked by the
  * same drift machinery.
  *
- * **What belongs here.** A type is a *class* of failure a client might handle differently — not a
+ * **What belongs here.** A type is a _class_ of failure a client might handle differently — not a
  * message. "The project root was refused" is a type; "root /x/y was refused" is a `detail`. If two
  * entries would only ever differ in their wording, they are one type.
  *
@@ -78,7 +78,18 @@ export const PROBLEM_TYPES = {
     403,
     "The path resolves outside the active project",
   ),
-
+  /*
+   * Refused for a reason the user can act on (desktop.md §10.4): a role, a policy, a plan, a quota.
+   * Its own type rather than a `forbidden` with a code, by the same test as
+   * `needsInstallationAccess`: the client does something different with it — it offers the
+   * `actions` the backend listed, under the backend's `heading`, and follows `retry` once one is
+   * done. Nothing here says WHY; that is the backend's, and so is every word the user reads.
+   */
+  actionRequired: problem("action-required", 403, "An action is required first", [
+    "actions",
+    "heading",
+    "retry",
+  ]),
   // ─── Backend state ────────────────────────────────────────────────────────
   noActiveProject: problem("no-active-project", 409, "No project is active on this backend"),
   capabilityUnavailable: problem(

package/src/routes.ts

@@ -1,10 +1,10 @@
 /**
- * Studio Backend Protocol — the canonical route table. The dev server
- * (@jxsuite/server) is the reference implementation; every other backend
- * (desktop RPC bridge, cloud platforms) serves the same shapes, either at
- * these literal paths or through an equivalent transport. Optional routes
- * back optional StudioPlatform members — Studio degrades without them, as
- * described by each entry's `degradation`.
+ * Studio Backend Protocol — the canonical route table. The dev server (@jxsuite/server) is the
+ * reference implementation; every other backend (desktop RPC bridge, cloud platforms) serves the
+ * same shapes, either at these literal paths or through an equivalent transport. Optional routes
+ * mostly back optional StudioPlatform members — Studio degrades without them, as described by each
+ * entry's `degradation`. A few back no member at all: an adapter uses them to serve members it
+ * already has more cheaply (`filesRead`), and their `degradation` is the route they stand in for.
  *
  * @license MIT
  */
@@ -28,7 +28,10 @@ export type StudioRouteMethod = "GET" | "POST" | "PUT" | "DELETE";
 export interface StudioRoute {
   path: string;
   method: StudioRouteMethod;
-  /** True when a backend may omit the route (its PAL member is optional). */
+  /**
+   * True when a backend may omit the route: its PAL member is optional, or it has no member and an
+   * adapter falls back to another route.
+   */
   optional: boolean;
   /** One-line contract summary. */
   summary: string;
@@ -107,10 +110,35 @@ export const STUDIO_ROUTES = {
   files: route(
     "GET",
     "/__studio/files",
-    "List a directory (DirEntry[]) in stable path order; with ?glob=<pattern>, search matching " +
-      "files project-wide",
+    "List a directory (DirEntry[]) in stable path order; an entry may carry an opaque content " +
+      "`version` the backend vouches for; with ?glob=<pattern>, search matching files project-wide",
   ),
   fileRead: route("GET", "/__studio/file", "Read a file's text content"),
+  /**
+   * Many reads in ONE round trip, for a backend whose every request is a network hop.
+   *
+   * The first optional route with no `StudioPlatform` member behind it: the PAL keeps `readFile`,
+   * and an adapter for such a backend coalesces the reads issued in one tick into this call itself
+   * (specs/desktop.md §3.1, §10.1). Callers never see it, so a backend without it costs latency and
+   * nothing else — which is why the dev server, whose reads are loopback, does not serve it.
+   *
+   * The answer is partial by design, never a 400: past `READ_FILES_MAX_PATHS` paths or the
+   * backend's byte budget, the rest come back in `omitted` for the client to ask again, and the
+   * first path is always answered so that asking again makes progress. Each answered path carries
+   * its own outcome, because one missing file is not a failed batch. It is a READ: a read-only
+   * session may call it, and whatever a single `fileRead` does on the backend's side (a cloud
+   * session fetches and stores the file it serves) this does per path too.
+   */
+  filesRead: route(
+    "POST",
+    "/__studio/files/read",
+    "Read many files' text content {paths} → ReadFilesResult {files: [path, {content} | " +
+      "{error: {status, code?, message}}][], omitted}. At most READ_FILES_MAX_PATHS (200) paths " +
+      "and a backend byte budget per call: the excess is listed in `omitted` (never a 400) and " +
+      "the first path is always answered. Per-path errors: 404 missing/deleted, 415 binary, 413 " +
+      "too large, 502 upstream. Allowed for read-only sessions; keeps fileRead's server-side effects",
+    "Adapters fall back to one fileRead per path.",
+  ),
   fileWrite: route("PUT", "/__studio/file", "Write a file's text content"),
   fileDelete: route("DELETE", "/__studio/file", "Delete a file"),
   fileUpload: route(
@@ -475,7 +503,10 @@ export function coreRouteNames(): StudioRouteName[] {
   );
 }
 
-/** Names of the optional routes (each backs an optional StudioPlatform member). */
+/**
+ * Names of the optional routes (each backs an optional StudioPlatform member, or is an adapter's
+ * optimisation with a fallback).
+ */
 export function optionalRouteNames(): StudioRouteName[] {
   return (Object.keys(STUDIO_ROUTES) as StudioRouteName[]).filter(
     (name) => STUDIO_ROUTES[name].optional,

package/src/types.ts

@@ -1,8 +1,7 @@
 /**
- * Studio Backend Protocol — wire types. Every shape a Studio backend serves
- * (or a `StudioPlatform` adapter consumes) lives here so client adapters and
- * server implementations (the dev server, the desktop RPC bridge, cloud
- * platforms) share one contract. Environment-agnostic: no DOM, no node —
+ * Studio Backend Protocol — wire types. Every shape a Studio backend serves (or a `StudioPlatform`
+ * adapter consumes) lives here so client adapters and server implementations (the dev server, the
+ * desktop RPC bridge, cloud platforms) share one contract. Environment-agnostic: no DOM, no node —
  * importable in browsers, Bun, and Cloudflare Workers alike.
  *
  * @license MIT
@@ -42,6 +41,13 @@ export interface DirEntry {
   type: "file" | "directory";
   size?: number;
   modified?: string;
+  /**
+   * An opaque version of the file's bytes: two equal versions mean identical bytes. ABSENT whenever
+   * the backend cannot vouch for the bytes — an uncommitted, dirty or just-uploaded file, and every
+   * directory. A client may append it to the file's URL (`?v=<version>`) so a host that recognizes
+   * it can answer with an immutable cache lifetime; a backend with no such notion never sets it.
+   */
+  version?: string;
 }
 
 /** A filesystem change pushed from the backend (project-relative, forward-slashed path). */
@@ -87,6 +93,45 @@ export interface UploadResult {
   size?: number;
 }
 
+/**
+ * The most paths one `filesRead` request may name. A backend answers at most this many and lists
+ * the rest under {@link ReadFilesResult.omitted}, so a client that sends more is not refused — it is
+ * answered in part, and asks again.
+ *
+ * The one runtime value in this file: a client sizes its batches to it, so it has to exist at
+ * runtime rather than only in a summary string.
+ */
+export const READ_FILES_MAX_PATHS = 200;
+
+/** Body of `POST /__studio/files/read` (`filesRead`): the project-relative paths to read. */
+export interface ReadFilesRequest {
+  paths: string[];
+}
+
+/**
+ * One path's answer inside a {@link ReadFilesResult}: its text, or why it has none.
+ *
+ * Per path rather than per request, because one unreadable file in a batch of two hundred is not a
+ * failed batch. `status` borrows the HTTP code the single-file read would have answered (404
+ * missing or deleted, 415 binary, 413 too large, 502 upstream), so a client can treat both routes'
+ * failures alike.
+ */
+export type ReadFilesOutcome =
+  | { content: string }
+  | { error: { status: number; code?: string; message: string } };
+
+/**
+ * Answer of `POST /__studio/files/read`. `files` pairs each answered path with its outcome;
+ * `omitted` lists the requested paths this response did not get to (a path or byte budget ran out).
+ * Omission is never an error and never a 400: the client asks for those paths again. A backend
+ * always answers the FIRST requested path, which is what guarantees that asking again makes
+ * progress.
+ */
+export interface ReadFilesResult {
+  files: [path: string, outcome: ReadFilesOutcome][];
+  omitted: string[];
+}
+
 /**
  * What a backend will accept as an upload, when it says.
  *
@@ -774,10 +819,47 @@ export interface AiModelsResponse {
    * true`: Cloudflare being briefly unreachable is not a reason to send someone round an OAuth flow
    * that fixes nothing. `cf_account_required` is a live grant with no account chosen (ai.md §2.1):
    * re-authorizing lands back in the same state, so it calls for the account picker instead.
+   *
+   * `action_required` is the fourth, and no connection fixes it: the backend requires something of
+   * the user before the assistant will run (desktop.md §10.4, ai.md §2.1). It arrives with
+   * {@link detail} and {@link actions}, the same members the `action-required` problem carries, so
+   * the gate can offer what the backend offers in the backend's own words.
    */
-  code?: "cf_not_connected" | "cf_reconnect_required" | "cf_account_required" | "cf_upstream_error";
+  code?:
+    | "cf_not_connected"
+    | "cf_reconnect_required"
+    | "cf_account_required"
+    | "cf_upstream_error"
+    | "action_required";
+  /** Why the backend refuses, in its own words. Sent with `action_required`. */
+  detail?: string;
+  /** What the user can do about it. Sent with `action_required`. */
+  actions?: OfferedAction[];
 }
 
+// ─── Backend-directed access (desktop.md §10.4) ──────────────────────────────
+
+/**
+ * Something the user can do, offered by the backend: on an `action-required` refusal, a notice, or
+ * an account row. The backend decides what it means; the platform adapter performs it.
+ */
+export interface OfferedAction {
+  /** Stable within the offer — for the backend's bookkeeping and a test's selector. */
+  id: string;
+  /** The button's words. */
+  label: string;
+  /** A page the platform opens for the user. Absent: the platform performs it by `id`. */
+  href?: string;
+  /** The one action a surface leads with. */
+  primary?: boolean;
+}
+
+/**
+ * What the client does once an offered action is done: `reload` the page (the refusal broke the
+ * session), `repeat` (the user runs what was refused again), or `none`.
+ */
+export type RetryHint = "reload" | "repeat" | "none";
+
 // ─── Cloudflare publish surface ──────────────────────────────────────────────
 
 /**