oui-spec 0.5.0 → 0.6.0

package/dist/types-CmJb1BQ8.d.cts

@@ -0,0 +1,403 @@
+/**
+ * Approvals: an irreversible action runs only on an approval the user gave,
+ * bound to the exact request.
+ *
+ * An agent runtime stops at an action that needs approval and shows the user
+ * a confirmation. Its approval store issues a single-use grant when the user
+ * confirms, and the request that then reaches the tab carries `approval:
+ * { approvalId, argsHash }`. The surface runtime runs the action only when
+ * that matches a grant this tab received from the user's own confirmation.
+ *
+ * Everything that checks a request computes the same args hash: SHA-256 over
+ * the RFC 8785 (JCS) canonical JSON of its params, lowercase hex. The
+ * published vectors (`oui-spec/approval-vectors.json`) hold every
+ * implementation, in any language, to it.
+ */
+/**
+ * What using an action does. One vocabulary for every kind of action, so an
+ * action is told apart by what it changes:
+ *
+ * | Effect | What it changes | Access |
+ * |---|---|---|
+ * | `view`, `selection`, `navigate`, `open` | What is shown | read |
+ * | `edit` | The document, one undo step | write |
+ * | `file` | Imports or exports a file | write |
+ * | `mutate` | Backend data, through an API operation | write |
+ * | `job` | Starts work that outlives the call | write |
+ * | `transaction` | An irreversible external act: an order, a payment, a send, a publish | write, approved |
+ */
+type OUIEffectKind = "view" | "selection" | "navigate" | "open" | "edit" | "file" | "mutate" | "job" | "transaction";
+/** Every effect, in the order of the table above. */
+declare const OUI_EFFECT_KINDS: readonly OUIEffectKind[];
+/** Whether an effect only changes what is shown, or changes something. */
+declare const OUI_EFFECT_ACCESS: Readonly<Record<OUIEffectKind, "read" | "write">>;
+/** `read` or `write`. An action that declares no effect is a `write`: nothing says it only shows. */
+declare function effectAccess(effect: OUIEffectKind | undefined): "read" | "write";
+/**
+ * Whether running an action needs the user's approval of the exact request: a
+ * `transaction` always, and a `write` declared destructive. An agent
+ * runtime's policy may require it of more; nothing waives these.
+ */
+declare function requiresApproval(effect: OUIEffectKind | undefined, destructive?: boolean): boolean;
+/** What a request for an approved action carries. */
+interface OUIActionApproval {
+    approvalId: string;
+    /** `argsHash(params)` of the request the user approved. */
+    argsHash: string;
+}
+/** A grant this tab holds: the user approved this request here. */
+interface OUIApprovalGrant extends OUIActionApproval {
+    /** Epoch ms after which the grant no longer admits anything. */
+    expiresAt: number;
+}
+/** An args hash: 64 lowercase hex digits. */
+declare const ARGS_HASH_PATTERN: RegExp;
+/**
+ * The RFC 8785 canonical form of a JSON value:
+ * - object members sorted by their names' UTF-16 code units, with no
+ *   whitespace;
+ * - numbers in ECMAScript's shortest round-trip form (`-0` is `0`);
+ * - strings escaped as ECMAScript's `JSON.stringify` escapes them.
+ *
+ * The value must be I-JSON (RFC 7493): anything JSON cannot carry — `NaN`,
+ * infinities, `undefined` outside an object member, a bigint, a function, a
+ * symbol, a class instance, or a string with a lone surrogate — is refused
+ * rather than hashed as something the other end never receives. An object
+ * member whose value is `undefined` is left out, as it is on the wire.
+ */
+declare function canonicalJson(value: unknown): string;
+/** SHA-256 of the canonical JSON of a request's params, lowercase hex. Runs wherever WebCrypto does. */
+declare function argsHash(params: unknown): Promise<string>;
+
+/**
+ * OUI — Open UI Specification
+ *
+ * The machine-readable contract for agent-controllable user interfaces.
+ * Any UI application that implements this interface can be controlled by
+ * any OUI-compatible agent runtime.
+ */
+/** JSON Schema type (subset used by OUI) */
+type JSONSchema = {
+    type?: string | string[];
+    properties?: Record<string, JSONSchema>;
+    items?: JSONSchema;
+    required?: string[];
+    enum?: (string | number | boolean)[];
+    description?: string;
+    default?: unknown;
+    oneOf?: JSONSchema[];
+    anyOf?: JSONSchema[];
+    allOf?: JSONSchema[];
+    const?: unknown;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    additionalProperties?: boolean | JSONSchema;
+};
+/**
+ * A Surface is a controllable boundary within an application.
+ * It declares what an agent can do (actions), what it can observe (state),
+ * and when it's available (activation conditions).
+ *
+ * Think of it as "one page" or "one feature" of an application, described
+ * in a way that an agent can understand and operate.
+ */
+interface OUISurface {
+    /** Unique identifier for this surface (e.g., 'dataviz-wizard', 'document-editor') */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what this surface does — included in agent context */
+    description: string;
+    /** Version of this surface's contract (semver) */
+    version?: string;
+    /** Actions the agent can invoke on this surface */
+    actions: OUIAction[];
+    /** Observable state the agent can read */
+    observations?: OUIObservation[];
+    /** When this surface is active/available */
+    activation?: OUIActivation;
+    /** Additional metadata for agent context */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Declarative polling configuration for async actions.
+ * The OUI runtime in the browser manages the polling lifecycle automatically
+ * after the action handler returns its dispatch result.
+ */
+interface OUIActionPolling {
+    /** How often to check (milliseconds) */
+    intervalMs: number;
+    /** Max poll attempts before giving up (optional) */
+    maxAttempts?: number;
+    /** Max total duration before giving up in ms (alternative to maxAttempts) */
+    maxDurationMs?: number;
+    /**
+     * Subscribe to a realtime event instead of polling.
+     * If provided, the runtime listens for this event instead of using setInterval.
+     * More efficient when realtime infrastructure exists.
+     */
+    subscribe?: {
+        /** Event name to listen for */
+        event: string;
+        /**
+         * Filter to match the event. Values prefixed with '$dispatchResult.'
+         * are resolved from the handler's return value.
+         * Example: { jobId: '$dispatchResult.jobId' }
+         */
+        filter?: Record<string, unknown>;
+    };
+}
+/**
+ * An Action is a single operation an agent can perform on a surface.
+ * Each action becomes a "tool" that the LLM can call.
+ *
+ * The action's handler executes in the UI (or API) and returns a result
+ * that the agent sees as the tool's output.
+ */
+interface OUIAction {
+    /** Unique action identifier (becomes the tool name) */
+    id: string;
+    /** Human-readable description — this is what the LLM reads to decide when to use it */
+    description: string;
+    /** The action's name as a person reads it, for a confirmation the user approves. */
+    title?: string;
+    /**
+     * What using the action does. A `transaction` runs only on the user's
+     * approval of the exact request (see `requiresApproval`). Undeclared counts
+     * as a write.
+     */
+    effect?: OUIEffectKind;
+    /** JSON Schema for the action's input parameters */
+    input: JSONSchema;
+    /** JSON Schema for the action's return value (optional — agent still gets the result) */
+    output?: JSONSchema;
+    /**
+     * Destructive: the action removes or replaces something the person made.
+     * Unless its effect only reads, it runs only on the user's approval of the
+     * exact request, which the surface runtime checks before it runs.
+     */
+    confirm?: boolean;
+    /** If true, the action is async — returns immediately with a job/tracking ID */
+    async?: boolean;
+    /** Declarative polling configuration — runtime manages the polling lifecycle after dispatch */
+    polling?: OUIActionPolling;
+    /** Human-readable hint about when this action is appropriate to use */
+    usage?: string;
+    /**
+     * Preconditions that should be met before this action is called.
+     * Expressed as a description (for the LLM) not as executable logic.
+     */
+    preconditions?: string;
+    /** Estimated duration hint (e.g., "instant", "2-5s", "30-120s") */
+    estimatedDuration?: string;
+    /** Tags for categorization */
+    tags?: string[];
+}
+/**
+ * An Observation is a piece of application state that the agent can read.
+ * Observations are pushed to the agent in real-time as the app state changes,
+ * giving it situational awareness without needing screenshots.
+ */
+interface OUIObservation {
+    /** Unique identifier for this observation */
+    id: string;
+    /** Description of what this observation represents */
+    description: string;
+    /** JSON Schema for the observation's value */
+    schema: JSONSchema;
+    /** How frequently this observation updates */
+    updateFrequency?: "realtime" | "on-change" | "polling";
+}
+/**
+ * Activation conditions — when a surface is available to the agent.
+ * A surface might only be active on a specific page, when certain
+ * entities are loaded, or under specific application states.
+ */
+interface OUIActivation {
+    /** URL path(s) where this surface is active */
+    routes?: string | string[];
+    /** Entity type/ID that must be present for this surface to activate */
+    entity?: {
+        type: string;
+        id?: string;
+    };
+    /** Custom predicate description (for documentation, not execution) */
+    condition?: string;
+}
+/**
+ * A request from the agent runtime to execute an action on a surface.
+ */
+interface OUIActionRequest {
+    /** Unique request ID for correlation */
+    requestId: string;
+    /** Which surface this request targets */
+    surfaceId: string;
+    /** Which action to invoke */
+    actionId: string;
+    /** The action's input parameters (validated against the action's input schema) */
+    params: Record<string, unknown>;
+    /** Timestamp of the request */
+    timestamp: number;
+    /**
+     * 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
+     * the tab received from the user's own confirmation, for exactly `params`.
+     */
+    approval?: OUIActionApproval;
+    /**
+     * The `surfacesHash` of the surfaces the agent runtime already holds for
+     * this client: from its snapshot, or from an earlier result. A client whose
+     * surfaces still hash to this answers without `surfaces`, so a result
+     * carries the client's surfaces only when they changed (§7.3.4).
+     */
+    knownSurfaces?: string;
+}
+/**
+ * Why a client's answer is shorter than the result it produced: the receiving
+ * side refused the full answer (too large, or otherwise not accepted), so the
+ * client sent it again without the parts named in `omitted`. The action's own
+ * outcome — `success`, `error`, and `data` unless omitted — is still the one
+ * that happened (§7.3.6).
+ */
+interface OUIResultDelivery {
+    trimmed: true;
+    /** 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">;
+}
+/**
+ * The result of an action execution, returned from the surface to the agent.
+ */
+interface OUIActionResult {
+    /** Correlates to the request */
+    requestId: string;
+    /** Whether the action succeeded */
+    success: boolean;
+    /** The action's return data (if successful) */
+    data?: unknown;
+    /** Error information (if failed) */
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    /** Progress indicator for interim polling results (0-100) */
+    progress?: number;
+    /** Whether this is an interim update (polling still in progress) or final */
+    interim?: boolean;
+    /** Duration of execution in milliseconds */
+    durationMs?: number;
+    /** Timestamp of the result */
+    timestamp: number;
+    /**
+     * The surfaces active on the client once the action's effects settled.
+     *
+     * An action can change what the agent is able to do next: navigating
+     * unmounts one page's surfaces and mounts another's. Without this, the agent
+     * would act on the capability set it had before the action, which is the
+     * set the action just replaced.
+     */
+    surfaces?: OUISurface[];
+    /** Latest observation values per surface once the action's effects settled. */
+    observations?: OUIObservationSnapshot;
+    /**
+     * The hash of the client's surfaces once the action's effects settled
+     * (`surfacesHash`). Always present from a client that sends it; `surfaces`
+     * is then present only when this differs from the request's
+     * `knownSurfaces`, and an agent runtime that holds surfaces with this hash
+     * keeps using them.
+     */
+    surfacesHash?: string;
+    /** Present when this answer was trimmed to be delivered (§7.3.6). */
+    delivery?: OUIResultDelivery;
+    /**
+     * False when the client's deadline passed before its UI settled, so
+     * `surfaces` and `observations` may still be changing. Absent or true
+     * otherwise.
+     */
+    settled?: boolean;
+}
+/** Latest observation values, keyed by surface id and then observation id. */
+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.
+ */
+interface OUISurfaceSnapshot {
+    surfaces: OUISurface[];
+    observations: OUIObservationSnapshot;
+    /**
+     * `surfacesHash(surfaces)`: what an agent runtime sends back as a request's
+     * `knownSurfaces`, so the client's answer need not repeat surfaces the
+     * runtime already holds.
+     */
+    surfacesHash?: string;
+}
+/**
+ * An observation update pushed from the surface to the agent.
+ */
+interface OUIObservationUpdate {
+    /** Which surface this observation belongs to */
+    surfaceId: string;
+    /** Which observation updated */
+    observationId: string;
+    /** The new value */
+    value: unknown;
+    /** Timestamp of the update */
+    timestamp: number;
+}
+/**
+ * Surface registration event — sent when a surface becomes active.
+ */
+interface OUISurfaceRegistration {
+    /** The full surface manifest */
+    surface: OUISurface;
+    /** Timestamp of registration */
+    timestamp: number;
+}
+/**
+ * Surface deregistration event — sent when a surface becomes inactive.
+ */
+interface OUISurfaceDeregistration {
+    /** Which surface is being deregistered */
+    surfaceId: string;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * All protocol events exchanged between agent runtime and surfaces.
+ */
+type OUIProtocolEvent = {
+    type: "surface:register";
+    payload: OUISurfaceRegistration;
+} | {
+    type: "surface:deregister";
+    payload: OUISurfaceDeregistration;
+} | {
+    type: "action:request";
+    payload: OUIActionRequest;
+} | {
+    type: "action:result";
+    payload: OUIActionResult;
+} | {
+    type: "observation:update";
+    payload: OUIObservationUpdate;
+};
+/**
+ * Protocol event type strings (for type guards and routing).
+ */
+declare const OUI_PROTOCOL_EVENTS: {
+    readonly SURFACE_REGISTER: "surface:register";
+    readonly SURFACE_DEREGISTER: "surface:deregister";
+    readonly ACTION_REQUEST: "action:request";
+    readonly ACTION_RESULT: "action:result";
+    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 };