oui-spec 0.6.0 → 0.7.0

package/README.md

@@ -64,13 +64,25 @@ change that: navigating unmounts one page's surfaces and mounts another's. An
 agent that only knew the capability set from before the action would be acting
 on the page it just left.
 
-Surfaces are heavy (every action's schema), so a result repeats them only when
-the agent runtime does not hold them: the runtime sends the `surfacesHash` it
-holds as the request's `knownSurfaces`, and the result carries `surfaces` only
-when the client's hash differs. A result the receiver refuses (too large,
-invalid) is acknowledged as refused, and the client sends it again trimmed,
-with `delivery` saying what was left out and why: the agent always learns the
-action's outcome. A request is acknowledged on receipt when the sender asks,
+Action definitions are heavy (every action's schema: several hundred KB on a
+studio page), so a client does not send them. It sends an **index**: one entry
+per action, with its title, the first sentence of its description, its effect
+and a one-line summary of what it takes. An agent runtime fetches the
+definition it needs with the runtime's own `oui.describe`, and reads state that
+did not fit with `oui.read`. This is the index form: pass `form: "index"` to
+`createSurfaceRuntime` once the agent runtime reads it. Until 1.0 the default is
+`"full"`, which sends every definition as earlier versions did.
+
+A result repeats the index only when the agent runtime does not hold it: the
+runtime sends the `surfacesHash` it holds as the request's `knownSurfaces`, and
+the result carries `index` only when the client's hash differs.
+
+What a client sends is fitted to a byte budget before it is sent (480 KB for a
+result, 256 KB for a snapshot): long lists are cut first, then long texts, and
+`fit` says where, so the rest can be read. A result the receiver still refuses
+is acknowledged as refused, and the client sends it again trimmed a step at a
+time (the index, then the observations, then the data), with `delivery` saying
+what was left out and why: the agent always learns the action's outcome. A request is acknowledged on receipt when the sender asks,
 and a repeat of a request whose answer is on its way gets no second copy.
 
 An async action (`async: true`) is acknowledged at once with `interim: true`,
@@ -173,7 +185,7 @@ function CounterPage() {
 }
 ```
 
-`runtime.snapshot()` returns `{ surfaces, observations, surfacesHash }` for
+`runtime.snapshot()` returns `{ surfaces, observations, surfacesHash }` (or `index` in place of `surfaces`, in index form) for
 everything mounted. An agent runtime that keeps no registry of its own can take it with
 each request (for example, with each chat turn); set `announce: false` and the
 runtime sends nothing but results over the socket.
@@ -256,7 +268,7 @@ sequenceDiagram
     WS->>Browser: oui:dispatch
     Note over Browser: Handler runs once (de-duplicated by requestId)
     Note over Browser: Waits until the UI settles
-    Browser->>WS: oui:action:result { requestId, success, data, observations, surfacesHash, surfaces if changed }
+    Browser->>WS: oui:action:result { requestId, success, data, observations, surfacesHash, surfaces or index if changed }
     WS->>Agent: result for requestId
 ```
 
@@ -736,6 +748,7 @@ They even share JSON Schema for parameter validation — a deliberate design cho
 - [x] `createSurfaceRuntime()` — client-side record of mounted surfaces; every request answered with a result and the snapshot after it
 - [x] Approvals — `transaction` and destructive actions run only on a grant from the user's own confirmation, bound to the exact params (0.5.0)
 - [x] Results carry surfaces only when they changed (`knownSurfaces` / `surfacesHash`), and a refused result is sent again trimmed, saying why (0.6.0)
+- [x] The index form: a client sends an index of its actions, definitions are fetched with `oui.describe`, state is read with `oui.read`, and every frame is fitted to a byte budget (0.7.0)
 - [ ] `oui-spec/devtools` — Surface inspector / debugger
 - [ ] `oui-spec/vue` — Vue bindings
 - [ ] `oui-spec/validator` — Runtime schema validation
@@ -747,20 +760,15 @@ They even share JSON Schema for parameter validation — a deliberate design cho
 
 Contributions welcome. Please read the spec at [`spec/OUI-SPEC-v0.1.md`](./spec/OUI-SPEC-v0.1.md) before proposing changes to ensure alignment with the design principles.
 
+`oui-spec` lives in the [OUI monorepo](https://github.com/wesreid/oui) beside the `@ouispec/*` packages. See its [CONTRIBUTING.md](https://github.com/wesreid/oui/blob/main/CONTRIBUTING.md):
+
 ```bash
-# Clone and install
 git clone https://github.com/wesreid/oui.git
 cd oui
-npm install
-
-# Build
-npm run build
-
-# Run tests
-npm test
-
-# Typecheck
-npm run typecheck
+pnpm install
+pnpm --filter oui-spec build
+pnpm --filter oui-spec test
+pnpm --filter oui-spec typecheck
 ```
 
 ---

package/dist/chunk-2CPOHQGI.cjs

@@ -0,0 +1,463 @@
+'use strict';
+
+// src/spec/types.ts
+var OUI_PROTOCOL_EVENTS = {
+  SURFACE_REGISTER: "surface:register",
+  SURFACE_DEREGISTER: "surface:deregister",
+  ACTION_REQUEST: "action:request",
+  ACTION_RESULT: "action:result",
+  OBSERVATION_UPDATE: "observation:update"
+};
+
+// src/spec/approval.ts
+var OUI_EFFECT_KINDS = [
+  "view",
+  "selection",
+  "navigate",
+  "open",
+  "edit",
+  "file",
+  "mutate",
+  "job",
+  "transaction"
+];
+var OUI_EFFECT_ACCESS = {
+  view: "read",
+  selection: "read",
+  navigate: "read",
+  open: "read",
+  edit: "write",
+  file: "write",
+  mutate: "write",
+  job: "write",
+  transaction: "write"
+};
+function effectAccess(effect) {
+  return effect === void 0 ? "write" : OUI_EFFECT_ACCESS[effect];
+}
+function requiresApproval(effect, destructive) {
+  if (effect === "transaction") return true;
+  return !!destructive && effectAccess(effect) === "write";
+}
+var ARGS_HASH_PATTERN = /^[0-9a-f]{64}$/;
+function canonicalJson(value) {
+  return serialize(value, "$");
+}
+async function argsHash(params) {
+  const canonical = canonicalJson(params);
+  const subtle = await webCrypto();
+  const digest = await subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(canonical)
+  );
+  let hex = "";
+  for (const byte of new Uint8Array(digest))
+    hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}
+async function webCrypto() {
+  const global = globalThis.crypto?.subtle;
+  if (global) return global;
+  const nodeCrypto = "node:crypto";
+  try {
+    const mod = await import(
+      /* @vite-ignore */
+      nodeCrypto
+    );
+    if (mod.webcrypto?.subtle) return mod.webcrypto.subtle;
+  } catch {
+  }
+  throw new Error(
+    "[OUI] argsHash needs WebCrypto (crypto.subtle), which this runtime does not provide"
+  );
+}
+function refuse(path, what) {
+  throw new TypeError(`[OUI] ${path} is not I-JSON: ${what}`);
+}
+function serialize(value, path) {
+  switch (typeof value) {
+    case "string":
+      return quote(value, path);
+    case "number":
+      if (!Number.isFinite(value)) refuse(path, String(value));
+      return JSON.stringify(value);
+    case "boolean":
+      return value ? "true" : "false";
+    case "object": {
+      if (value === null) return "null";
+      if (Array.isArray(value)) {
+        return `[${value.map((item, i) => serialize(item, `${path}[${i}]`)).join(",")}]`;
+      }
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) {
+        refuse(path, `a ${proto?.constructor?.name ?? "non-plain"} object`);
+      }
+      const record = value;
+      const keys = Object.keys(record).filter((k) => record[k] !== void 0).sort();
+      return `{${keys.map(
+        (k) => `${quote(k, `${path} key`)}:${serialize(record[k], `${path}.${k}`)}`
+      ).join(",")}}`;
+    }
+    default:
+      return refuse(path, typeof value);
+  }
+}
+function quote(text, path) {
+  for (let i = 0; i < text.length; i++) {
+    const unit = text.charCodeAt(i);
+    if (unit >= 55296 && unit <= 56319) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 56320 && next <= 57343) {
+        i++;
+        continue;
+      }
+      refuse(path, `a lone surrogate at ${i}`);
+    }
+    if (unit >= 56320 && unit <= 57343)
+      refuse(path, `a lone surrogate at ${i}`);
+  }
+  return JSON.stringify(text);
+}
+
+// src/spec/surfaces-hash.ts
+var PREFIX = "fnv1a64:";
+function surfacesHash(surfaces) {
+  return PREFIX + fnv1a64(sortedJson(surfaces));
+}
+function sortedJson(value) {
+  return JSON.stringify(sortKeys(value)) ?? "null";
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      const member = value[key];
+      if (member !== void 0) out[key] = sortKeys(member);
+    }
+    return out;
+  }
+  return value;
+}
+function fnv1a64(text) {
+  let hi = 3421674724;
+  let lo = 2216829733;
+  for (let i = 0; i < text.length; i++) {
+    lo = (lo ^ text.charCodeAt(i)) >>> 0;
+    const loProduct = lo * 435;
+    const carry = Math.floor(loProduct / 4294967296);
+    const newLo = loProduct >>> 0;
+    hi = Math.imul(hi, 435) + Math.imul(lo, 256) + carry >>> 0;
+    lo = newLo;
+  }
+  return hex32(hi) + hex32(lo);
+}
+function hex32(n) {
+  return (n >>> 0).toString(16).padStart(8, "0");
+}
+
+// src/spec/index-form.ts
+var INDEX_DESCRIPTION_CHARS = 160;
+var INDEX_INPUT_CHARS = 120;
+var INDEX_INPUT_PROPERTIES = 6;
+var INDEX_ENUM_VALUES = 4;
+var OUI_RUNTIME_SURFACE = "oui";
+var OUI_DESCRIBE_ACTION = "describe";
+var OUI_READ_ACTION = "read";
+function utf8Length(text) {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 128) bytes += 1;
+    else if (code < 2048) bytes += 2;
+    else if (code >= 55296 && code <= 56319) {
+      bytes += 4;
+      i++;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+function jsonBytes(value) {
+  const json = JSON.stringify(value);
+  return json === void 0 ? 0 : utf8Length(json);
+}
+function clip(text, max) {
+  return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}\u2026`;
+}
+function firstSentence(text) {
+  const line = text.replace(/\s+/g, " ").trim();
+  const end = line.search(/[.!?](?= [A-Z0-9"'([])/);
+  return clip(
+    end >= 0 ? line.slice(0, end + 1) : line,
+    INDEX_DESCRIPTION_CHARS
+  );
+}
+function typeOf(schema) {
+  const t = schema.type;
+  return Array.isArray(t) ? t.join("|") : t ?? "";
+}
+function unitOf(schema) {
+  const unit = schema["x-unit"];
+  return typeof unit === "string" && unit ? ` ${unit}` : "";
+}
+function unionOf(schema) {
+  const members = schema.oneOf ?? schema.anyOf;
+  return members && members.length > 0 ? members : null;
+}
+function discriminatorOf(members) {
+  const first = members[0]?.properties;
+  if (!first) return null;
+  for (const name of Object.keys(first)) {
+    const constants = members.map((m) => constantOf(m.properties?.[name]));
+    if (constants.every((c) => c !== void 0) && new Set(constants).size === members.length)
+      return name;
+  }
+  return null;
+}
+function constantOf(schema) {
+  if (!schema) return void 0;
+  if (typeof schema.const === "string" || typeof schema.const === "number" || typeof schema.const === "boolean") {
+    return schema.const;
+  }
+  return schema.enum?.length === 1 ? schema.enum[0] : void 0;
+}
+function valueSummary(schema) {
+  const constant = constantOf(schema);
+  if (constant !== void 0 && !schema.enum) return JSON.stringify(constant);
+  if (schema.enum) {
+    const shown = schema.enum.slice(0, INDEX_ENUM_VALUES).map(String).join("|");
+    return schema.enum.length > INDEX_ENUM_VALUES ? `${shown}|\u2026(${schema.enum.length})` : shown;
+  }
+  const union = unionOf(schema);
+  if (union) return `one of ${union.length}`;
+  const type = typeOf(schema);
+  if (type === "number" || type === "integer") {
+    const { minimum: min, maximum: max } = schema;
+    const range = min !== void 0 && max !== void 0 ? ` ${min}\u2013${max}` : min !== void 0 ? ` \u2265${min}` : max !== void 0 ? ` \u2264${max}` : "";
+    return `${type}${range}${unitOf(schema)}`;
+  }
+  if (type === "string")
+    return schema.format ? `string(${schema.format})` : "string";
+  if (type === "array")
+    return schema.items ? `list of ${valueSummary(schema.items)}` : "list";
+  if (type === "object") {
+    const n = Object.keys(schema.properties ?? {}).length;
+    return n > 0 ? `object(${n})` : "object";
+  }
+  return type || "any";
+}
+function summarizeInput(schema) {
+  if (!schema) return "none";
+  const union = unionOf(schema);
+  if (union) {
+    const by = discriminatorOf(union);
+    return clip(
+      `one of ${union.length} shapes${by ? ` by ${by}` : ""}`,
+      INDEX_INPUT_CHARS
+    );
+  }
+  const properties = schema.properties ?? {};
+  const names = Object.keys(properties);
+  if (names.length === 0)
+    return typeOf(schema) && typeOf(schema) !== "object" ? valueSummary(schema) : "none";
+  const required = new Set(schema.required ?? []);
+  const ordered = [
+    ...names.filter((n) => required.has(n)),
+    ...names.filter((n) => !required.has(n))
+  ];
+  const shown = ordered.slice(0, INDEX_INPUT_PROPERTIES);
+  const more = ordered.length - shown.length;
+  const parts = shown.map(
+    (n) => `${n}${required.has(n) ? "" : "?"}: ${valueSummary(properties[n])}`
+  );
+  if (more > 0) parts.push(`+${more} more`);
+  return clip(parts.join(", "), INDEX_INPUT_CHARS);
+}
+function definitionHash(action) {
+  return fnv1a64(sortedJson(action));
+}
+function indexEntry(action) {
+  return {
+    id: action.id,
+    ...action.title ? { title: action.title } : {},
+    description: firstSentence(action.description),
+    ...action.effect !== void 0 ? { effect: action.effect } : {},
+    ...action.confirm ? { confirm: true } : {},
+    ...action.async ? { async: true } : {},
+    ...action.estimatedDuration ? { estimatedDuration: action.estimatedDuration } : {},
+    ...action.polling?.maxDurationMs !== void 0 ? { maxDurationMs: action.polling.maxDurationMs } : {},
+    input: summarizeInput(action.input),
+    definitionHash: definitionHash(action),
+    definitionBytes: jsonBytes(action)
+  };
+}
+function surfaceIndex(surface) {
+  return {
+    id: surface.id,
+    name: surface.name,
+    description: surface.description,
+    ...surface.version !== void 0 ? { version: surface.version } : {},
+    ...surface.observations ? { observations: surface.observations } : {},
+    index: surface.actions.map(indexEntry)
+  };
+}
+
+// src/spec/fit.ts
+var FIT_LIST_STEPS = [200, 50, 20, 5, 0];
+var FIT_TEXT_CHARS = 2e3;
+function pointerStep(pointer, key) {
+  return `${pointer}/${String(key).replace(/~/g, "~0").replace(/\//g, "~1")}`;
+}
+function pointerSteps(pointer) {
+  if (pointer === "") return [];
+  if (!pointer.startsWith("/"))
+    throw new Error(
+      `"${pointer}" is not a JSON Pointer: it must be "" or start with "/"`
+    );
+  return pointer.slice(1).split("/").map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+function atPointer(value, pointer) {
+  let at = value;
+  for (const step of pointerSteps(pointer)) {
+    if (Array.isArray(at)) {
+      at = /^(0|[1-9]\d*)$/.test(step) ? at[Number(step)] : void 0;
+    } else if (at && typeof at === "object") {
+      at = Object.prototype.hasOwnProperty.call(at, step) ? at[step] : void 0;
+    } else return void 0;
+    if (at === void 0) return void 0;
+  }
+  return at;
+}
+function slots(observations, want) {
+  const found = [];
+  const walk = (holder, key, surface, observation, path) => {
+    const value = holder[key];
+    if (Array.isArray(value)) {
+      if (want === "list")
+        found.push({ holder, key, surface, observation, path });
+      value.forEach(
+        (_, i) => walk(value, i, surface, observation, pointerStep(path, i))
+      );
+    } else if (value && typeof value === "object") {
+      for (const k of Object.keys(value))
+        walk(
+          value,
+          k,
+          surface,
+          observation,
+          pointerStep(path, k)
+        );
+    } else if (typeof value === "string" && want === "text") {
+      found.push({ holder, key, surface, observation, path });
+    }
+  };
+  for (const surface of Object.keys(observations)) {
+    for (const observation of Object.keys(observations[surface])) {
+      walk(observations[surface], observation, surface, observation, "");
+    }
+  }
+  return found;
+}
+function fitObservations(observations, budget) {
+  if (jsonBytes(observations) <= budget) return { observations, cuts: [] };
+  const fitted = JSON.parse(
+    JSON.stringify(observations)
+  );
+  const cuts = /* @__PURE__ */ new Map();
+  const note = (slot, kind, total, kept) => {
+    const id = `${slot.surface}\0${slot.observation}\0${slot.path}`;
+    const prior = cuts.get(id);
+    cuts.set(id, {
+      surface: slot.surface,
+      observation: slot.observation,
+      path: slot.path,
+      kind,
+      total: prior ? prior.total : total,
+      kept
+    });
+  };
+  const fits = () => jsonBytes(fitted) <= budget;
+  for (const rows of FIT_LIST_STEPS) {
+    for (const slot of slots(fitted, "list")) {
+      const list = slot.holder[slot.key];
+      if (list.length <= rows) continue;
+      note(slot, "list", list.length, rows);
+      list.length = rows;
+    }
+    for (const [id, cut] of cuts) {
+      if (cut.kind === "list" && atPointer(fitted[cut.surface]?.[cut.observation], cut.path) === void 0)
+        cuts.delete(id);
+    }
+    if (fits()) return { observations: fitted, cuts: [...cuts.values()] };
+  }
+  for (const slot of slots(fitted, "text")) {
+    const text = slot.holder[slot.key];
+    if (text.length <= FIT_TEXT_CHARS) continue;
+    note(slot, "text", text.length, FIT_TEXT_CHARS);
+    slot.holder[slot.key] = text.slice(
+      0,
+      FIT_TEXT_CHARS
+    );
+  }
+  if (fits()) return { observations: fitted, cuts: [...cuts.values()] };
+  const values = Object.keys(fitted).flatMap(
+    (surface) => Object.keys(fitted[surface]).map((observation) => ({
+      surface,
+      observation,
+      bytes: jsonBytes(fitted[surface][observation])
+    }))
+  ).sort(
+    (a, b) => b.bytes - a.bytes || a.surface.localeCompare(b.surface) || a.observation.localeCompare(b.observation)
+  );
+  for (const { surface, observation, bytes } of values) {
+    if (fits()) break;
+    for (const [id, cut] of cuts) {
+      if (cut.surface === surface && cut.observation === observation)
+        cuts.delete(id);
+    }
+    fitted[surface][observation] = null;
+    cuts.set(`${surface}\0${observation}\0`, {
+      surface,
+      observation,
+      path: "",
+      kind: "value",
+      total: bytes,
+      kept: 0
+    });
+  }
+  return { observations: fitted, cuts: [...cuts.values()] };
+}
+
+exports.ARGS_HASH_PATTERN = ARGS_HASH_PATTERN;
+exports.FIT_LIST_STEPS = FIT_LIST_STEPS;
+exports.FIT_TEXT_CHARS = FIT_TEXT_CHARS;
+exports.INDEX_DESCRIPTION_CHARS = INDEX_DESCRIPTION_CHARS;
+exports.INDEX_INPUT_CHARS = INDEX_INPUT_CHARS;
+exports.INDEX_INPUT_PROPERTIES = INDEX_INPUT_PROPERTIES;
+exports.OUI_DESCRIBE_ACTION = OUI_DESCRIBE_ACTION;
+exports.OUI_EFFECT_ACCESS = OUI_EFFECT_ACCESS;
+exports.OUI_EFFECT_KINDS = OUI_EFFECT_KINDS;
+exports.OUI_PROTOCOL_EVENTS = OUI_PROTOCOL_EVENTS;
+exports.OUI_READ_ACTION = OUI_READ_ACTION;
+exports.OUI_RUNTIME_SURFACE = OUI_RUNTIME_SURFACE;
+exports.argsHash = argsHash;
+exports.atPointer = atPointer;
+exports.canonicalJson = canonicalJson;
+exports.constantOf = constantOf;
+exports.definitionHash = definitionHash;
+exports.discriminatorOf = discriminatorOf;
+exports.effectAccess = effectAccess;
+exports.firstSentence = firstSentence;
+exports.fitObservations = fitObservations;
+exports.indexEntry = indexEntry;
+exports.jsonBytes = jsonBytes;
+exports.pointerStep = pointerStep;
+exports.pointerSteps = pointerSteps;
+exports.requiresApproval = requiresApproval;
+exports.sortedJson = sortedJson;
+exports.summarizeInput = summarizeInput;
+exports.surfaceIndex = surfaceIndex;
+exports.surfacesHash = surfacesHash;
+exports.utf8Length = utf8Length;
+//# sourceMappingURL=chunk-2CPOHQGI.cjs.map
+//# sourceMappingURL=chunk-2CPOHQGI.cjs.map