@ai-presence/adapters 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# @ai-presence/adapters
+
+Starter adapter utilities for converting AI runtime events into AI Presence Kit events.
+
+Adapters should stay upstream of any renderer. Their job is to translate signals like user input, stream open, first token, speech start, interruption, and errors into the canonical state machine exposed by `@ai-presence/core`.
+
+Current adapters:
+
+- `createRuntimeSignalAdapter`: generic signal-to-presence bridge.
+- `createVercelAISDKAdapter`: maps AI SDK chat statuses and callbacks to presence.
+- `createOpenAIRealtimeAdapter`: maps OpenAI Realtime server events to presence.
+- `createChatEventAdapter`: maps small generic chat lifecycle events to presence.
+
+The adapters intentionally avoid importing framework packages. They accept plain objects so they can be wrapped by React, Svelte, Vue, server streams, WebRTC handlers, or custom chat runtimes later.
+
+```js
+import { createVercelAISDKAdapter } from "@ai-presence/adapters";
+
+const aiSdkPresence = createVercelAISDKAdapter(presenceRuntime);
+aiSdkPresence.update({ status: "streaming", messages: [] });
+```
+
+Run the local adapter trace demo with:
+
+```bash
+npm run demo:adapters
+```
+
+The trace demo prints each adapter transition with the shared core control inputs, reference face frame evidence, and bounded six-channel decision-trace evidence that a renderer can consume, for example `phase=before-output`, `attention=response`, `face=thinking`, `channels=gaze,blink,brows,mouth,posture,motion`, `trace=complete`, `decisions=6`, `safe=true`, `warnings=0`, `transition=thinking:stream-open+0ms`, `transitionReads=6/6`, and `reads=state,transitionEvent,transitionAgeMs`.
+
+## Vercel AI SDK
+
+The current AI SDK `useChat` status values are:
+
+```text
+submitted
+streaming
+ready
+error
+```
+
+Adapter mapping:
+
+```text
+submitted -> model-waiting -> thinking
+streaming with no assistant content -> stream-open -> waiting
+streaming with assistant content -> token -> streaming
+ready -> response-complete -> ready
+error -> error -> error
+```
+
+This preserves the important distinction from the AI SDK docs and troubleshooting notes: `streaming` can begin before user-visible assistant text exists, so the presence state should be `waiting` until content arrives.
+
+## OpenAI Realtime
+
+Adapter mapping:
+
+```text
+input_audio_buffer.speech_started -> local-read -> reading
+input_audio_buffer.speech_stopped -> model-waiting -> thinking
+response.created -> model-waiting -> thinking
+response.output_item.created -> stream-open -> waiting
+response.content_part.added -> stream-open -> waiting
+response.output_text.delta -> token -> streaming
+response.output_audio_transcript.delta -> token -> streaming
+response.output_audio.delta -> speech-start -> speaking
+response.output_audio.done -> speech-end -> ready
+response.done -> response-complete -> ready
+error / response.failed -> error -> error
+```
+
+Older alias events already used by the prototype, such as `response.audio.delta` and `response.text.delta`, are also accepted.

package/dist/index.mjs

@@ -0,0 +1,21 @@
+import adapters from "../src/runtime-adapter.js";
+
+export const VercelAIStatus = adapters.VercelAIStatus;
+export const OPENAI_REALTIME_EVENT_MAP = adapters.OPENAI_REALTIME_EVENT_MAP;
+export const RuntimeSignal = adapters.RuntimeSignal;
+export const RUNTIME_SIGNALS = adapters.RUNTIME_SIGNALS;
+export const applyRuntimeSignal = adapters.applyRuntimeSignal;
+export const chatEventToRuntimeSignal = adapters.chatEventToRuntimeSignal;
+export const createChatEventAdapter = adapters.createChatEventAdapter;
+export const createOpenAIRealtimeAdapter = adapters.createOpenAIRealtimeAdapter;
+export const createRuntimeSignalAdapter = adapters.createRuntimeSignalAdapter;
+export const createVercelAISDKAdapter = adapters.createVercelAISDKAdapter;
+export const isRuntimeSignal = adapters.isRuntimeSignal;
+export const lastAssistantText = adapters.lastAssistantText;
+export const normalizeRuntimeSignal = adapters.normalizeRuntimeSignal;
+export const openAIRealtimeEventToRuntimeSignal = adapters.openAIRealtimeEventToRuntimeSignal;
+export const presenceEventForRuntimeSignal = adapters.presenceEventForRuntimeSignal;
+export const textFromMessage = adapters.textFromMessage;
+export const vercelAIStatusToRuntimeSignal = adapters.vercelAIStatusToRuntimeSignal;
+
+export default adapters;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ai-presence/adapters",
+  "version": "0.1.0",
+  "description": "Runtime signal adapters for AI Presence Kit.",
+  "type": "commonjs",
+  "main": "./src/runtime-adapter.js",
+  "module": "./dist/index.mjs",
+  "types": "./src/runtime-adapter.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/runtime-adapter.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./src/runtime-adapter.js",
+      "default": "./src/runtime-adapter.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@ai-presence/core": "0.1.0"
+  },
+  "sideEffects": false,
+  "license": "MIT"
+}

package/src/runtime-adapter.d.ts

@@ -0,0 +1,91 @@
+import type { PresenceEventValue, PresenceRuntime, PresenceSnapshot } from "@ai-presence/core";
+
+export declare const RuntimeSignal: Readonly<{
+  RESET: "reset";
+  USER_INPUT: "user-input";
+  USER_PAUSE: "user-pause";
+  LOCAL_READ: "local-read";
+  MODEL_WAITING: "model-waiting";
+  STREAM_OPEN: "stream-open";
+  TOKEN: "token";
+  RESPONSE_COMPLETE: "response-complete";
+  SPEECH_START: "speech-start";
+  SPEECH_END: "speech-end";
+  VOICE_WAITING: "voice-waiting";
+  INTERRUPT: "interrupt";
+  ERROR: "error";
+}>;
+
+export type RuntimeSignalValue = typeof RuntimeSignal[keyof typeof RuntimeSignal];
+
+export declare const VercelAIStatus: Readonly<{
+  SUBMITTED: "submitted";
+  STREAMING: "streaming";
+  READY: "ready";
+  ERROR: "error";
+}>;
+
+export type VercelAIStatusValue = typeof VercelAIStatus[keyof typeof VercelAIStatus];
+
+export interface RuntimeSignalObject {
+  type: RuntimeSignalValue;
+  detail?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface NormalizedRuntimeSignal {
+  type: RuntimeSignalValue;
+  detail: Record<string, unknown>;
+}
+
+export interface RuntimeSignalAdapter {
+  send(signal: RuntimeSignalValue | RuntimeSignalObject): PresenceSnapshot;
+}
+
+export interface AdapterOptions {
+  onSignal?: (signal: NormalizedRuntimeSignal, snapshot: PresenceSnapshot) => void;
+}
+
+export interface VercelChatState {
+  status: VercelAIStatusValue | string;
+  messages?: Array<Record<string, unknown>>;
+  assistantText?: string;
+  completion?: string;
+  [key: string]: unknown;
+}
+
+export interface VercelAISDKAdapter {
+  onInput(text: string, detail?: Record<string, unknown>): PresenceSnapshot;
+  onSubmit(text: string, detail?: Record<string, unknown>): PresenceSnapshot;
+  update(chatState: VercelChatState | VercelAIStatusValue): PresenceSnapshot;
+  onData(dataPart: Record<string, unknown>, detail?: Record<string, unknown>): PresenceSnapshot;
+  onFinish(result?: Record<string, unknown>): PresenceSnapshot;
+  onError(error: unknown, detail?: Record<string, unknown>): PresenceSnapshot;
+}
+
+export interface EventAdapter {
+  handleEvent(event: string | Record<string, unknown>): PresenceSnapshot;
+}
+
+export declare const RUNTIME_SIGNALS: readonly RuntimeSignalValue[];
+export declare const OPENAI_REALTIME_EVENT_MAP: Readonly<Record<string, RuntimeSignalValue>>;
+
+export declare function applyRuntimeSignal(
+  presenceRuntime: PresenceRuntime,
+  signal: RuntimeSignalValue | RuntimeSignalObject,
+): PresenceSnapshot;
+export declare function chatEventToRuntimeSignal(event?: string | Record<string, unknown>): NormalizedRuntimeSignal;
+export declare function createChatEventAdapter(presenceRuntime: PresenceRuntime, options?: AdapterOptions): EventAdapter;
+export declare function createOpenAIRealtimeAdapter(presenceRuntime: PresenceRuntime, options?: AdapterOptions): EventAdapter;
+export declare function createRuntimeSignalAdapter(presenceRuntime: PresenceRuntime, options?: AdapterOptions): RuntimeSignalAdapter;
+export declare function createVercelAISDKAdapter(presenceRuntime: PresenceRuntime, options?: AdapterOptions): VercelAISDKAdapter;
+export declare function isRuntimeSignal(value: unknown): value is RuntimeSignalValue;
+export declare function lastAssistantText(messages?: Array<Record<string, unknown>>): string;
+export declare function normalizeRuntimeSignal(signal: RuntimeSignalValue | RuntimeSignalObject): NormalizedRuntimeSignal;
+export declare function openAIRealtimeEventToRuntimeSignal(event?: string | Record<string, unknown>): NormalizedRuntimeSignal;
+export declare function presenceEventForRuntimeSignal(signal: RuntimeSignalValue | RuntimeSignalObject): {
+  event: PresenceEventValue;
+  detail: Record<string, unknown>;
+};
+export declare function textFromMessage(message: Record<string, unknown>): string;
+export declare function vercelAIStatusToRuntimeSignal(chatState?: VercelChatState | VercelAIStatusValue): NormalizedRuntimeSignal;

package/src/runtime-adapter.js

@@ -0,0 +1,343 @@
+(function initPresenceAdapters(globalScope) {
+  "use strict";
+
+  const core = resolveCore(globalScope);
+  const PresenceEvent = core?.PresenceEvent || {};
+
+  const RuntimeSignal = Object.freeze({
+    RESET: "reset",
+    USER_INPUT: "user-input",
+    USER_PAUSE: "user-pause",
+    LOCAL_READ: "local-read",
+    MODEL_WAITING: "model-waiting",
+    STREAM_OPEN: "stream-open",
+    TOKEN: "token",
+    RESPONSE_COMPLETE: "response-complete",
+    SPEECH_START: "speech-start",
+    SPEECH_END: "speech-end",
+    VOICE_WAITING: "voice-waiting",
+    INTERRUPT: "interrupt",
+    ERROR: "error",
+  });
+
+  const RUNTIME_SIGNALS = Object.freeze(Object.values(RuntimeSignal));
+  const runtimeSignalSet = new Set(RUNTIME_SIGNALS);
+
+  const signalToPresenceEvent = Object.freeze({
+    [RuntimeSignal.RESET]: PresenceEvent.RESET,
+    [RuntimeSignal.USER_INPUT]: PresenceEvent.USER_INPUT,
+    [RuntimeSignal.USER_PAUSE]: PresenceEvent.USER_PAUSE,
+    [RuntimeSignal.LOCAL_READ]: PresenceEvent.LOCAL_READ,
+    [RuntimeSignal.MODEL_WAITING]: PresenceEvent.SUBMIT,
+    [RuntimeSignal.STREAM_OPEN]: PresenceEvent.STREAM_OPEN,
+    [RuntimeSignal.TOKEN]: PresenceEvent.TOKEN,
+    [RuntimeSignal.RESPONSE_COMPLETE]: PresenceEvent.RESPONSE_COMPLETE,
+    [RuntimeSignal.SPEECH_START]: PresenceEvent.SPEECH_START,
+    [RuntimeSignal.SPEECH_END]: PresenceEvent.SPEECH_END,
+    [RuntimeSignal.VOICE_WAITING]: PresenceEvent.VOICE_WAITING,
+    [RuntimeSignal.INTERRUPT]: PresenceEvent.INTERRUPT,
+    [RuntimeSignal.ERROR]: PresenceEvent.ERROR,
+  });
+
+  const VercelAIStatus = Object.freeze({
+    SUBMITTED: "submitted",
+    STREAMING: "streaming",
+    READY: "ready",
+    ERROR: "error",
+  });
+
+  const OPENAI_REALTIME_EVENT_MAP = Object.freeze({
+    "session.created": RuntimeSignal.VOICE_WAITING,
+    "session.updated": RuntimeSignal.VOICE_WAITING,
+    "input_audio_buffer.speech_started": RuntimeSignal.LOCAL_READ,
+    "input_audio_buffer.speech_stopped": RuntimeSignal.MODEL_WAITING,
+    "input_audio_buffer.committed": RuntimeSignal.MODEL_WAITING,
+    "response.created": RuntimeSignal.MODEL_WAITING,
+    "response.output_item.created": RuntimeSignal.STREAM_OPEN,
+    "response.content_part.added": RuntimeSignal.STREAM_OPEN,
+    "response.output_text.delta": RuntimeSignal.TOKEN,
+    "response.text.delta": RuntimeSignal.TOKEN,
+    "response.output_audio_transcript.delta": RuntimeSignal.TOKEN,
+    "response.audio_transcript.delta": RuntimeSignal.TOKEN,
+    "response.output_audio.delta": RuntimeSignal.SPEECH_START,
+    "response.audio.delta": RuntimeSignal.SPEECH_START,
+    "response.output_audio.done": RuntimeSignal.SPEECH_END,
+    "response.audio.done": RuntimeSignal.SPEECH_END,
+    "response.output_text.done": RuntimeSignal.RESPONSE_COMPLETE,
+    "response.text.done": RuntimeSignal.RESPONSE_COMPLETE,
+    "response.output_audio_transcript.done": RuntimeSignal.RESPONSE_COMPLETE,
+    "response.audio_transcript.done": RuntimeSignal.RESPONSE_COMPLETE,
+    "response.done": RuntimeSignal.RESPONSE_COMPLETE,
+    "response.completed": RuntimeSignal.RESPONSE_COMPLETE,
+    "response.failed": RuntimeSignal.ERROR,
+    error: RuntimeSignal.ERROR,
+  });
+
+  function resolveCore(scope) {
+    if (scope?.AIPresenceCore) return scope.AIPresenceCore;
+    if (typeof require === "function") {
+      try {
+        return require("@ai-presence/core");
+      } catch {
+        // Fall back to the no-build monorepo path used by the prototype.
+      }
+      try {
+        return require("../../core/src/presence-core.js");
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  function isRuntimeSignal(value) {
+    return runtimeSignalSet.has(value);
+  }
+
+  function normalizeRuntimeSignal(signal) {
+    if (typeof signal === "string") {
+      return { type: signal, detail: {} };
+    }
+
+    if (!signal || typeof signal !== "object") {
+      return { type: RuntimeSignal.RESET, detail: {} };
+    }
+
+    const { type, detail: explicitDetail, ...rest } = signal;
+    const detail = explicitDetail && typeof explicitDetail === "object"
+      ? { ...rest, ...explicitDetail }
+      : rest;
+
+    return {
+      type: isRuntimeSignal(type) ? type : RuntimeSignal.RESET,
+      detail,
+    };
+  }
+
+  function presenceEventForRuntimeSignal(signal) {
+    const normalized = normalizeRuntimeSignal(signal);
+    return {
+      event: signalToPresenceEvent[normalized.type] || PresenceEvent.RESET,
+      detail: normalized.detail,
+    };
+  }
+
+  function textFromPart(part) {
+    if (!part || typeof part !== "object") return "";
+    if (typeof part.text === "string") return part.text;
+    if (typeof part.content === "string") return part.content;
+    if (typeof part.delta === "string") return part.delta;
+    return "";
+  }
+
+  function textFromMessage(message) {
+    if (!message || typeof message !== "object") return "";
+    if (typeof message.content === "string") return message.content;
+    if (typeof message.text === "string") return message.text;
+    if (!Array.isArray(message.parts)) return "";
+    return message.parts.map(textFromPart).join("");
+  }
+
+  function lastAssistantText(messages = []) {
+    if (!Array.isArray(messages)) return "";
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+      const message = messages[index];
+      if (message?.role === "assistant") return textFromMessage(message);
+    }
+    return "";
+  }
+
+  function hasAssistantContent(chatState = {}) {
+    if (typeof chatState.assistantText === "string") return chatState.assistantText.length > 0;
+    if (typeof chatState.completion === "string") return chatState.completion.length > 0;
+    return lastAssistantText(chatState.messages).length > 0;
+  }
+
+  function vercelAIStatusToRuntimeSignal(chatState = {}) {
+    const status = typeof chatState === "string" ? chatState : chatState.status;
+    const detail = typeof chatState === "string" ? {} : { ...chatState };
+
+    if (status === VercelAIStatus.SUBMITTED) {
+      return { type: RuntimeSignal.MODEL_WAITING, detail };
+    }
+
+    if (status === VercelAIStatus.STREAMING) {
+      return {
+        type: hasAssistantContent(detail) ? RuntimeSignal.TOKEN : RuntimeSignal.STREAM_OPEN,
+        detail,
+      };
+    }
+
+    if (status === VercelAIStatus.READY) {
+      return { type: RuntimeSignal.RESPONSE_COMPLETE, detail };
+    }
+
+    if (status === VercelAIStatus.ERROR) {
+      return { type: RuntimeSignal.ERROR, detail };
+    }
+
+    return { type: RuntimeSignal.RESET, detail };
+  }
+
+  function createVercelAISDKAdapter(presenceRuntime, options = {}) {
+    const adapter = createRuntimeSignalAdapter(presenceRuntime, options);
+
+    return Object.freeze({
+      onInput(text, detail = {}) {
+        return adapter.send({ type: RuntimeSignal.USER_INPUT, text, ...detail });
+      },
+      onSubmit(text, detail = {}) {
+        adapter.send({ type: RuntimeSignal.USER_INPUT, text, ...detail });
+        return adapter.send({ type: RuntimeSignal.MODEL_WAITING, text, ...detail });
+      },
+      update(chatState) {
+        return adapter.send(vercelAIStatusToRuntimeSignal(chatState));
+      },
+      onData(dataPart, detail = {}) {
+        return adapter.send({
+          type: hasAssistantContent({ assistantText: textFromPart(dataPart) })
+            ? RuntimeSignal.TOKEN
+            : RuntimeSignal.STREAM_OPEN,
+          dataPart,
+          ...detail,
+        });
+      },
+      onFinish(result = {}) {
+        if (result.isAbort) return adapter.send({ type: RuntimeSignal.INTERRUPT, ...result });
+        if (result.isError) return adapter.send({ type: RuntimeSignal.ERROR, ...result });
+        return adapter.send({ type: RuntimeSignal.RESPONSE_COMPLETE, ...result });
+      },
+      onError(error, detail = {}) {
+        return adapter.send({ type: RuntimeSignal.ERROR, error, ...detail });
+      },
+    });
+  }
+
+  function openAIRealtimeEventToRuntimeSignal(event = {}) {
+    const type = typeof event === "string" ? event : event.type;
+    const signalType = OPENAI_REALTIME_EVENT_MAP[type] || RuntimeSignal.RESET;
+    const detail = typeof event === "string" ? { eventType: event } : { ...event, eventType: type };
+
+    if (type === "input_audio_buffer.speech_started") {
+      detail.text = detail.text || "voice input";
+      detail.completion = 0.2;
+    }
+
+    if (type === "input_audio_buffer.speech_stopped" || type === "input_audio_buffer.committed") {
+      detail.text = detail.text || "voice input";
+    }
+
+    if (type?.endsWith(".delta")) {
+      detail.delta = detail.delta || detail.text || "";
+    }
+
+    return { type: signalType, detail };
+  }
+
+  function createOpenAIRealtimeAdapter(presenceRuntime, options = {}) {
+    const adapter = createRuntimeSignalAdapter(presenceRuntime, options);
+
+    return Object.freeze({
+      handleEvent(event) {
+        return adapter.send(openAIRealtimeEventToRuntimeSignal(event));
+      },
+    });
+  }
+
+  function chatEventToRuntimeSignal(event = {}) {
+    const type = typeof event === "string" ? event : event.type;
+    const detail = typeof event === "string" ? {} : { ...event };
+
+    switch (type) {
+      case "input":
+      case "user-input":
+        return { type: RuntimeSignal.USER_INPUT, detail };
+      case "pause":
+      case "user-pause":
+        return { type: RuntimeSignal.USER_PAUSE, detail };
+      case "submit":
+      case "request":
+        return { type: RuntimeSignal.MODEL_WAITING, detail };
+      case "stream-open":
+      case "response-start":
+        return { type: RuntimeSignal.STREAM_OPEN, detail };
+      case "delta":
+      case "token":
+      case "message-delta":
+        return { type: RuntimeSignal.TOKEN, detail };
+      case "finish":
+      case "done":
+      case "response-complete":
+        return { type: RuntimeSignal.RESPONSE_COMPLETE, detail };
+      case "abort":
+      case "interrupt":
+        return { type: RuntimeSignal.INTERRUPT, detail };
+      case "speech-start":
+        return { type: RuntimeSignal.SPEECH_START, detail };
+      case "speech-end":
+        return { type: RuntimeSignal.SPEECH_END, detail };
+      case "error":
+        return { type: RuntimeSignal.ERROR, detail };
+      default:
+        return { type: RuntimeSignal.RESET, detail };
+    }
+  }
+
+  function createChatEventAdapter(presenceRuntime, options = {}) {
+    const adapter = createRuntimeSignalAdapter(presenceRuntime, options);
+
+    return Object.freeze({
+      handleEvent(event) {
+        return adapter.send(chatEventToRuntimeSignal(event));
+      },
+    });
+  }
+
+  function applyRuntimeSignal(presenceRuntime, signal) {
+    if (!presenceRuntime || typeof presenceRuntime.send !== "function") {
+      throw new TypeError("applyRuntimeSignal requires a presence runtime with send(event, detail).");
+    }
+
+    const { event, detail } = presenceEventForRuntimeSignal(signal);
+    return presenceRuntime.send(event, detail);
+  }
+
+  function createRuntimeSignalAdapter(presenceRuntime, options = {}) {
+    const onSignal = typeof options.onSignal === "function" ? options.onSignal : null;
+
+    return Object.freeze({
+      send(signal) {
+        const normalized = normalizeRuntimeSignal(signal);
+        const result = applyRuntimeSignal(presenceRuntime, normalized);
+        if (onSignal) onSignal(normalized, result);
+        return result;
+      },
+    });
+  }
+
+  const api = Object.freeze({
+    VercelAIStatus,
+    OPENAI_REALTIME_EVENT_MAP,
+    RuntimeSignal,
+    RUNTIME_SIGNALS,
+    applyRuntimeSignal,
+    chatEventToRuntimeSignal,
+    createChatEventAdapter,
+    createOpenAIRealtimeAdapter,
+    createRuntimeSignalAdapter,
+    createVercelAISDKAdapter,
+    isRuntimeSignal,
+    lastAssistantText,
+    normalizeRuntimeSignal,
+    openAIRealtimeEventToRuntimeSignal,
+    presenceEventForRuntimeSignal,
+    textFromMessage,
+    vercelAIStatusToRuntimeSignal,
+  });
+
+  if (typeof module === "object" && module.exports) {
+    module.exports = api;
+  }
+
+  globalScope.AIPresenceAdapters = api;
+})(typeof globalThis !== "undefined" ? globalThis : window);