oui-spec 0.7.1 → 0.10.0

package/dist/index.js

@@ -1,7 +1,7 @@
-export { createOUI, createSurfaceRuntime, defineSurface } from './chunk-NKKWL7RK.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';
+export { acceptCurrentTurn, createOUI, createSurfaceRuntime, defineSurface } from './chunk-UNQZXT7C.js';
+export { ARGS_HASH_PATTERN, DEFINITION_HASH_HEX, 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, withoutTitleLeadIn } from './chunk-JOWXACVF.js';
 export { SurfaceRuntimeProvider, useObservation, useSurface, useSurfaceHold, useSurfaceRuntime } from './chunk-UOTAHGIV.js';
 export { createDirectTransportPair } from './chunk-IIZ6HL2L.js';
-export { createWebSocketTransport } from './chunk-R3SGP2UY.js';
+export { createWebSocketTransport } from './chunk-NXDPC3KW.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/react/index.d.cts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { e as OUIActionResult } from '../types-CnlVRPFL.cjs';
-import { f as SurfaceRuntime, e as SurfaceForm, D as DefinedSurface } from '../surface-runtime-CexHqUn-.cjs';
-import '../websocket-HnzPlfk6.cjs';
+import { e as OUIActionResult } from '../types-DLOa7CWj.cjs';
+import { f as SurfaceRuntime, e as SurfaceForm, D as DefinedSurface } from '../surface-runtime-DCPEz_JF.cjs';
+import '../websocket-CoSpb5nB.cjs';
 
 interface SurfaceRuntimeProviderProps {
     /** A runtime in either form (§7.3.8). */

package/dist/react/index.d.ts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { e as OUIActionResult } from '../types-CnlVRPFL.js';
-import { f as SurfaceRuntime, e as SurfaceForm, D as DefinedSurface } from '../surface-runtime-BPEtT3LZ.js';
-import '../websocket-DKL9qoO-.js';
+import { e as OUIActionResult } from '../types-DLOa7CWj.js';
+import { f as SurfaceRuntime, e as SurfaceForm, D as DefinedSurface } from '../surface-runtime-B6NED8eV.js';
+import '../websocket-Bf7xMzs1.js';
 
 interface SurfaceRuntimeProviderProps {
     /** A runtime in either form (§7.3.8). */

package/dist/spec/index.cjs

@@ -1,132 +1,140 @@
 'use strict';
 
-var chunk2CPOHQGI_cjs = require('../chunk-2CPOHQGI.cjs');
+var chunkOJ6Y2WWS_cjs = require('../chunk-OJ6Y2WWS.cjs');
 
 
 
 Object.defineProperty(exports, "ARGS_HASH_PATTERN", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.ARGS_HASH_PATTERN; }
+  get: function () { return chunkOJ6Y2WWS_cjs.ARGS_HASH_PATTERN; }
+});
+Object.defineProperty(exports, "DEFINITION_HASH_HEX", {
+  enumerable: true,
+  get: function () { return chunkOJ6Y2WWS_cjs.DEFINITION_HASH_HEX; }
 });
 Object.defineProperty(exports, "FIT_LIST_STEPS", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.FIT_LIST_STEPS; }
+  get: function () { return chunkOJ6Y2WWS_cjs.FIT_LIST_STEPS; }
 });
 Object.defineProperty(exports, "FIT_TEXT_CHARS", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.FIT_TEXT_CHARS; }
+  get: function () { return chunkOJ6Y2WWS_cjs.FIT_TEXT_CHARS; }
 });
 Object.defineProperty(exports, "INDEX_DESCRIPTION_CHARS", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.INDEX_DESCRIPTION_CHARS; }
+  get: function () { return chunkOJ6Y2WWS_cjs.INDEX_DESCRIPTION_CHARS; }
 });
 Object.defineProperty(exports, "INDEX_INPUT_CHARS", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.INDEX_INPUT_CHARS; }
+  get: function () { return chunkOJ6Y2WWS_cjs.INDEX_INPUT_CHARS; }
 });
 Object.defineProperty(exports, "INDEX_INPUT_PROPERTIES", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.INDEX_INPUT_PROPERTIES; }
+  get: function () { return chunkOJ6Y2WWS_cjs.INDEX_INPUT_PROPERTIES; }
 });
 Object.defineProperty(exports, "OUI_DESCRIBE_ACTION", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.OUI_DESCRIBE_ACTION; }
+  get: function () { return chunkOJ6Y2WWS_cjs.OUI_DESCRIBE_ACTION; }
 });
 Object.defineProperty(exports, "OUI_EFFECT_ACCESS", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.OUI_EFFECT_ACCESS; }
+  get: function () { return chunkOJ6Y2WWS_cjs.OUI_EFFECT_ACCESS; }
 });
 Object.defineProperty(exports, "OUI_EFFECT_KINDS", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.OUI_EFFECT_KINDS; }
+  get: function () { return chunkOJ6Y2WWS_cjs.OUI_EFFECT_KINDS; }
 });
 Object.defineProperty(exports, "OUI_PROTOCOL_EVENTS", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.OUI_PROTOCOL_EVENTS; }
+  get: function () { return chunkOJ6Y2WWS_cjs.OUI_PROTOCOL_EVENTS; }
 });
 Object.defineProperty(exports, "OUI_READ_ACTION", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.OUI_READ_ACTION; }
+  get: function () { return chunkOJ6Y2WWS_cjs.OUI_READ_ACTION; }
 });
 Object.defineProperty(exports, "OUI_RUNTIME_SURFACE", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.OUI_RUNTIME_SURFACE; }
+  get: function () { return chunkOJ6Y2WWS_cjs.OUI_RUNTIME_SURFACE; }
 });
 Object.defineProperty(exports, "argsHash", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.argsHash; }
+  get: function () { return chunkOJ6Y2WWS_cjs.argsHash; }
 });
 Object.defineProperty(exports, "atPointer", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.atPointer; }
+  get: function () { return chunkOJ6Y2WWS_cjs.atPointer; }
 });
 Object.defineProperty(exports, "canonicalJson", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.canonicalJson; }
+  get: function () { return chunkOJ6Y2WWS_cjs.canonicalJson; }
 });
 Object.defineProperty(exports, "constantOf", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.constantOf; }
+  get: function () { return chunkOJ6Y2WWS_cjs.constantOf; }
 });
 Object.defineProperty(exports, "definitionHash", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.definitionHash; }
+  get: function () { return chunkOJ6Y2WWS_cjs.definitionHash; }
 });
 Object.defineProperty(exports, "discriminatorOf", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.discriminatorOf; }
+  get: function () { return chunkOJ6Y2WWS_cjs.discriminatorOf; }
 });
 Object.defineProperty(exports, "effectAccess", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.effectAccess; }
+  get: function () { return chunkOJ6Y2WWS_cjs.effectAccess; }
 });
 Object.defineProperty(exports, "firstSentence", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.firstSentence; }
+  get: function () { return chunkOJ6Y2WWS_cjs.firstSentence; }
 });
 Object.defineProperty(exports, "fitObservations", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.fitObservations; }
+  get: function () { return chunkOJ6Y2WWS_cjs.fitObservations; }
 });
 Object.defineProperty(exports, "indexEntry", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.indexEntry; }
+  get: function () { return chunkOJ6Y2WWS_cjs.indexEntry; }
 });
 Object.defineProperty(exports, "jsonBytes", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.jsonBytes; }
+  get: function () { return chunkOJ6Y2WWS_cjs.jsonBytes; }
 });
 Object.defineProperty(exports, "pointerStep", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.pointerStep; }
+  get: function () { return chunkOJ6Y2WWS_cjs.pointerStep; }
 });
 Object.defineProperty(exports, "pointerSteps", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.pointerSteps; }
+  get: function () { return chunkOJ6Y2WWS_cjs.pointerSteps; }
 });
 Object.defineProperty(exports, "requiresApproval", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.requiresApproval; }
+  get: function () { return chunkOJ6Y2WWS_cjs.requiresApproval; }
 });
 Object.defineProperty(exports, "sortedJson", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.sortedJson; }
+  get: function () { return chunkOJ6Y2WWS_cjs.sortedJson; }
 });
 Object.defineProperty(exports, "summarizeInput", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.summarizeInput; }
+  get: function () { return chunkOJ6Y2WWS_cjs.summarizeInput; }
 });
 Object.defineProperty(exports, "surfaceIndex", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.surfaceIndex; }
+  get: function () { return chunkOJ6Y2WWS_cjs.surfaceIndex; }
 });
 Object.defineProperty(exports, "surfacesHash", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.surfacesHash; }
+  get: function () { return chunkOJ6Y2WWS_cjs.surfacesHash; }
 });
 Object.defineProperty(exports, "utf8Length", {
   enumerable: true,
-  get: function () { return chunk2CPOHQGI_cjs.utf8Length; }
+  get: function () { return chunkOJ6Y2WWS_cjs.utf8Length; }
+});
+Object.defineProperty(exports, "withoutTitleLeadIn", {
+  enumerable: true,
+  get: function () { return chunkOJ6Y2WWS_cjs.withoutTitleLeadIn; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/spec/index.d.cts

@@ -1,5 +1,5 @@
-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.cjs';
-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.cjs';
+import { r as OUISurface, t as OUISurfaceIndex, J as JSONSchema, O as OUIAction, b as OUIActionIndexEntry, n as OUIObservationSnapshot, k as OUIFitCut } from '../types-DLOa7CWj.cjs';
+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-DLOa7CWj.cjs';
 
 /**
  * The identity of a set of surfaces, for an answer that need not repeat them
@@ -66,7 +66,32 @@ declare function constantOf(schema: JSONSchema | undefined): string | number | b
  * - "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. */
+/**
+ * A description without the opening that only repeats the action's title.
+ *
+ * An entry carries the title beside the description, and descriptions are
+ * commonly written to stand alone: `Add artboard: Adds an artboard…`, or, for
+ * a control, `Press "Save": Saves the project`. In an index that names the
+ * title twice for every action, and an index is hundreds of actions. So an
+ * opening of the title followed by ": ", or of a short lead-in, the title in
+ * double quotes and ": ", is left out: what the entry keeps is what the title
+ * does not already say. A description that does not open that way is kept as
+ * it is, and one that is only its title is kept too.
+ */
+declare function withoutTitleLeadIn(description: string, title: string | undefined): string;
+/** The hex digits an entry's `definitionHash` has: 32 bits. */
+declare const DEFINITION_HASH_HEX = 8;
+/**
+ * The hash of an action's definition, as an index entry's `definitionHash`
+ * carries it: the first 32 bits of the 64-bit FNV-1a of its sorted-key JSON.
+ *
+ * It answers one question, for one action: has this action's definition
+ * changed since it was fetched? It is only ever compared with the same
+ * action's earlier hash, so 32 bits are enough (a change goes unseen once in
+ * 2^32, and costs one stale definition until the next change), and an index of
+ * hundreds of actions carries half the digits. The hash of a whole page
+ * (`surfacesHash`) is compared across everything on it, and stays 64 bits.
+ */
 declare function definitionHash(action: OUIAction): string;
 /** An action's index entry (§7.3.8). */
 declare function indexEntry(action: OUIAction): OUIActionIndexEntry;
@@ -96,4 +121,4 @@ declare function fitObservations(observations: OUIObservationSnapshot, budget: n
     cuts: OUIFitCut[];
 };
 
-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 };
+export { DEFINITION_HASH_HEX, 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, withoutTitleLeadIn };

package/dist/spec/index.d.ts

@@ -1,5 +1,5 @@
-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';
+import { r as OUISurface, t as OUISurfaceIndex, J as JSONSchema, O as OUIAction, b as OUIActionIndexEntry, n as OUIObservationSnapshot, k as OUIFitCut } from '../types-DLOa7CWj.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-DLOa7CWj.js';
 
 /**
  * The identity of a set of surfaces, for an answer that need not repeat them
@@ -66,7 +66,32 @@ declare function constantOf(schema: JSONSchema | undefined): string | number | b
  * - "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. */
+/**
+ * A description without the opening that only repeats the action's title.
+ *
+ * An entry carries the title beside the description, and descriptions are
+ * commonly written to stand alone: `Add artboard: Adds an artboard…`, or, for
+ * a control, `Press "Save": Saves the project`. In an index that names the
+ * title twice for every action, and an index is hundreds of actions. So an
+ * opening of the title followed by ": ", or of a short lead-in, the title in
+ * double quotes and ": ", is left out: what the entry keeps is what the title
+ * does not already say. A description that does not open that way is kept as
+ * it is, and one that is only its title is kept too.
+ */
+declare function withoutTitleLeadIn(description: string, title: string | undefined): string;
+/** The hex digits an entry's `definitionHash` has: 32 bits. */
+declare const DEFINITION_HASH_HEX = 8;
+/**
+ * The hash of an action's definition, as an index entry's `definitionHash`
+ * carries it: the first 32 bits of the 64-bit FNV-1a of its sorted-key JSON.
+ *
+ * It answers one question, for one action: has this action's definition
+ * changed since it was fetched? It is only ever compared with the same
+ * action's earlier hash, so 32 bits are enough (a change goes unseen once in
+ * 2^32, and costs one stale definition until the next change), and an index of
+ * hundreds of actions carries half the digits. The hash of a whole page
+ * (`surfacesHash`) is compared across everything on it, and stays 64 bits.
+ */
 declare function definitionHash(action: OUIAction): string;
 /** An action's index entry (§7.3.8). */
 declare function indexEntry(action: OUIAction): OUIActionIndexEntry;
@@ -96,4 +121,4 @@ declare function fitObservations(observations: OUIObservationSnapshot, budget: n
     cuts: OUIFitCut[];
 };
 
-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 };
+export { DEFINITION_HASH_HEX, 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, withoutTitleLeadIn };

package/dist/spec/index.js

@@ -1,3 +1,3 @@
-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';
+export { ARGS_HASH_PATTERN, DEFINITION_HASH_HEX, 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, withoutTitleLeadIn } from '../chunk-JOWXACVF.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

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

@@ -1,5 +1,5 @@
-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';
+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-DLOa7CWj.js';
+import { S as SocketLike, e as OUITransportConfig } from './websocket-Bf7xMzs1.js';
 
 /**
  * Nominal branding for values OUI must construct itself.
@@ -47,10 +47,18 @@ interface ActionPollingConfig<TContext = unknown> extends OUIActionPolling {
      * Called on each poll interval. Receives the dispatch result from the handler
      * plus the current context. Return { done: true, data } to stop polling,
      * or { done: false, data } to continue.
+     *
+     * Work that ended in failure returns { done: true, data, error }: the final
+     * result is then a failure (§7.3.3) carrying `error`, with `data` kept, so
+     * the agent never records failed work as a success.
      */
     resolve?: (dispatchResult: unknown, context: TContext) => Promise<{
         done: boolean;
         data: unknown;
+        error?: {
+            code: string;
+            message: string;
+        };
     }>;
 }
 /**
@@ -206,11 +214,13 @@ interface SurfaceRuntimeOptions {
     dedupeWindow?: number;
     /**
      * Decides whether a request that arrived on the socket may run at all. A
-     * refused request is neither run nor answered, and is logged.
+     * refused request is not run: its sender gets a receipt saying it was
+     * received and not accepted, and the refusal is logged.
      *
      * The server should be the only sender of action requests, but a client can
-     * also check that a request is one it expects: for example, only while its
-     * agent has a turn in progress. Requests passed to `execute` directly are
+     * also check that a request is one it expects: for example, only for the
+     * turn its agent is running now (the request's `turnId`), so a request sent
+     * late by a stopped turn does not run. Requests passed to `execute` directly are
      * not checked; they come from the application itself.
      */
     accept?: (request: OUIActionRequest) => boolean;

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

@@ -1,5 +1,5 @@
-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';
+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-DLOa7CWj.cjs';
+import { S as SocketLike, e as OUITransportConfig } from './websocket-CoSpb5nB.cjs';
 
 /**
  * Nominal branding for values OUI must construct itself.
@@ -47,10 +47,18 @@ interface ActionPollingConfig<TContext = unknown> extends OUIActionPolling {
      * Called on each poll interval. Receives the dispatch result from the handler
      * plus the current context. Return { done: true, data } to stop polling,
      * or { done: false, data } to continue.
+     *
+     * Work that ended in failure returns { done: true, data, error }: the final
+     * result is then a failure (§7.3.3) carrying `error`, with `data` kept, so
+     * the agent never records failed work as a success.
      */
     resolve?: (dispatchResult: unknown, context: TContext) => Promise<{
         done: boolean;
         data: unknown;
+        error?: {
+            code: string;
+            message: string;
+        };
     }>;
 }
 /**
@@ -206,11 +214,13 @@ interface SurfaceRuntimeOptions {
     dedupeWindow?: number;
     /**
      * Decides whether a request that arrived on the socket may run at all. A
-     * refused request is neither run nor answered, and is logged.
+     * refused request is not run: its sender gets a receipt saying it was
+     * received and not accepted, and the refusal is logged.
      *
      * The server should be the only sender of action requests, but a client can
-     * also check that a request is one it expects: for example, only while its
-     * agent has a turn in progress. Requests passed to `execute` directly are
+     * also check that a request is one it expects: for example, only for the
+     * turn its agent is running now (the request's `turnId`), so a request sent
+     * late by a stopped turn does not run. Requests passed to `execute` directly are
      * not checked; they come from the application itself.
      */
     accept?: (request: OUIActionRequest) => boolean;

package/dist/transport/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 var chunkROGKEMLL_cjs = require('../chunk-ROGKEMLL.cjs');
-var chunk5UUJ3F7C_cjs = require('../chunk-5UUJ3F7C.cjs');
+var chunk2FFUDX2L_cjs = require('../chunk-2FFUDX2L.cjs');
 
 
 
@@ -11,7 +11,7 @@ Object.defineProperty(exports, "createDirectTransportPair", {
 });
 Object.defineProperty(exports, "createWebSocketTransport", {
   enumerable: true,
-  get: function () { return chunk5UUJ3F7C_cjs.createWebSocketTransport; }
+  get: function () { return chunk2FFUDX2L_cjs.createWebSocketTransport; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/transport/index.d.cts

@@ -1,6 +1,6 @@
-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';
+import { d as OUITransport } from '../websocket-CoSpb5nB.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-CoSpb5nB.cjs';
+import '../types-DLOa7CWj.cjs';
 
 /**
  * Direct transport — for same-process communication.

package/dist/transport/index.d.ts

@@ -1,6 +1,6 @@
-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';
+import { d as OUITransport } from '../websocket-Bf7xMzs1.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-Bf7xMzs1.js';
+import '../types-DLOa7CWj.js';
 
 /**
  * Direct transport — for same-process communication.

package/dist/transport/index.js

@@ -1,4 +1,4 @@
 export { createDirectTransportPair } from '../chunk-IIZ6HL2L.js';
-export { createWebSocketTransport } from '../chunk-R3SGP2UY.js';
+export { createWebSocketTransport } from '../chunk-NXDPC3KW.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

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

@@ -254,10 +254,12 @@ interface OUIActionIndexEntry {
     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. */
+    /**
+     * A hash of the full definition: a fetched definition is good until this
+     * changes. Opaque to a reader, which only compares it with the same action's
+     * earlier one: 8 hex digits since 0.8, 16 before.
+     */
     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 {
@@ -309,6 +311,15 @@ interface OUIActionRequest {
     params: Record<string, unknown>;
     /** Timestamp of the request */
     timestamp: number;
+    /**
+     * The turn of the agent's work this request belongs to. A client that runs
+     * one turn at a time accepts a request only for its current turn (`accept`),
+     * so a request sent late by a turn the person has stopped or superseded does
+     * not run under their newer instruction. Optional: an agent runtime that
+     * does not know of turns sends none, and a client then applies whatever rule
+     * it had without it.
+     */
+    turnId?: string;
     /**
      * The user's approval this request runs on, for an action that needs one.
      * The surface runtime runs such an action only when this matches a grant

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

@@ -254,10 +254,12 @@ interface OUIActionIndexEntry {
     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. */
+    /**
+     * A hash of the full definition: a fetched definition is good until this
+     * changes. Opaque to a reader, which only compares it with the same action's
+     * earlier one: 8 hex digits since 0.8, 16 before.
+     */
     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 {
@@ -309,6 +311,15 @@ interface OUIActionRequest {
     params: Record<string, unknown>;
     /** Timestamp of the request */
     timestamp: number;
+    /**
+     * The turn of the agent's work this request belongs to. A client that runs
+     * one turn at a time accepts a request only for its current turn (`accept`),
+     * so a request sent late by a turn the person has stopped or superseded does
+     * not run under their newer instruction. Optional: an agent runtime that
+     * does not know of turns sends none, and a client then applies whatever rule
+     * it had without it.
+     */
+    turnId?: string;
     /**
      * The user's approval this request runs on, for an action that needs one.
      * The surface runtime runs such an action only when this matches a grant

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

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

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

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

package/package.json

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

package/spec/OUI-SPEC-v0.1.md

@@ -608,6 +608,7 @@ When the agent invokes an action, the runtime sends an `action:request`:
 - `params` MUST conform to the action's declared `input` schema
 - The agent runtime SHOULD validate `params` before sending; the surface MUST validate upon receipt
 - `knownSurfaces` (OPTIONAL) is the `surfacesHash` of the client's surfaces that the agent runtime already holds, from the client's snapshot (§7.3.5) or an earlier result. A runtime that holds the client's surfaces SHOULD send it (§7.3.4).
+- `turnId` (OPTIONAL) names the turn of the agent's work the request belongs to. An agent runtime whose work is divided into turns that a person can stop SHOULD send it. A client MAY refuse a request whose `turnId` is not its current turn; a refused request is not run, and its receipt (§7.3.7) says it was received and not accepted. A client MUST NOT refuse a request only because it carries no `turnId`.
 
 #### 7.3.2 Action Result (Success)
 
@@ -655,6 +656,7 @@ When the agent invokes an action, the runtime sends an `action:request`:
 - If `success` is `false`, the `error` field MUST be present
 - If `success` is `true`, the `error` field MUST NOT be present
 - An async action's acknowledgment result MUST set `interim: true`; its final result MUST set `interim: false`
+- An async action whose work failed MUST send its final result as a failure (`success: false`, with `error`); it MAY keep the work's own report in `data`
 
 #### 7.3.4 The Client's State After an Action
 
@@ -770,15 +772,14 @@ interface OUISurfaceIndex {
 interface OUIActionIndexEntry {
   id: string;
   title?: string;
-  description: string; // the first sentence, at most 160 characters
+  description: string; // the first sentence, at most 160 characters, without an opening that only repeats the title (`Title: …`, `Press "Title": …`)
   effect?: OUIEffectKind;
   confirm?: boolean;
   async?: boolean;
   estimatedDuration?: string;
   maxDurationMs?: number; // an async action's polling limit
   input: string; // what it takes, in one line, at most 120 characters
-  definitionHash: string; // 64-bit FNV-1a of the definition's sorted-key JSON, 16 hex digits
-  definitionBytes: number; // the definition's size as JSON
+  definitionHash: string; // the first 32 bits of the 64-bit FNV-1a of the definition's sorted-key JSON, 8 hex digits
 }
 ```
 
@@ -794,6 +795,11 @@ interface OUIActionIndexEntry {
   same index.
 - An agent runtime fetches an action's definition when it needs it (§7.3.10),
   and MAY keep it until the entry's `definitionHash` changes.
+- `definitionHash` is opaque to an agent runtime: it compares an action's hash
+  only with that action's earlier one, as strings, and MUST accept a hash of any
+  length (an entry made before 0.8 carries 16 hex digits and a `definitionBytes`
+  field, which a runtime ignores). `surfacesHash` stays 64 bits: it is compared
+  across the whole page.
 
 #### 7.3.9 Fitting a Frame