@tribe-nest/forge 3.65.0 → 3.69.0

package/src/ui/headless/agent/_tests/useAgentCall.spec.tsx

@@ -0,0 +1,213 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { ForgeClientProvider } from "../../../../provider/ForgeProvider";
+import { useAgentCall } from "../useAgentCall";
+
+/**
+ * "Call us", headless. Every call costs the business by the minute, so what
+ * is pinned here is the money-shaped part: the request sequence that starts a
+ * call, that a reconnect asks for a FRESH ticket with the identity the start
+ * gave, and that every way out (hang up, hang up mid-setup, leaving the page,
+ * unmounting) ends the call on the server.
+ */
+
+const API = "https://api.test";
+const PROFILE = "11111111-1111-4111-8111-111111111111";
+const WEBSITE = "22222222-2222-4222-8222-222222222222";
+
+const CALL = {
+  callId: "call-1",
+  roomId: "room-1",
+  mediaUrl: "wss://media.test",
+  token: "ticket-1",
+  expiresAt: "2026-10-05T12:00:00Z",
+  identity: "visitor-33333333-3333-4333-8333-333333333333",
+  callKey: "key-1",
+};
+
+type Route = (body: Record<string, unknown>) => { status: number; body: unknown };
+
+let routes: Record<string, Route>;
+let calls: { url: string; body: Record<string, unknown>; keepalive?: boolean }[];
+
+beforeEach(() => {
+  calls = [];
+  routes = {
+    "/public/agent/calls/challenge": () => ({ status: 201, body: { challenge: "c1", difficulty: 4, expiresAt: "x" } }),
+    "/public/agent/calls": () => ({ status: 201, body: CALL }),
+    "/public/agent/calls/call-1/join": () => ({ status: 201, body: { ...CALL, token: "ticket-2" } }),
+    "/public/agent/calls/call-1/end": () => ({ status: 201, body: { ended: true } }),
+  };
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string, init: RequestInit) => {
+      const path = url.replace(API, "");
+      const body = JSON.parse(String(init.body ?? "{}"));
+      calls.push({ url: path, body, keepalive: init.keepalive });
+      const route = routes[path];
+      const res = route ? route(body) : { status: 404, body: { message: "no route" } };
+      return new Response(JSON.stringify(res.body), { status: res.status, headers: { "Content-Type": "application/json" } });
+    }),
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+const wrapper =
+  (websiteId?: string) =>
+  ({ children }: { children: ReactNode }) => (
+    <ForgeClientProvider apiUrl={API} profileId={PROFILE} websiteId={websiteId}>
+      {children}
+    </ForgeClientProvider>
+  );
+
+const mount = ({ websiteId }: { websiteId?: string } = { websiteId: WEBSITE }) =>
+  renderHook(() => useAgentCall({ visitorId: "visitor-a", solver: { yieldToPage: async () => undefined } }), {
+    wrapper: wrapper(websiteId),
+  });
+
+describe("useAgentCall: starting a call", () => {
+  it("asks for the check, solves it, and starts the call for THIS website", async () => {
+    const { result } = mount();
+    await act(() => result.current.start());
+
+    expect(result.current.state).toEqual({ phase: "live", call: CALL });
+    expect(calls.map((c) => c.url)).toEqual(["/public/agent/calls/challenge", "/public/agent/calls"]);
+    expect(calls[0].body).toEqual({ profileId: PROFILE, websiteId: WEBSITE, visitorId: "visitor-a" });
+    const start = calls[1].body;
+    expect(start).toMatchObject({ profileId: PROFILE, websiteId: WEBSITE, visitorId: "visitor-a", challenge: "c1" });
+    expect(String(start.solution)).toMatch(/^\d{1,12}$/);
+  });
+
+  it("leaves websiteId out when the site does not know it, so the profile's agent answers", async () => {
+    const { result } = mount({});
+    await act(() => result.current.start());
+    expect(calls[0].body).toEqual({ profileId: PROFILE, visitorId: "visitor-a" });
+    expect(calls[1].body).not.toHaveProperty("websiteId");
+  });
+
+  it.each([
+    [429, "too_many"],
+    [404, "unavailable"],
+    [409, "busy"],
+    [400, "check_failed"],
+    [503, "failed"],
+  ])("reports a %i refusal as %s, with the API's message", async (status, kind) => {
+    routes["/public/agent/calls"] = () => ({ status, body: { status, message: `refused ${status}` } });
+    const { result } = mount();
+    await act(() => result.current.start());
+    expect(result.current.state).toEqual({ phase: "error", error: kind, message: `refused ${status}` });
+  });
+
+  it("reports a refused CHALLENGE too (404: this site's agent takes no calls) without starting anything", async () => {
+    routes["/public/agent/calls/challenge"] = () => ({ status: 404, body: { message: "no calls" } });
+    const { result } = mount();
+    await act(() => result.current.start());
+    expect(result.current.state).toMatchObject({ phase: "error", error: "unavailable" });
+    expect(calls.map((c) => c.url)).toEqual(["/public/agent/calls/challenge"]);
+  });
+
+  it("can try again after an error", async () => {
+    routes["/public/agent/calls"] = () => ({ status: 409, body: { message: "busy" } });
+    const { result } = mount();
+    await act(() => result.current.start());
+    routes["/public/agent/calls"] = () => ({ status: 201, body: CALL });
+    await act(() => result.current.start());
+    expect(result.current.state.phase).toBe("live");
+  });
+
+  it("does not start a second call while one is connecting", async () => {
+    const { result } = mount();
+    await act(async () => {
+      void result.current.start();
+      void result.current.start();
+    });
+    await waitFor(() => expect(result.current.state.phase).toBe("live"));
+    expect(calls.filter((c) => c.url === "/public/agent/calls/challenge")).toHaveLength(1);
+  });
+});
+
+describe("useAgentCall: the media room's credentials", () => {
+  it("uses the start response first, then a fresh ticket per reconnect with the start's identity", async () => {
+    const { result } = mount();
+    await act(() => result.current.start());
+
+    await expect(result.current.getCredentials()).resolves.toEqual({ mediaUrl: CALL.mediaUrl, token: "ticket-1" });
+    expect(calls.some((c) => c.url.endsWith("/join"))).toBe(false);
+
+    await expect(result.current.getCredentials()).resolves.toEqual({ mediaUrl: CALL.mediaUrl, token: "ticket-2" });
+    const join = calls.find((c) => c.url === "/public/agent/calls/call-1/join");
+    expect(join?.body).toEqual({ callKey: CALL.callKey, identity: CALL.identity });
+  });
+});
+
+describe("useAgentCall: every way out ends the call on the server", () => {
+  it("hang up posts the end with the call key and shows the call ended", async () => {
+    const { result } = mount();
+    await act(() => result.current.start());
+    act(() => result.current.end());
+
+    expect(result.current.state).toEqual({ phase: "ended", callId: "call-1" });
+    await waitFor(() =>
+      expect(calls.find((c) => c.url === "/public/agent/calls/call-1/end")?.body).toEqual({ callKey: CALL.callKey }),
+    );
+  });
+
+  it("hanging up while the call is being set up ends the call the server then creates", async () => {
+    let releaseStart!: () => void;
+    const gate = new Promise<void>((resolve) => (releaseStart = resolve));
+    const fetchMock = globalThis.fetch as ReturnType<typeof vi.fn>;
+    const original = fetchMock.getMockImplementation()!;
+    fetchMock.mockImplementation(async (url: string, init: RequestInit) => {
+      if (url === `${API}/public/agent/calls`) await gate;
+      return original(url, init);
+    });
+
+    const { result } = mount();
+    let starting!: Promise<void>;
+    act(() => {
+      starting = result.current.start();
+    });
+    await waitFor(() => expect(calls.some((c) => c.url === "/public/agent/calls")).toBe(false));
+    act(() => result.current.end());
+    expect(result.current.state).toEqual({ phase: "idle" });
+
+    releaseStart();
+    await act(() => starting);
+    // Either the solver saw the abort before starting (nothing to end), or the
+    // start went out and the call it created is ended straight away. Never a
+    // live call nobody can hang up.
+    expect(result.current.state).toEqual({ phase: "idle" });
+    const started = calls.some((c) => c.url === "/public/agent/calls");
+    const ended = calls.some((c) => c.url === "/public/agent/calls/call-1/end");
+    expect(ended).toBe(started);
+  });
+
+  it("leaving the page ends the call with a request that outlives the page", async () => {
+    const { result } = mount();
+    await act(() => result.current.start());
+    act(() => {
+      window.dispatchEvent(new Event("pagehide"));
+    });
+    const end = calls.find((c) => c.url === "/public/agent/calls/call-1/end");
+    expect(end).toMatchObject({ body: { callKey: CALL.callKey }, keepalive: true });
+  });
+
+  it("unmounting ends the call", async () => {
+    const { result, unmount } = mount();
+    await act(() => result.current.start());
+    unmount();
+    expect(calls.filter((c) => c.url === "/public/agent/calls/call-1/end")).toHaveLength(1);
+  });
+
+  it("does not end anything when there is no call", () => {
+    const { unmount } = mount();
+    window.dispatchEvent(new Event("pagehide"));
+    unmount();
+    expect(calls).toEqual([]);
+  });
+});

package/src/ui/headless/agent/callChallenge.ts

@@ -0,0 +1,72 @@
+/**
+ * The bot check in front of "Call us".
+ *
+ * A call costs real money per minute, so before the backend starts one it asks
+ * the browser to spend a second or so of work: find a decimal `solution` such
+ * that SHA-256 of `${challenge}:${solution}` starts with `difficulty` zero
+ * bits. One visitor barely notices; a script dialling thousands of calls pays
+ * for every one. The backend checks the same thing in `callGuard.ts`.
+ */
+
+/** How many zero bits the digest starts with. */
+export function leadingZeroBits(bytes: Uint8Array): number {
+  let bits = 0;
+  for (const byte of bytes) {
+    if (byte === 0) {
+      bits += 8;
+      continue;
+    }
+    return bits + Math.clz32(byte) - 24;
+  }
+  return bits;
+}
+
+/** The backend accepts up to 12 digits. */
+const MAX_SOLUTION = 999_999_999_999;
+
+export interface SolveCallChallengeOptions {
+  /** Hashes per batch. Between batches the solver yields, so the page can paint. */
+  batchSize?: number;
+  signal?: AbortSignal;
+  /** How the solver gives the page a turn. Defaults to a zero timeout. */
+  yieldToPage?: () => Promise<void>;
+}
+
+const defaultYield = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+/**
+ * Finds the smallest solution. At the backend's difficulty of 16 that is about
+ * 65k hashes on average. `crypto.subtle` is async, so a batch is hashed in
+ * parallel and the solver then yields, which keeps a "Connecting" spinner
+ * turning while it works. Rejects with an `AbortError` when `signal` aborts.
+ */
+export async function solveCallChallenge(
+  challenge: string,
+  difficulty: number,
+  { batchSize = 512, signal, yieldToPage = defaultYield }: SolveCallChallengeOptions = {},
+): Promise<string> {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) throw new Error("This browser cannot run the call check.");
+  const encoder = new TextEncoder();
+
+  for (let start = 0; start <= MAX_SOLUTION; start += batchSize) {
+    if (signal?.aborted) throw abortError();
+    const end = Math.min(start + batchSize, MAX_SOLUTION + 1);
+    const candidates: number[] = [];
+    for (let n = start; n < end; n++) candidates.push(n);
+    const digests = await Promise.all(
+      candidates.map((n) => subtle.digest("SHA-256", encoder.encode(`${challenge}:${n}`))),
+    );
+    for (let i = 0; i < digests.length; i++) {
+      if (leadingZeroBits(new Uint8Array(digests[i])) >= difficulty) return String(candidates[i]);
+    }
+    await yieldToPage();
+  }
+  throw new Error("No solution found.");
+}
+
+function abortError(): Error {
+  const err = new Error("The call check was cancelled.");
+  err.name = "AbortError";
+  return err;
+}

package/src/ui/headless/agent/useAgentCall.ts

@@ -0,0 +1,189 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useForge } from "../../../provider/ForgeProvider";
+import {
+  AgentCallRequestError,
+  endAgentCall,
+  joinAgentCall,
+  requestAgentCallChallenge,
+  startAgentCall,
+  type AgentCallCredentials,
+} from "../../../data/queries/useWebsiteAgent";
+import { solveCallChallenge, type SolveCallChallengeOptions } from "./callChallenge";
+import { getAgentVisitorId } from "./visitorId";
+
+/**
+ * Why a call could not start, by what the backend said.
+ *
+ * - `too_many`: the visitor or their network called too often (429).
+ * - `unavailable`: this website's agent takes no calls (404).
+ * - `busy`: every line is taken, or the business's minutes are used up (409).
+ * - `check_failed`: the bot check was refused, usually an expired challenge (400).
+ * - `failed`: anything else, including the call network being down (503).
+ */
+export type AgentCallErrorKind = "too_many" | "unavailable" | "busy" | "check_failed" | "failed";
+
+export type AgentCallState =
+  | { phase: "idle" }
+  /** Asking for the bot check, solving it and starting the call. */
+  | { phase: "connecting" }
+  /** The call exists: join its media room with `getCredentials`. */
+  | { phase: "live"; call: AgentCallCredentials }
+  | { phase: "ended"; callId: string }
+  | { phase: "error"; error: AgentCallErrorKind; message: string };
+
+export function classifyAgentCallError(err: unknown): AgentCallErrorKind {
+  if (!(err instanceof AgentCallRequestError)) return "failed";
+  switch (err.status) {
+    case 429:
+      return "too_many";
+    case 404:
+      return "unavailable";
+    case 409:
+      return "busy";
+    case 400:
+      return "check_failed";
+    default:
+      return "failed";
+  }
+}
+
+export interface UseAgentCallOptions {
+  /** Defaults to the widget's own visitor id, which the chat uses too. */
+  visitorId?: string;
+  /** Passed to the bot-check solver; tests use it to keep the work small. */
+  solver?: SolveCallChallengeOptions;
+}
+
+/**
+ * Headless "Call us": a voice call with the website's agent, in the browser.
+ *
+ * `start()` asks for the bot check, solves it, and starts the call; the state
+ * then turns `live` and the UI mounts a `MediaRoomProvider` with
+ * `getCredentials`. The first connect uses the start response, and every
+ * reconnect after it fetches a fresh ticket, because a ticket expires in
+ * minutes. `end()` hangs up. Leaving the page, or unmounting the hook, hangs
+ * up too, so a forgotten tab does not hold a line that costs the business by
+ * the minute.
+ *
+ * This hook has no media code in it on purpose: the room lives in the UI that
+ * mounts on `live`, which a site can load lazily.
+ */
+export function useAgentCall(options: UseAgentCallOptions = {}) {
+  const { apiUrl, profileId, websiteId } = useForge();
+  const visitorId = useMemo(() => options.visitorId ?? getAgentVisitorId(), [options.visitorId]);
+  const [state, setState] = useState<AgentCallState>({ phase: "idle" });
+
+  // Refs, so hanging up from `pagehide` or an unmount reads the call as it is
+  // NOW rather than as it was when the listener was attached.
+  const apiUrlRef = useRef(apiUrl);
+  apiUrlRef.current = apiUrl;
+  const solverRef = useRef(options.solver);
+  solverRef.current = options.solver;
+  const callRef = useRef<AgentCallCredentials | null>(null);
+  const firstCredentials = useRef<AgentCallCredentials | null>(null);
+  const runRef = useRef<AbortController | null>(null);
+
+  const start = useCallback(async () => {
+    if (!apiUrl || !profileId || runRef.current) return;
+    const run = new AbortController();
+    runRef.current = run;
+    setState({ phase: "connecting" });
+    try {
+      const check = await requestAgentCallChallenge({ apiUrl, profileId, websiteId, visitorId });
+      const solution = await solveCallChallenge(check.challenge, check.difficulty, {
+        ...solverRef.current,
+        signal: run.signal,
+      });
+      if (run.signal.aborted) return;
+      const call = await startAgentCall({
+        apiUrl,
+        profileId,
+        websiteId,
+        visitorId,
+        challenge: check.challenge,
+        solution,
+      });
+      if (run.signal.aborted) {
+        // Hung up while the call was being set up: it exists now, so end it.
+        void endAgentCall({ apiUrl, callId: call.callId, callKey: call.callKey }).catch(() => undefined);
+        return;
+      }
+      callRef.current = call;
+      firstCredentials.current = call;
+      setState({ phase: "live", call });
+    } catch (err) {
+      if (run.signal.aborted) return;
+      runRef.current = null;
+      setState({
+        phase: "error",
+        error: classifyAgentCallError(err),
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }, [apiUrl, profileId, websiteId, visitorId]);
+
+  /** Hangs up, or stops a call that is still connecting. */
+  const end = useCallback(() => {
+    const run = runRef.current;
+    runRef.current = null;
+    run?.abort();
+    const call = callRef.current;
+    callRef.current = null;
+    firstCredentials.current = null;
+    if (call) {
+      void endAgentCall({ apiUrl: apiUrlRef.current, callId: call.callId, callKey: call.callKey }).catch(
+        () => undefined,
+      );
+      setState({ phase: "ended", callId: call.callId });
+    } else {
+      setState({ phase: "idle" });
+    }
+  }, []);
+
+  /** Back to idle from `ended` or `error`, ready for another call. */
+  const reset = useCallback(() => {
+    if (runRef.current) return;
+    setState({ phase: "idle" });
+  }, []);
+
+  const getCredentials = useCallback(async () => {
+    const first = firstCredentials.current;
+    if (first) {
+      firstCredentials.current = null;
+      return { mediaUrl: first.mediaUrl, token: first.token };
+    }
+    const call = callRef.current;
+    if (!call) throw new Error("The call has ended.");
+    const fresh = await joinAgentCall({
+      apiUrl: apiUrlRef.current,
+      callId: call.callId,
+      callKey: call.callKey,
+      identity: call.identity,
+    });
+    return { mediaUrl: fresh.mediaUrl, token: fresh.token };
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const hangUpOnLeave = () => {
+      runRef.current?.abort();
+      runRef.current = null;
+      const call = callRef.current;
+      if (!call) return;
+      callRef.current = null;
+      void endAgentCall({
+        apiUrl: apiUrlRef.current,
+        callId: call.callId,
+        callKey: call.callKey,
+        keepalive: true,
+      }).catch(() => undefined);
+    };
+    window.addEventListener("pagehide", hangUpOnLeave);
+    return () => {
+      window.removeEventListener("pagehide", hangUpOnLeave);
+      hangUpOnLeave();
+    };
+  }, []);
+
+  return { state, start, end, reset, getCredentials, visitorId };
+}

package/src/ui/headless/agent/useAgentCallRoom.ts

@@ -0,0 +1,113 @@
+import { useEffect, useRef, useState } from "react";
+import { useLocalMedia, useMediaRoom, useRemoteTrack, useRoomState, useVisibleProducers } from "../../media";
+
+/**
+ * What a call with the agent looks like from inside its media room.
+ *
+ * - `connecting`: joining the room, or waiting for the agent to arrive.
+ * - `listening`: the agent is there and quiet, so it is the caller's turn.
+ * - `speaking`: the agent's audio is audible right now.
+ * - `no_mic`: the browser refused the microphone.
+ */
+export type AgentCallRoomStatus = "connecting" | "listening" | "speaking" | "no_mic";
+
+/**
+ * Inside a `MediaRoomProvider`: publishes the microphone once joined, finds
+ * the agent's audio, and says when the call is over from the room's side (the
+ * agent left, or the room closed), so the caller does not sit on a dead line.
+ *
+ * Imports the media module, so only load it with the call UI.
+ */
+export function useAgentCallRoom({ selfIdentity, onEnded }: { selfIdentity: string; onEnded: () => void }) {
+  const room = useRoomState();
+  const { connectionState } = useMediaRoom();
+  const local = useLocalMedia();
+  const producers = useVisibleProducers();
+  const [micError, setMicError] = useState<string | null>(null);
+  const [agentSpeaking, setAgentSpeaking] = useState(false);
+  const published = useRef(false);
+  const agentWasHere = useRef(false);
+  const onEndedRef = useRef(onEnded);
+  onEndedRef.current = onEnded;
+
+  // The browser asks for the microphone here, once in the room. Its own echo
+  // cancellation keeps the agent from hearing itself through the speakers.
+  useEffect(() => {
+    if (room.phase !== "joined" || published.current) return;
+    published.current = true;
+    local.publishMicrophone().catch((err: unknown) => {
+      published.current = false;
+      setMicError(err instanceof Error ? err.message : String(err));
+    });
+  }, [room.phase, local]);
+
+  const agentHere = room.peers.some((p) => p.identity !== selfIdentity);
+  const agentAudioProducerIds = producers
+    .filter((p) => p.kind === "audio" && p.identity !== selfIdentity)
+    .map((p) => p.producerId);
+
+  useEffect(() => {
+    if (agentHere) agentWasHere.current = true;
+    else if (agentWasHere.current) onEndedRef.current();
+  }, [agentHere]);
+
+  useEffect(() => {
+    if (connectionState === "closed") onEndedRef.current();
+  }, [connectionState]);
+
+  const status: AgentCallRoomStatus = micError
+    ? "no_mic"
+    : room.phase !== "joined" || !agentHere
+      ? "connecting"
+      : agentSpeaking
+        ? "speaking"
+        : "listening";
+
+  return { status, micError, agentAudioProducerIds, setAgentSpeaking };
+}
+
+/** How loud (RMS, 0 to 1) the agent's audio must be to count as speaking. */
+const SPEAKING_LEVEL = 0.01;
+/** How long below that before it counts as silent again, so a pause between
+ * words does not flicker the status. */
+const SPEAKING_HOLD_MS = 400;
+
+/**
+ * Plays one of the agent's audio producers and reports whether it is audible.
+ * Returns the ref for an `<audio autoPlay>` element. Measured in the browser
+ * because the node's speaker ranking is for people, and an agent is not in it.
+ */
+export function useAgentAudio(producerId: string, onSpeaking: (speaking: boolean) => void) {
+  const { track, attach } = useRemoteTrack(producerId);
+  const mediaTrack = track?.track ?? null;
+
+  useEffect(() => {
+    if (!mediaTrack || typeof AudioContext === "undefined") return;
+    const context = new AudioContext();
+    const analyser = context.createAnalyser();
+    analyser.fftSize = 512;
+    context.createMediaStreamSource(new MediaStream([mediaTrack])).connect(analyser);
+    const samples = new Float32Array(analyser.fftSize);
+    let lastLoudAt = 0;
+    let speaking = false;
+    const timer = window.setInterval(() => {
+      analyser.getFloatTimeDomainData(samples);
+      let sum = 0;
+      for (const sample of samples) sum += sample * sample;
+      const now = performance.now();
+      if (Math.sqrt(sum / samples.length) > SPEAKING_LEVEL) lastLoudAt = now;
+      const next = now - lastLoudAt < SPEAKING_HOLD_MS;
+      if (next !== speaking) {
+        speaking = next;
+        onSpeaking(next);
+      }
+    }, 100);
+    return () => {
+      window.clearInterval(timer);
+      onSpeaking(false);
+      void context.close();
+    };
+  }, [mediaTrack, onSpeaking]);
+
+  return attach;
+}

package/src/ui/headless/agent/useAiAgent.ts

@@ -7,35 +7,20 @@ import {
 } from "../../../data/queries/useWebsiteAgent";
 import { isPathExcluded } from "./pathExclusion";
 import { useCurrentPath } from "./useCurrentPath";
+import { getAgentVisitorId } from "./visitorId";
 
 export interface AiAgentMessage {
   role: "user" | "assistant";
   text: string;
 }
 
-const VISITOR_KEY = "forge_agent_visitor_id";
-
-function getVisitorId(): string {
-  if (typeof window === "undefined") return "ssr";
-  try {
-    let id = window.localStorage.getItem(VISITOR_KEY);
-    if (!id) {
-      id = (window.crypto?.randomUUID?.() ?? `v_${Date.now()}_${Math.random().toString(36).slice(2)}`);
-      window.localStorage.setItem(VISITOR_KEY, id);
-    }
-    return id;
-  } catch {
-    return `v_${Date.now()}`;
-  }
-}
-
 /**
  * Headless controller for the website AI agent widget. Owns visitor identity,
  * the conversation (created lazily on first send), the message list, and the
  * streaming turn. A site can build any UI on top of this.
  */
 export function useAiAgent() {
-  const { apiUrl, profileId, token } = useForge();
+  const { apiUrl, profileId, websiteId, token } = useForge();
   const config = useWebsiteAgentConfig();
   const path = useCurrentPath();
 
@@ -43,15 +28,15 @@ export function useAiAgent() {
   const [sending, setSending] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const conversationIdRef = useRef<string | null>(null);
-  const visitorId = useMemo(getVisitorId, []);
+  const visitorId = useMemo(getAgentVisitorId, []);
 
   const ensureConversation = useCallback(async (): Promise<string | null> => {
     if (conversationIdRef.current) return conversationIdRef.current;
     if (!apiUrl || !profileId) return null;
-    const res = await createAgentConversation({ apiUrl, token, profileId, visitorId });
+    const res = await createAgentConversation({ apiUrl, token, profileId, websiteId, visitorId });
     conversationIdRef.current = res.id;
     return res.id;
-  }, [apiUrl, profileId, token, visitorId]);
+  }, [apiUrl, profileId, websiteId, token, visitorId]);
 
   const send = useCallback(
     async (text: string) => {
@@ -107,6 +92,9 @@ export function useAiAgent() {
     config: config.data,
     isEnabled: !!config.data?.enabled && !excluded,
     loading: config.isLoading,
+    /** "Call us": the agent takes calls from the browser. See `useAgentCall`. */
+    canCall: !!config.data?.enabled && !!config.data?.voiceEnabled && !excluded,
+    visitorId,
     messages,
     sending,
     error,

package/src/ui/headless/agent/visitorId.ts

@@ -0,0 +1,20 @@
+const VISITOR_KEY = "forge_agent_visitor_id";
+
+/**
+ * The widget's anonymous visitor id, kept in localStorage so a returning
+ * visitor keeps their conversations. Chat and calls share it, which is also
+ * what the per-visitor call limit counts.
+ */
+export function getAgentVisitorId(): string {
+  if (typeof window === "undefined") return "ssr";
+  try {
+    let id = window.localStorage.getItem(VISITOR_KEY);
+    if (!id) {
+      id = window.crypto?.randomUUID?.() ?? `v_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+      window.localStorage.setItem(VISITOR_KEY, id);
+    }
+    return id;
+  } catch {
+    return `v_${Date.now()}`;
+  }
+}