oui-spec 0.8.0 → 0.11.0

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-D4czecOw.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-D4czecOw.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
@@ -121,4 +121,62 @@ declare function fitObservations(observations: OUIObservationSnapshot, budget: n
     cuts: OUIFitCut[];
 };
 
-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 };
+/**
+ * An action input that takes a file the person attached (OUI spec §7.3.11,
+ * ADR-0252 §2.13).
+ *
+ * The agent passes an attachment's id. The client resolves it, through its
+ * host's file area, to what the input declares it takes, before the action's
+ * handler runs:
+ *
+ * - `file`: a `File`, exactly what the person's own file choice produces;
+ * - `text`: the file's text, for an input that takes markup or JSON.
+ *
+ * Declared on a string schema:
+ * `{ type: 'string', format: 'oui-attachment', 'x-oui-attachment': { as: 'file', mediaTypes: ['image/png'] } }`.
+ * The request stays small: only the id travels.
+ */
+
+/** The JSON Schema `format` of an input that takes an attachment's id. */
+declare const OUI_ATTACHMENT_FORMAT = "oui-attachment";
+/** What an attachment input takes once resolved, and which files it accepts. */
+interface OUIAttachmentInput {
+    as: "file" | "text";
+    /** The media types it accepts; any when absent. A type ending in `/*` accepts the family. */
+    mediaTypes?: string[];
+}
+/** Whether a string is an attachment id: opaque, 8 to 64 of A–Z, a–z, 0–9, `_` and `-`. */
+declare function isAttachmentId(value: unknown): value is string;
+/** The same rule as a pattern, for a validator's format. */
+declare const ATTACHMENT_ID_PATTERN: RegExp;
+/** The attachment declaration of a schema, when it is an attachment input. */
+declare function attachmentInputOf(schema: JSONSchema | undefined): OUIAttachmentInput | null;
+/** Whether a media type is one an attachment input accepts. */
+declare function acceptsMediaType(input: OUIAttachmentInput, mediaType: string): boolean;
+/**
+ * Every attachment input of an action's input schema, by where its id sits in
+ * the params: a property (`["logo"]`), or each item of a list property
+ * (`["images", "*"]`). Only the input's own properties and their list items
+ * are looked at: a file is an argument of the action, not buried in its data.
+ */
+declare function attachmentInputs(schema: JSONSchema | undefined): Array<{
+    path: [string] | [string, "*"];
+    input: OUIAttachmentInput;
+}>;
+/**
+ * Where an action's input schema declares an attachment input anywhere other
+ * than a property of the input or the items of a list property: inside an
+ * object property, a list of lists, `anyOf`/`oneOf`/`allOf`, or anything a
+ * schema nests. Such an input is neither checked nor resolved, so an action
+ * declaring one is refused (§7.3.11). Each entry is a path in the schema, as
+ * `property.sub`, `property[]`, `property.anyOf[0]`.
+ */
+declare function misplacedAttachmentInputs(schema: JSONSchema | undefined): string[];
+/** Every attachment id an action's params name, with the input that takes it. */
+declare function attachmentIdsIn(schema: JSONSchema | undefined, params: Record<string, unknown>): Array<{
+    id: string;
+    property: string;
+    input: OUIAttachmentInput;
+}>;
+
+export { ATTACHMENT_ID_PATTERN, DEFINITION_HASH_HEX, FIT_LIST_STEPS, FIT_TEXT_CHARS, INDEX_DESCRIPTION_CHARS, INDEX_INPUT_CHARS, INDEX_INPUT_PROPERTIES, JSONSchema, OUIAction, OUIActionIndexEntry, type OUIAttachmentInput, OUIFitCut, OUIObservationSnapshot, OUISurface, OUISurfaceIndex, OUI_ATTACHMENT_FORMAT, OUI_DESCRIBE_ACTION, OUI_READ_ACTION, OUI_RUNTIME_SURFACE, acceptsMediaType, atPointer, attachmentIdsIn, attachmentInputOf, attachmentInputs, constantOf, definitionHash, discriminatorOf, firstSentence, fitObservations, indexEntry, isAttachmentId, jsonBytes, misplacedAttachmentInputs, pointerStep, pointerSteps, sortedJson, summarizeInput, surfaceIndex, surfacesHash, utf8Length, withoutTitleLeadIn };

package/dist/spec/index.js

@@ -1,3 +1,3 @@
-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-JRXQLNUL.js';
+export { ARGS_HASH_PATTERN, ATTACHMENT_ID_PATTERN, DEFINITION_HASH_HEX, FIT_LIST_STEPS, FIT_TEXT_CHARS, INDEX_DESCRIPTION_CHARS, INDEX_INPUT_CHARS, INDEX_INPUT_PROPERTIES, OUI_ATTACHMENT_FORMAT, OUI_DESCRIBE_ACTION, OUI_EFFECT_ACCESS, OUI_EFFECT_KINDS, OUI_PROTOCOL_EVENTS, OUI_READ_ACTION, OUI_RUNTIME_SURFACE, acceptsMediaType, argsHash, atPointer, attachmentIdsIn, attachmentInputOf, attachmentInputs, canonicalJson, constantOf, definitionHash, discriminatorOf, effectAccess, firstSentence, fitObservations, indexEntry, isAttachmentId, jsonBytes, misplacedAttachmentInputs, pointerStep, pointerSteps, requiresApproval, sortedJson, summarizeInput, surfaceIndex, surfacesHash, utf8Length, withoutTitleLeadIn } from '../chunk-G4HLDVAI.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{surface-runtime-bXSSONF4.d.cts → surface-runtime-C3883XHJ.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-D4czecOw.cjs';
-import { S as SocketLike, e as OUITransportConfig } from './websocket-EzQq1mxO.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;
@@ -239,7 +249,35 @@ interface SurfaceRuntimeOptions {
      * acknowledge — is a repeat answered again. Default 8000 ms.
      */
     reanswerAfterMs?: number;
+    /**
+     * The host's file area, for actions whose input takes a file the person
+     * attached (`format: "oui-attachment"`, §7.3.11). The agent sends the
+     * attachment's id; before the handler runs, the runtime resolves it to what
+     * the input declares (`as`): a `File`, or the file's text. The host checks
+     * the file is the person's. Without it, such an action is refused.
+     */
+    attachments?: AttachmentResolver;
+}
+/** A file's text as a host resolves it, with what the file is, so its type can be checked (§7.3.11). */
+interface AttachmentText {
+    name: string;
+    mediaType: string;
+    text: string;
+}
+/** How a client turns an attachment's id into what an action takes (§7.3.11). */
+interface AttachmentResolver {
+    /**
+     * The file, as a `File`, or as its text with its name and type. A `File`
+     * for an input that takes text is read as text once its type is checked.
+     * A bare string is taken only by an input that accepts any type: there is
+     * nothing to check it against. Rejects with an `Error` whose message says
+     * why (it is not the person's, it was removed, it is still being checked),
+     * which the agent is told.
+     */
+    resolve(id: string, as: "file" | "text"): Promise<File | AttachmentText | string>;
 }
+/** The most files one list input takes (§7.3.11). */
+declare const ATTACHMENT_LIST_MAX = 20;
 interface MountedSurface {
     readonly surfaceId: string;
     /** Record an observation value. A no-op once unmounted. */
@@ -293,4 +331,4 @@ 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 SurfaceForm as e, type SurfaceRuntime as f, type SurfaceRuntimeOptions as g, createSurfaceRuntime as h, defineSurface as i };
+export { ATTACHMENT_LIST_MAX as A, type DefinedSurface as D, type MountedSurface as M, type OUIBranded as O, type SettleOptions as S, type ActionDefinition as a, type ActionHandlerResult as b, type ActionPollingConfig as c, type AttachmentResolver as d, type AttachmentText as e, type ObservationDefinition as f, type SurfaceDefinition as g, type SurfaceForm as h, type SurfaceRuntime as i, type SurfaceRuntimeOptions as j, createSurfaceRuntime as k, defineSurface as l };

package/dist/{surface-runtime-BsRS0EV1.d.ts → surface-runtime-Da1FSjNF.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-D4czecOw.js';
-import { S as SocketLike, e as OUITransportConfig } from './websocket-BcWDNt_V.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;
@@ -239,7 +249,35 @@ interface SurfaceRuntimeOptions {
      * acknowledge — is a repeat answered again. Default 8000 ms.
      */
     reanswerAfterMs?: number;
+    /**
+     * The host's file area, for actions whose input takes a file the person
+     * attached (`format: "oui-attachment"`, §7.3.11). The agent sends the
+     * attachment's id; before the handler runs, the runtime resolves it to what
+     * the input declares (`as`): a `File`, or the file's text. The host checks
+     * the file is the person's. Without it, such an action is refused.
+     */
+    attachments?: AttachmentResolver;
+}
+/** A file's text as a host resolves it, with what the file is, so its type can be checked (§7.3.11). */
+interface AttachmentText {
+    name: string;
+    mediaType: string;
+    text: string;
+}
+/** How a client turns an attachment's id into what an action takes (§7.3.11). */
+interface AttachmentResolver {
+    /**
+     * The file, as a `File`, or as its text with its name and type. A `File`
+     * for an input that takes text is read as text once its type is checked.
+     * A bare string is taken only by an input that accepts any type: there is
+     * nothing to check it against. Rejects with an `Error` whose message says
+     * why (it is not the person's, it was removed, it is still being checked),
+     * which the agent is told.
+     */
+    resolve(id: string, as: "file" | "text"): Promise<File | AttachmentText | string>;
 }
+/** The most files one list input takes (§7.3.11). */
+declare const ATTACHMENT_LIST_MAX = 20;
 interface MountedSurface {
     readonly surfaceId: string;
     /** Record an observation value. A no-op once unmounted. */
@@ -293,4 +331,4 @@ 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 SurfaceForm as e, type SurfaceRuntime as f, type SurfaceRuntimeOptions as g, createSurfaceRuntime as h, defineSurface as i };
+export { ATTACHMENT_LIST_MAX as A, type DefinedSurface as D, type MountedSurface as M, type OUIBranded as O, type SettleOptions as S, type ActionDefinition as a, type ActionHandlerResult as b, type ActionPollingConfig as c, type AttachmentResolver as d, type AttachmentText as e, type ObservationDefinition as f, type SurfaceDefinition as g, type SurfaceForm as h, type SurfaceRuntime as i, type SurfaceRuntimeOptions as j, createSurfaceRuntime as k, defineSurface as l };

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-EzQq1mxO.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-EzQq1mxO.cjs';
-import '../types-D4czecOw.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-BcWDNt_V.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-BcWDNt_V.js';
-import '../types-D4czecOw.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-D4czecOw.d.ts → types-DLOa7CWj.d.cts}

@@ -311,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-D4czecOw.d.cts → types-DLOa7CWj.d.ts}

@@ -311,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-BcWDNt_V.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-D4czecOw.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-EzQq1mxO.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-D4czecOw.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.8.0",
+  "version": "0.11.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
 
@@ -856,6 +858,36 @@ them now (including what it narrowed at run time):
 - For any other value, data is `{ value, fit? }`, fitted as in §7.3.9.
 - An unknown surface, observation or path is `NOT_FOUND`.
 
+#### 7.3.11 Inputs That Take an Attached File
+
+An action input MAY take a file the user attached to their conversation with the agent. It is a string schema with the format `oui-attachment` and a declaration of what the action takes:
+
+```json
+{
+  "type": "string",
+  "format": "oui-attachment",
+  "x-oui-attachment": {
+    "as": "file",
+    "mediaTypes": ["image/png", "image/jpeg"]
+  }
+}
+```
+
+- `as` is `file` (the action receives a `File`, as the user's own file choice produces) or `text` (the action receives the file's text, for an input that takes markup or JSON).
+- `mediaTypes` lists the types the input accepts; a type ending in `/*` accepts the family. Without it, any file is accepted.
+- Such an input is a property of the action's input, or the items of a list property. It is nowhere else: not inside an object property, a list of lists, or an `anyOf`, `oneOf` or `allOf` alternative.
+
+**Requirements:**
+
+- The agent runtime MUST send the attachment's id, never the file's content. An id is 8 to 64 characters of `A–Z`, `a–z`, `0–9`, `_` and `-`.
+- The agent runtime MUST check, before it sends the request, that each file is one of the conversation's and of a type the input accepts.
+- The client MUST resolve each id through its host before the handler runs. The host MUST check that the file is the user's.
+- The client MUST check the file's type against `mediaTypes` for `text` inputs as well as `file` inputs. A host resolving a `text` input gives the file, or its text with its name and type; text whose type is unknown is taken only by an input that accepts any type.
+- The client MUST refuse the request without running the handler when an id cannot be resolved or names a file of a type the input does not accept (`ATTACHMENT_UNAVAILABLE`), when a list input names more than 20 files (`ATTACHMENT_UNAVAILABLE`), when it has no way to resolve files (`ATTACHMENTS_UNSUPPORTED`), and when the action declares an attachment input anywhere other than where it may be (`ATTACHMENT_INPUT_UNSUPPORTED`).
+- A file named more than once in one request SHOULD be resolved once, and a list's files a few at a time.
+- An approval (§7.3.6) is of the request as sent: it binds the file by its id.
+- The action's index entry (§7.3.8) MUST describe the input as a file, not as a string.
+
 ### 7.4 Observation Updates
 
 #### 7.4.1 Push Update