@agent-native/core 0.93.0 → 0.94.0

package/corpus/core/src/server/realtime-voice.ts

@@ -0,0 +1,590 @@
+import {
+  defineEventHandler,
+  getHeader,
+  getMethod,
+  readRawBody,
+  setResponseHeader,
+  setResponseStatus,
+  type H3Event,
+} from "h3";
+
+import {
+  actionsToEngineTools,
+  type ActionEntry,
+} from "../agent/production-agent.js";
+import {
+  redactSensitiveFields,
+  sanitizeToolErrorText,
+  sanitizeToolErrorValue,
+} from "../agent/tool-error-redaction.js";
+import { getSession } from "./auth.js";
+import { resolveSecret } from "./credential-provider.js";
+import { getH3App } from "./framework-request-handler.js";
+import { runWithRequestContext } from "./request-context.js";
+
+export const REALTIME_VOICE_SESSION_PATH =
+  "/_agent-native/realtime-voice/session";
+export const REALTIME_VOICE_TOOL_PATH = "/_agent-native/realtime-voice/tool";
+export const REALTIME_VOICE_MAX_SDP_BYTES = 64 * 1024;
+export const REALTIME_VOICE_MAX_TOOL_BODY_BYTES = 64 * 1024;
+export const REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS = 16_000;
+
+const OPENAI_REALTIME_CALLS_URL = "https://api.openai.com/v1/realtime/calls";
+const DEFAULT_MODEL = "gpt-realtime-2.1";
+const DEFAULT_VOICE = "marin";
+const DEFAULT_INSTRUCTIONS =
+  "You are the live voice interface for this Agent Native app. Speak naturally, briefly, and conversationally. Use the available function tools when the user asks you to navigate or take an action. Never claim an action succeeded until its tool result confirms success. If a tool requires approval, explain that the user must approve it in chat.";
+const MAX_INSTRUCTIONS_CHARS = 16_000;
+const MAX_TOOL_DESCRIPTION_CHARS = 2_000;
+const MAX_TOOL_SCHEMA_CHARS = 64 * 1024;
+const MAX_APPROVAL_KEY_CHARS = 1_024;
+const REALTIME_TOOL_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const CALL_ID = /^[A-Za-z0-9_-]{1,256}$/;
+const SESSION_ID = /^[A-Za-z0-9_.:-]{1,256}$/;
+const BROWSER_TAB_ID = /^[A-Za-z0-9_-]{1,96}$/;
+
+export interface RealtimeVoiceRequestContext {
+  event: H3Event;
+  userEmail: string;
+  orgId?: string;
+  browserTabId?: string;
+}
+
+export interface RealtimeVoiceToolExecutionRequest extends RealtimeVoiceRequestContext {
+  name: string;
+  args: Record<string, unknown>;
+  callId: string;
+  sessionId?: string;
+}
+
+export interface RealtimeVoiceToolExecutionResult {
+  status: "completed" | "failed" | "approval_required";
+  output: string;
+  approvalKey?: string;
+}
+
+export interface MountRealtimeVoiceRoutesOptions {
+  /** Server-controlled model. Defaults to gpt-realtime-2.1. */
+  model?: string;
+  /** Server-controlled output voice. Defaults to marin. */
+  voice?: string;
+  /** Static app guidance appended to the safe default voice instructions. */
+  instructions?: string;
+  /** Per-request app/navigation guidance. It is sent only to OpenAI. */
+  getInstructions?: (
+    context: RealtimeVoiceRequestContext,
+  ) => string | null | undefined | Promise<string | null | undefined>;
+  /** Optional app-specific active-organization resolver. */
+  resolveOrgId?: (
+    event: H3Event,
+  ) => string | null | undefined | Promise<string | null | undefined>;
+  /**
+   * Central agent tool executor supplied by the agent-chat plugin. The executor
+   * owns validation, approval, journaling, timeout, mutation notification, and
+   * action-result normalization; this transport must not call ActionEntry.run.
+   */
+  executeTool: (
+    request: RealtimeVoiceToolExecutionRequest,
+  ) =>
+    | RealtimeVoiceToolExecutionResult
+    | Promise<RealtimeVoiceToolExecutionResult>;
+}
+
+interface RealtimeFunctionTool {
+  type: "function";
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+interface AuthenticatedVoiceContext extends RealtimeVoiceRequestContext {
+  timezone?: string;
+}
+
+function readSafeHeader(event: H3Event, name: string): string | undefined {
+  const value = getHeader(event, name);
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function configuredIdentifier(
+  value: string | undefined,
+  fallback: string,
+): string {
+  const trimmed = value?.trim();
+  return trimmed && /^[A-Za-z0-9_.:-]{1,128}$/.test(trimmed)
+    ? trimmed
+    : fallback;
+}
+
+function truncate(value: string, maxChars: number): string {
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, maxChars)}\n\n...[truncated]`;
+}
+
+function sanitizeOutput(value: unknown, maxChars: number): string {
+  let serialized: string;
+  try {
+    const redacted = redactSensitiveFields(value);
+    serialized =
+      typeof redacted === "string"
+        ? redacted
+        : (JSON.stringify(redacted, (_key, entry) =>
+            typeof entry === "bigint" ? entry.toString() : entry,
+          ) ?? "null");
+  } catch {
+    serialized = "[Unserializable tool result]";
+  }
+  return truncate(sanitizeToolErrorText(serialized), maxChars);
+}
+
+async function safeOpenAiErrorDetail(
+  response: Response,
+  apiKey: string,
+): Promise<string | null> {
+  const raw = await response.text().catch(() => "");
+  if (!raw) return null;
+  let detail = raw;
+  try {
+    const parsed = JSON.parse(raw) as {
+      error?: { message?: unknown; code?: unknown; type?: unknown } | unknown;
+    };
+    if (parsed.error && typeof parsed.error === "object") {
+      const error = parsed.error as {
+        message?: unknown;
+        code?: unknown;
+        type?: unknown;
+      };
+      detail = [error.message, error.code, error.type]
+        .filter((value) => typeof value === "string" && value.trim())
+        .join(" · ");
+    }
+  } catch {
+    // Plain-text upstream errors are sanitized below.
+  }
+  const redacted = sanitizeToolErrorText(detail).replaceAll(
+    apiKey,
+    "[REDACTED]",
+  );
+  return truncate(redacted, 500) || null;
+}
+
+function normalizeToolSchema(
+  inputSchema: unknown,
+): Record<string, unknown> | null {
+  try {
+    const serialized = JSON.stringify(inputSchema);
+    if (!serialized || serialized.length > MAX_TOOL_SCHEMA_CHARS) return null;
+    const parsed = JSON.parse(serialized) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function buildRealtimeTools(
+  actions: Record<string, ActionEntry>,
+): RealtimeFunctionTool[] {
+  const tools: RealtimeFunctionTool[] = [];
+  for (const tool of actionsToEngineTools(actions)) {
+    if (!REALTIME_TOOL_NAME.test(tool.name)) continue;
+    const parameters = normalizeToolSchema(tool.inputSchema);
+    if (!parameters) continue;
+    tools.push({
+      type: "function",
+      name: tool.name,
+      description: truncate(
+        sanitizeToolErrorText(tool.description || ""),
+        MAX_TOOL_DESCRIPTION_CHARS,
+      ),
+      parameters,
+    });
+  }
+  return tools;
+}
+
+function declaredBodyBytes(event: H3Event): number | undefined {
+  const raw = readSafeHeader(event, "content-length");
+  if (!raw) return undefined;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+async function readLimitedRawBody(
+  event: H3Event,
+  maxBytes: number,
+): Promise<string | null | "oversize"> {
+  const declared = declaredBodyBytes(event);
+  if (declared !== undefined && declared > maxBytes) return "oversize";
+
+  const raw = await readRawBody(event, "utf8").catch(() => undefined);
+  if (raw == null) return null;
+  const text =
+    typeof raw === "string" ? raw : new TextDecoder().decode(raw as Uint8Array);
+  return new TextEncoder().encode(text).byteLength > maxBytes
+    ? "oversize"
+    : text;
+}
+
+async function authenticateVoiceRequest(
+  event: H3Event,
+  options: MountRealtimeVoiceRoutesOptions,
+): Promise<AuthenticatedVoiceContext | null> {
+  const session = await getSession(event).catch(() => null);
+  if (!session?.email) return null;
+  const resolvedOrgId = options.resolveOrgId
+    ? await options.resolveOrgId(event)
+    : session.orgId;
+  const timezone = readSafeHeader(event, "x-user-timezone");
+  const rawBrowserTabId = readSafeHeader(event, "x-agent-native-browser-tab");
+  const browserTabId =
+    rawBrowserTabId && BROWSER_TAB_ID.test(rawBrowserTabId)
+      ? rawBrowserTabId
+      : undefined;
+  return {
+    event,
+    userEmail: session.email,
+    ...(resolvedOrgId ? { orgId: resolvedOrgId } : {}),
+    ...(timezone && timezone.length < 64 ? { timezone } : {}),
+    ...(browserTabId ? { browserTabId } : {}),
+  };
+}
+
+async function buildInstructions(
+  context: RealtimeVoiceRequestContext,
+  options: MountRealtimeVoiceRoutesOptions,
+): Promise<string> {
+  const dynamic = await options.getInstructions?.(context);
+  const appInstructions = dynamic ?? options.instructions;
+  if (!appInstructions?.trim()) return DEFAULT_INSTRUCTIONS;
+  return truncate(
+    sanitizeToolErrorText(
+      `${DEFAULT_INSTRUCTIONS}\n\n${appInstructions.trim()}`,
+    ),
+    MAX_INSTRUCTIONS_CHARS,
+  );
+}
+
+/**
+ * Hash the authenticated identity before sending it to OpenAI. The stable
+ * digest is useful for abuse detection without disclosing the user's email.
+ */
+export async function realtimeVoiceSafetyIdentifier(
+  userEmail: string,
+): Promise<string> {
+  const input = new TextEncoder().encode(
+    `agent-native:${userEmail.trim().toLowerCase()}`,
+  );
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", input);
+  return Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");
+}
+
+function invalidMethod(event: H3Event): { error: string } {
+  setResponseStatus(event, 405);
+  return { error: "Method not allowed" };
+}
+
+function createSessionHandler(
+  tools: RealtimeFunctionTool[],
+  options: MountRealtimeVoiceRoutesOptions,
+) {
+  return defineEventHandler(async (event: H3Event) => {
+    if (getMethod(event) !== "POST") return invalidMethod(event);
+    setResponseHeader(event, "Cache-Control", "no-store");
+
+    const auth = await authenticateVoiceRequest(event, options);
+    if (!auth) {
+      setResponseStatus(event, 401);
+      return { error: "Authentication required" };
+    }
+
+    const contentType = readSafeHeader(event, "content-type")?.toLowerCase();
+    if (!contentType?.includes("application/sdp")) {
+      setResponseStatus(event, 415);
+      return { error: "Expected Content-Type: application/sdp" };
+    }
+
+    const rawSdp = await readLimitedRawBody(
+      event,
+      REALTIME_VOICE_MAX_SDP_BYTES,
+    );
+    if (rawSdp === "oversize") {
+      setResponseStatus(event, 413);
+      return {
+        error: `SDP offer is too large (max ${REALTIME_VOICE_MAX_SDP_BYTES} bytes)`,
+      };
+    }
+    const sdp = rawSdp ?? "";
+    if (!sdp.trim()) {
+      setResponseStatus(event, 400);
+      return { error: "SDP offer is required" };
+    }
+
+    return runWithRequestContext(
+      {
+        userEmail: auth.userEmail,
+        orgId: auth.orgId,
+        timezone: auth.timezone,
+        run: auth.browserTabId
+          ? { browserTabId: auth.browserTabId }
+          : undefined,
+      },
+      async () => {
+        const apiKey = (await resolveSecret("OPENAI_API_KEY"))?.trim();
+        if (!apiKey) {
+          setResponseStatus(event, 400);
+          return {
+            error:
+              "Configure OPENAI_API_KEY in Settings to use realtime voice.",
+          };
+        }
+
+        const instructions = await buildInstructions(auth, options);
+        const session = {
+          type: "realtime",
+          model: configuredIdentifier(options.model, DEFAULT_MODEL),
+          instructions,
+          output_modalities: ["audio"],
+          audio: {
+            input: {
+              transcription: { model: "gpt-4o-mini-transcribe" },
+              turn_detection: {
+                type: "semantic_vad",
+                create_response: true,
+                interrupt_response: true,
+                eagerness: "auto",
+              },
+            },
+            output: {
+              voice: configuredIdentifier(options.voice, DEFAULT_VOICE),
+            },
+          },
+          tools,
+          tool_choice: "auto",
+        };
+
+        const form = new FormData();
+        form.set("sdp", sdp);
+        form.set("session", JSON.stringify(session));
+
+        let upstream: Response;
+        try {
+          upstream = await fetch(OPENAI_REALTIME_CALLS_URL, {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${apiKey}`,
+              "OpenAI-Safety-Identifier": await realtimeVoiceSafetyIdentifier(
+                auth.userEmail,
+              ),
+            },
+            body: form,
+          });
+        } catch {
+          setResponseStatus(event, 502);
+          return { error: "Could not reach the OpenAI Realtime API" };
+        }
+
+        if (!upstream.ok) {
+          const detail = await safeOpenAiErrorDetail(upstream, apiKey);
+          setResponseStatus(event, 502);
+          return {
+            error: `OpenAI rejected the realtime session (${upstream.status})${detail ? `: ${detail}` : ""}`,
+          };
+        }
+
+        const answerSdp = await upstream.text().catch(() => "");
+        if (!answerSdp.trim()) {
+          setResponseStatus(event, 502);
+          return { error: "OpenAI returned an empty realtime session answer" };
+        }
+
+        setResponseStatus(event, upstream.status);
+        setResponseHeader(event, "Content-Type", "application/sdp");
+        return answerSdp;
+      },
+    );
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseToolRequest(value: unknown): {
+  name: string;
+  args: Record<string, unknown>;
+  callId: string;
+  sessionId?: string;
+  browserTabId?: string;
+} | null {
+  if (!isRecord(value)) return null;
+  const { name, args, callId, sessionId, browserTabId } = value;
+  if (typeof name !== "string" || !REALTIME_TOOL_NAME.test(name)) return null;
+  if (typeof callId !== "string" || !CALL_ID.test(callId)) return null;
+  if (!isRecord(args)) return null;
+  if (
+    sessionId !== undefined &&
+    (typeof sessionId !== "string" || !SESSION_ID.test(sessionId))
+  ) {
+    return null;
+  }
+  if (
+    browserTabId !== undefined &&
+    (typeof browserTabId !== "string" || !BROWSER_TAB_ID.test(browserTabId))
+  ) {
+    return null;
+  }
+  return {
+    name,
+    args,
+    callId,
+    ...(sessionId ? { sessionId } : {}),
+    ...(browserTabId ? { browserTabId } : {}),
+  };
+}
+
+function normalizeExecutionResult(
+  result: RealtimeVoiceToolExecutionResult,
+): RealtimeVoiceToolExecutionResult {
+  const status = result?.status;
+  if (
+    status !== "completed" &&
+    status !== "failed" &&
+    status !== "approval_required"
+  ) {
+    throw new Error("Invalid realtime tool execution status");
+  }
+  const output = sanitizeOutput(
+    result.output,
+    REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS,
+  );
+  return {
+    status,
+    output,
+    ...(status === "approval_required" &&
+    typeof result.approvalKey === "string" &&
+    result.approvalKey.length > 0 &&
+    result.approvalKey.length <= MAX_APPROVAL_KEY_CHARS
+      ? { approvalKey: result.approvalKey }
+      : {}),
+  };
+}
+
+function createToolHandler(
+  allowedToolNames: ReadonlySet<string>,
+  options: MountRealtimeVoiceRoutesOptions,
+) {
+  return defineEventHandler(async (event: H3Event) => {
+    if (getMethod(event) !== "POST") return invalidMethod(event);
+    setResponseHeader(event, "Cache-Control", "no-store");
+
+    const auth = await authenticateVoiceRequest(event, options);
+    if (!auth) {
+      setResponseStatus(event, 401);
+      return { error: "Authentication required" };
+    }
+
+    const contentType = readSafeHeader(event, "content-type")?.toLowerCase();
+    if (!contentType?.includes("application/json")) {
+      setResponseStatus(event, 415);
+      return { error: "Expected Content-Type: application/json" };
+    }
+
+    const raw = await readLimitedRawBody(
+      event,
+      REALTIME_VOICE_MAX_TOOL_BODY_BYTES,
+    );
+    if (raw === "oversize") {
+      setResponseStatus(event, 413);
+      return {
+        error: `Tool request is too large (max ${REALTIME_VOICE_MAX_TOOL_BODY_BYTES} bytes)`,
+      };
+    }
+
+    let parsedBody: unknown;
+    try {
+      parsedBody = JSON.parse(raw ?? "");
+    } catch {
+      setResponseStatus(event, 400);
+      return { error: "Invalid realtime tool request" };
+    }
+    const request = parseToolRequest(parsedBody);
+    if (!request) {
+      setResponseStatus(event, 400);
+      return { error: "Invalid realtime tool request" };
+    }
+    if (!allowedToolNames.has(request.name)) {
+      setResponseStatus(event, 404);
+      return { error: "Unknown realtime voice tool" };
+    }
+
+    const browserTabId = request.browserTabId ?? auth.browserTabId;
+    const threadId = request.sessionId
+      ? `realtime:${request.sessionId}`
+      : `realtime:${request.callId}`;
+    return runWithRequestContext(
+      {
+        userEmail: auth.userEmail,
+        orgId: auth.orgId,
+        timezone: auth.timezone,
+        run: {
+          threadId,
+          ...(browserTabId ? { browserTabId } : {}),
+        },
+      },
+      async () => {
+        try {
+          const result = normalizeExecutionResult(
+            await options.executeTool({
+              event,
+              userEmail: auth.userEmail,
+              orgId: auth.orgId,
+              ...request,
+            }),
+          );
+          return { callId: request.callId, ...result };
+        } catch (error) {
+          setResponseStatus(event, 500);
+          return {
+            callId: request.callId,
+            status: "failed" as const,
+            output: truncate(
+              sanitizeToolErrorValue(error) || "Tool execution failed",
+              REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS,
+            ),
+          };
+        }
+      },
+    );
+  });
+}
+
+/** Mount the authenticated OpenAI Realtime WebRTC and tool bridge routes. */
+export function mountRealtimeVoiceRoutes(
+  nitroApp: any,
+  actions: Record<string, ActionEntry>,
+  options: MountRealtimeVoiceRoutesOptions,
+): { sessionPath: string; toolPath: string } {
+  if (typeof options?.executeTool !== "function") {
+    throw new Error("mountRealtimeVoiceRoutes requires executeTool");
+  }
+
+  const tools = buildRealtimeTools(actions);
+  const allowedToolNames = new Set(tools.map((tool) => tool.name));
+  const app = getH3App(nitroApp);
+  app.use(REALTIME_VOICE_SESSION_PATH, createSessionHandler(tools, options));
+  app.use(
+    REALTIME_VOICE_TOOL_PATH,
+    createToolHandler(allowedToolNames, options),
+  );
+  return {
+    sessionPath: REALTIME_VOICE_SESSION_PATH,
+    toolPath: REALTIME_VOICE_TOOL_PATH,
+  };
+}