@kottera/tera-web 0.1.0-rc.5 → 0.1.0-rc.7

package/README.md

@@ -11,11 +11,15 @@ author's — and has no runtime dependencies. It is not yet published.
 |------|---------------|
 | `src/index.ts` | The package's one entry point. Everything public is re-exported here. |
 | `src/routes.ts` | The route prefix, `routePath`, and the app's base (`appBase`, `underBase`) every route and the sign-out are reached under. |
-| `src/client.ts` | `TeraClient`, the typed client over D3's routes (D4 items 1, 3 and 4): `me()`, `invoke(capability, params)`, `feed(options)` (a `FeedConnection` read with the client's fetch), `upload(file, options)` with progress, and `signOut()`. A kit refusal throws `KitRequestError`; a verb's refusal answers as its verdict. |
+| `src/client.ts` | `TeraClient`, the typed client over D3's routes (D4 items 1, 3 and 4): `me()`, `invoke(capability, params)`, `feed(options)` (a `FeedConnection` read with the client's fetch), `stream(options)` (a `StreamConnection` probed with the client's fetch), `terminal(options)` (a `TerminalView` opened the same way), `upload(file, options)` with progress, and `signOut()`. A kit refusal throws `KitRequestError`; a verb's refusal answers as its verdict. |
 | `src/phone.ts` | `phoneURL(me, location, base?)`, the "Open on your phone" link (ADR-177 D4): `me().phone_path` resolved against the app's base (`/` by default, `/plugins/<name>/` on a path-based installation), with `next` set to `location.href`, fragment included. tera's proxy sends it on to tera's phone page, which draws the page's URL as a QR code, so the page needs no knowledge of tera's URL. A `phone_path` that is not relative to the base throws. |
+| `src/signin.ts` | Signing in again after tera forgets the page's session, as a daemon restart does: `isSignInRequired(response)` recognises the UI proxy's 401 `sign_in_required`, and `reSignIn()` loads the page again, which signs the person in with no prompt while their tera session lives. `TeraClient`, `FeedConnection` and `StreamConnection` do it on their own, once; a page reading its own routes with its own `fetch` applies `isSignInRequired`. |
+| `src/unreached.ts` | The codes tera's UI proxy answers the page's script with in the kit's envelope when the plugin did not answer: `PLUGIN_BUSY` and `PLUGIN_STARTING` (503, with `Retry-After`), `PLUGIN_RUNNER_UNREACHABLE` and `PLUGIN_NOT_ANSWERING` (502), all retryable, listed as `PLUGIN_UNREACHED_CODES`. |
 | `src/stepup.ts` | A person's step-up from the page's side (ADR-173 D11): the step-up header, the `return_to` the navigation fallback carries, and `StepUpError`. Every `TeraClient` request — `me()`, `invoke()`, `upload()` and `fetch(path)` to the plugin's own routes — has the person confirm a `step_up_required` and sends the request once more; `stepUp(id)` reads `GET /tera/v1/step-ups/{id}`. |
-| `src/generated/` | The contract, generated from the committed schemas under `sdk/plugin/webui/schema/`, `sdk/workorder/schema/`, `sdk/feed/schema/` and `sdk/shares/schema/` (D4 item 1; the share types, ADR-174 D14): one type per schema, the kit's route table as `KIT_ROUTE_TABLE`, and the maps from a route or a feed event to the type it carries. Never hand-edited, and never hand-write a type it declares: `make web-types` regenerates it, and `TestWebTypes_MatchCommitted` (`cmd/internal/genwebtypes`) fails on a hand edit or a stale generation. |
-| `src/feed/` | The stream connection (D4 item 2). |
+| `src/generated/` | The contract, generated from the committed schemas under `sdk/plugin/webui/schema/`, `sdk/workorder/schema/`, `sdk/feed/schema/`, `sdk/shares/schema/` and `sdk/wsstream/schema/` (D4 item 1; the share types, ADR-174 D14; the close codes, ADR-181 D15): one type per schema, the kit's route table as `KIT_ROUTE_TABLE`, a closed set of named constants as a map by name (`STREAM_CLOSE_CODES`), and the maps from a route or a feed event to the type it carries. Never hand-edited, and never hand-write a type it declares: `make web-types` regenerates it, and `TestWebTypes_MatchCommitted` (`cmd/internal/genwebtypes`) fails on a hand edit or a stale generation. |
+| `src/feed/` | The feed connection (D4 item 2). |
+| `src/stream/` | `StreamConnection`, one WebSocket to a kit stream route (ADR-181 D9, D11 item 1), reopened by the close code the far side chose: after backoff on `going_away`, `retry_later` and any code it does not know, at once on `reconnect` (three in 30 seconds, then backoff), never on `refused` or `too_big`, and on a normal closure as the protocol above said with `onNormalClose`. A failed handshake is settled by one probe of `GET /tera/v1/me`; more than 1 MiB unsent is a defect, closed and reconnected; `reconnect(reason)` gives up on a socket the protocol above finds dead; `close()` is the page's own end. |
+| `src/terminal/` | `TerminalView`, one view of an attended session's terminal (ADR-181 D11 item 2): `terminalwire` over a `StreamConnection` to the kit's terminal route, holding ADR-180's client duties itself — the resume offset in bytes handed to the renderer, an `ACK` only for bytes the renderer's `parsed` callback reported, at most 64 KiB of `INPUT` beyond `INPUT_ACK` (a paste queued in the view), a one-byte keystroke the window cannot hold sent as `SIGNAL` (P-R2), input dropped while history is drawn, `CONTROL {take}` before a viewer's first keystroke, `RESIZE` only while the view sets the size, and the step after each `CLOSE` reason. The renderer is named by its shape (`TerminalRenderer`, which xterm.js's `Terminal` meets), so xterm.js is the page's dependency, not the package's. Its tests drive it with a scripted socket and a recording renderer; no real browser runs here. |
 | `src/**/*.test.ts` | The suite, beside what it tests. |
 
 ## Tests

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 import { FeedConnection, type FeedConnectionOptions } from "./feed/connection.ts";
+import { StreamConnection, type StreamConnectionOptions } from "./stream/connection.ts";
+import { TerminalView, type TerminalViewOptions } from "./terminal/view.ts";
 import type { KitError, KitInvokeResponse, KitMeResponse, KitStepUpResponse, KitUploadResponse } from "./generated/kit.ts";
 import { type StepUpChallenge, type StepUpOptions } from "./stepup.ts";
 /** The body of a kit failure: the envelope's `error` member. */
@@ -107,6 +109,10 @@ export interface TeraClientOptions {
 }
 /** The options of {@link TeraClient.feed}: a {@link FeedConnection}'s, with the opener the client's own. */
 export type FeedOptions = Omit<FeedConnectionOptions, "open" | "base">;
+/** The options of {@link TeraClient.stream}: a {@link StreamConnection}'s, with the probe's fetch the client's own. */
+export type StreamOptions = Omit<StreamConnectionOptions, "fetch" | "base" | "reSignIn">;
+/** What {@link TeraClient.terminal} takes: a view's options but what the client supplies. */
+export type TerminalOptions = Omit<TerminalViewOptions, "fetch" | "base" | "reSignIn">;
 export declare class TeraClient {
     private readonly base;
     private readonly fetchFn;
@@ -118,6 +124,8 @@ export declare class TeraClient {
     private readonly pollMs;
     /** Whether the step-up the page was loaded back with has been taken up. */
     private resumeTaken;
+    /** Whether this client has loaded the page again to sign in. */
+    private signingIn;
     constructor(options?: TeraClientOptions);
     /** `GET /tera/v1/me`: who is signed in, and where to send them to sign out. */
     me(): Promise<KitMeResponse>;
@@ -138,6 +146,18 @@ export declare class TeraClient {
      * the page no longer wants it.
      */
     feed(options: FeedOptions): FeedConnection;
+    /**
+     * A {@link StreamConnection} to one of the kit's stream routes, its failed
+     * handshakes probed with this client's fetch. It opens at once: call
+     * `close()` on it when the page no longer wants it.
+     */
+    stream(options: StreamOptions): StreamConnection;
+    /**
+     * A {@link TerminalView} of an attended session's terminal at the kit's
+     * terminal route, its failed handshakes probed with this client's fetch. It
+     * opens at once: call `detach()` on it when the pane closes.
+     */
+    terminal(options: TerminalOptions): TerminalView;
     /**
      * `POST /tera/v1/uploads`: sends one file as the signed-in person and
      * answers the staged artifact, whose `handle` a Work Order's attachments
@@ -159,9 +179,20 @@ export declare class TeraClient {
      * person and the request sent once more with `Tera-Step-Up`; any other
      * answer, a success or a refusal, is returned as it arrived. A body sent
      * again must be one that can be: a string, a `Blob`, `FormData` or a
-     * buffer, never a stream.
+     * buffer, never a stream. A `sign_in_required` answer loads the page again
+     * ({@link TeraClient.reSignIn}) and is returned as it arrived.
      */
     fetch(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Loads the page again to sign the person in to the plugin's origin: a
+     * top-level navigation to the page's own URL, which tera's UI proxy answers
+     * with its silent sign-in. The client does it itself on a
+     * `sign_in_required` answer; a page calls it for one it read on its own.
+     * It navigates once per client: a second call does nothing.
+     */
+    reSignIn(): void;
+    /** Loads the page again when `request` rejects as `sign_in_required`, and rejects as it did. */
+    private signInOnRefusal;
     /**
      * Has the person confirm the step-up `challenge` names, and answers its id
      * once it is satisfied, to send the act again with. It opens the step-up's

package/dist/client.js

@@ -43,6 +43,15 @@
  * params. A step-up the person declines, lets expire or walks away from
  * rejects with a {@link StepUpError}, and the request is not sent again.
  *
+ * # Signing in again
+ *
+ * A request tera's UI proxy answers `sign_in_required` — the person's session
+ * on the plugin's origin is gone, as it is after a daemon restart — loads the
+ * page again ({@link TeraClient.reSignIn}), which signs the person in, and
+ * still rejects (or, from {@link TeraClient.fetch}, answers) as it arrived.
+ * The page is loaded again once per client, however many requests were
+ * refused together. A feed or stream the client opens does the same.
+ *
  * It is a plain class with an injected fetch, request factory, navigation,
  * window opener and timer, so its tests drive it against a fake and no
  * network.
@@ -50,6 +59,9 @@
 import { appBase, isBaseRelative, routePath, underBase } from "./routes.js";
 import { FeedConnection } from "./feed/connection.js";
 import { fetchOpener } from "./feed/sse.js";
+import { StreamConnection } from "./stream/connection.js";
+import { TerminalView } from "./terminal/view.js";
+import { SIGN_IN_REQUIRED, isSignInRequired } from "./signin.js";
 import { STEP_UP_HEADER, STEP_UP_POLL_MS, StepUpError, defaultOpenWindow, defaultSleep, resumedStepUp, stepUpChallengeOf, stepUpPageURL, } from "./stepup.js";
 /**
  * The `code` of a {@link KitRequestError} whose answer was not the kit's
@@ -102,6 +114,8 @@ export class TeraClient {
     pollMs;
     /** Whether the step-up the page was loaded back with has been taken up. */
     resumeTaken = false;
+    /** Whether this client has loaded the page again to sign in. */
+    signingIn = false;
     constructor(options = {}) {
         this.base = appBase(options.base);
         this.fetchFn = options.fetch ?? ((...args) => globalThis.fetch(...args));
@@ -157,7 +171,23 @@ export class TeraClient {
      * the page no longer wants it.
      */
     feed(options) {
-        return new FeedConnection({ ...options, base: this.base, open: fetchOpener(this.fetchFn) });
+        return new FeedConnection({ ...options, base: this.base, open: fetchOpener(this.fetchFn), reSignIn: () => this.reSignIn() });
+    }
+    /**
+     * A {@link StreamConnection} to one of the kit's stream routes, its failed
+     * handshakes probed with this client's fetch. It opens at once: call
+     * `close()` on it when the page no longer wants it.
+     */
+    stream(options) {
+        return new StreamConnection({ ...options, base: this.base, fetch: this.fetchFn, reSignIn: () => this.reSignIn() });
+    }
+    /**
+     * A {@link TerminalView} of an attended session's terminal at the kit's
+     * terminal route, its failed handshakes probed with this client's fetch. It
+     * opens at once: call `detach()` on it when the pane closes.
+     */
+    terminal(options) {
+        return new TerminalView({ ...options, base: this.base, fetch: this.fetchFn, reSignIn: () => this.reSignIn() });
     }
     /**
      * `POST /tera/v1/uploads`: sends one file as the signed-in person and
@@ -167,13 +197,13 @@ export class TeraClient {
      */
     async upload(file, options = {}) {
         try {
-            return await this.uploadOnce(file, options, null);
+            return await this.signInOnRefusal(this.uploadOnce(file, options, null));
         }
         catch (err) {
             const challenge = err instanceof KitRequestError ? stepUpChallengeOf(err.code, err.envelope?.step_up) : null;
             if (challenge === null)
                 throw err;
-            return this.uploadOnce(file, options, await this.confirmStepUp(challenge));
+            return this.signInOnRefusal(this.uploadOnce(file, options, await this.confirmStepUp(challenge)));
         }
     }
     uploadOnce(file, options, stepUpId) {
@@ -246,15 +276,47 @@ export class TeraClient {
      * person and the request sent once more with `Tera-Step-Up`; any other
      * answer, a success or a refusal, is returned as it arrived. A body sent
      * again must be one that can be: a string, a `Blob`, `FormData` or a
-     * buffer, never a stream.
+     * buffer, never a stream. A `sign_in_required` answer loads the page again
+     * ({@link TeraClient.reSignIn}) and is returned as it arrived.
      */
     async fetch(path, init = {}) {
         const url = underBase(this.base, path);
         const first = await this.fetchSameOrigin(url, init, null);
+        if (await isSignInRequired(first)) {
+            this.reSignIn();
+            return first;
+        }
         const challenge = await stepUpRefusalOf(first);
         if (challenge === null)
             return first;
-        return this.fetchSameOrigin(url, init, await this.confirmStepUp(challenge));
+        const second = await this.fetchSameOrigin(url, init, await this.confirmStepUp(challenge));
+        if (await isSignInRequired(second))
+            this.reSignIn();
+        return second;
+    }
+    /**
+     * Loads the page again to sign the person in to the plugin's origin: a
+     * top-level navigation to the page's own URL, which tera's UI proxy answers
+     * with its silent sign-in. The client does it itself on a
+     * `sign_in_required` answer; a page calls it for one it read on its own.
+     * It navigates once per client: a second call does nothing.
+     */
+    reSignIn() {
+        if (this.signingIn)
+            return;
+        this.signingIn = true;
+        this.navigate(this.pageURL());
+    }
+    /** Loads the page again when `request` rejects as `sign_in_required`, and rejects as it did. */
+    async signInOnRefusal(request) {
+        try {
+            return await request;
+        }
+        catch (err) {
+            if (err instanceof KitRequestError && err.status === 401 && err.code === SIGN_IN_REQUIRED)
+                this.reSignIn();
+            throw err;
+        }
     }
     /**
      * Has the person confirm the step-up `challenge` names, and answers its id
@@ -346,13 +408,13 @@ export class TeraClient {
     }
     async json(url, init, stepUp = true) {
         try {
-            return await this.jsonOnce(url, init, null);
+            return await this.signInOnRefusal(this.jsonOnce(url, init, null));
         }
         catch (err) {
             const challenge = stepUp && err instanceof KitRequestError ? stepUpChallengeOf(err.code, err.envelope?.step_up) : null;
             if (challenge === null)
                 throw err;
-            return this.jsonOnce(url, init, await this.confirmStepUp(challenge));
+            return this.signInOnRefusal(this.jsonOnce(url, init, await this.confirmStepUp(challenge)));
         }
     }
     async jsonOnce(url, init, stepUpId) {

package/dist/feed/connection.d.ts

@@ -99,6 +99,12 @@ export interface FeedConnectionOptions {
     orderKey?: (record: FeedFrameRecord) => number | undefined;
     /** Opens one stream; {@link fetchOpener} when absent. */
     open?: FeedOpener;
+    /**
+     * Loads the page again when tera's UI proxy refuses the stream
+     * `sign_in_required`, which signs the person in; {@link reSignIn} when
+     * absent. A {@link TeraClient}'s feed passes the client's own.
+     */
+    reSignIn?: () => void;
     clock?: Clock;
     /** {@link browserSignals} when absent. */
     signals?: FeedSignals;

package/dist/feed/connection.js

@@ -16,6 +16,7 @@
  * | a `reauthenticate` event (D7: the token expired)    | reconnect at once                  |
  * | a `credential_expired` status (D7, the same ending)  | reconnect at once                  |
  * | a status reporting loss                             | one replay, rationed (see Loss)    |
+ * | a 401 `sign_in_required` (tera forgot the session)  | STOP, and load the page again      |
  * | any other 4xx, a 501, or a success that is not an   | STOP: a refusal. A person has to   |
  * | event stream                                        | act ({@link FeedConnection.retry}) |
  *
@@ -65,6 +66,7 @@
  */
 import { routePath, underBase, ROOT_BASE } from "../routes.js";
 import { fetchOpener, isRefusal } from "./sse.js";
+import { isSignInRequiredAnswer, reSignIn } from "../signin.js";
 export const BASE_DELAY_MS = 1_000;
 export const MAX_DELAY_MS = 30_000;
 /** Replays allowed in {@link REPLAY_WINDOW_MS} before a loss is surfaced. */
@@ -233,6 +235,10 @@ export class FeedConnection {
                 this.generation += 1;
                 this.teardown();
                 this.set({ phase: "refused", refusal: err, lastError: err.message, delayMs: 0 });
+                // The person's session on the plugin's origin is gone; only a page
+                // load brings it back, and that ends this connection with the page.
+                if (isSignInRequiredAnswer(err.status, err.contentType, err.body))
+                    (this.options.reSignIn ?? reSignIn)();
                 return;
             }
             this.reopen(err instanceof Error ? err.message : String(err));

package/dist/generated/kit.d.ts

@@ -2,11 +2,11 @@ import type { FeedFrameRecord, FeedFrameStatus } from "./feed.ts";
 /**
  * The vocabulary of the kit's own error codes (sdk/plugin/webui.KitCodes).
  *
- * Every code the kit answers with when no verb gave a verdict. Only tera_unavailable is retryable. A failure envelope may also carry a verb's own code, or tera's own code for a call it refused, verbatim, which is not a member: a reader keeps a code it does not know as it arrived and branches on retryable.
+ * Every code the kit answers with when no verb gave a verdict, and sign_in_required, which tera's UI proxy answers in front of the kit when a request that is not a page load reaches the plugin's origin with no live session: load the page again to sign in; and the codes the proxy answers such a request with when it did not reach the plugin: plugin_busy (503, the plugin is at its runner link's stream cap, with Retry-After), plugin_starting (503, tera has not yet settled where the plugin runs, with Retry-After), plugin_runner_unreachable (502, the plugin's runner has no live link) and plugin_not_answering (502, the plugin's UI did not answer on its socket). Only tera_unavailable and those four are retryable. A failure envelope may also carry a verb's own code, or tera's own code for a call it refused, verbatim, which is not a member: a reader keeps a code it does not know as it arrived and branches on retryable.
  *
  * Schema: sdk/plugin/webui/schema/v1/error-code.json
  */
-export type KitErrorCode = "unauthenticated" | "cross_origin" | "route_not_found" | "method_not_allowed" | "route_not_served" | "invalid_request" | "exchange_refused" | "tera_unavailable" | "step_up_required";
+export type KitErrorCode = "unauthenticated" | "cross_origin" | "route_not_found" | "method_not_allowed" | "route_not_served" | "invalid_request" | "exchange_refused" | "tera_unavailable" | "step_up_required" | "sign_in_required" | "plugin_busy" | "plugin_starting" | "plugin_runner_unreachable" | "plugin_not_answering";
 /**
  * Kit error envelope.
  *
@@ -33,6 +33,7 @@ export type KitError = {
             url?: string;
             methods?: string[];
             expires_at?: string;
+            label?: string;
             state?: string;
         };
     };
@@ -282,6 +283,73 @@ export declare const KIT_ROUTE_TABLE: {
             readonly schema: "https://kottera.dev/schemas/plugin/webui/step-up.response/v1";
             readonly description: "The step-up's state.";
         };
+    }, {
+        readonly name: "terminal";
+        readonly method: "GET";
+        readonly path: "/tera/v1/workorders/{id}/terminal";
+        readonly summary: "Open one view of an attended session's terminal as the person (ADR-181 D8): a WebSocket the kit splices to tera's terminal door, opened with the person's token. Which Work Order it is, and whether the person may see it, is tera's to decide; the kit keeps no list of sessions. Every refusal after the upgrade is a close: a query of the wrong shape is refused invalid_request; tera's 401 is reconnect, reason reauthenticate, and a second within the minute refused; its 400, 403 and 404 are refused with tera's code (not_attendee, attend_view_not_granted, not_found); its 410 is refused, reason ended, a session with no process and none coming without the person's act; its 409 (not_running, a session whose process is coming), 408, 429 and 5xx, and no answer, are retry_later with tera's code or tera_unavailable. A text message is refused binary_only.";
+        readonly same_origin: true;
+        readonly path_params: readonly [{
+            readonly name: "id";
+            readonly description: "The attended Work Order's id.";
+            readonly required: true;
+        }];
+        readonly query: readonly [{
+            readonly name: "view";
+            readonly description: "The view's id: a canonical, lower-case UUIDv7 the page mints per pane and keeps across reconnects.";
+            readonly required: true;
+        }, {
+            readonly name: "want";
+            readonly description: "Whether the view asks to type (control) or only to watch (view).";
+            readonly required: true;
+            readonly values: readonly ["control", "view"];
+        }, {
+            readonly name: "resume";
+            readonly description: "The output offset the page has handed to its renderer so far, a decimal integer from 0 to 9007199254740991; absent on a fresh view, which replays.";
+        }, {
+            readonly name: "cols";
+            readonly description: "The view's width in cells, a decimal integer from 1 to 65535.";
+            readonly required: true;
+        }, {
+            readonly name: "rows";
+            readonly description: "The view's height in cells, a decimal integer from 1 to 65535.";
+            readonly required: true;
+        }];
+        readonly response: {
+            readonly media_type: "application/octet-stream";
+            readonly description: "A WebSocket upgrade (101), then messages both ways until either side closes, with the close vocabulary.";
+        };
+        readonly upgrade: "websocket";
+        readonly subprotocol: "tera.terminalwire.v1";
+        readonly messages: {
+            readonly media_type: "application/octet-stream";
+            readonly description: "One sdk/terminalwire frame per binary message, each way, at most 16388 bytes. The kit relays each as it arrived, reading no payload and redacting nothing.";
+        };
+    }];
+    readonly close_codes: readonly [{
+        readonly code: 1000;
+        readonly name: "ended";
+        readonly does: "what the protocol above said last; otherwise nothing";
+    }, {
+        readonly code: 1001;
+        readonly name: "going_away";
+        readonly does: "reconnects after backoff: the peer is stopping or stopped answering pings";
+    }, {
+        readonly code: 1009;
+        readonly name: "too_big";
+        readonly does: "nothing: a message broke the route's bound, a client defect";
+    }, {
+        readonly code: 4000;
+        readonly name: "reconnect";
+        readonly does: "reconnects at once with the same identity: a token renewal";
+    }, {
+        readonly code: 4001;
+        readonly name: "retry_later";
+        readonly does: "reconnects after backoff: the far side is unreachable or not ready";
+    }, {
+        readonly code: 4003;
+        readonly name: "refused";
+        readonly does: "nothing until something changes; the reason is the error code";
     }];
 };
 /** The name of a route in KIT_ROUTE_TABLE. */

package/dist/generated/kit.js

@@ -167,5 +167,91 @@ export const KIT_ROUTE_TABLE = {
                 description: "The step-up's state.",
             },
         },
+        {
+            name: "terminal",
+            method: "GET",
+            path: "/tera/v1/workorders/{id}/terminal",
+            summary: "Open one view of an attended session's terminal as the person (ADR-181 D8): a WebSocket the kit splices to tera's terminal door, opened with the person's token. Which Work Order it is, and whether the person may see it, is tera's to decide; the kit keeps no list of sessions. Every refusal after the upgrade is a close: a query of the wrong shape is refused invalid_request; tera's 401 is reconnect, reason reauthenticate, and a second within the minute refused; its 400, 403 and 404 are refused with tera's code (not_attendee, attend_view_not_granted, not_found); its 410 is refused, reason ended, a session with no process and none coming without the person's act; its 409 (not_running, a session whose process is coming), 408, 429 and 5xx, and no answer, are retry_later with tera's code or tera_unavailable. A text message is refused binary_only.",
+            same_origin: true,
+            path_params: [
+                {
+                    name: "id",
+                    description: "The attended Work Order's id.",
+                    required: true,
+                },
+            ],
+            query: [
+                {
+                    name: "view",
+                    description: "The view's id: a canonical, lower-case UUIDv7 the page mints per pane and keeps across reconnects.",
+                    required: true,
+                },
+                {
+                    name: "want",
+                    description: "Whether the view asks to type (control) or only to watch (view).",
+                    required: true,
+                    values: [
+                        "control",
+                        "view",
+                    ],
+                },
+                {
+                    name: "resume",
+                    description: "The output offset the page has handed to its renderer so far, a decimal integer from 0 to 9007199254740991; absent on a fresh view, which replays.",
+                },
+                {
+                    name: "cols",
+                    description: "The view's width in cells, a decimal integer from 1 to 65535.",
+                    required: true,
+                },
+                {
+                    name: "rows",
+                    description: "The view's height in cells, a decimal integer from 1 to 65535.",
+                    required: true,
+                },
+            ],
+            response: {
+                media_type: "application/octet-stream",
+                description: "A WebSocket upgrade (101), then messages both ways until either side closes, with the close vocabulary.",
+            },
+            upgrade: "websocket",
+            subprotocol: "tera.terminalwire.v1",
+            messages: {
+                media_type: "application/octet-stream",
+                description: "One sdk/terminalwire frame per binary message, each way, at most 16388 bytes. The kit relays each as it arrived, reading no payload and redacting nothing.",
+            },
+        },
+    ],
+    close_codes: [
+        {
+            code: 1000,
+            name: "ended",
+            does: "what the protocol above said last; otherwise nothing",
+        },
+        {
+            code: 1001,
+            name: "going_away",
+            does: "reconnects after backoff: the peer is stopping or stopped answering pings",
+        },
+        {
+            code: 1009,
+            name: "too_big",
+            does: "nothing: a message broke the route's bound, a client defect",
+        },
+        {
+            code: 4000,
+            name: "reconnect",
+            does: "reconnects at once with the same identity: a token renewal",
+        },
+        {
+            code: 4001,
+            name: "retry_later",
+            does: "reconnects after backoff: the far side is unreachable or not ready",
+        },
+        {
+            code: 4003,
+            name: "refused",
+            does: "nothing until something changes; the reason is the error code",
+        },
     ],
 };

package/dist/generated/shares.d.ts

@@ -124,7 +124,7 @@ export type SharesMakeRequest = {
  *
  * Schema: sdk/shares/schema/v1/refusal-code.json
  */
-export type SharesRefusalCode = "share_sharer_not_a_person" | "share_sharing_disabled" | "share_resource_not_shareable" | "share_resource_unknown" | "share_actor_other_installation" | "share_verb_not_shareable" | "share_verb_confers_sharing" | "share_verb_not_held" | "share_grantee_not_admitted" | "share_guest_cannot_invite" | "share_invitation_refused" | "share_grantee_is_sharer" | "share_expiry_beyond_max" | "share_cap_active" | "share_cap_pending_invitations" | "share_exists" | "share_caller_not_a_person" | "share_not_found" | "share_sharer_lost_access" | "share_expiry_not_later" | "share_admin_required" | "share_list_query" | "shares_unavailable";
+export type SharesRefusalCode = "share_sharer_not_a_person" | "share_sharing_disabled" | "share_resource_not_shareable" | "share_resource_unknown" | "share_actor_other_installation" | "share_verb_not_shareable" | "share_verb_confers_sharing" | "share_verb_not_held" | "share_grantee_not_admitted" | "share_guest_cannot_invite" | "share_invitation_refused" | "share_grantee_is_sharer" | "share_expiry_beyond_max" | "share_cap_active" | "share_cap_pending_invitations" | "share_exists" | "share_plugin_only" | "share_caller_not_a_person" | "share_not_found" | "share_sharer_lost_access" | "share_expiry_not_later" | "share_admin_required" | "share_list_query" | "shares_unavailable";
 /**
  * A share act refused.
  *
@@ -143,6 +143,8 @@ export type SharesRefusal = {
     existing?: string;
     /** On share_invitation_refused, why the address was not invited (inviter_limited, email_unavailable, ...). */
     invitation?: string;
+    /** On share_plugin_only, the installation's name: the plugin the share is made or extended through. */
+    plugin?: string;
 };
 /**
  * A share.

package/dist/generated/workorder-events.d.ts

@@ -5,7 +5,7 @@
  *
  * Schema: sdk/workorder/schema/events/v1/event-kind.workorder.json
  */
-export type WorkOrderEventKind = "cohort.set" | "off_tera.wake" | "relation.set" | "relation.removed" | "off_tera.taken" | "off_tera.progress" | "off_tera.reposted" | "off_tera.late_report" | "off_tera.checks_started" | "created" | "transitioned" | "acknowledged" | "retention_expired" | "edited" | "seat.reclaimed" | "claim.overdue" | "claim.unreadable" | "subject_claim.overridden" | "seat.cooling" | "seat.credential_held" | "member_credential.requested" | "member_credential.settled" | "seat.acquired" | "seat.runner_released" | "seat.meters_voided" | "step.binding" | "session.terminated" | "postcondition.verdict" | "parked_run.unreadable" | "parked_run.reclaimed" | "dispatch.settled_unobserved" | "parked_run.parked" | "parked_run.resumed" | "resume.refused" | "dispatch.salvaged" | "workspace.retired" | "dispatch.routed" | "session.lost" | "activity_partition.pinned" | "session.continuity" | "session.context_compacted" | "upstream.answer_forwarded" | "invocation.checkpoint" | "invocation.guidance" | "invocation.guidance.ack" | "invocation.reply" | "invocation.checkpoint.unreadable" | "invocation.guidance.unreadable" | "config_pin.unreadable" | "config_pin.repinned" | "type.followed" | "observation.scrubbed" | "observation.secret-shape-redacted" | "observation.promoted" | "observation.refuted" | "observation.purged" | "conversation.input_barrier" | "walk_resume.fell_back" | "store.ahead_of_binary" | "artifact.published" | "history.dropped" | "history.archived" | "seat.work_order_released" | "step.settled_late" | "step.reattached" | "relay.unrebuilt" | "references.recorded";
+export type WorkOrderEventKind = "cohort.set" | "off_tera.wake" | "relation.set" | "relation.removed" | "off_tera.taken" | "off_tera.progress" | "off_tera.reposted" | "off_tera.late_report" | "off_tera.checks_started" | "created" | "transitioned" | "acknowledged" | "retention_expired" | "edited" | "seat.reclaimed" | "claim.overdue" | "claim.unreadable" | "subject_claim.overridden" | "seat.cooling" | "seat.credential_held" | "member_credential.requested" | "member_credential.settled" | "seat.acquired" | "seat.runner_released" | "seat.meters_voided" | "step.binding" | "session.terminated" | "postcondition.verdict" | "parked_run.unreadable" | "parked_run.reclaimed" | "dispatch.settled_unobserved" | "parked_run.parked" | "parked_run.resumed" | "resume.refused" | "dispatch.salvaged" | "workspace.retired" | "dispatch.routed" | "session.lost" | "activity_partition.pinned" | "session.continuity" | "session.context_compacted" | "upstream.answer_forwarded" | "invocation.checkpoint" | "invocation.guidance" | "invocation.guidance.ack" | "invocation.reply" | "invocation.checkpoint.unreadable" | "invocation.guidance.unreadable" | "config_pin.unreadable" | "config_pin.repinned" | "type.followed" | "observation.scrubbed" | "observation.secret-shape-redacted" | "observation.promoted" | "observation.refuted" | "observation.purged" | "conversation.input_barrier" | "walk_resume.fell_back" | "store.ahead_of_binary" | "artifact.published" | "history.dropped" | "history.archived" | "seat.work_order_released" | "step.settled_late" | "step.reattached" | "relay.unrebuilt" | "references.recorded" | "attended.wall_reported" | "attended.signal";
 /**
  * `workorder` event payload (event/workorder).
  *