oui-spec 0.6.1 → 0.7.0

package/dist/spec/index.d.ts

@@ -1,5 +1,5 @@
-import { m as OUISurface } from '../types-CmJb1BQ8.js';
-export { A as ARGS_HASH_PATTERN, J as JSONSchema, O as OUIAction, a as OUIActionApproval, b as OUIActionPolling, c as OUIActionRequest, d as OUIActionResult, e as OUIActivation, f as OUIApprovalGrant, g as OUIEffectKind, h as OUIObservation, i as OUIObservationSnapshot, j as OUIObservationUpdate, k as OUIProtocolEvent, l as OUIResultDelivery, n as OUISurfaceDeregistration, o as OUISurfaceRegistration, p as OUISurfaceSnapshot, q as OUI_EFFECT_ACCESS, r as OUI_EFFECT_KINDS, s as OUI_PROTOCOL_EVENTS, t as argsHash, u as canonicalJson, v as effectAccess, w as requiresApproval } from '../types-CmJb1BQ8.js';
+import { r as OUISurface, t as OUISurfaceIndex, J as JSONSchema, O as OUIAction, b as OUIActionIndexEntry, n as OUIObservationSnapshot, k as OUIFitCut } from '../types-CnlVRPFL.js';
+export { A as ARGS_HASH_PATTERN, a as OUIActionApproval, c as OUIActionPolling, d as OUIActionRequest, e as OUIActionResult, f as OUIActivation, g as OUIApprovalGrant, h as OUIClientSnapshot, i as OUIEffectKind, j as OUIFit, l as OUIIndexSnapshot, m as OUIObservation, o as OUIObservationUpdate, p as OUIProtocolEvent, q as OUIResultDelivery, s as OUISurfaceDeregistration, u as OUISurfaceRegistration, v as OUISurfaceSnapshot, w as OUI_EFFECT_ACCESS, x as OUI_EFFECT_KINDS, y as OUI_PROTOCOL_EVENTS, z as argsHash, B as canonicalJson, C as effectAccess, D as requiresApproval } from '../types-CnlVRPFL.js';
 
 /**
  * The identity of a set of surfaces, for an answer that need not repeat them
@@ -22,6 +22,78 @@ export { A as ARGS_HASH_PATTERN, J as JSONSchema, O as OUIAction, a as OUIAction
  */
 
 /** `surfaces`' hash, as a result's `surfacesHash` and a request's `knownSurfaces` carry it. */
-declare function surfacesHash(surfaces: readonly OUISurface[]): string;
+declare function surfacesHash(surfaces: readonly OUISurface[] | readonly OUISurfaceIndex[]): string;
+/**
+ * JSON with every object's keys sorted, and what JSON cannot carry dropped as
+ * JSON.stringify drops it. Not approval.ts's `canonicalJson`, which refuses
+ * such values on purpose (an approval must hash exactly what crosses the
+ * wire): a snapshot is taken on every answer, and must never throw on a
+ * manifest that carries, say, an `undefined` in an array.
+ */
+declare function sortedJson(value: unknown): string;
+
+/** The longest description an index entry carries. */
+declare const INDEX_DESCRIPTION_CHARS = 160;
+/** The longest input line an index entry carries. */
+declare const INDEX_INPUT_CHARS = 120;
+/** How many of an input's properties its line names before "+N more". */
+declare const INDEX_INPUT_PROPERTIES = 6;
+/** The surface id the runtime itself answers (§7.3.10). No surface may be defined with it. */
+declare const OUI_RUNTIME_SURFACE = "oui";
+/** `oui.describe`: the full definitions of the actions asked for. */
+declare const OUI_DESCRIBE_ACTION = "describe";
+/** `oui.read`: part of an observation's value, by path, a page of a list at a time. */
+declare const OUI_READ_ACTION = "read";
+/** The bytes `text` takes as UTF-8, which is what a frame's size limit counts. */
+declare function utf8Length(text: string): number;
+/** The bytes `value` takes as JSON on the wire; 0 for what JSON drops. */
+declare function jsonBytes(value: unknown): number;
+/** A description's first sentence, on one line, at most `INDEX_DESCRIPTION_CHARS` characters. */
+declare function firstSentence(text: string): string;
+/**
+ * The property every member of a union fixes to its own constant, which is
+ * what tells the members apart: `effect` in `{ effect: "glow", … } | { effect:
+ * "blur", … }`. Null when the members share no such property.
+ */
+declare function discriminatorOf(members: readonly JSONSchema[]): string | null;
+/** The one value a schema allows, when it allows one. */
+declare function constantOf(schema: JSONSchema | undefined): string | number | boolean | undefined;
+/**
+ * What an action takes, in one line of at most `INDEX_INPUT_CHARS` characters:
+ * - "none" for an action that takes nothing;
+ * - each property with its type, required ones first, optional ones marked
+ *   "?", the first `INDEX_INPUT_PROPERTIES` of them, then "+N more";
+ * - "one of N shapes by <property>" for a union.
+ */
+declare function summarizeInput(schema: JSONSchema | undefined): string;
+/** The hash of an action's definition, as an index entry's `definitionHash` carries it. */
+declare function definitionHash(action: OUIAction): string;
+/** An action's index entry (§7.3.8). */
+declare function indexEntry(action: OUIAction): OUIActionIndexEntry;
+/** A surface in index form (§7.3.8). */
+declare function surfaceIndex(surface: OUISurface): OUISurfaceIndex;
+
+/** Rows a list keeps at each step of fitting, until the whole fits. */
+declare const FIT_LIST_STEPS: readonly [200, 50, 20, 5, 0];
+/** Characters a text keeps once lists alone did not make the whole fit. */
+declare const FIT_TEXT_CHARS = 2000;
+/** One step into a JSON Pointer (RFC 6901). */
+declare function pointerStep(pointer: string, key: string | number): string;
+/** The steps of a JSON Pointer; "" is no steps. Throws on a pointer that does not start with "/". */
+declare function pointerSteps(pointer: string): string[];
+/** The value a pointer names inside `value`, or `undefined` when nothing is there. */
+declare function atPointer(value: unknown, pointer: string): unknown;
+/**
+ * `observations` within `budget` bytes of JSON, and where they were cut.
+ * Returned as they are when they already fit; otherwise a copy is shortened:
+ * 1. every list longer than a step of `FIT_LIST_STEPS` is cut to it, a step at
+ *    a time, until the whole fits;
+ * 2. then every text longer than `FIT_TEXT_CHARS` is cut to that;
+ * 3. then whole observation values are left out, the largest first.
+ */
+declare function fitObservations(observations: OUIObservationSnapshot, budget: number): {
+    observations: OUIObservationSnapshot;
+    cuts: OUIFitCut[];
+};
 
-export { OUISurface, surfacesHash };
+export { FIT_LIST_STEPS, FIT_TEXT_CHARS, INDEX_DESCRIPTION_CHARS, INDEX_INPUT_CHARS, INDEX_INPUT_PROPERTIES, JSONSchema, OUIAction, OUIActionIndexEntry, OUIFitCut, OUIObservationSnapshot, OUISurface, OUISurfaceIndex, OUI_DESCRIBE_ACTION, OUI_READ_ACTION, OUI_RUNTIME_SURFACE, atPointer, constantOf, definitionHash, discriminatorOf, firstSentence, fitObservations, indexEntry, jsonBytes, pointerStep, pointerSteps, sortedJson, summarizeInput, surfaceIndex, surfacesHash, utf8Length };

package/dist/spec/index.js

@@ -1,3 +1,3 @@
-export { ARGS_HASH_PATTERN, OUI_EFFECT_ACCESS, OUI_EFFECT_KINDS, OUI_PROTOCOL_EVENTS, argsHash, canonicalJson, effectAccess, requiresApproval, surfacesHash } from '../chunk-B2EFZMGY.js';
+export { ARGS_HASH_PATTERN, FIT_LIST_STEPS, FIT_TEXT_CHARS, INDEX_DESCRIPTION_CHARS, INDEX_INPUT_CHARS, INDEX_INPUT_PROPERTIES, OUI_DESCRIBE_ACTION, OUI_EFFECT_ACCESS, OUI_EFFECT_KINDS, OUI_PROTOCOL_EVENTS, OUI_READ_ACTION, OUI_RUNTIME_SURFACE, argsHash, atPointer, canonicalJson, constantOf, definitionHash, discriminatorOf, effectAccess, firstSentence, fitObservations, indexEntry, jsonBytes, pointerStep, pointerSteps, requiresApproval, sortedJson, summarizeInput, surfaceIndex, surfacesHash, utf8Length } from '../chunk-RZUYWZFK.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{surface-runtime-D5nINY4b.d.ts → surface-runtime-BPEtT3LZ.d.ts}

@@ -1,5 +1,5 @@
-import { g as OUIEffectKind, J as JSONSchema, b as OUIActionPolling, e as OUIActivation, m as OUISurface, p as OUISurfaceSnapshot, c as OUIActionRequest, d as OUIActionResult, f as OUIApprovalGrant } from './types-CmJb1BQ8.js';
-import { S as SocketLike, e as OUITransportConfig } from './websocket-Ce3tDSsJ.js';
+import { i as OUIEffectKind, J as JSONSchema, c as OUIActionPolling, f as OUIActivation, r as OUISurface, l as OUIIndexSnapshot, v as OUISurfaceSnapshot, d as OUIActionRequest, e as OUIActionResult, g as OUIApprovalGrant } from './types-CnlVRPFL.js';
+import { S as SocketLike, e as OUITransportConfig } from './websocket-DKL9qoO-.js';
 
 /**
  * Nominal branding for values OUI must construct itself.
@@ -214,6 +214,23 @@ interface SurfaceRuntimeOptions {
      * not checked; they come from the application itself.
      */
     accept?: (request: OUIActionRequest) => boolean;
+    /**
+     * What a snapshot and an answer say of the mounted surfaces (§7.3.8):
+     * - `"index"`: each action as an index entry. The agent runtime fetches a
+     *   definition when it needs one (`oui.describe`). Use it with an agent
+     *   runtime that reads the index form.
+     * - `"full"` (the default until 1.0): each action's whole definition, as
+     *   every earlier version sent. A page's definitions can outweigh what a
+     *   frame may carry; then its answers are refused and arrive trimmed.
+     */
+    form?: "index" | "full";
+    /** The most bytes of JSON a frame carries; what does not fit is shortened and said so (§7.3.9). */
+    budgets?: {
+        /** One answer. Default 480 KB: under the 512 KB a relay commonly caps a frame at. */
+        answerBytes?: number;
+        /** One snapshot, as sent with a turn. Default 256 KB. */
+        snapshotBytes?: number;
+    };
     /**
      * A request sent again while its answer is on the way is not answered again
      * (§7.3.7): every copy of a large answer queues on the one socket, ahead of
@@ -230,7 +247,9 @@ interface MountedSurface {
     /** Remove this mount. Other mounts of the same surface id are unaffected. */
     unmount(): void;
 }
-interface SurfaceRuntime {
+/** The form a runtime sends its surfaces in (§7.3.8). */
+type SurfaceForm = "full" | "index";
+interface SurfaceRuntime<F extends SurfaceForm = "full"> {
     /**
      * Mount a surface. `getContext` is read when an action runs, so handlers see
      * the latest state rather than the state at mount time.
@@ -242,7 +261,7 @@ interface SurfaceRuntime {
     /** Answer requests arriving on this socket (null detaches). */
     attach(socket: SocketLike | null): void;
     /** What the client can do right now. */
-    snapshot(): OUISurfaceSnapshot;
+    snapshot(): F extends "index" ? OUIIndexSnapshot : OUISurfaceSnapshot;
     /**
      * Run a request once and resolve with its result. A request id seen before
      * resolves with the first result instead of running again.
@@ -267,6 +286,11 @@ interface SurfaceRuntime {
     /** Stop polling, detach from the socket and forget every mount. */
     dispose(): void;
 }
-declare function createSurfaceRuntime(options?: SurfaceRuntimeOptions): SurfaceRuntime;
+declare function createSurfaceRuntime(options: SurfaceRuntimeOptions & {
+    form: "index";
+}): SurfaceRuntime<"index">;
+declare function createSurfaceRuntime(options?: SurfaceRuntimeOptions & {
+    form?: "full";
+}): SurfaceRuntime<"full">;
 
-export { type ActionDefinition as A, type DefinedSurface as D, type MountedSurface as M, type OUIBranded as O, type SettleOptions as S, type ActionHandlerResult as a, type ActionPollingConfig as b, type ObservationDefinition as c, type SurfaceDefinition as d, type SurfaceRuntime as e, type SurfaceRuntimeOptions as f, createSurfaceRuntime as g, defineSurface as h };
+export { type ActionDefinition as A, type DefinedSurface as D, type MountedSurface as M, type OUIBranded as O, type SettleOptions as S, type ActionHandlerResult as a, type ActionPollingConfig as b, type ObservationDefinition as c, type SurfaceDefinition as d, type SurfaceForm as e, type SurfaceRuntime as f, type SurfaceRuntimeOptions as g, createSurfaceRuntime as h, defineSurface as i };

package/dist/{surface-runtime-CSZ9UtBO.d.cts → surface-runtime-CexHqUn-.d.cts}

@@ -1,5 +1,5 @@
-import { g as OUIEffectKind, J as JSONSchema, b as OUIActionPolling, e as OUIActivation, m as OUISurface, p as OUISurfaceSnapshot, c as OUIActionRequest, d as OUIActionResult, f as OUIApprovalGrant } from './types-CmJb1BQ8.cjs';
-import { S as SocketLike, e as OUITransportConfig } from './websocket-Ds2Rh_jL.cjs';
+import { i as OUIEffectKind, J as JSONSchema, c as OUIActionPolling, f as OUIActivation, r as OUISurface, l as OUIIndexSnapshot, v as OUISurfaceSnapshot, d as OUIActionRequest, e as OUIActionResult, g as OUIApprovalGrant } from './types-CnlVRPFL.cjs';
+import { S as SocketLike, e as OUITransportConfig } from './websocket-HnzPlfk6.cjs';
 
 /**
  * Nominal branding for values OUI must construct itself.
@@ -214,6 +214,23 @@ interface SurfaceRuntimeOptions {
      * not checked; they come from the application itself.
      */
     accept?: (request: OUIActionRequest) => boolean;
+    /**
+     * What a snapshot and an answer say of the mounted surfaces (§7.3.8):
+     * - `"index"`: each action as an index entry. The agent runtime fetches a
+     *   definition when it needs one (`oui.describe`). Use it with an agent
+     *   runtime that reads the index form.
+     * - `"full"` (the default until 1.0): each action's whole definition, as
+     *   every earlier version sent. A page's definitions can outweigh what a
+     *   frame may carry; then its answers are refused and arrive trimmed.
+     */
+    form?: "index" | "full";
+    /** The most bytes of JSON a frame carries; what does not fit is shortened and said so (§7.3.9). */
+    budgets?: {
+        /** One answer. Default 480 KB: under the 512 KB a relay commonly caps a frame at. */
+        answerBytes?: number;
+        /** One snapshot, as sent with a turn. Default 256 KB. */
+        snapshotBytes?: number;
+    };
     /**
      * A request sent again while its answer is on the way is not answered again
      * (§7.3.7): every copy of a large answer queues on the one socket, ahead of
@@ -230,7 +247,9 @@ interface MountedSurface {
     /** Remove this mount. Other mounts of the same surface id are unaffected. */
     unmount(): void;
 }
-interface SurfaceRuntime {
+/** The form a runtime sends its surfaces in (§7.3.8). */
+type SurfaceForm = "full" | "index";
+interface SurfaceRuntime<F extends SurfaceForm = "full"> {
     /**
      * Mount a surface. `getContext` is read when an action runs, so handlers see
      * the latest state rather than the state at mount time.
@@ -242,7 +261,7 @@ interface SurfaceRuntime {
     /** Answer requests arriving on this socket (null detaches). */
     attach(socket: SocketLike | null): void;
     /** What the client can do right now. */
-    snapshot(): OUISurfaceSnapshot;
+    snapshot(): F extends "index" ? OUIIndexSnapshot : OUISurfaceSnapshot;
     /**
      * Run a request once and resolve with its result. A request id seen before
      * resolves with the first result instead of running again.
@@ -267,6 +286,11 @@ interface SurfaceRuntime {
     /** Stop polling, detach from the socket and forget every mount. */
     dispose(): void;
 }
-declare function createSurfaceRuntime(options?: SurfaceRuntimeOptions): SurfaceRuntime;
+declare function createSurfaceRuntime(options: SurfaceRuntimeOptions & {
+    form: "index";
+}): SurfaceRuntime<"index">;
+declare function createSurfaceRuntime(options?: SurfaceRuntimeOptions & {
+    form?: "full";
+}): SurfaceRuntime<"full">;
 
-export { type ActionDefinition as A, type DefinedSurface as D, type MountedSurface as M, type OUIBranded as O, type SettleOptions as S, type ActionHandlerResult as a, type ActionPollingConfig as b, type ObservationDefinition as c, type SurfaceDefinition as d, type SurfaceRuntime as e, type SurfaceRuntimeOptions as f, createSurfaceRuntime as g, defineSurface as h };
+export { type ActionDefinition as A, type DefinedSurface as D, type MountedSurface as M, type OUIBranded as O, type SettleOptions as S, type ActionHandlerResult as a, type ActionPollingConfig as b, type ObservationDefinition as c, type SurfaceDefinition as d, type SurfaceForm as e, type SurfaceRuntime as f, type SurfaceRuntimeOptions as g, createSurfaceRuntime as h, defineSurface as i };

package/dist/transport/index.d.cts

@@ -1,6 +1,6 @@
-import { d as OUITransport } from '../websocket-Ds2Rh_jL.cjs';
-export { O as OUIAcknowledgment, a as OUIActionHandler, b as OUIObservationHandler, c as OUIResultHandler, e as OUITransportConfig, S as SocketLike, f as createWebSocketTransport } from '../websocket-Ds2Rh_jL.cjs';
-import '../types-CmJb1BQ8.cjs';
+import { d as OUITransport } from '../websocket-HnzPlfk6.cjs';
+export { O as OUIAcknowledgment, a as OUIActionHandler, b as OUIObservationHandler, c as OUIResultHandler, e as OUITransportConfig, S as SocketLike, f as createWebSocketTransport } from '../websocket-HnzPlfk6.cjs';
+import '../types-CnlVRPFL.cjs';
 
 /**
  * Direct transport — for same-process communication.

package/dist/transport/index.d.ts

@@ -1,6 +1,6 @@
-import { d as OUITransport } from '../websocket-Ce3tDSsJ.js';
-export { O as OUIAcknowledgment, a as OUIActionHandler, b as OUIObservationHandler, c as OUIResultHandler, e as OUITransportConfig, S as SocketLike, f as createWebSocketTransport } from '../websocket-Ce3tDSsJ.js';
-import '../types-CmJb1BQ8.js';
+import { d as OUITransport } from '../websocket-DKL9qoO-.js';
+export { O as OUIAcknowledgment, a as OUIActionHandler, b as OUIObservationHandler, c as OUIResultHandler, e as OUITransportConfig, S as SocketLike, f as createWebSocketTransport } from '../websocket-DKL9qoO-.js';
+import '../types-CnlVRPFL.js';
 
 /**
  * Direct transport — for same-process communication.

package/dist/{types-CmJb1BQ8.d.cts → types-CnlVRPFL.d.cts}

@@ -96,6 +96,9 @@ type JSONSchema = {
     pattern?: string;
     format?: string;
     additionalProperties?: boolean | JSONSchema;
+    title?: string;
+    /** Annotations (`x-unit`, `x-rows`, …) a product's contract adds; OUI carries them unread. */
+    [annotation: `x-${string}`]: unknown;
 };
 /**
  * A Surface is a controllable boundary within an application.
@@ -228,6 +231,70 @@ interface OUIActivation {
     /** Custom predicate description (for documentation, not execution) */
     condition?: string;
 }
+/**
+ * One action as a snapshot and an answer carry it: enough to choose it and to
+ * know what it takes in outline, without its definition. A page's actions
+ * weigh what its whole catalogue weighs (on a studio page, several hundred
+ * KB), and an agent runtime that received every definition could neither be
+ * sent them in one frame nor give them all to its model. The definition of an
+ * action is fetched when it is needed (`oui.describe`, §7.3.10).
+ */
+interface OUIActionIndexEntry {
+    /** The action's id. */
+    id: string;
+    /** Its name as a person reads it. */
+    title?: string;
+    /** The first sentence of its description, at most `INDEX_DESCRIPTION_CHARS` characters. */
+    description: string;
+    effect?: OUIEffectKind;
+    confirm?: boolean;
+    async?: boolean;
+    estimatedDuration?: string;
+    /** For an async action: how long its work is followed before it is reported as not finished. */
+    maxDurationMs?: number;
+    /** What it takes, in one line (`summarizeInput`): "none", "value: number 0–100", "clipId, start?, +4 more". */
+    input: string;
+    /** A hash of the full definition: a fetched definition is good until this changes. */
+    definitionHash: string;
+    /** The full definition's size in bytes of JSON, so a reader knows to ask for it in outline. */
+    definitionBytes: number;
+}
+/** A surface as a snapshot and an answer carry it in index form: its actions as index entries. */
+interface OUISurfaceIndex {
+    id: string;
+    name: string;
+    description: string;
+    version?: string;
+    /** Observation definitions travel whole: they are small, and say how to read the values that follow. */
+    observations?: OUIObservation[];
+    index: OUIActionIndexEntry[];
+}
+/**
+ * One place where a snapshot's or an answer's observations were shortened to
+ * fit its byte budget (§7.3.9): a list cut to its first rows, a long text cut,
+ * or a value left out. The rest is read with `oui.read` (§7.3.10), by this
+ * surface, observation and path.
+ */
+interface OUIFitCut {
+    surface: string;
+    observation: string;
+    /** JSON Pointer (RFC 6901) into the observation's value; "" is the value itself. */
+    path: string;
+    kind: "list" | "text" | "value";
+    /** Rows of a list, characters of a text, bytes of a value. */
+    total: number;
+    /** How many of them this frame keeps. */
+    kept: number;
+}
+/** What was shortened or left out to fit a frame's byte budget (§7.3.9). */
+interface OUIFit {
+    observations?: OUIFitCut[];
+    /** The action's `data` was left out: its size, and the most a frame could carry. */
+    data?: {
+        bytes: number;
+        limit: number;
+    };
+}
 /**
  * A request from the agent runtime to execute an action on a surface.
  */
@@ -268,7 +335,7 @@ interface OUIResultDelivery {
     /** What the receiving side said when it refused the full answer. */
     reason: string;
     /** The fields left out of this answer. */
-    omitted: Array<"surfaces" | "observations" | "data">;
+    omitted: Array<"surfaces" | "index" | "observations" | "data">;
 }
 /**
  * The result of an action execution, returned from the surface to the agent.
@@ -303,8 +370,15 @@ interface OUIActionResult {
      * set the action just replaced.
      */
     surfaces?: OUISurface[];
+    /**
+     * The same, in index form (§7.3.8): what a client sends in place of
+     * `surfaces` unless it was made to send definitions.
+     */
+    index?: OUISurfaceIndex[];
     /** Latest observation values per surface once the action's effects settled. */
     observations?: OUIObservationSnapshot;
+    /** What was shortened or left out so this answer fits its byte budget (§7.3.9). */
+    fit?: OUIFit;
     /**
      * The hash of the client's surfaces once the action's effects settled
      * (`surfacesHash`). Always present from a client that sends it; `surfaces`
@@ -328,6 +402,9 @@ type OUIObservationSnapshot = Record<string, Record<string, unknown>>;
  * What a client can do right now: the surfaces it has mounted and their latest
  * observation values. A client sends this to its agent runtime (for example,
  * with each turn), and returns it on every action result.
+ *
+ * This is the full form: every action with its definition. A client made in
+ * index form (§7.3.8) sends an `OUIIndexSnapshot` instead.
  */
 interface OUISurfaceSnapshot {
     surfaces: OUISurface[];
@@ -338,7 +415,20 @@ interface OUISurfaceSnapshot {
      * runtime already holds.
      */
     surfacesHash?: string;
+    /** What was shortened so the snapshot fits its byte budget (§7.3.9). */
+    fit?: OUIFit;
+}
+/** A client's snapshot in index form (§7.3.8): each action as an index entry, not its definition. */
+interface OUIIndexSnapshot {
+    index: OUISurfaceIndex[];
+    observations: OUIObservationSnapshot;
+    /** `surfacesHash(index)`. */
+    surfacesHash?: string;
+    /** What was shortened so the snapshot fits its byte budget (§7.3.9). */
+    fit?: OUIFit;
 }
+/** A snapshot as an agent runtime receives it: in either form. */
+type OUIClientSnapshot = OUISurfaceSnapshot | OUIIndexSnapshot;
 /**
  * An observation update pushed from the surface to the agent.
  */
@@ -400,4 +490,4 @@ declare const OUI_PROTOCOL_EVENTS: {
     readonly OBSERVATION_UPDATE: "observation:update";
 };
 
-export { ARGS_HASH_PATTERN as A, type JSONSchema as J, type OUIAction as O, type OUIActionApproval as a, type OUIActionPolling as b, type OUIActionRequest as c, type OUIActionResult as d, type OUIActivation as e, type OUIApprovalGrant as f, type OUIEffectKind as g, type OUIObservation as h, type OUIObservationSnapshot as i, type OUIObservationUpdate as j, type OUIProtocolEvent as k, type OUIResultDelivery as l, type OUISurface as m, type OUISurfaceDeregistration as n, type OUISurfaceRegistration as o, type OUISurfaceSnapshot as p, OUI_EFFECT_ACCESS as q, OUI_EFFECT_KINDS as r, OUI_PROTOCOL_EVENTS as s, argsHash as t, canonicalJson as u, effectAccess as v, requiresApproval as w };
+export { ARGS_HASH_PATTERN as A, canonicalJson as B, effectAccess as C, requiresApproval as D, type JSONSchema as J, type OUIAction as O, type OUIActionApproval as a, type OUIActionIndexEntry as b, type OUIActionPolling as c, type OUIActionRequest as d, type OUIActionResult as e, type OUIActivation as f, type OUIApprovalGrant as g, type OUIClientSnapshot as h, type OUIEffectKind as i, type OUIFit as j, type OUIFitCut as k, type OUIIndexSnapshot as l, type OUIObservation as m, type OUIObservationSnapshot as n, type OUIObservationUpdate as o, type OUIProtocolEvent as p, type OUIResultDelivery as q, type OUISurface as r, type OUISurfaceDeregistration as s, type OUISurfaceIndex as t, type OUISurfaceRegistration as u, type OUISurfaceSnapshot as v, OUI_EFFECT_ACCESS as w, OUI_EFFECT_KINDS as x, OUI_PROTOCOL_EVENTS as y, argsHash as z };

package/dist/{types-CmJb1BQ8.d.ts → types-CnlVRPFL.d.ts}

@@ -96,6 +96,9 @@ type JSONSchema = {
     pattern?: string;
     format?: string;
     additionalProperties?: boolean | JSONSchema;
+    title?: string;
+    /** Annotations (`x-unit`, `x-rows`, …) a product's contract adds; OUI carries them unread. */
+    [annotation: `x-${string}`]: unknown;
 };
 /**
  * A Surface is a controllable boundary within an application.
@@ -228,6 +231,70 @@ interface OUIActivation {
     /** Custom predicate description (for documentation, not execution) */
     condition?: string;
 }
+/**
+ * One action as a snapshot and an answer carry it: enough to choose it and to
+ * know what it takes in outline, without its definition. A page's actions
+ * weigh what its whole catalogue weighs (on a studio page, several hundred
+ * KB), and an agent runtime that received every definition could neither be
+ * sent them in one frame nor give them all to its model. The definition of an
+ * action is fetched when it is needed (`oui.describe`, §7.3.10).
+ */
+interface OUIActionIndexEntry {
+    /** The action's id. */
+    id: string;
+    /** Its name as a person reads it. */
+    title?: string;
+    /** The first sentence of its description, at most `INDEX_DESCRIPTION_CHARS` characters. */
+    description: string;
+    effect?: OUIEffectKind;
+    confirm?: boolean;
+    async?: boolean;
+    estimatedDuration?: string;
+    /** For an async action: how long its work is followed before it is reported as not finished. */
+    maxDurationMs?: number;
+    /** What it takes, in one line (`summarizeInput`): "none", "value: number 0–100", "clipId, start?, +4 more". */
+    input: string;
+    /** A hash of the full definition: a fetched definition is good until this changes. */
+    definitionHash: string;
+    /** The full definition's size in bytes of JSON, so a reader knows to ask for it in outline. */
+    definitionBytes: number;
+}
+/** A surface as a snapshot and an answer carry it in index form: its actions as index entries. */
+interface OUISurfaceIndex {
+    id: string;
+    name: string;
+    description: string;
+    version?: string;
+    /** Observation definitions travel whole: they are small, and say how to read the values that follow. */
+    observations?: OUIObservation[];
+    index: OUIActionIndexEntry[];
+}
+/**
+ * One place where a snapshot's or an answer's observations were shortened to
+ * fit its byte budget (§7.3.9): a list cut to its first rows, a long text cut,
+ * or a value left out. The rest is read with `oui.read` (§7.3.10), by this
+ * surface, observation and path.
+ */
+interface OUIFitCut {
+    surface: string;
+    observation: string;
+    /** JSON Pointer (RFC 6901) into the observation's value; "" is the value itself. */
+    path: string;
+    kind: "list" | "text" | "value";
+    /** Rows of a list, characters of a text, bytes of a value. */
+    total: number;
+    /** How many of them this frame keeps. */
+    kept: number;
+}
+/** What was shortened or left out to fit a frame's byte budget (§7.3.9). */
+interface OUIFit {
+    observations?: OUIFitCut[];
+    /** The action's `data` was left out: its size, and the most a frame could carry. */
+    data?: {
+        bytes: number;
+        limit: number;
+    };
+}
 /**
  * A request from the agent runtime to execute an action on a surface.
  */
@@ -268,7 +335,7 @@ interface OUIResultDelivery {
     /** What the receiving side said when it refused the full answer. */
     reason: string;
     /** The fields left out of this answer. */
-    omitted: Array<"surfaces" | "observations" | "data">;
+    omitted: Array<"surfaces" | "index" | "observations" | "data">;
 }
 /**
  * The result of an action execution, returned from the surface to the agent.
@@ -303,8 +370,15 @@ interface OUIActionResult {
      * set the action just replaced.
      */
     surfaces?: OUISurface[];
+    /**
+     * The same, in index form (§7.3.8): what a client sends in place of
+     * `surfaces` unless it was made to send definitions.
+     */
+    index?: OUISurfaceIndex[];
     /** Latest observation values per surface once the action's effects settled. */
     observations?: OUIObservationSnapshot;
+    /** What was shortened or left out so this answer fits its byte budget (§7.3.9). */
+    fit?: OUIFit;
     /**
      * The hash of the client's surfaces once the action's effects settled
      * (`surfacesHash`). Always present from a client that sends it; `surfaces`
@@ -328,6 +402,9 @@ type OUIObservationSnapshot = Record<string, Record<string, unknown>>;
  * What a client can do right now: the surfaces it has mounted and their latest
  * observation values. A client sends this to its agent runtime (for example,
  * with each turn), and returns it on every action result.
+ *
+ * This is the full form: every action with its definition. A client made in
+ * index form (§7.3.8) sends an `OUIIndexSnapshot` instead.
  */
 interface OUISurfaceSnapshot {
     surfaces: OUISurface[];
@@ -338,7 +415,20 @@ interface OUISurfaceSnapshot {
      * runtime already holds.
      */
     surfacesHash?: string;
+    /** What was shortened so the snapshot fits its byte budget (§7.3.9). */
+    fit?: OUIFit;
+}
+/** A client's snapshot in index form (§7.3.8): each action as an index entry, not its definition. */
+interface OUIIndexSnapshot {
+    index: OUISurfaceIndex[];
+    observations: OUIObservationSnapshot;
+    /** `surfacesHash(index)`. */
+    surfacesHash?: string;
+    /** What was shortened so the snapshot fits its byte budget (§7.3.9). */
+    fit?: OUIFit;
 }
+/** A snapshot as an agent runtime receives it: in either form. */
+type OUIClientSnapshot = OUISurfaceSnapshot | OUIIndexSnapshot;
 /**
  * An observation update pushed from the surface to the agent.
  */
@@ -400,4 +490,4 @@ declare const OUI_PROTOCOL_EVENTS: {
     readonly OBSERVATION_UPDATE: "observation:update";
 };
 
-export { ARGS_HASH_PATTERN as A, type JSONSchema as J, type OUIAction as O, type OUIActionApproval as a, type OUIActionPolling as b, type OUIActionRequest as c, type OUIActionResult as d, type OUIActivation as e, type OUIApprovalGrant as f, type OUIEffectKind as g, type OUIObservation as h, type OUIObservationSnapshot as i, type OUIObservationUpdate as j, type OUIProtocolEvent as k, type OUIResultDelivery as l, type OUISurface as m, type OUISurfaceDeregistration as n, type OUISurfaceRegistration as o, type OUISurfaceSnapshot as p, OUI_EFFECT_ACCESS as q, OUI_EFFECT_KINDS as r, OUI_PROTOCOL_EVENTS as s, argsHash as t, canonicalJson as u, effectAccess as v, requiresApproval as w };
+export { ARGS_HASH_PATTERN as A, canonicalJson as B, effectAccess as C, requiresApproval as D, type JSONSchema as J, type OUIAction as O, type OUIActionApproval as a, type OUIActionIndexEntry as b, type OUIActionPolling as c, type OUIActionRequest as d, type OUIActionResult as e, type OUIActivation as f, type OUIApprovalGrant as g, type OUIClientSnapshot as h, type OUIEffectKind as i, type OUIFit as j, type OUIFitCut as k, type OUIIndexSnapshot as l, type OUIObservation as m, type OUIObservationSnapshot as n, type OUIObservationUpdate as o, type OUIProtocolEvent as p, type OUIResultDelivery as q, type OUISurface as r, type OUISurfaceDeregistration as s, type OUISurfaceIndex as t, type OUISurfaceRegistration as u, type OUISurfaceSnapshot as v, OUI_EFFECT_ACCESS as w, OUI_EFFECT_KINDS as x, OUI_PROTOCOL_EVENTS as y, argsHash as z };

package/dist/{websocket-Ce3tDSsJ.d.ts → websocket-DKL9qoO-.d.ts}

@@ -1,4 +1,4 @@
-import { c as OUIActionRequest, d as OUIActionResult, j as OUIObservationUpdate, m as OUISurface } from './types-CmJb1BQ8.js';
+import { d as OUIActionRequest, e as OUIActionResult, o as OUIObservationUpdate, r as OUISurface } from './types-CnlVRPFL.js';
 
 /**
  * OUI Transport — the wire protocol between agent runtime and surfaces.

package/dist/{websocket-Ds2Rh_jL.d.cts → websocket-HnzPlfk6.d.cts}

@@ -1,4 +1,4 @@
-import { c as OUIActionRequest, d as OUIActionResult, j as OUIObservationUpdate, m as OUISurface } from './types-CmJb1BQ8.cjs';
+import { d as OUIActionRequest, e as OUIActionResult, o as OUIObservationUpdate, r as OUISurface } from './types-CnlVRPFL.cjs';
 
 /**
  * OUI Transport — the wire protocol between agent runtime and surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oui-spec",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "OUI — The OpenUI Specification. A machine-readable contract for agent-controllable user interfaces.",
   "keywords": [
     "oui",