@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/src/useConversation.ts

@@ -0,0 +1,627 @@
+import { useEffect, useReducer, useRef, useState } from "react";
+
+import { createScreen, type Screen } from "./browser";
+import type { Client } from "./client";
+import { note } from "./dev";
+import { sayOf, toolResultOf, type Frame, type ToolResult } from "./frames";
+import type {
+  Action,
+  BrowserControl,
+  BrowserFrame,
+  BrowserInput,
+  BrowserState,
+  Handover,
+  Holder,
+  Message,
+  Request,
+  Step,
+  ToolCall,
+} from "./types";
+import { useLive } from "./useLive";
+
+/**
+ * Where a conversation stands: its stored messages, the turn (whether a reply is on its way, what
+ * of it has come so far, and what it waits on), and what its history read has said.
+ */
+export interface ConversationState {
+  messages: Message[];
+  pending: boolean;
+  draft: string;
+  /** The step the turn stopped on (a surface to answer, or an action to allow), until the person acts. */
+  awaiting: string | null;
+  /** Whether the history has landed once; until then an empty list means nothing. */
+  loaded: boolean;
+  /** What the last read threw; null once one lands. */
+  error: unknown;
+  /** The conversation's browser while it is open. */
+  browser: BrowserState | null;
+  /** Who answers it now; null until the history lands. */
+  holder: Holder | null;
+  /** Every change of who answers it, in order: read with the history, then heard live. */
+  handovers: Handover[];
+  /**
+   * The host's tools the page runs now, by the call's id: the turn is under way while one runs
+   * (its `done` said only that it stopped to wait for them), until its step is done or failed.
+   */
+  tools: string[];
+  /**
+   * The yes or no the person just gave, until the step's own frames say what came of it: what
+   * the API refuses as the business's (`business`) is drawn as waiting for the business again.
+   */
+  answered: { id: string; request: Request } | null;
+}
+
+export const EMPTY: ConversationState = {
+  messages: [],
+  pending: false,
+  draft: "",
+  awaiting: null,
+  loaded: false,
+  error: null,
+  browser: null,
+  holder: null,
+  handovers: [],
+  tools: [],
+  answered: null,
+};
+
+/**
+ * What moves the state: the socket opening afresh, a read landing (with who answers it, and its
+ * changes, when the API tells them) or failing, the person acting on a surface, or a frame.
+ */
+export type ConversationAction =
+  | { type: "reset" }
+  | {
+      type: "history";
+      messages: Message[];
+      pending: boolean;
+      holder?: Holder;
+      handovers?: Handover[];
+    }
+  | { type: "failed"; error: unknown }
+  | { type: "acted"; action: Action }
+  | Frame;
+
+/**
+ * Errors told only to the socket that sent something (the agent still replying, a frame it did
+ * not understand, a turn waiting on a surface, files it can't carry, what only the channel or the
+ * business answers, a tool's answer no call waits on: nothing was stored): the turn, if there is
+ * one, goes on. Any other error ends it.
+ */
+const ASIDE: ReadonlySet<string> = new Set([
+  "busy",
+  "unknown",
+  "pending",
+  "files",
+  "channel",
+  "business",
+  "tool",
+]);
+
+/**
+ * Told when the page answered a host's tool no call waits on any more (answered already, from
+ * another tab or before a reload; or late): nothing for the person to hear.
+ */
+const STALE = "tool";
+
+/** Whether a step's state is its last: done, or failed. */
+const settled = (step: Step | undefined): boolean =>
+  step?.state === "done" || step?.state === "failed";
+
+/**
+ * The turn, one step at a time, from what the socket says alone, so a page opened mid-turn (a
+ * reload, another tab) reads it as the one that sent. The person's message opens it (their words,
+ * or their answer on a surface); on a channel, where the reply comes on its own time, its first
+ * words or step do. `done`, `stopped` or an error closes it, and either way the
+ * draft goes: the reply now lives in the messages, and after an error there is none (on a
+ * refusal the partial text was never one). A reply that calls actions is stored before they run,
+ * so what `step`, `ui` and `request` frames say lands on its steps: the message is the one place
+ * a step is drawn from, live or read back. The socket opening afresh empties the draft too, since
+ * the turn so far is then told again. Who answers the conversation is the read's, then each
+ * `holder` frame's: its change kept once beside those read, in order, and who answers taken from
+ * it only when it is the newest; a `decision` lands on its message (null clears it). A host's
+ * tool the page runs (`tool`) is its step working, and a turn under way until its step is done
+ * or failed, whatever `done` said meanwhile. A yes the business gives (`decides: "business"`)
+ * waits on its step without stopping the turn or holding the person; one the person gave and the
+ * API refused as the business's (`business`) waits for the business again.
+ */
+export function reduce(state: ConversationState, action: ConversationAction): ConversationState {
+  switch (action.type) {
+    case "reset":
+      // The socket that opens is told the browser again, if there is one, and the tools awaited.
+      return {
+        ...state,
+        pending: false,
+        draft: "",
+        awaiting: null,
+        browser: null,
+        tools: [],
+        answered: null,
+      };
+    case "history": {
+      // A change heard while the read was on its way is newer than what it says.
+      const read = action.handovers ?? [];
+      const handovers = withHandovers(read, state.handovers);
+      const heard = handovers.length > read.length ? handovers.at(-1)?.holder : undefined;
+      return {
+        ...state,
+        messages: withMessages(action.messages, state.messages),
+        awaiting: action.pending ? awaited(action.messages) : null,
+        loaded: true,
+        error: null,
+        holder: heard ?? action.holder ?? state.holder,
+        handovers,
+      };
+    }
+    case "failed":
+      return { ...state, error: action.error };
+    case "working":
+      // The agent began its reply: told first to a socket that opens while it thinks.
+      return { ...state, pending: true };
+    case "text":
+      return { ...state, pending: true, draft: state.draft + action.delta };
+    case "message": {
+      const { message } = action;
+      const messages = withStored(state.messages, message);
+      // On a channel the turn is no one's message's: the person's words wait for the agent's
+      // reply on its own time, and the business's own go out beside the turn, never in it.
+      if (message.author === "contact" || message.author === "operator") {
+        return { ...state, messages };
+      }
+      if (message.role === "assistant") return { ...state, messages, draft: "" };
+      return {
+        ...state,
+        messages: message.action ? answered(messages, message.action) : messages,
+        pending: true,
+        draft: "",
+      };
+    }
+    case "ui":
+      return {
+        ...state,
+        messages: withStep(state.messages, action.id, (step) => ({
+          ...step,
+          surface: action.surface,
+          awaits: action.awaits,
+        })),
+        awaiting: action.awaits ? action.id : state.awaiting,
+      };
+    case "step": {
+      // A step that waits holds the turn until the person answers, as the history reads it; one
+      // that runs says a turn is under way (on a channel, nobody's message told so before).
+      const waits = action.state === "waiting";
+      const ended = action.state === "done" || action.state === "failed";
+      return {
+        ...state,
+        pending: state.pending || action.state === "running",
+        messages: withStep(state.messages, action.id, (step) => ({
+          ...step,
+          state: action.state,
+          output: action.output ?? step.output,
+          awaits: waits || step.awaits,
+        })),
+        // One answered elsewhere (another screen, the owner's own Chrome) ends here too.
+        awaiting: waits ? action.id : ended && state.awaiting === action.id ? null : state.awaiting,
+        tools: ended ? state.tools.filter((id) => id !== action.id) : state.tools,
+        answered: state.answered?.id === action.id ? null : state.answered,
+      };
+    }
+    case "tool":
+      // Told again once its answer is in (a socket opening as it went): nothing runs anew.
+      if (settled(stepOf(state.messages, action.id))) return state;
+      // The page runs it now: its step works like any step, until the step's own frames move it,
+      // and it is never the person's to answer.
+      return {
+        ...state,
+        pending: true,
+        awaiting: state.awaiting === action.id ? null : state.awaiting,
+        messages: withStep(state.messages, action.id, (step) => ({
+          ...step,
+          state: "running",
+          awaits: false,
+        })),
+        tools: state.tools.includes(action.id) ? state.tools : [...state.tools, action.id],
+      };
+    case "request": {
+      const { id, action: name, input, decides = "person" } = action;
+      // The business's yes: the turn went on, and nothing waits on the person.
+      const theirs = decides === "person";
+      return {
+        ...state,
+        awaiting: theirs ? id : state.awaiting,
+        messages: withStep(state.messages, id, (step) => ({
+          ...step,
+          state: "waiting",
+          awaits: theirs,
+          request: { action: name, input, decides },
+        })),
+      };
+    }
+    case "acted": {
+      const { surface } = action.action;
+      const request = stepOf(state.messages, surface)?.request ?? null;
+      return {
+        ...state,
+        awaiting: surface === state.awaiting ? null : state.awaiting,
+        // Leave given or refused: the card goes at once; the step's own frames say what came of it.
+        messages: withStep(state.messages, surface, (step) => ({ ...step, request: null })),
+        answered: request === null ? state.answered : { id: surface, request },
+      };
+    }
+    case "handoff":
+      // Nothing to keep: the reply's `escalate` step says it, live (its `done` follows this
+      // frame) and read back alike; who answers now comes in its `holder` frame.
+      return state;
+    case "holder": {
+      const handovers = withHandovers(state.handovers, [action.handover]);
+      // One older than a change known says nothing of who answers now.
+      const newest = handovers.at(-1) === action.handover;
+      return { ...state, holder: newest ? action.handled_by : state.holder, handovers };
+    }
+    case "decision":
+      return {
+        ...state,
+        messages: withMessage(state.messages, action.message_id, (message) => ({
+          ...message,
+          decision: action.decision,
+        })),
+      };
+    case "done":
+      // The turn ended, or stopped to wait: on the host's tools the page still runs, it goes on.
+      return { ...state, pending: state.tools.length > 0, draft: "" };
+    case "stopped":
+      return { ...state, pending: false, draft: "", tools: [] };
+    case "error":
+      if (action.code === "business" && state.answered !== null) {
+        // The person's yes or no on what the business decides: it waits for the business again.
+        const { id, request } = state.answered;
+        return {
+          ...state,
+          answered: null,
+          messages: withStep(state.messages, id, (step) => ({
+            ...step,
+            awaits: false,
+            request: { ...request, decides: "business" },
+          })),
+        };
+      }
+      return ASIDE.has(action.code)
+        ? state
+        : { ...state, pending: false, draft: "", awaiting: null, tools: [], answered: null };
+    case "browser":
+      if (!action.open) return { ...state, browser: null };
+      return {
+        ...state,
+        browser: {
+          url: action.url,
+          title: action.title,
+          where: action.where,
+          control: action.control,
+          reason: action.reason,
+          wait: action.wait,
+          width: action.width,
+          height: action.height,
+        },
+      };
+    case "browser.frame":
+      // Pictures repaint the screen, never the conversation (`Screen`).
+      return state;
+  }
+}
+
+/**
+ * `known` with whatever of `more` it lacks, at the end, by id: a message is kept once however
+ * many times it is heard (stored live, then read in the history, or told again on a reconnect).
+ */
+function withMessages(known: Message[], more: Message[]): Message[] {
+  const ids = new Set(known.map((message) => message.id));
+  const missing = more.filter((message) => !ids.has(message.id));
+  return missing.length === 0 ? known : [...known, ...missing];
+}
+
+/** What going out on a channel changes of a message once it is stored, as it goes. */
+const OUTGOING = ["delivery", "delivery_error", "pieces", "sent_parts", "voice"] as const;
+
+/**
+ * `known` with a message stored: one it lacks joins at the end; one it holds takes what going out
+ * on its channel changed since (where it got to, its parts, its voice note) and keeps the rest as
+ * this page has it (its steps, moved by their own frames); untouched when nothing changed.
+ */
+function withStored(known: Message[], stored: Message): Message[] {
+  const held = known.find((message) => message.id === stored.id);
+  if (held === undefined) return [...known, stored];
+  if (OUTGOING.every((field) => isEqual(held[field], stored[field]))) return known;
+  const outgoing = Object.fromEntries(OUTGOING.map((field) => [field, stored[field]]));
+  return known.map((message) => (message === held ? { ...held, ...outgoing } : message));
+}
+
+/** The same value, told again: equal by what it holds. */
+const isEqual = (one: unknown, other: unknown): boolean =>
+  JSON.stringify(one ?? null) === JSON.stringify(other ?? null);
+
+/** A change of who answers, as one however it was told: its moment, and to whom. */
+const handoverKey = ({ at, holder }: Handover): string => `${Date.parse(at)} ${holder}`;
+
+/**
+ * `known` with whatever of `more` it lacks, in the order they were made: a change is kept once
+ * however often, and by whatever, it is told (the read, a frame, the host's own request).
+ */
+function withHandovers(known: Handover[], more: Handover[]): Handover[] {
+  const keys = new Set(known.map(handoverKey));
+  const missing = more.filter((handover) => !keys.has(handoverKey(handover)));
+  if (missing.length === 0) return known;
+  return [...known, ...missing].sort((one, other) => Date.parse(one.at) - Date.parse(other.at));
+}
+
+/** The messages with message `id` changed; untouched when none is it. */
+function withMessage(
+  messages: Message[],
+  id: string,
+  change: (message: Message) => Message,
+): Message[] {
+  const at = messages.findIndex((message) => message.id === id);
+  const message = messages[at];
+  return message ? messages.with(at, change(message)) : messages;
+}
+
+/** Step `id`, wherever it is; none when no message holds it. */
+function stepOf(messages: Message[], id: string): Step | undefined {
+  return messages.flatMap((message) => message.steps).findLast((step) => step.id === id);
+}
+
+/** The messages with step `id` changed, wherever it is; untouched when no message holds it. */
+function withStep(messages: Message[], id: string, change: (step: Step) => Step): Message[] {
+  const at = messages.findLastIndex((message) => message.steps.some((step) => step.id === id));
+  const message = messages[at];
+  if (!message) return messages;
+  const steps = message.steps.map((step) => (step.id === id ? change(step) : step));
+  return messages.with(at, { ...message, steps });
+}
+
+/** The surface a stopped turn waits on, as the history tells it. */
+function awaited(messages: Message[]): string | null {
+  return messages.flatMap((message) => message.steps).find((step) => step.awaits)?.id ?? null;
+}
+
+/**
+ * The person's answer, landed on the step that waited for it: a question is done with their
+ * words as its output (what the history reads back); an action they allowed or declined was
+ * already told its own state.
+ */
+function answered(messages: Message[], action: Action): Message[] {
+  return withStep(messages, action.surface, (step) =>
+    step.state === "waiting"
+      ? { ...step, state: "done", output: action.label, awaits: false, request: null }
+      : { ...step, awaits: false, request: null },
+  );
+}
+
+/** How often the history is read again while something goes out on a channel. */
+const DELIVERY_EVERY = 3_000;
+/** How long a message sent is watched for its receipt before the next read brings it. */
+const RECEIPT_WITHIN = 60_000;
+
+/**
+ * Whether a message is still on its way to the person on a channel: waiting to go, or gone a
+ * moment ago and not yet received. What it gets to moves without a frame, so it is read again.
+ */
+export function onItsWay(message: Message, now: number): boolean {
+  if (message.delivery === "queued") return true;
+  return message.delivery === "sent" && now - Date.parse(message.created_at) < RECEIPT_WITHIN;
+}
+
+/**
+ * Runs one of the host's own tools in the page, for the agent: what it resolves to goes back as
+ * the tool's output, what it rejects with as why it failed (an error's message).
+ */
+export type ToolHandler = (call: ToolCall) => Promise<unknown>;
+
+/** What the page answers a tool of the host's when it runs none (no `onTool`), for the agent. */
+export const NO_TOOL = "This page can't do that";
+
+const refuse = (): Promise<never> => Promise.reject(new Error(NO_TOOL));
+
+/** A conversation, live: its messages, where its turn stands, and the ways to speak. */
+export interface LiveConversation {
+  messages: Message[];
+  draft: string;
+  pending: boolean;
+  /**
+   * The step the turn waits on: a surface to answer, or an action the person allows (its
+   * `request`, `decides: "person"`; `act` on its id with `approve` or `decline`). Nothing else
+   * goes until the person acts. A yes the business gives holds nothing.
+   */
+  awaiting: string | null;
+  open: boolean;
+  /** Until the history has landed once. */
+  loading: boolean;
+  /** What the last history read threw, if it failed. */
+  error: unknown;
+  /**
+   * Says something: words, the ids of files uploaded to the conversation for it, or both; false
+   * when it cannot go now: nothing to say, a turn running or waiting, the socket closed.
+   */
+  say: (text: string, files?: readonly string[]) => boolean;
+  /** What the person did on a surface; false when the socket is closed. */
+  act: (action: Action) => boolean;
+  /** Stops the reply on its way; false when the socket is closed. */
+  stop: () => boolean;
+  /** The conversation's browser while it is open: where it is, who holds it. */
+  browser: BrowserState | null;
+  /** Hears each picture of the browser's screen, the latest at once; returns how to stop. */
+  watchScreen: (listener: (frame: BrowserFrame) => void) => () => void;
+  /** Takes the browser from the agent, or gives it back; false when the socket is closed. */
+  control: (to: BrowserControl) => boolean;
+  /** Closes the browser now (it stops being billed); false when the socket is closed. */
+  closeBrowser: () => boolean;
+  /** What the person does on the browser's screen while they hold it. */
+  input: (event: BrowserInput) => boolean;
+  /** Who answers it now: its agent, a person of the business, or nobody; null until the history lands. */
+  holder: Holder | null;
+  /** Every change of who answers it, in order, kept live. */
+  handovers: Handover[];
+}
+
+/**
+ * Conversation `conversationId` as the person sees it: the history, kept live by the socket.
+ * Each time the socket opens the history is read, with the socket already listening, so nothing
+ * stored can fall between the two; what came live meanwhile is kept. `onError` hears each
+ * error's code (the socket's, or `load` for a history that could not be read): the host words
+ * it, this hook shows no text; but `tool`, the page's answer to a call no longer waiting (one it
+ * answered already, told again), which is let pass (noted in development). `onHolder` hears each
+ * change of who answers it, live, for the host's own views of it; `handover` is the last change
+ * the host knows of (one it made itself, as its request answered), taken at once, so it shows
+ * whether or not the socket tells it.
+ * `onStep` hears each step the agent starts, live, by its action's name, for the host's own
+ * views of it (the builder's column, opened as the agent asks it).
+ * `onTool` runs the host's own tools the agent calls in the page (a `tool` frame), and its answer
+ * goes up (`tool_result`); each call runs once, and one told again while it waits (the socket
+ * opened anew) is answered again with what it gave. Without `onTool`, each is refused with
+ * `NO_TOOL`, so the turn never waits on a page that can't run it. One conversation per mount: key
+ * the component on the id.
+ */
+export function useConversation(
+  client: Client,
+  conversationId: string,
+  {
+    onError,
+    onHolder,
+    onStep,
+    handover,
+    onTool,
+  }: {
+    onError?: ((code: string) => void) | undefined;
+    onHolder?: ((holder: Holder, handover: Handover) => void) | undefined;
+    onStep?: ((action: string) => void) | undefined;
+    handover?: Handover | null | undefined;
+    onTool?: ToolHandler | undefined;
+  } = {},
+): LiveConversation {
+  const [state, dispatch] = useReducer(reduce, EMPTY);
+  // The host's change, taken once by what it is: the same one told again changes nothing.
+  const told = handover ?? null;
+  const toldKey = told === null ? null : handoverKey(told);
+  useEffect(() => {
+    if (told !== null) dispatch({ type: "holder", handled_by: told.holder, handover: told });
+  }, [toldKey]);
+  // The browser's pictures, out of the state: each repaints its screen alone.
+  const [screen] = useState<Screen>(createScreen);
+  // Reads are numbered: one that lands after a newer one began, or after the conversation went,
+  // is dropped on the floor.
+  const reads = useRef(0);
+  useEffect(
+    () => () => {
+      reads.current += 1;
+    },
+    [client, conversationId],
+  );
+
+  const read = () => {
+    const run = ++reads.current;
+    client.conversations.get(conversationId).then(
+      ({ messages, pending, handled_by, handovers = [] }) => {
+        if (run !== reads.current) return;
+        dispatch({ type: "history", messages, pending, holder: handled_by, handovers });
+      },
+      (error: unknown) => {
+        if (run !== reads.current) return;
+        dispatch({ type: "failed", error });
+        onError?.("load");
+      },
+    );
+  };
+
+  // The host's tools the agent called, by the call's id: running (null), or what each answered.
+  const tools = useRef(new Map<string, ToolResult | null>());
+  const runTool = ({ id, name, input }: ToolCall) => {
+    const known = tools.current.get(id);
+    if (known !== undefined) {
+      if (known !== null) live.send(known);
+      return;
+    }
+    tools.current.set(id, null);
+    void Promise.resolve({ id, name, input })
+      .then(onTool ?? refuse)
+      .then(
+        (value): PromiseSettledResult<unknown> => ({ status: "fulfilled", value }),
+        (reason: unknown): PromiseSettledResult<unknown> => ({ status: "rejected", reason }),
+      )
+      .then((settled) => {
+        const answer = toolResultOf(id, settled);
+        tools.current.set(id, answer);
+        // A socket closed now hears it when it opens: the call is told again while it waits.
+        live.send(answer);
+      });
+  };
+
+  const live = useLive(client, conversationId, {
+    onFrame: (frame: Frame) => {
+      if (frame.type === "browser.frame") {
+        screen.show({ jpeg: frame.jpeg, width: frame.width, height: frame.height });
+        return;
+      }
+      if (frame.type === "error" && frame.code === STALE) {
+        // An answer of the page's that no call waits on any more: nothing for the person.
+        note("A host's tool answer was let pass:", frame.detail);
+        return;
+      }
+      if (frame.type === "browser" && !frame.open) screen.clear();
+      dispatch(frame);
+      if (frame.type === "error") onError?.(frame.code);
+      if (frame.type === "holder") onHolder?.(frame.handled_by, frame.handover);
+      if (frame.type === "step" && frame.state === "running" && frame.action !== undefined) {
+        onStep?.(frame.action);
+      }
+      if (frame.type === "tool") runTool(frame);
+    },
+    onOpen: () => {
+      dispatch({ type: "reset" });
+      read();
+    },
+  });
+
+  // On a channel, while something of the business's is on its way to the person, the history is
+  // read again every few seconds: where it got to (sent, delivered, read, failed) comes no other
+  // way. Each read is a new state, so the question is asked again after it.
+  const travelling = state.messages.some((message) => onItsWay(message, Date.now()));
+  useEffect(() => {
+    if (!travelling || !live.open) return undefined;
+    const again = setInterval(read, DELIVERY_EVERY);
+    return () => {
+      clearInterval(again);
+    };
+    // `read` does the same work from any render: what it reads is in refs and the dispatch.
+  }, [travelling, live.open]);
+
+  const say = (text: string, files: readonly string[] = []): boolean => {
+    const frame = sayOf(text, files);
+    if (frame === null || state.pending || state.awaiting !== null) return false;
+    return live.send(frame);
+  };
+
+  const act = (action: Action): boolean => {
+    if (!live.send({ type: "action", ...action })) return false;
+    dispatch({ type: "acted", action });
+    return true;
+  };
+
+  return {
+    messages: state.messages,
+    draft: state.draft,
+    pending: state.pending,
+    awaiting: state.awaiting,
+    open: live.open,
+    loading: !state.loaded,
+    error: state.error,
+    say,
+    act,
+    stop: () => live.send({ type: "stop" }),
+    browser: state.browser,
+    watchScreen: screen.watch,
+    control: (to) => live.send({ type: "browser.control", to }),
+    closeBrowser: () => live.send({ type: "browser.close" }),
+    input: (event) => live.send({ type: "browser.input", event }),
+    holder: state.holder,
+    handovers: state.handovers,
+  };
+}