oui-spec 0.2.0 → 0.4.0

package/dist/chunk-DGMKSJTY.cjs

@@ -0,0 +1,573 @@
+'use strict';
+
+var chunkDCVVTP3V_cjs = require('./chunk-DCVVTP3V.cjs');
+
+// src/core/brand.ts
+function brand(value) {
+  return value;
+}
+
+// src/core/define-surface.ts
+function defineSurface(definition) {
+  const actionIds = /* @__PURE__ */ new Set();
+  for (const action of definition.actions) {
+    if (actionIds.has(action.id)) {
+      throw new Error(
+        `[OUI] Duplicate action ID "${action.id}" in surface "${definition.id}"`
+      );
+    }
+    actionIds.add(action.id);
+  }
+  if (definition.observations) {
+    const obsIds = /* @__PURE__ */ new Set();
+    for (const obs of definition.observations) {
+      if (obsIds.has(obs.id)) {
+        throw new Error(
+          `[OUI] Duplicate observation ID "${obs.id}" in surface "${definition.id}"`
+        );
+      }
+      obsIds.add(obs.id);
+    }
+  }
+  return brand({
+    ...definition,
+    /** Extract the manifest (schema only, no handlers) for transmission to the agent runtime */
+    toManifest() {
+      return {
+        id: definition.id,
+        name: definition.name,
+        description: definition.description,
+        version: definition.version,
+        activation: definition.activation,
+        actions: definition.actions.map(actionToManifest),
+        observations: definition.observations?.map(obsToManifest),
+        metadata: definition.metadata
+      };
+    },
+    /** Execute an action by ID with the given params and context */
+    async executeAction(actionId, params, context) {
+      const action = definition.actions.find((a) => a.id === actionId);
+      if (!action) {
+        return {
+          success: false,
+          error: {
+            code: "ACTION_NOT_FOUND",
+            message: `Action "${actionId}" not found on surface "${definition.id}"`
+          }
+        };
+      }
+      try {
+        return await action.handler(params, context);
+      } catch (err) {
+        return {
+          success: false,
+          error: {
+            code: "ACTION_EXECUTION_ERROR",
+            message: err instanceof Error ? err.message : String(err)
+          }
+        };
+      }
+    },
+    /** Get all action IDs */
+    getActionIds() {
+      return definition.actions.map((a) => a.id);
+    },
+    /** Get the polling config for an action (if async) */
+    getPollingConfig(actionId) {
+      const action = definition.actions.find((a) => a.id === actionId);
+      return action?.polling;
+    }
+  });
+}
+function actionToManifest(action) {
+  return {
+    id: action.id,
+    description: action.description,
+    input: action.input,
+    output: action.output,
+    confirm: action.confirm,
+    async: action.async,
+    polling: action.polling,
+    usage: action.usage,
+    preconditions: action.preconditions,
+    estimatedDuration: action.estimatedDuration,
+    tags: action.tags
+  };
+}
+function obsToManifest(obs) {
+  return {
+    id: obs.id,
+    description: obs.description,
+    schema: obs.schema
+  };
+}
+
+// src/core/create-oui.ts
+function createOUI(config) {
+  const {
+    socket,
+    surfaces,
+    transport: transportConfig
+  } = config;
+  if (!socket) {
+    throw new Error(
+      "[OUI] createOUI requires a socket. OUI owns the wire; the integrator owns the connection."
+    );
+  }
+  if (!Array.isArray(surfaces) || surfaces.length === 0) {
+    throw new Error("[OUI] createOUI requires at least one surface.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const surface of surfaces) {
+    if (seen.has(surface.id)) {
+      throw new Error(
+        `[OUI] Duplicate surface id "${surface.id}". Registration is keyed by id, so the second would replace the first.`
+      );
+    }
+    seen.add(surface.id);
+  }
+  const transport = brand(
+    chunkDCVVTP3V_cjs.createWebSocketTransport(socket, transportConfig)
+  );
+  const byId = new Map(surfaces.map((s) => [s.id, s]));
+  return {
+    transport,
+    manifests: surfaces.map((s) => s.toManifest()),
+    async start() {
+      await transport.connect();
+      for (const surface of surfaces) {
+        transport.registerSurface(surface.toManifest());
+      }
+    },
+    stop() {
+      for (const surface of surfaces) {
+        transport.deregisterSurface(surface.id);
+      }
+      transport.dispose();
+    },
+    getSurface(id) {
+      return byId.get(id);
+    }
+  };
+}
+
+// src/core/surface-runtime.ts
+var DEFAULT_QUIET_MS = 250;
+var DEFAULT_SETTLE_TIMEOUT_MS = 5e3;
+var DEFAULT_DEDUPE_WINDOW = 500;
+var SETTLE_TICK_MS = 50;
+function createSurfaceRuntime(options = {}) {
+  const announce = options.announce ?? true;
+  const quietMs = options.settle?.quietMs ?? DEFAULT_QUIET_MS;
+  const settleTimeoutMs = options.settle?.timeoutMs ?? DEFAULT_SETTLE_TIMEOUT_MS;
+  const dedupeWindow = options.dedupeWindow ?? DEFAULT_DEDUPE_WINDOW;
+  let nextKey = 1;
+  const entries = [];
+  const observations = /* @__PURE__ */ new Map();
+  const serializedObservations = /* @__PURE__ */ new Map();
+  const holds = /* @__PURE__ */ new Set();
+  let nextHold = 1;
+  const results = /* @__PURE__ */ new Map();
+  const pollers = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  const acks = /* @__PURE__ */ new Map();
+  function ackFor(requestId) {
+    let ack = acks.get(requestId);
+    if (!ack) {
+      let resolve;
+      const promise = new Promise((r) => resolve = r);
+      ack = { promise, resolve };
+      acks.set(requestId, ack);
+    }
+    return ack;
+  }
+  function acknowledged(requestId) {
+    return ackFor(requestId).promise;
+  }
+  let lastChangeAt = Date.now();
+  let socket = null;
+  let transport = null;
+  let detachTransport = [];
+  function changed(settles = true) {
+    if (settles) lastChangeAt = Date.now();
+    for (const l of [...listeners]) l();
+  }
+  function activeFor(surfaceId) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+      if (entries[i].surface.id === surfaceId) return entries[i];
+    }
+    return void 0;
+  }
+  function activeEntries() {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const e of entries) {
+      if (seen.has(e.surface.id)) continue;
+      seen.add(e.surface.id);
+      out.push(activeFor(e.surface.id));
+    }
+    return out;
+  }
+  function announceSurface(entry) {
+    if (!announce || !transport) return;
+    transport.registerSurface(entry.surface.toManifest());
+    const obs = observations.get(entry.surface.id);
+    if (obs) {
+      for (const [observationId, value] of obs) {
+        transport.pushObservation({
+          surfaceId: entry.surface.id,
+          observationId,
+          value,
+          timestamp: Date.now()
+        });
+      }
+    }
+  }
+  function announceAll() {
+    for (const e of activeEntries()) announceSurface(e);
+  }
+  function setObservation(surfaceId, observationId, value, settles = true) {
+    const key = `${surfaceId}\0${observationId}`;
+    let serialized;
+    try {
+      serialized = JSON.stringify(value) ?? "undefined";
+    } catch {
+      serialized = String(value);
+    }
+    if (serializedObservations.get(key) === serialized) return;
+    serializedObservations.set(key, serialized);
+    let obs = observations.get(surfaceId);
+    if (!obs) {
+      obs = /* @__PURE__ */ new Map();
+      observations.set(surfaceId, obs);
+    }
+    obs.set(observationId, toJsonSafe(value));
+    if (announce && transport) {
+      transport.pushObservation({
+        surfaceId,
+        observationId,
+        value,
+        timestamp: Date.now()
+      });
+    }
+    changed(settles);
+  }
+  function forgetSurface(surfaceId) {
+    observations.delete(surfaceId);
+    for (const key of [...serializedObservations.keys()]) {
+      if (key.startsWith(`${surfaceId}\0`))
+        serializedObservations.delete(key);
+    }
+    for (const [key, timer] of pollers) {
+      if (key.startsWith(`${surfaceId}\0`)) {
+        clearInterval(timer);
+        pollers.delete(key);
+      }
+    }
+  }
+  function startPolling(requestId, surfaceId, actionId, polling, dispatchResult) {
+    const finish = async (success, data, error) => {
+      await acknowledged(requestId);
+      const snap = snapshot();
+      transport?.sendResult({
+        requestId,
+        success,
+        ...data !== void 0 ? { data: toJsonSafe(data) } : {},
+        ...error ? { error } : {},
+        interim: false,
+        timestamp: Date.now(),
+        surfaces: snap.surfaces,
+        observations: snap.observations
+      });
+      acks.delete(requestId);
+    };
+    const observationId = `${surfaceId}:${actionId}:status`;
+    const pollerKey = `${surfaceId}\0${actionId}`;
+    if (polling.subscribe) {
+      setObservation(
+        surfaceId,
+        observationId,
+        { status: "dispatched", dispatchResult, interim: true },
+        false
+      );
+      return;
+    }
+    if (!polling.resolve) {
+      setObservation(
+        surfaceId,
+        observationId,
+        { status: "dispatched", dispatchResult, interim: false },
+        false
+      );
+      return;
+    }
+    const existing = pollers.get(pollerKey);
+    if (existing) clearInterval(existing);
+    setObservation(
+      surfaceId,
+      observationId,
+      { status: "polling", dispatchResult, interim: true },
+      false
+    );
+    const maxAttempts = polling.maxAttempts ?? Infinity;
+    const maxDuration = polling.maxDurationMs ?? Infinity;
+    const startedAt = Date.now();
+    let attempts = 0;
+    const timer = setInterval(async () => {
+      attempts++;
+      if (attempts > maxAttempts || Date.now() - startedAt > maxDuration) {
+        clearInterval(timer);
+        pollers.delete(pollerKey);
+        setObservation(
+          surfaceId,
+          observationId,
+          { status: "timeout", dispatchResult, interim: false },
+          false
+        );
+        void finish(false, void 0, {
+          code: "TIMEOUT",
+          message: `"${actionId}" did not finish within its polling limits.`
+        });
+        return;
+      }
+      const entry = activeFor(surfaceId);
+      const action = entry?.surface.actions.find((a) => a.id === actionId);
+      if (!entry || !action?.polling?.resolve) {
+        clearInterval(timer);
+        pollers.delete(pollerKey);
+        return;
+      }
+      try {
+        const r = await action.polling.resolve(
+          dispatchResult,
+          entry.getContext()
+        );
+        setObservation(
+          surfaceId,
+          observationId,
+          {
+            ...r.data,
+            interim: !r.done
+          },
+          false
+        );
+        if (r.done) {
+          clearInterval(timer);
+          pollers.delete(pollerKey);
+          void finish(true, r.data);
+        }
+      } catch (err) {
+        setObservation(
+          surfaceId,
+          observationId,
+          { status: "poll_error", error: String(err), interim: true },
+          false
+        );
+      }
+    }, polling.intervalMs);
+    pollers.set(pollerKey, timer);
+  }
+  async function waitUntilSettled(since) {
+    const deadline = since + settleTimeoutMs;
+    for (; ; ) {
+      const now = Date.now();
+      const quietFor = now - Math.max(since, lastChangeAt);
+      if (holds.size === 0 && quietFor >= quietMs) return true;
+      if (now >= deadline) return false;
+      await sleep(Math.min(SETTLE_TICK_MS, deadline - now));
+    }
+  }
+  async function run(request) {
+    const startedAt = Date.now();
+    const entry = activeFor(request.surfaceId);
+    let result;
+    let interim = false;
+    if (!entry) {
+      const mounted = activeEntries().map((e) => e.surface.id);
+      result = {
+        success: false,
+        error: {
+          code: "SURFACE_NOT_MOUNTED",
+          message: `Surface "${request.surfaceId}" is not on screen. Mounted surfaces: ${mounted.length ? mounted.join(", ") : "none"}.`
+        }
+      };
+    } else {
+      result = await entry.surface.executeAction(
+        request.actionId,
+        request.params ?? {},
+        entry.getContext()
+      );
+      if (result.success) {
+        const action = entry.surface.actions.find(
+          (a) => a.id === request.actionId
+        );
+        if (action?.polling) {
+          interim = true;
+          startPolling(
+            request.requestId,
+            entry.surface.id,
+            action.id,
+            action.polling,
+            result.data ?? result.dispatchMeta
+          );
+        }
+      }
+    }
+    const settled = await waitUntilSettled(startedAt);
+    const snap = snapshot();
+    return {
+      requestId: request.requestId,
+      success: result.success,
+      ...result.data !== void 0 ? { data: toJsonSafe(result.data) } : {},
+      ...result.error ? { error: toJsonSafe(result.error) } : {},
+      ...interim ? { interim: true } : {},
+      durationMs: Date.now() - startedAt,
+      timestamp: Date.now(),
+      surfaces: snap.surfaces,
+      observations: snap.observations,
+      settled
+    };
+  }
+  function execute(request) {
+    const seen = results.get(request.requestId);
+    if (seen) return seen;
+    const pending = run(request);
+    results.set(request.requestId, pending);
+    while (results.size > dedupeWindow) {
+      const oldest = results.keys().next().value;
+      results.delete(oldest);
+    }
+    return pending;
+  }
+  function snapshot() {
+    const surfaces = [];
+    const obs = {};
+    for (const e of activeEntries()) {
+      surfaces.push(e.surface.toManifest());
+      const values = observations.get(e.surface.id);
+      if (values && values.size > 0)
+        obs[e.surface.id] = Object.fromEntries(values);
+    }
+    return { surfaces, observations: obs };
+  }
+  function attach(next) {
+    if (next === socket) return;
+    for (const off of detachTransport) off();
+    detachTransport = [];
+    transport?.dispose();
+    transport = null;
+    socket = next;
+    if (!next) return;
+    const t = chunkDCVVTP3V_cjs.createWebSocketTransport(next, options.transport);
+    transport = t;
+    detachTransport.push(
+      t.onAction((request) => {
+        if (options.accept && !options.accept(request)) {
+          console.warn(
+            `[OUI] Refused a request the client does not accept: ${request.surfaceId}.${request.actionId} (${request.requestId})`
+          );
+          return;
+        }
+        void execute(request).then((result) => {
+          transport?.sendResult(result);
+          const ack = ackFor(request.requestId);
+          ack.resolve();
+          if (!result.interim) acks.delete(request.requestId);
+        });
+      })
+    );
+    if (announce) {
+      detachTransport.push(
+        t.onConnectionChange((connected) => {
+          if (connected) announceAll();
+        })
+      );
+      if (t.connected) announceAll();
+    }
+  }
+  if (options.socket) attach(options.socket);
+  function mount(surface, getContext) {
+    const entry = {
+      key: nextKey++,
+      surface,
+      getContext
+    };
+    entries.push(entry);
+    announceSurface(entry);
+    changed();
+    let mounted = true;
+    return {
+      surfaceId: surface.id,
+      pushObservation(observationId, value) {
+        if (!mounted || activeFor(surface.id) !== entry) return;
+        setObservation(surface.id, observationId, value);
+      },
+      unmount() {
+        if (!mounted) return;
+        mounted = false;
+        const i = entries.indexOf(entry);
+        if (i >= 0) entries.splice(i, 1);
+        const replacement = activeFor(surface.id);
+        if (replacement) {
+          announceSurface(replacement);
+        } else {
+          forgetSurface(surface.id);
+          if (announce && transport) transport.deregisterSurface(surface.id);
+        }
+        changed();
+      }
+    };
+  }
+  return {
+    mount,
+    attach,
+    snapshot,
+    execute,
+    hold() {
+      const id = nextHold++;
+      holds.add(id);
+      changed();
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        holds.delete(id);
+        changed();
+      };
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose() {
+      for (const timer of pollers.values()) clearInterval(timer);
+      pollers.clear();
+      attach(null);
+      entries.length = 0;
+      observations.clear();
+      serializedObservations.clear();
+      holds.clear();
+      listeners.clear();
+      acks.clear();
+    }
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function toJsonSafe(value) {
+  if (value === void 0) return void 0;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return String(value);
+  }
+}
+
+exports.createOUI = createOUI;
+exports.createSurfaceRuntime = createSurfaceRuntime;
+exports.defineSurface = defineSurface;
+//# sourceMappingURL=chunk-DGMKSJTY.cjs.map
+//# sourceMappingURL=chunk-DGMKSJTY.cjs.map