@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/AgentSpace.tsx

@@ -0,0 +1,540 @@
+import { PhoneIcon, XIcon } from "@phosphor-icons/react";
+import { lazy, Suspense, useEffect, useRef, useState } from "react";
+
+import { AgentChat, type ChatMessages, type ChatPart, type ChatSteps } from "./AgentChat";
+import { agentGlyph } from "./agentIcons";
+import {
+  AgentTasks,
+  TASK_MESSAGES,
+  useTasks,
+  type TaskMessages,
+  type TaskPart,
+} from "./AgentTasks";
+import type { BrowserPart } from "./BrowserView";
+import { classes } from "./classes";
+import { ApiError, type Client } from "./client";
+import { Button } from "./kit/Button";
+import { KitProvider, type KitPart } from "./kit/context";
+import type { KitLocale } from "./kit/messages";
+import { Modes, type ModeMessages, type ModePart, type SpaceMode } from "./Modes";
+import type { SurfaceComponents, SurfacePart } from "./surface/scope";
+import { agentTint, type AgentTint } from "./tint";
+import { useAgentFace } from "./useAgentFace";
+import { useConversation, type LiveConversation, type ToolHandler } from "./useConversation";
+import type { VoiceCallMessages, VoiceCallPart } from "./VoiceCall";
+import type { OrbStyle } from "./voice/orbs";
+
+// The call, and LiveKit under it, load the first time someone calls.
+const VoiceCall = lazy(() =>
+  import("./VoiceCall").then((module) => ({ default: module.VoiceCall })),
+);
+
+/** The words the space says around the chat and the call; a host gives its own, in its language. */
+export interface SpaceMessages {
+  /** The two modes beside the composer's paperclip: the group's name, and each mode's. */
+  modes: ModeMessages;
+  /** After a call that couldn't begin: try it again. */
+  again: string;
+  /** The button that closes the space, where the host gives `onClose`. */
+  close: string;
+  /** The agent's name when its face can't be read. */
+  agent: string;
+  /** While the conversation is found, or started. */
+  opening: string;
+  /** The conversation could not be opened; and the button that tries again. */
+  failed: string;
+  retry: string;
+  /** What the chat says (`AgentChat`'s words). */
+  chat: Partial<ChatMessages>;
+  /** What a call says (`VoiceCall`'s words). */
+  voice: Partial<VoiceCallMessages>;
+  /** What the person's tasks say (`AgentTasks`'s words). */
+  tasks: TaskMessages;
+}
+
+export const SPACE_MESSAGES: SpaceMessages = {
+  modes: { label: "Mode", text: "Text", voice: "Voice" },
+  again: "Call again",
+  close: "Close",
+  agent: "Agent",
+  opening: "Opening the conversation…",
+  failed: "The conversation couldn't be opened.",
+  retry: "Try again",
+  chat: {},
+  voice: {},
+  tasks: TASK_MESSAGES,
+};
+
+/** The space's parts, by the class each carries; `classNames` adds a host's own under the same keys. */
+export type SpacePart =
+  | "sc-space"
+  | "sc-space--compact"
+  | "sc-space--full"
+  | "sc-space--voice"
+  | "sc-space__face"
+  | "sc-space__mark"
+  | `sc-space__mark--${AgentTint}`
+  | "sc-space__who"
+  | "sc-space__name"
+  | "sc-space__role"
+  | "sc-space__close"
+  | "sc-space__body"
+  | "sc-space__voice"
+  | "sc-space__foot"
+  | "sc-space__caption"
+  | "sc-space__caption--person"
+  | "sc-space__caption--agent"
+  | "sc-space__status"
+  | "sc-space__tasks"
+  | ModePart;
+
+/**
+ * How the space sits: `compact` in a small panel (a widget's, a side of the host's page); `full`
+ * as a page's main column, the conversation at a reading measure.
+ */
+export type SpaceLayout = "compact" | "full";
+
+/** How big a call's orb is drawn in each layout: a small panel keeps room for what is said. */
+const ORB_SIZES: Readonly<Record<SpaceLayout, number>> = { compact: 200, full: 280 };
+
+export interface AgentSpaceProps {
+  client: Client;
+  /** The agent the person talks to (its face is read with `client`). One per mount: key on it. */
+  agentId: string;
+  /**
+   * The person's conversation to go on with, read when the space opens. Without one, or once it
+   * is gone (not theirs, not there), a new one starts, told through `onConversation`.
+   */
+  conversationId?: string | undefined;
+  /** Hears the conversation the space started, for the host to keep and give back next time. */
+  onConversation?: ((id: string) => void) | undefined;
+  layout?: SpaceLayout | undefined;
+  /**
+   * Draws the agent's face at the top: its mark in its tint, its name and role (and the close).
+   * Off by default: the host's page says who it is, or draws its own with `useAgentFace`.
+   */
+  header?: boolean | undefined;
+  /**
+   * Whether the chat shows the agent's steps (`AgentChat`'s `steps`): by default hidden for a
+   * person or a visitor, shown for the business.
+   */
+  steps?: ChatSteps | undefined;
+  messages?: Partial<SpaceMessages> | undefined;
+  classNames?:
+    | Partial<
+        Record<
+          SpacePart | ChatPart | SurfacePart | KitPart | BrowserPart | VoiceCallPart | TaskPart,
+          string
+        >
+      >
+    | undefined;
+  /** The host's own drawing of a block type, for every surface the agent shows. */
+  components?: SurfaceComponents | undefined;
+  /** The language of the surfaces' calendars, days, times and numbers; English by default. */
+  locale?: KitLocale | undefined;
+  /** A few things the person might say first, offered while nothing has been said. */
+  suggestions?: readonly string[] | undefined;
+  /** Runs the host's own tools the agent calls in the page (`AgentChat`'s `onTool`). */
+  onTool?: ToolHandler | undefined;
+  /** An error's code, from the chat's socket or `load`; the host words it. */
+  onError?: ((code: string) => void) | undefined;
+  /** How a call's orb is drawn: `"wave"` (the default) or `"fluid-dots"`. */
+  orb?: OrbStyle | undefined;
+  /** Draws a close button (in the face, or at the top's end without it), for a space in a panel. */
+  onClose?: (() => void) | undefined;
+  /**
+   * Whether a person sees the tasks the agent runs for them (`AgentTasks`): a line over the chat
+   * while there are any, which opens them. On by default; the business's own space never has it.
+   */
+  tasks?: boolean | undefined;
+}
+
+/**
+ * An agent in a host's page, for the people it serves: the conversation, and when the agent has a
+ * voice, two modes beside the composer's paperclip, text and voice. Voice turns the space into
+ * the call (`VoiceCall`, with the orb and what is being said), in the same place and size, with
+ * the modes at its foot to go back; a call is a conversation of its own (the API makes one with
+ * each), and once the agent took it the space goes on in it, where what was said shows, told
+ * through `onConversation`. Ending the call, or choosing text, comes back to writing; a call that
+ * couldn't begin stays to say why, and offers to try again. While the agent runs tasks for the
+ * person (what they asked it to do later), a line over the chat opens them, with their runs, to
+ * pause or take away. The conversation is the one given, or
+ * one the space starts. The agent's face over it all is the host's to turn on (`header`). Styled
+ * as `AgentChat` is: the tokens, `messages`, `classNames` and `components`. One agent per mount:
+ * key it on the agent's id.
+ */
+export function AgentSpace({
+  client,
+  agentId,
+  conversationId,
+  onConversation,
+  layout = "compact",
+  header = false,
+  steps,
+  messages,
+  classNames,
+  components,
+  locale,
+  suggestions,
+  onTool,
+  onError,
+  orb,
+  onClose,
+  tasks: showsTasks = true,
+}: AgentSpaceProps) {
+  const words = { ...SPACE_MESSAGES, ...messages };
+  const theirs = useTasks(client, agentId, showsTasks && client.who === "person");
+  const [listing, setListing] = useState(false);
+  const { face, loading } = useAgentFace(client, agentId);
+  const opened = useOpened(client, agentId, conversationId, onConversation);
+  const [mode, setMode] = useState<SpaceMode>("text");
+  // Each call made is a new attempt, which keys a new `VoiceCall`.
+  const [attempt, setAttempt] = useState(0);
+  // The conversation the call being made is (each call is one of its own, made with it), and
+  // whether the agent took it: once it did, the space goes on in it.
+  const [called, setCalled] = useState<string | null>(null);
+  const answered = useRef(false);
+  // Whether the modes drawn after a switch take the keyboard: when it was in the space (asked of
+  // the space itself, which a shadow root's focus answers too).
+  const [refocus, setRefocus] = useState(false);
+  const root = useRef<HTMLElement>(null);
+  const tint = agentTint(agentId);
+  const Glyph = agentGlyph(face?.icon);
+  const name = face?.name ?? (loading ? "" : words.agent);
+  const id = opened.id;
+  const voice = face?.voice.enabled === true;
+  const parts: SpacePart[] = [`sc-space--${layout}`];
+  if (mode === "voice") parts.push("sc-space--voice");
+
+  /** Back to writing: in the call's conversation once the agent took the call. */
+  const write = () => {
+    if (answered.current && called !== null) opened.go(called);
+    setMode("text");
+  };
+  const choose = (next: SpaceMode) => {
+    setRefocus(root.current?.matches(":focus-within") ?? false);
+    if (next === "text") {
+      write();
+      return;
+    }
+    answered.current = false;
+    setCalled(null);
+    setAttempt((count) => count + 1);
+    setMode("voice");
+  };
+  const modes = (current: SpaceMode) => (
+    <Modes
+      mode={current}
+      onChange={choose}
+      words={words.modes}
+      classNames={classNames}
+      focus={refocus}
+    />
+  );
+
+  const body = () => {
+    if (opened.failed) {
+      return (
+        <div className={classes(classNames, "sc-space__status")}>
+          <p>{words.failed}</p>
+          <Button size="sm" onClick={opened.retry}>
+            {words.retry}
+          </Button>
+        </div>
+      );
+    }
+    if (id === null || loading) {
+      return (
+        <p role="status" className={classes(classNames, "sc-space__status")}>
+          {words.opening}
+        </p>
+      );
+    }
+    if (listing && theirs.tasks !== null) {
+      return (
+        <AgentTasks
+          client={client}
+          agentId={agentId}
+          tasks={theirs.tasks}
+          onChange={theirs.refresh}
+          onBack={() => {
+            setListing(false);
+          }}
+          words={words.tasks}
+          classNames={classNames}
+        />
+      );
+    }
+    if (mode === "voice" && voice) {
+      return (
+        <div part="voice" className={classes(classNames, "sc-space__voice")}>
+          <Suspense fallback={null}>
+            <VoiceCall
+              key={attempt}
+              connect={async () => {
+                const join = await client.conversations.call(agentId);
+                setCalled(join.conversation_id);
+                return join;
+              }}
+              onAnswer={() => {
+                answered.current = true;
+              }}
+              // Over, the call gives the space back to writing; one that couldn't begin stays to
+              // say why, with the way to try again and the modes to go back.
+              onEnd={(_, problem) => {
+                if (problem !== null) return;
+                setRefocus(root.current?.matches(":focus-within") ?? false);
+                write();
+              }}
+              name={name}
+              tint={tint}
+              orb={orb}
+              orbSize={ORB_SIZES[layout]}
+              messages={words.voice}
+              classNames={classNames}
+              captions={
+                called !== null && (
+                  <Captions
+                    client={client}
+                    conversationId={called}
+                    onTool={onTool}
+                    classNames={classNames}
+                  />
+                )
+              }
+              after={
+                <Button
+                  tone="primary"
+                  icon={PhoneIcon}
+                  onClick={() => {
+                    choose("voice");
+                  }}
+                >
+                  {words.again}
+                </Button>
+              }
+            />
+          </Suspense>
+          <div className={classes(classNames, "sc-space__foot")}>{modes("voice")}</div>
+        </div>
+      );
+    }
+    const count = theirs.tasks?.length ?? 0;
+    return (
+      <>
+        {count > 0 && (
+          <button
+            type="button"
+            part="tasks-open"
+            className={classes(classNames, "sc-space__tasks")}
+            onClick={() => {
+              setListing(true);
+              void theirs.refresh();
+            }}
+          >
+            {words.tasks.open(count)}
+          </button>
+        )}
+        <AgentChat
+          client={client}
+          conversationId={id}
+          name={name}
+          messages={words.chat}
+          classNames={classNames}
+          components={components}
+          locale={locale}
+          suggestions={suggestions}
+          steps={steps}
+          actions={voice ? modes("text") : undefined}
+          onTool={onTool}
+          onError={onError}
+        />
+      </>
+    );
+  };
+
+  const close = onClose && (
+    <Button
+      tone="ghost"
+      size="sm"
+      icon={XIcon}
+      aria-label={words.close}
+      title={words.close}
+      onClick={onClose}
+      part="close"
+      className={classes(classNames, "sc-space__close")}
+    />
+  );
+
+  return (
+    <KitProvider classNames={classNames} messages={words.chat.kit} locale={locale}>
+      <section
+        ref={root}
+        aria-label={name || undefined}
+        part="space"
+        className={`sc ${classes(classNames, "sc-space", ...parts)}`}
+      >
+        {header ? (
+          <header part="header" className={classes(classNames, "sc-space__face")}>
+            <span
+              aria-hidden
+              className={classes(classNames, "sc-space__mark", `sc-space__mark--${tint}`)}
+            >
+              <Glyph weight="duotone" />
+            </span>
+            <div className={classes(classNames, "sc-space__who")}>
+              <h2 className={classes(classNames, "sc-space__name")}>{name}</h2>
+              {face?.role && <p className={classes(classNames, "sc-space__role")}>{face.role}</p>}
+            </div>
+            {close}
+          </header>
+        ) : (
+          close
+        )}
+        <div className={classes(classNames, "sc-space__body")}>{body()}</div>
+      </section>
+    </KitProvider>
+  );
+}
+
+/**
+ * What is being said on the call, under the orb: the person's last words, and the agent's answer
+ * as it comes, read live from the call's own conversation (where the platform keeps them). The
+ * host's tools the agent calls meanwhile run here too, as in the chat.
+ */
+function Captions({
+  client,
+  conversationId,
+  onTool,
+  classNames,
+}: {
+  client: Client;
+  conversationId: string;
+  onTool: ToolHandler | undefined;
+  classNames: Partial<Record<SpacePart, string>> | undefined;
+}) {
+  const live = useConversation(client, conversationId, { onTool });
+  const { person, agent } = captionsOf(live);
+  return (
+    <>
+      {person !== "" && (
+        <p className={classes(classNames, "sc-space__caption", "sc-space__caption--person")}>
+          {person}
+        </p>
+      )}
+      {agent !== "" && (
+        <p className={classes(classNames, "sc-space__caption", "sc-space__caption--agent")}>
+          {agent}
+        </p>
+      )}
+    </>
+  );
+}
+
+/**
+ * The last exchange of a call, as its captions say it: what the person last said, and the agent's
+ * words after it (as they stream, else the last it said; its greeting before anything was said).
+ */
+export function captionsOf({
+  messages,
+  pending,
+  draft,
+}: Pick<LiveConversation, "messages" | "pending" | "draft">): {
+  person: string;
+  agent: string;
+} {
+  const lastSaid = messages.findLastIndex((message) => message.role === "user");
+  const replied = messages
+    .slice(lastSaid + 1)
+    .findLast(
+      (message) =>
+        message.role === "assistant" && message.author !== "operator" && message.text !== "",
+    );
+  return {
+    person: messages[lastSaid]?.text ?? "",
+    agent: pending && draft !== "" ? draft : (replied?.text ?? ""),
+  };
+}
+
+/** Whether a conversation asked for is gone for this person: not there, or not theirs. */
+const isGone = (error: unknown): boolean =>
+  error instanceof ApiError && (error.status === 404 || error.status === 403);
+
+/**
+ * The conversation the space shows: the one given while it is still the person's, else a new one
+ * with the agent, told to `onConversation`. Asked once per attempt (a second effect of the same
+ * attempt, as React's strict mode runs, waits on the first rather than starting another); after
+ * that, the conversation it opened is the one it goes on with, until it goes on in another (`go`:
+ * a call's), told the same way.
+ */
+function useOpened(
+  client: Client,
+  agentId: string,
+  given: string | undefined,
+  onConversation: ((id: string) => void) | undefined,
+): { id: string | null; failed: boolean; retry: () => void; go: (id: string) => void } {
+  const kept = useRef(given);
+  const asking = useRef<{ client: Client; attempt: number; id: Promise<string> } | null>(null);
+  const [id, setId] = useState<string | null>(null);
+  const [failed, setFailed] = useState(false);
+  const [attempt, setAttempt] = useState(0);
+  // The host's ear as it last gave it, told from the effect's answer and from a call's end alike.
+  const told = useRef(onConversation);
+  useEffect(() => {
+    told.current = onConversation;
+  });
+  const started = (conversation: string) => {
+    told.current?.(conversation);
+  };
+
+  useEffect(() => {
+    let current = true;
+    const start = () =>
+      client.conversations.start(agentId).then((conversation) => {
+        started(conversation.id);
+        return conversation.id;
+      });
+    const open = (): Promise<string> => {
+      const known = kept.current;
+      if (known === undefined) return start();
+      return client.conversations.get(known).then(
+        (conversation) => conversation.id,
+        (error: unknown) => (isGone(error) ? start() : Promise.reject(error)),
+      );
+    };
+    const asked = asking.current;
+    const ask =
+      asked?.client === client && asked.attempt === attempt
+        ? asked
+        : { client, attempt, id: open() };
+    asking.current = ask;
+    ask.id.then(
+      (opened) => {
+        if (!current) return;
+        kept.current = opened;
+        setId(opened);
+      },
+      () => {
+        if (current) setFailed(true);
+      },
+    );
+    return () => {
+      current = false;
+    };
+  }, [client, agentId, attempt]);
+
+  return {
+    id,
+    failed,
+    retry: () => {
+      setFailed(false);
+      setAttempt((count) => count + 1);
+    },
+    go: (conversation) => {
+      if (conversation === kept.current) return;
+      kept.current = conversation;
+      setId(conversation);
+      started(conversation);
+    },
+  };
+}

package/src/AgentTasks.tsx

@@ -0,0 +1,163 @@
+import { ArrowLeftIcon, TrashIcon } from "@phosphor-icons/react";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { Automation } from "./automation/Automation";
+import type { Task } from "./automation/types";
+import { classes } from "./classes";
+import type { Client } from "./client";
+import { Button } from "./kit/Button";
+
+/** What the person's tasks say, in the space; a host gives its own, in its language. */
+export interface TaskMessages {
+  /** Over the chat, when the agent runs any for them: how many, to open them. */
+  open: (count: number) => string;
+  /** Over the list. */
+  title: string;
+  back: string;
+  /** Taking one away. */
+  remove: string;
+  /** None left. */
+  empty: string;
+  /** A change that didn't go through. */
+  failed: string;
+}
+
+export const TASK_MESSAGES: TaskMessages = {
+  open: (count) => (count === 1 ? "1 task set up for you" : `${count} tasks set up for you`),
+  title: "Your tasks",
+  back: "Back to the conversation",
+  remove: "Remove",
+  empty: "Nothing set up. Ask the agent to remind you of something, or to check back later.",
+  failed: "That didn't go through. Try again.",
+};
+
+export type TaskPart =
+  | "sc-tasks"
+  | "sc-tasks__head"
+  | "sc-tasks__title"
+  | "sc-tasks__list"
+  | "sc-tasks__empty"
+  | "sc-tasks__problem";
+
+/** How often the person's tasks are read again while the space is open. */
+export const TASKS_POLL_MS = 20_000;
+
+/**
+ * The tasks the agent runs for the person the client speaks for, read when the space opens,
+ * again every `TASKS_POLL_MS` and on `refresh`. Null until read, and whenever it can't be (an API
+ * without tasks, the business's own client): the space then shows none.
+ */
+export function useTasks(
+  client: Client,
+  agentId: string,
+  enabled: boolean,
+): { tasks: Task[] | null; refresh: () => Promise<void> } {
+  const [tasks, setTasks] = useState<Task[] | null>(null);
+  const live = useRef(true);
+  const refresh = useCallback(async () => {
+    try {
+      const read = await client.tasks.list(agentId);
+      if (live.current) setTasks(read);
+    } catch {
+      if (live.current) setTasks(null);
+    }
+  }, [client, agentId]);
+  useEffect(() => {
+    live.current = true;
+    if (!enabled) return;
+    void refresh();
+    const timer = setInterval(() => void refresh(), TASKS_POLL_MS);
+    return () => {
+      live.current = false;
+      clearInterval(timer);
+    };
+  }, [enabled, refresh]);
+  return { tasks: enabled ? tasks : null, refresh };
+}
+
+export interface AgentTasksProps {
+  client: Client;
+  agentId: string;
+  tasks: readonly Task[];
+  /** Read them again, after a change. */
+  onChange: () => Promise<void>;
+  onBack: () => void;
+  words: TaskMessages;
+  classNames?: Partial<Record<TaskPart, string>> | undefined;
+}
+
+/**
+ * The person's tasks, as they asked the agent for them: each as an automation reads (when, its
+ * words, its last runs and how each went), with their switch to pause it and the way to take it
+ * away; the way back to the conversation over them.
+ */
+export function AgentTasks({
+  client,
+  agentId,
+  tasks,
+  onChange,
+  onBack,
+  words,
+  classNames,
+}: AgentTasksProps) {
+  const [busy, setBusy] = useState<string | null>(null);
+  const [failed, setFailed] = useState(false);
+  const change = async (task: Task, doing: () => Promise<unknown>) => {
+    setBusy(task.id);
+    setFailed(false);
+    try {
+      await doing();
+      await onChange();
+    } catch {
+      setFailed(true);
+    } finally {
+      setBusy(null);
+    }
+  };
+  return (
+    <section aria-label={words.title} part="tasks" className={classes(classNames, "sc-tasks")}>
+      <header className={classes(classNames, "sc-tasks__head")}>
+        <Button
+          tone="ghost"
+          size="sm"
+          icon={ArrowLeftIcon}
+          aria-label={words.back}
+          title={words.back}
+          onClick={onBack}
+        />
+        <h3 className={classes(classNames, "sc-tasks__title")}>{words.title}</h3>
+      </header>
+      {failed && (
+        <p role="alert" className={classes(classNames, "sc-tasks__problem")}>
+          {words.failed}
+        </p>
+      )}
+      {tasks.length === 0 ? (
+        <p className={classes(classNames, "sc-tasks__empty")}>{words.empty}</p>
+      ) : (
+        <div className={classes(classNames, "sc-tasks__list")}>
+          {tasks.map((task) => (
+            <Automation
+              key={task.id}
+              automation={task}
+              runs={task.runs}
+              switching={busy === task.id}
+              onSwitch={(on) => void change(task, () => client.tasks.switch(agentId, task.id, on))}
+              actions={
+                <Button
+                  tone="ghost"
+                  size="sm"
+                  icon={TrashIcon}
+                  aria-label={words.remove}
+                  title={words.remove}
+                  disabled={busy === task.id}
+                  onClick={() => void change(task, () => client.tasks.remove(agentId, task.id))}
+                />
+              }
+            />
+          ))}
+        </div>
+      )}
+    </section>
+  );
+}