@jxsuite/protocol 2.5.0 → 2.6.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/protocol",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "The Studio Backend Protocol — wire types and the canonical route table every Jx Studio backend implements",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,6 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^2.3.0"
+    "@jxsuite/schema": "^3.0.0"
   }
 }

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

@@ -110,8 +110,8 @@ 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"),
   /**

package/src/types.ts

@@ -41,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). */
@@ -812,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 ──────────────────────────────────────────────
 
 /**