@unoverse-platform/studio 0.1.103 → 0.1.105

package/vendor/sdk/lib/voice.tsx

@@ -1,422 +0,0 @@
-/**
- * useVoiceService — the Unoverse `voice` NATIVE SERVICE (UNOVERSE_SPEC §2e-1 Tier-3).
- *
- * Audio I/O is inherently native (getUserMedia / AudioContext / the /ws/gravity WS
- * lane), so it cannot be expressed as definition data — it is the spec's sanctioned
- * escape hatch: a fixed `{ state, actions }` capability the SDK provides and a template
- * REFERENCES (`service: "voice"`), binding its neutral state + dispatching its actions.
- *
- * This composes the ported realtime hooks (capture / playback / the WS audio lane) +
- * the orchestration from the legacy useVoiceCall + useAudioContext into ONE neutral
- * projection. The channel spreads `state` into the template's data scope and routes the
- * voice action names to the actions — see the workbench wiring. The SDK owns NO styles
- * and exposes only NEUTRAL model facts here (never UX flags).
- *
- * Transport split (docs/UNOVERSE_MCP_APP_PROTOCOL §5): the live PCM frames AND the
- * synchronized audio-state control events both ride the /ws/gravity WS lane (they stay
- * frame-synchronized); only structured component data is on MCP, untouched by voice.
- */
-
-import { useState, useCallback, useEffect, useRef, useMemo } from "react";
-import { useRealtimeWebSocket } from "./realtime/useRealtimeWebSocket";
-import { useAudioCapture } from "./realtime/useAudioCapture";
-import { useAudioPlayback } from "./realtime/useAudioPlayback";
-import type { AudioStateEvent } from "./realtime/types";
-import type { ComponentStore } from "./core";
-import { sessionUserId } from "./connection";
-
-export type VoiceConnectionStatus = "idle" | "connecting" | "connected" | "ended" | "error";
-
-export interface VoiceSession {
-  userId: string;
-  conversationId: string;
-  chatId?: string;
-  workflowId: string;
-  targetTriggerNode: string;
-}
-
-export interface UseVoiceServiceConfig {
-  /** Gateway REST base, e.g. http://localhost:4100 (the workflow `…/execute` host). */
-  apiUrl: string;
-  /** Audio WS base, e.g. ws://localhost:4100. Defaults to `apiUrl` with http→ws. */
-  wsUrl?: string;
-  /** Fresh access token provider (rides the WS lane + the REST Authorization header). */
-  getAccessToken?: () => Promise<string | null> | string | null;
-  session: VoiceSession;
-  /** The shared store. When given, the service acts as a PRODUCER (STATE_MODEL §4):
-   *  every state change is merged into TEMPLATE STATE, so templates read voice exactly
-   *  like any global key (`visibleWhen: { field: "callState", … }`) with zero host
-   *  glue — the voice twin of `lifecycle`/`isThinking`/`isStreaming`. */
-  store?: ComponentStore;
-}
-
-/** The single call-phase VALUE a voice template branches its states on — the standard voice
- *  state vocabulary (`visibleWhen: { field: "callState", eq: … }`). Derived from the neutral
- *  facts below so every voice template keys off one field, exactly like `mode` for focus. */
-export type VoiceCallState = "idle" | "active" | "speaking" | "listening" | "thinking";
-
-/** NEUTRAL voice projections — flat, so the channel can spread them into the template scope. */
-export interface VoiceServiceState {
-  connectionStatus: VoiceConnectionStatus;
-  /** The single phase the template's states key off (idle | active | listening | thinking | speaking). */
-  callState: VoiceCallState;
-  isIdle: boolean;
-  isCallActive: boolean;
-  isConnecting: boolean;
-  isConnected: boolean;
-  isAssistantSpeaking: boolean;
-  isUserSpeaking: boolean;
-  /** user speaking AND assistant not — mutual exclusion (the template can't express NOT). */
-  showUserSpeaking: boolean;
-  isMuted: boolean;
-  isLookingUp: boolean;
-  lookupLabel: string;
-  callDuration: number;
-  durationText: string;
-  statusText: string;
-  error: string | null;
-}
-
-export interface StartCall {
-  message?: string;
-  metadata?: Record<string, unknown>;
-  workflowId?: string;
-  targetTriggerNode?: string;
-}
-
-export interface VoiceService {
-  /** Spread into the template's data scope (channel overrides → rootData). */
-  state: VoiceServiceState;
-  /** Start a call. `start` is what it starts with, as any request to the workflow: the text,
-   *  and metadata a trigger reads (`metadata.task` names the task). Omitted → "Start call".
-   *  `workflowId`/`targetTriggerNode` name the workflow to run, else the session's own: a page
-   *  template's binding (UNOVERSE_HOST_PAGE.md rule 4). Started while a call is live, it MOVES
-   *  the call: the same line, the new workflow, and the server closes the session before it
-   *  (VOICE_STREAMING_GUIDE.md, "One Live Session Per Conversation"). */
-  startCall: (start?: StartCall) => Promise<void>;
-  /** Join a call already running: the audio lane and the microphone for a workflow something
-   *  else started (a canvas Run, a button, `JOIN_CALL`), without starting it again. `workflowId`
-   *  is what the hang-up names; omitted, the session's own. Joining a call already joined is
-   *  nothing. */
-  joinCall: (workflowId?: string) => Promise<void>;
-  /** Wake the speaker. Call it inside the click that may start a call. */
-  unlock: () => void;
-  endCall: () => Promise<void>;
-  toggleMute: () => void;
-}
-
-function formatDuration(totalSeconds: number): string {
-  const m = Math.floor(totalSeconds / 60)
-    .toString()
-    .padStart(2, "0");
-  const s = (totalSeconds % 60).toString().padStart(2, "0");
-  return `${m}:${s}`;
-}
-
-export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
-  const { apiUrl, getAccessToken } = config;
-  const wsUrl = config.wsUrl ?? apiUrl.replace(/^http/, "ws");
-  // Same identity as the data plane (connection.tsx): without a token the audio socket is a
-  // guest socket, and the server refuses INIT_SESSION unless the id is guest-prefixed.
-  const session = useMemo(
-    () => ({ ...config.session, userId: sessionUserId(config.session.userId, getAccessToken) }),
-    [config.session, getAccessToken],
-  );
-
-  const [connectionStatus, setConnectionStatus] = useState<VoiceConnectionStatus>("idle");
-  const [isMuted, setIsMuted] = useState(false);
-  const [callDuration, setCallDuration] = useState(0);
-  const [error, setError] = useState<string | null>(null);
-  const [assistantHint, setAssistantHint] = useState(false);
-  const [userSpeaking, setUserSpeaking] = useState(false);
-  const [isLookingUp, setIsLookingUp] = useState(false);
-  const [lookupTool, setLookupTool] = useState<string | null>(null);
-
-  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
-  /** The workflow the live call is on, which a hang-up names; null with no call. */
-  const callWorkflowRef = useRef<string | null>(null);
-  /** Lets go of the microphone and the audio lane when the server ends the call (set below,
-   *  once they exist). */
-  const releaseRef = useRef<() => void>(() => {});
-  const sendAudioRef = useRef<(d: ArrayBuffer) => void>(() => {});
-
-  const playback = useAudioPlayback();
-
-  // Audio-state events arrive on the WS lane, in lockstep with the frames.
-  const handleAudioState = useCallback(
-    (event: AudioStateEvent) => {
-      const { state, metadata } = event;
-      if (state === "SPEECH_STARTED") {
-        setAssistantHint(true);
-      } else if (state === "SPEECH_ENDED") {
-        setAssistantHint(false);
-        playback.markAsLastChunk();
-      } else if (state === "USER_SPEECH_STARTED") {
-        setUserSpeaking(true);
-        playback.stopAll(); // barge-in: cut assistant playback the moment the user speaks
-      } else if (state === "USER_SPEECH_ENDED") {
-        setUserSpeaking(false);
-      } else if (state === "SESSION_READY") {
-        setConnectionStatus("connected");
-      } else if (state === "SESSION_ENDED") {
-        // THE SERVER ENDED THE CALL (the model hung up, a minute of silence, a timeout): the
-        // microphone stops and the lane closes, or the page streams to nobody.
-        releaseRef.current();
-        setConnectionStatus("ended");
-        setAssistantHint(false);
-        setUserSpeaking(false);
-        setIsLookingUp(false);
-        setLookupTool(null);
-        playback.markAsLastChunk();
-      } else if (state === "TOOL_USE") {
-        setIsLookingUp(true);
-        setLookupTool((metadata?.toolName as string | undefined) ?? null);
-      } else if (state === "TOOL_USE_COMPLETED") {
-        setIsLookingUp(false);
-        setLookupTool(null);
-      }
-    },
-    [playback],
-  );
-
-  const ws = useRealtimeWebSocket({
-    sessionId: session.conversationId,
-    userId: session.userId,
-    chatId: session.chatId,
-    wsUrl,
-    getAccessToken,
-    onAudioReceived: playback.playAudio,
-    onAudioState: handleAudioState,
-  });
-
-  // Capture → WS via a ref so the capture graph isn't rebuilt when sendAudio changes.
-  const handleAudioData = useCallback((d: ArrayBuffer) => sendAudioRef.current(d), []);
-  useEffect(() => {
-    sendAudioRef.current = ws.sendAudio;
-  }, [ws.sendAudio]);
-
-  const capture = useAudioCapture({ onAudioData: handleAudioData });
-  useEffect(() => {
-    releaseRef.current = () => {
-      if (timerRef.current) {
-        clearInterval(timerRef.current);
-        timerRef.current = null;
-      }
-      callWorkflowRef.current = null;
-      void capture.stopCapture();
-      ws.disconnect();
-    };
-  }, [capture, ws]);
-
-  const startCall = useCallback(async (start?: StartCall) => {
-    const workflowId = start?.workflowId || session.workflowId;
-    const targetTriggerNode = start?.targetTriggerNode || session.targetTriggerNode;
-    if (!workflowId) {
-      // NOTHING TO CALL: no workflow was named and the session has none. Never a default.
-      setError("No workflow to call");
-      setConnectionStatus("error");
-      return;
-    }
-    // A CALL ALREADY LIVE IS MOVED, not started again: the line and the microphone stay open,
-    // and only the workflow changes. The old voice is cut at once so two are never heard.
-    const moving = callWorkflowRef.current !== null;
-    if (moving) {
-      playback.stopAll();
-      setAssistantHint(false);
-      setIsLookingUp(false);
-      setLookupTool(null);
-    } else {
-      setConnectionStatus("connecting");
-      setError(null);
-      setCallDuration(0);
-    }
-    try {
-      // 1. Open the audio lane (sends INIT_SESSION on open) BEFORE the trigger,
-      //    so the server can route audio the moment the Nova/Grok session is up.
-      if (!moving) await ws.connect();
-      callWorkflowRef.current = workflowId;
-
-      // 2. START_CALL via REST — fire-and-forget; the workflow stays open for the call.
-      const token = getAccessToken ? await getAccessToken() : null;
-      const headers: Record<string, string> = { "Content-Type": "application/json" };
-      if (token) headers["Authorization"] = `Bearer ${token}`;
-      const chatId = session.chatId ?? `voice_${session.conversationId}`;
-      fetch(`${apiUrl}/api/workflows/${workflowId}/execute`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({
-          input: {
-            message: start?.message ?? "Start call",
-            chatId,
-            conversationId: session.conversationId,
-            userId: session.userId,
-            providerId: "gravity-voice",
-            isAudio: true,
-            metadata: {
-              ...(start?.metadata ?? {}),
-              targetTriggerNode,
-              action: "START_CALL",
-              isAction: true,
-              workflowId,
-              continuousStream: true,
-            },
-          },
-          conversationId: session.conversationId,
-        }),
-      }).catch((e) => console.error("[voice] START_CALL error:", e));
-      if (moving) return;
-
-      // 3. Start streaming the mic.
-      await capture.startCapture();
-      timerRef.current = setInterval(() => setCallDuration((p) => p + 1), 1000);
-      setConnectionStatus("connected");
-    } catch (err: unknown) {
-      callWorkflowRef.current = null;
-      setError(err instanceof Error ? err.message : "Failed to start call");
-      setConnectionStatus("error");
-      setIsLookingUp(false);
-      setLookupTool(null);
-    }
-  }, [ws, capture, playback, apiUrl, session, getAccessToken]);
-
-  // JOIN, NOT START. The workflow is already running and its voice node has opened the vendor
-  // session on this conversation; all that is missing is a browser on the audio lane. So open
-  // the lane and the microphone, and send no execute: a second one would start a second run.
-  const joinCall = useCallback(async (workflowId?: string) => {
-    if (callWorkflowRef.current !== null) return;
-    callWorkflowRef.current = workflowId ?? session.workflowId ?? "";
-    setConnectionStatus("connecting");
-    setError(null);
-    setCallDuration(0);
-    try {
-      await ws.connect();
-      await capture.startCapture();
-      timerRef.current = setInterval(() => setCallDuration((p) => p + 1), 1000);
-      setConnectionStatus("connected");
-    } catch (err: unknown) {
-      callWorkflowRef.current = null;
-      setError(err instanceof Error ? err.message : "Failed to join call");
-      setConnectionStatus("error");
-    }
-  }, [ws, capture, session.workflowId]);
-
-  const endCall = useCallback(async () => {
-    if (timerRef.current) {
-      clearInterval(timerRef.current);
-      timerRef.current = null;
-    }
-    await capture.stopCapture();
-    playback.stopAll();
-    // END via WS control — NOT a new REST execute (that would start a new workflow).
-    ws.sendControl("AUDIO_CONTROL", { command: "stop", workflowId: callWorkflowRef.current ?? session.workflowId });
-    callWorkflowRef.current = null;
-    ws.disconnect();
-    setConnectionStatus("ended");
-    setIsMuted(false);
-    setIsLookingUp(false);
-    setLookupTool(null);
-  }, [capture, playback, ws, session.workflowId]);
-
-  const toggleMute = useCallback(() => {
-    setIsMuted((prev) => {
-      const next = !prev;
-      capture.setMuted(next);
-      return next;
-    });
-  }, [capture]);
-
-  // Cleanup on unmount.
-  useEffect(() => {
-    return () => {
-      if (timerRef.current) clearInterval(timerRef.current);
-      ws.disconnect();
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  const isAssistantSpeaking = assistantHint || playback.isPlaying;
-  const isUserSpeaking = userSpeaking || capture.isSpeaking;
-  const isCallActive = connectionStatus === "connecting" || connectionStatus === "connected";
-  const lookupLabel =
-    lookupTool === "findIntent" ? "Searching the knowledge base…" : `Looking up ${lookupTool ?? "information"}…`;
-  const durationText = formatDuration(callDuration);
-  const statusText =
-    connectionStatus === "idle"
-      ? "Ready to call"
-      : connectionStatus === "connecting"
-        ? "Connecting…"
-        : connectionStatus === "connected"
-          ? durationText
-          : connectionStatus === "error"
-            ? (error ?? "Connection error")
-            : "Call ended";
-
-  const state: VoiceServiceState = useMemo(
-    () => ({
-      connectionStatus,
-      // The one phase the template branches on — derived from the neutral facts. Order matters:
-      // a lookup wins, then agent speaking over user (barge-in), and all three win over plain
-      // "active".
-      //
-      // `thinking` sits ABOVE speaking because a lookup has a true start and a true end (the
-      // hand-off and its answer), while speaking may have no end at all: GPT-Live sends no
-      // end-of-speech event and streams silence, so speaking can read true for the whole call
-      // and would hide the lookup. Thinking clears on the answer, a hang-up or a dropped call.
-      //
-      // It also sits ABOVE "active" because that is the bug it fixed. A lookup takes 8 to 9 seconds,
-      // and for all of it callState read "active" — which every voice template draws as a calm
-      // halo meaning "the floor is yours". The orb is the only progress indicator a call has,
-      // and it was saying the opposite of what was happening. `isLookingUp` was already right
-      // here in this hook, feeding the small lookup caption; it simply never reached the one
-      // field the templates branch on.
-      callState: (!isCallActive
-        ? "idle"
-        : isLookingUp
-          ? "thinking"
-          : isAssistantSpeaking
-            ? "speaking"
-            : isUserSpeaking
-              ? "listening"
-              : "active") as VoiceCallState,
-      isIdle: !isCallActive,
-      isCallActive,
-      isConnecting: connectionStatus === "connecting",
-      isConnected: connectionStatus === "connected",
-      isAssistantSpeaking,
-      isUserSpeaking,
-      showUserSpeaking: isUserSpeaking && !isAssistantSpeaking,
-      isMuted,
-      isLookingUp,
-      lookupLabel,
-      callDuration,
-      durationText,
-      statusText,
-      error: error ?? capture.error ?? null,
-    }),
-    [
-      connectionStatus,
-      isCallActive,
-      isAssistantSpeaking,
-      isUserSpeaking,
-      isMuted,
-      isLookingUp,
-      lookupLabel,
-      callDuration,
-      durationText,
-      statusText,
-      error,
-      capture.error,
-    ],
-  );
-
-  // PRODUCER write (STATE_MODEL §4): the service feeds the state, it is not state.
-  // Call state lands in TEMPLATE STATE like any dev-named key, so every template —
-  // studio, canvas, native — reads voice from the store's global bag with no
-  // host-side props spread. Low-frequency (call phases + a 1Hz duration tick).
-  const store = config.store;
-  useEffect(() => {
-    store?.mergeAppState(state as unknown as Record<string, unknown>);
-  }, [store, state]);
-
-  return { state, startCall, joinCall, endCall, toggleMute, unlock: playback.unlock };
-}

package/vendor/sdk/main.tsx

@@ -1,125 +0,0 @@
-/**
- * The `ui://` app entry (§6d) — what a HOST loads (the unoverse server's SAB host in an
- * iframe, or Claude/ChatGPT). Boots the AppEngine on the LOCAL vendored SDK. The host
- * provides config (server, bearer, session facts) via `window.__UNOVERSE_APP_CONFIG` or a
- * postMessage `{ type: "unoverse:config", config }` (also the token-refresh channel).
- */
-import { createRoot, type Root } from "react-dom/client";
-import { AppEngine, type AppConfig } from "./appEngine";
-import { connectMcpAppHost } from "./mcpAppBridge";
-import { ResponseView } from "./responseView";
-
-type HostConfig = Omit<AppConfig, "getAccessToken"> & { token?: string };
-
-let root: Root | null = null;
-let current: HostConfig | null = null;
-
-// Stable identity, module-level: the connection hook keys its lifecycle on the
-// `getAccessToken` reference (connection.tsx effect deps), and the host re-posts
-// config on every iframe load — an inline closure here would recycle the live
-// /stream session on each repost.
-const readToken = () => current?.token ?? null;
-
-function render() {
-  if (!current) return;
-  const el = document.getElementById("root")!;
-  if (!root) root = createRoot(el);
-  root.render(
-    <AppEngine
-      serverUrl={current.serverUrl}
-      apiUrl={current.apiUrl}
-      appId={current.appId}
-      userId={current.userId}
-      conversationId={current.conversationId}
-      // ANALYTICS (UNOVERSE_ANALYTICS.md). Host-supplied: the same bundle boots inside a
-      // customer's page, our own client, and an MCP app host, and it cannot tell which
-      // from in here. A host that says nothing gets `mcp_app_host`, the one surface with
-      // no parent page to report to, so an unconfigured boot reports as the surface where
-      // events go nowhere rather than mislabelling itself as a customer embed.
-      surface={current.surface ?? "mcp_app_host"}
-      analyticsDebug={current.analyticsDebug}
-      // Only claim auth when the host actually sent a token. A fabricated accessor on a
-      // tokenless boot made the SDK skip its guest-id substitution (connection.tsx), so
-      // the session registered a non-guest id and the public-entry gate refused it.
-      // No token ⇒ no accessor ⇒ the SDK mints/persists `guest-<uuid>` per the contract
-      // (UNOVERSE_MCP_APP_PROTOCOL §5, docs/auth-security/IDENTITY.md Run Authorization).
-      getAccessToken={current.token ? readToken : undefined}
-    />,
-  );
-}
-
-function apply(cfg: HostConfig) {
-  current = { ...current, ...cfg };
-  // Re-render on every apply so a token appearing/disappearing takes effect; a same-token
-  // refresh changes nothing (readToken is stable, values equal), so no connection churn.
-  render();
-}
-
-declare global {
-  interface Window {
-    __UNOVERSE_APP_CONFIG?: HostConfig;
-  }
-}
-
-if (window.__UNOVERSE_APP_CONFIG) apply(window.__UNOVERSE_APP_CONFIG);
-window.addEventListener("message", (e) => {
-  const msg = e?.data;
-  if (msg?.type === "unoverse:config" && msg.config) apply(msg.config);
-});
-
-// ── MCP Apps host bootstrap (SEP-1865, the STANDARD door) ──────────────────
-// An MCP Apps host (ChatGPT, Claude Desktop, Goose, …) speaks JSON-RPC over postMessage:
-// we send `ui/initialize`, the host pushes `ui/notifications/tool-result`, and the boot
-// facts ride the result's `_meta` (`unoverse/serverUrl` + app + token — widget-only,
-// never seen by the model) with `structuredContent` as the belt-and-braces copy.
-// The legacy `window.openai` config path is REMOVED (2026-08-13): ChatGPT delivers
-// `toolResponseMetadata` empty now, non-OpenAI hosts never had the global, and two boot
-// paths for one host class meant every failure had two explanations. One standard door;
-// our own hosts keep `unoverse:config` / `__UNOVERSE_APP_CONFIG` above.
-connectMcpAppHost((r) => {
-  const meta = (r._meta ?? {}) as Record<string, unknown>;
-  const out = (r.structuredContent ?? {}) as Record<string, unknown>;
-  // serverUrl is SERVER-PROVIDED (`_meta` first, structuredContent as fallback). NEVER
-  // hardcode/guess it — a baked URL ties the bundle to one environment and hides a
-  // missing config. If it's absent, fail loudly and don't mount.
-  const serverUrl = (meta["unoverse/serverUrl"] as string) || (out.serverUrl as string);
-  const conversationId = (out.conversationId as string) || (meta["unoverse/conversationId"] as string);
-  const token = (meta["unoverse/token"] as string) || undefined;
-  const userId = (meta["unoverse/userId"] as string) || undefined;
-
-  // THE NAMING RULE (UNOVERSE_MCP_APP_PROTOCOL § THE NAMING RULE): the RESULT names
-  // its interface. `interface.kind === "components"` → render exactly those (the
-  // response view — no app mount, no session, no home). `interface.kind === "app"`
-  // or a legacy `app`/`unoverse/app` boot fact (the app tools' results, internal
-  // hosts) → the named app mounts. Nothing mounts by default: a result naming
-  // nothing renders nothing, loudly.
-  const iface = out.interface as { kind?: string; components?: Record<string, unknown>[]; app?: string } | undefined;
-  if (iface?.kind === "components" && Array.isArray(iface.components)) {
-    if (!serverUrl) {
-      // eslint-disable-next-line no-console
-      console.warn("[unoverse:boot] response result carried no serverUrl — cannot resolve definitions");
-      return;
-    }
-    // eslint-disable-next-line no-console
-    console.log("[unoverse:boot] rendering RESPONSE from MCP host", { serverUrl, components: iface.components.length });
-    const el = document.getElementById("root")!;
-    if (!root) root = createRoot(el);
-    root.render(<ResponseView serverUrl={serverUrl} events={iface.components} />);
-    return;
-  }
-
-  const appId = (iface?.kind === "app" ? iface.app : undefined) || (out.app as string) || (meta["unoverse/app"] as string);
-  if (!appId || !serverUrl) {
-    // eslint-disable-next-line no-console
-    console.warn("[unoverse:boot] cannot mount — result named no interface (no components, no app)", {
-      serverUrl,
-      appId,
-      structuredContent: out,
-      metaKeys: Object.keys(meta),
-    });
-    return;
-  }
-  // eslint-disable-next-line no-console
-  console.log("[unoverse:boot] mounting NAMED app from MCP host", { serverUrl, appId, conversationId, userId, hasToken: Boolean(token) });
-  apply({ serverUrl, appId, conversationId, userId, token });
-});