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

package/README.md

@@ -11,12 +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` and `FeedConnection` do it on their own, once; a page reading its own routes with its own `fetch` applies `isSignInRequired`. |
+| `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;
@@ -140,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

package/dist/client.js

@@ -50,7 +50,7 @@
  * 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 the client opens does the same.
+ * 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
@@ -59,6 +59,8 @@
 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";
 /**
@@ -171,6 +173,22 @@ export class TeraClient {
     feed(options) {
         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
      * answers the staged artifact, whose `handle` a Work Order's attachments

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, 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. 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" | "sign_in_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.
  *
@@ -283,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/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).
  *

package/dist/generated/workorder.d.ts

@@ -1004,6 +1004,9 @@ export type WorkOrderGetResult = {
                 at: string;
             };
             display_name?: string;
+            work_order?: string;
+            attempt?: number;
+            runner?: string;
         };
     };
     question?: {
@@ -1024,6 +1027,7 @@ export type WorkOrderGetResult = {
             member?: string;
             pool?: string;
             pool_cause?: string;
+            pool_note?: string;
             verb?: string;
             repairable: boolean;
             refused_at?: string;
@@ -1442,6 +1446,27 @@ export type WorkOrderGetResult = {
     created_at: string;
     updated_at: string;
     off_tera: boolean;
+    attended?: {
+        host?: string;
+        personal: boolean;
+        candidate?: string;
+        unsandboxed: boolean;
+        unsandboxed_notice?: string;
+        attendee: string;
+        attached: {
+            views: number;
+            controller?: string;
+            size_setter?: string;
+            since?: string;
+            last_detached_at?: string;
+        } | null;
+        signal: {
+            signal: string;
+            message?: string;
+            at: string;
+            dropped?: number;
+        } | null;
+    };
     has_outputs?: boolean;
     archived: boolean;
     history?: {
@@ -1771,6 +1796,8 @@ export type WorkOrderInterruptResult = {
  * Schema: sdk/workorder/schema/v1/list.params.json
  */
 export type WorkOrderListParams = {
+    /** Select only attended Work Orders — sessions a person attends in a terminal — and carry on each row the `attended` projection work_order.get answers (host, personal, candidate, unsandboxed, attendee, attached, signal), so a list of sessions needs no get per row. Absent or false is no constraint, and rows then carry no projection. Unindexed on both store backends; pair it with `states` or `parent_id`. */
+    attended?: boolean;
     /** Select the Work Orders in this cohort — the undertaking a Work Order belongs to, read off any row's `cohort_id` (a Work Order filed alone is a cohort of one, whose id is its own). A UUID; anything else is refused rather than matched. Unlike `tag` this reads an indexed column on both store backends, so it is the filter to pass alone for 'everything in this undertaking', in every state, terminal included. Composes with the other filters as an AND. */
     cohort?: string;
     /** Select Work Orders filed with exactly this resolved capacity key. Matched verbatim against the key on the row, which is already materialized against that Work Order's own inputs — pass `prefilter/<subject id>`, not the type's `${inputs...}` template. This is how a caller asks 'is another Work Order of this tier already working my subject?' without reading inputs back out of every row. */
@@ -1848,6 +1875,27 @@ export type WorkOrderListResult = {
                 at: string;
             };
         };
+        attended?: {
+            host?: string;
+            personal: boolean;
+            candidate?: string;
+            unsandboxed: boolean;
+            unsandboxed_notice?: string;
+            attendee: string;
+            attached: {
+                views: number;
+                controller?: string;
+                size_setter?: string;
+                since?: string;
+                last_detached_at?: string;
+            } | null;
+            signal: {
+                signal: string;
+                message?: string;
+                at: string;
+                dropped?: number;
+            } | null;
+        };
     }[] | null;
 };
 /**
@@ -3147,6 +3195,7 @@ export type WorkOrderTreeResult = {
                 member?: string;
                 pool?: string;
                 pool_cause?: string;
+                pool_note?: string;
                 verb?: string;
                 repairable: boolean;
                 refused_at?: string;
@@ -3377,6 +3426,7 @@ export type WorkOrderTreeResult = {
                 member?: string;
                 pool?: string;
                 pool_cause?: string;
+                pool_note?: string;
                 verb?: string;
                 repairable: boolean;
                 refused_at?: string;

package/dist/generated/wsstream.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The close vocabulary of a tera stream (sdk/wsstream.CloseCodes).
+ *
+ * The WebSocket close codes a tera stream is closed with. Each states only what the hop that closed decided, and a relay passes a close on as it arrived. The reason beside a code is a code of at most 64 bytes of [a-z0-9_.:-], or "closed". A code is never renamed or given a new meaning; a client that meets a code it does not know treats it as retry_later (4001).
+ *
+ * Schema: sdk/wsstream/schema/v1/close-code.json
+ */
+export type StreamCloseCode = 1000 | 1001 | 1009 | 4000 | 4001 | 4003;
+/**
+ * Each member of StreamCloseCode, by name.
+ *
+ * Schema: sdk/wsstream/schema/v1/close-code.json
+ */
+export declare const STREAM_CLOSE_CODES: {
+    /** What the client does: what the protocol above said last; otherwise nothing. */
+    readonly ended: 1000;
+    /** What the client does: reconnects after backoff: the peer is stopping or stopped answering pings. */
+    readonly going_away: 1001;
+    /** What the client does: nothing: a message broke the route's bound, a client defect. */
+    readonly too_big: 1009;
+    /** What the client does: reconnects at once with the same identity: a token renewal. */
+    readonly reconnect: 4000;
+    /** What the client does: reconnects after backoff: the far side is unreachable or not ready. */
+    readonly retry_later: 4001;
+    /** What the client does: nothing until something changes; the reason is the error code. */
+    readonly refused: 4003;
+};
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export declare const STREAM_SCHEMAS: {
+    readonly StreamCloseCode: "sdk/wsstream/schema/v1/close-code.json";
+};

package/dist/generated/wsstream.js

@@ -0,0 +1,28 @@
+// Code generated by cmd/internal/genwebtypes from sdk/wsstream/schema/v1/; DO NOT EDIT.
+// Regenerate with `make web-types` (ADR-162 D4 item 1).
+/**
+ * Each member of StreamCloseCode, by name.
+ *
+ * Schema: sdk/wsstream/schema/v1/close-code.json
+ */
+export const STREAM_CLOSE_CODES = {
+    /** What the client does: what the protocol above said last; otherwise nothing. */
+    ended: 1000,
+    /** What the client does: reconnects after backoff: the peer is stopping or stopped answering pings. */
+    going_away: 1001,
+    /** What the client does: nothing: a message broke the route's bound, a client defect. */
+    too_big: 1009,
+    /** What the client does: reconnects at once with the same identity: a token renewal. */
+    reconnect: 4000,
+    /** What the client does: reconnects after backoff: the far side is unreachable or not ready. */
+    retry_later: 4001,
+    /** What the client does: nothing until something changes; the reason is the error code. */
+    refused: 4003,
+};
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export const STREAM_SCHEMAS = {
+    StreamCloseCode: "sdk/wsstream/schema/v1/close-code.json",
+};

package/dist/index.d.ts

@@ -1,17 +1,23 @@
 export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.ts";
 export { phoneURL } from "./phone.ts";
 export { SIGN_IN_REQUIRED, isSignInRequired, isSignInRequiredAnswer, reSignIn, type ReSignInOptions } from "./signin.ts";
-export { TeraClient, KitRequestError, UNRECOGNIZED_RESPONSE, type FeedOptions, type InvokeVerdict, type KitErrorBody, type TeraClientOptions, type UploadOptions, type UploadProgress, type UploadRequest, type VerbRefusal, } from "./client.ts";
+export { PLUGIN_BUSY, PLUGIN_STARTING, PLUGIN_RUNNER_UNREACHABLE, PLUGIN_NOT_ANSWERING, PLUGIN_UNREACHED_CODES, } from "./unreached.ts";
+export { TeraClient, KitRequestError, UNRECOGNIZED_RESPONSE, type FeedOptions, type StreamOptions, type TerminalOptions, type InvokeVerdict, type KitErrorBody, type TeraClientOptions, type UploadOptions, type UploadProgress, type UploadRequest, type VerbRefusal, } from "./client.ts";
 export { STEP_UP_HEADER, STEP_UP_POLL_MS, STEP_UP_REQUIRED, STEP_UP_RESUME_PARAM, StepUpError, resumedStepUp, stepUpChallengeOf, stepUpPageURL, type StepUpChallenge, type StepUpEnd, type StepUpOptions, type StepUpWindow, } from "./stepup.ts";
 export { BASE_DELAY_MS, MAX_DELAY_MS, REPLAY_LIMIT, REPLAY_WINDOW_MS, HEARTBEAT_GRACE_MS, REAUTHENTICATE_EVENT, FeedConnection, browserSignals, defaultOrderKey, type Clock, type FeedConnectionOptions, type FeedConnectionPhase, type FeedConnectionState, type FeedFrame, type FeedLoss, type FeedSignal, type FeedSignals, } from "./feed/connection.ts";
+export { IMMEDIATE_LIMIT, IMMEDIATE_WINDOW_MS, MAX_BUFFERED_BYTES, SEND_BUFFER_EXCEEDED, STABLE_OPEN_MS, StreamConnection, webSocketURL, type NormalCloseNext, type StreamConnectionOptions, type StreamConnectionState, type WebSocketLike, } from "./stream/connection.ts";
+export { ACK_EVERY, INPUT_GRANT_TIMEOUT, INPUT_GRANT_TIMEOUT_MS, INPUT_WINDOW, MAX_QUEUED_INPUT, MAX_SIGNALS_PER_GRANT, RESIZE_DEBOUNCE_MS, TerminalView, newViewId, nextAfterClose, type TerminalRenderer, type TerminalStatus, type TerminalViewOptions, } from "./terminal/view.ts";
 export { FeedOpenError, SSEParser, fetchOpener, isRefusal, type FeedOpener, type SSEEvent } from "./feed/sse.ts";
+export * as terminalwire from "./terminalwire/codec.ts";
 export type * from "./generated/feed.ts";
 export type * from "./generated/kit.ts";
 export type * from "./generated/shares.ts";
 export type * from "./generated/workorder.ts";
 export type * from "./generated/workorder-events.ts";
+export type * from "./generated/wsstream.ts";
 export { FEED_SCHEMAS } from "./generated/feed.ts";
 export { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_PHONE_PATH, KIT_SCHEMAS, KIT_SIGNOUT_PATH } from "./generated/kit.ts";
 export { SHARES_SCHEMAS } from "./generated/shares.ts";
 export { WORK_ORDER_SCHEMAS } from "./generated/workorder.ts";
 export { WORK_ORDER_EVENT_SCHEMAS } from "./generated/workorder-events.ts";
+export { STREAM_CLOSE_CODES, STREAM_SCHEMAS } from "./generated/wsstream.ts";

package/dist/index.js

@@ -5,12 +5,20 @@
 export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.js";
 export { phoneURL } from "./phone.js";
 export { SIGN_IN_REQUIRED, isSignInRequired, isSignInRequiredAnswer, reSignIn } from "./signin.js";
+export { PLUGIN_BUSY, PLUGIN_STARTING, PLUGIN_RUNNER_UNREACHABLE, PLUGIN_NOT_ANSWERING, PLUGIN_UNREACHED_CODES, } from "./unreached.js";
 export { TeraClient, KitRequestError, UNRECOGNIZED_RESPONSE, } from "./client.js";
 export { STEP_UP_HEADER, STEP_UP_POLL_MS, STEP_UP_REQUIRED, STEP_UP_RESUME_PARAM, StepUpError, resumedStepUp, stepUpChallengeOf, stepUpPageURL, } from "./stepup.js";
 export { BASE_DELAY_MS, MAX_DELAY_MS, REPLAY_LIMIT, REPLAY_WINDOW_MS, HEARTBEAT_GRACE_MS, REAUTHENTICATE_EVENT, FeedConnection, browserSignals, defaultOrderKey, } from "./feed/connection.js";
+export { IMMEDIATE_LIMIT, IMMEDIATE_WINDOW_MS, MAX_BUFFERED_BYTES, SEND_BUFFER_EXCEEDED, STABLE_OPEN_MS, StreamConnection, webSocketURL, } from "./stream/connection.js";
+export { ACK_EVERY, INPUT_GRANT_TIMEOUT, INPUT_GRANT_TIMEOUT_MS, INPUT_WINDOW, MAX_QUEUED_INPUT, MAX_SIGNALS_PER_GRANT, RESIZE_DEBOUNCE_MS, TerminalView, newViewId, nextAfterClose, } from "./terminal/view.js";
 export { FeedOpenError, SSEParser, fetchOpener, isRefusal } from "./feed/sse.js";
+// The frames a view of an attended session's terminal speaks (ADR-180 D4):
+// github.com/kottera/sdk/terminalwire's codec in the browser, under one name,
+// so its frame and vocabulary names claim nothing at the package's root.
+export * as terminalwire from "./terminalwire/codec.js";
 export { FEED_SCHEMAS } from "./generated/feed.js";
 export { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_PHONE_PATH, KIT_SCHEMAS, KIT_SIGNOUT_PATH } from "./generated/kit.js";
 export { SHARES_SCHEMAS } from "./generated/shares.js";
 export { WORK_ORDER_SCHEMAS } from "./generated/workorder.js";
 export { WORK_ORDER_EVENT_SCHEMAS } from "./generated/workorder-events.js";
+export { STREAM_CLOSE_CODES, STREAM_SCHEMAS } from "./generated/wsstream.js";