@signalcore/ui 1.0.0-beta.1 → 1.0.0-beta.3

package/src/Threads.tsx

@@ -0,0 +1,218 @@
+import { ArrowLeftIcon, PlusIcon } from "@phosphor-icons/react";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { AgentChat, type AgentChatProps } from "./AgentChat";
+import { classes } from "./classes";
+import type { Client } from "./client";
+import { Button } from "./kit/Button";
+import type { Conversation as Thread } from "./types";
+
+/** What the person's threads say; a host gives its own, in its language. */
+export interface ThreadMessages {
+  /** Over the chat, to open the list; and the list's title. */
+  open: string;
+  title: string;
+  back: string;
+  /** Starts another conversation with the agent. */
+  new: string;
+  /** A thread nothing names yet. */
+  untitled: string;
+  /** Beside a thread: how many of the agent's messages are unread; that it waits on them. */
+  unread: (count: number) => string;
+  waiting: string;
+  empty: string;
+}
+
+export const THREAD_MESSAGES: ThreadMessages = {
+  open: "Conversations",
+  title: "Your conversations",
+  back: "Back to the conversation",
+  new: "New conversation",
+  untitled: "New conversation",
+  unread: (count) => (count === 1 ? "1 unread message" : `${count} unread messages`),
+  waiting: "Waiting for you",
+  empty: "Nothing here yet.",
+};
+
+export type ThreadPart =
+  | "sc-threads"
+  | "sc-threads__head"
+  | "sc-threads__title"
+  | "sc-threads__list"
+  | "sc-threads__item"
+  | "sc-threads__item--current"
+  | "sc-threads__name"
+  | "sc-threads__badge"
+  | "sc-threads__dot"
+  | "sc-threads__empty";
+
+/** How often the person's threads are read again, for what is unread. */
+export const THREADS_POLL_MS = 20_000;
+
+/** The person's threads with an agent, and what of them waits on the person. */
+export interface Unread {
+  /** Newest first; null until read, and whenever they can't be. */
+  threads: Thread[] | null;
+  /** Every unread message of the agent's, across the threads. */
+  unread: number;
+  /** Whether a thread waits on the person (a question, their yes). */
+  waiting: boolean;
+  refresh: () => Promise<void>;
+}
+
+/**
+ * The threads the person the client speaks for has with the agent, read now, again every
+ * `THREADS_POLL_MS`, when the page comes back into sight, and on `refresh`: what draws a dot on
+ * a launcher, a count beside a tab. `enabled` off reads nothing.
+ */
+export function useUnread(client: Client, agentId: string, enabled = true): Unread {
+  const [threads, setThreads] = useState<Thread[] | null>(null);
+  const live = useRef(true);
+  const refresh = useCallback(async () => {
+    try {
+      const read = await client.conversations.list(agentId);
+      if (live.current) setThreads(read);
+    } catch {
+      if (live.current) setThreads(null);
+    }
+  }, [client, agentId]);
+  useEffect(() => {
+    live.current = true;
+    if (!enabled) return undefined;
+    void refresh();
+    const timer = setInterval(() => void refresh(), THREADS_POLL_MS);
+    const shown = () => {
+      if (document.visibilityState === "visible") void refresh();
+    };
+    document.addEventListener("visibilitychange", shown);
+    return () => {
+      live.current = false;
+      clearInterval(timer);
+      document.removeEventListener("visibilitychange", shown);
+    };
+  }, [enabled, refresh]);
+  const read = enabled ? threads : null;
+  return {
+    threads: read,
+    unread: (read ?? []).reduce((sum, thread) => sum + (thread.unread ?? 0), 0),
+    waiting: (read ?? []).some((thread) => thread.waiting_on_person === true),
+    refresh,
+  };
+}
+
+export interface ThreadsProps {
+  /** The threads, newest first (`useUnread`'s). */
+  threads: readonly Thread[];
+  /** The one open now, marked. */
+  current?: string | null | undefined;
+  onSelect: (id: string) => void;
+  /** Starts another; without it, no button for it. */
+  onNew?: (() => void) | undefined;
+  /** The way back to the open conversation; without it, none. */
+  onBack?: (() => void) | undefined;
+  messages?: Partial<ThreadMessages> | undefined;
+  classNames?: Partial<Record<ThreadPart, string>> | undefined;
+}
+
+/**
+ * The person's threads with the agent: each by its title, how many of the agent's messages in
+ * it are unread, a dot when it waits on them; the open one marked; another to start.
+ */
+export function Threads({
+  threads,
+  current = null,
+  onSelect,
+  onNew,
+  onBack,
+  messages,
+  classNames,
+}: ThreadsProps) {
+  const words = { ...THREAD_MESSAGES, ...messages };
+  return (
+    <section aria-label={words.title} part="threads" className={classes(classNames, "sc-threads")}>
+      <header className={classes(classNames, "sc-threads__head")}>
+        {onBack && (
+          <Button
+            tone="ghost"
+            size="sm"
+            icon={ArrowLeftIcon}
+            aria-label={words.back}
+            title={words.back}
+            onClick={onBack}
+          />
+        )}
+        <h3 className={classes(classNames, "sc-threads__title")}>{words.title}</h3>
+        {onNew && (
+          <Button tone="ghost" size="sm" icon={PlusIcon} onClick={onNew}>
+            {words.new}
+          </Button>
+        )}
+      </header>
+      {threads.length === 0 ? (
+        <p className={classes(classNames, "sc-threads__empty")}>{words.empty}</p>
+      ) : (
+        <ul className={classes(classNames, "sc-threads__list")}>
+          {threads.map((thread) => {
+            const unread = thread.unread ?? 0;
+            const open = thread.id === current;
+            return (
+              <li key={thread.id}>
+                <button
+                  type="button"
+                  aria-current={open || undefined}
+                  className={classes(
+                    classNames,
+                    "sc-threads__item",
+                    ...(open ? (["sc-threads__item--current"] as const) : []),
+                  )}
+                  onClick={() => {
+                    onSelect(thread.id);
+                  }}
+                >
+                  <span className={classes(classNames, "sc-threads__name")}>
+                    {thread.title ?? words.untitled}
+                  </span>
+                  {unread > 0 ? (
+                    <span
+                      aria-label={words.unread(unread)}
+                      className={classes(classNames, "sc-threads__badge")}
+                    >
+                      {unread}
+                    </span>
+                  ) : (
+                    thread.waiting_on_person === true && (
+                      <span
+                        role="img"
+                        aria-label={words.waiting}
+                        className={classes(classNames, "sc-threads__dot")}
+                      />
+                    )
+                  )}
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </section>
+  );
+}
+
+/**
+ * A conversation between a person and one agent, as the API reads it (`types.ts`): one name for
+ * the shape and for the component that shows one.
+ */
+export type Conversation = Thread;
+
+export type ConversationProps = Omit<AgentChatProps, "conversationId"> & {
+  /** The conversation to show, by its id. */
+  id: string;
+};
+
+/**
+ * One conversation, for a host that lays out its own threads: the chat (`AgentChat`), which reads
+ * what comes as it shows it on a person's page, so their `unread` follows.
+ */
+export function Conversation({ id, ...chat }: ConversationProps) {
+  return <AgentChat conversationId={id} {...chat} />;
+}

package/src/VoiceCall.tsx

@@ -92,7 +92,7 @@ export const VOICE_CALL_MESSAGES: VoiceCallMessages = {
     },
     builder: {
       title: (name) => `${name} doesn't take calls`,
-      help: "A squad's builder only writes. Call one of the squad's agents.",
+      help: "The builder only writes. Call one of the agents.",
     },
     refused: {
       title: (name) => `${name} can't take this call`,

package/src/about.ts

@@ -1,9 +1,12 @@
 /**
  * Qué puede: what an agent says about itself and the facts it rests on (`GET /agents/{id}/about`,
  * `POST /agents/{id}/describe`). The words are the model's, written from the agent's folder and
- * stale the moment it changes; the facts are the platform's, read each time.
+ * stale the moment it changes; the facts are the platform's, read each time. Their types are the
+ * contract's (`contract.ts`).
  */
 
+import type * as C from "./contract";
+
 /** The marks the package draws (a topic's, an automation's kind, a note's tone). */
 export const ICONS = [
   "message",
@@ -30,89 +33,33 @@ export const ICONS = [
 
 export type Icon = (typeof ICONS)[number];
 
-/** One automation as the agent tells it: what it does then, and when. */
-export interface Does {
-  /** The automation's id. */
-  automation: string;
-  text: string;
-  /** When it runs, the way a person says it: "Cada día a las 8:00". */
-  when: string;
-}
+/** One automation as the agent tells it: what it does then, and when ("Cada día a las 8:00"). */
+export type Does = C.Does;
 
 /** What the agent says about itself: a lead, what it does, what it asks leave for. */
-export interface About {
-  /** Two or three sentences, first person, in the owner's language. */
-  summary: string;
-  does: Does[];
-  asks: string[];
-}
+export type About = C.About;
 
-export type ActionSource = "default" | "library" | "own";
-
-export interface ActionFact {
-  name: string;
-  description: string;
-  source: ActionSource;
-  on: boolean;
-  needs_approval: boolean;
-  destructive: boolean;
-  /** Its input as the model gets it (JSON Schema); left out by an API from before. */
-  input_schema?: Readonly<Record<string, unknown>> | undefined;
-}
+export type ActionSource = C.ActionRowOut["source"];
 
-export type AutomationKind = "schedule" | "webhook" | "event";
-
-/** Something the agent does on its own: at a time, when another system calls, on an event. */
-export interface AutomationFact {
-  id: string;
-  /** Its file's name, `automations/<name>.py`: how its page is reached. */
-  name: string;
-  kind: AutomationKind;
-  title: string;
-  /** What it does, in the owner's words. */
-  summary: string;
-  /** The same words, for a reader of the older shape. */
-  say: string;
-  /** A cron line and its time zone, for one that runs at a time. */
-  schedule?: string | null | undefined;
-  timezone?: string | null | undefined;
-  /** Where another system calls it, for a webhook (a path on the API). */
-  url?: string | null | undefined;
-  /** For one on an app's event: the app (the connection's name), the event as its provider
-   * names it, and the app as its mark is drawn (`composio:gmail`, the provider's logo). */
-  app?: string | null | undefined;
-  /** The app as people write it (`Google Calendar`). */
-  app_title?: string | null | undefined;
-  event?: string | null | undefined;
-  provider?: string | undefined;
-  icon?: string | null | undefined;
-  /** Off: declared, but it doesn't run. */
-  on: boolean;
-  next_run_at?: string | null | undefined;
-}
+/** One of its actions: where it comes from, whether it is on and asks first, its input. */
+export type ActionFact = C.ActionRowOut;
 
+export type AutomationKind = C.FactAutomation["kind"];
+
+/** Something the agent does on its own: at a time, when another system calls, on an app's event
+ * (with the app's name and mark), on a message. */
+export type AutomationFact = C.FactAutomation;
+
+/** Who brings an app: one of the providers, an MCP server, the business's own API. */
 export type Provider = "arcade" | "composio" | "mcp" | "api";
 
-export interface ConnectionFact {
-  provider: Provider;
-  name: string;
-  /** The app, as the provider names it (`gmail`). */
-  toolkit?: string | undefined;
-  /** The app as people write it (`Google Calendar`). */
-  title?: string | undefined;
-  /** pending · active · error · disconnected */
-  status?: string | undefined;
-  /** The provider's names of what the agent may do in it (`Gmail.SendEmail`). */
-  actions: string[];
-  /** What the provider calls each of them for people (`List Events`), when it says. */
-  titles?: Readonly<Record<string, string>> | undefined;
-  /** A URL to the app's own mark, when the provider gives one. */
-  icon?: string | null | undefined;
-}
+/** An app it was given: its name and mark, and its tools, with their names for people
+ * (`titles`) and as the model calls them (`called`). */
+export type ConnectionFact = C.FactConnection;
 
 /** An app of the agent's as people write it: its provider's name, else its alias made words. */
 export const appTitle = (connection: ConnectionFact): string =>
-  connection.title ?? toolName(connection.name);
+  connection.title || toolName(connection.name);
 
 /** A tool of an app as people read it: its provider's name for it, else its own made words. */
 export const toolTitle = (connection: ConnectionFact, action: string): string =>
@@ -143,7 +90,10 @@ export function actionWords(name: string): string {
 /** The longest name the model takes for a tool (`app/connections` cuts there too). */
 const MAX_TOOL_NAME = 64;
 
-/** `gmail` + `Gmail.SendEmail` → `gmail__Gmail_SendEmail`: the tool the model is given. */
+/**
+ * `gmail` + `Gmail.SendEmail` → `gmail__Gmail_SendEmail`: the tool the model is given.
+ * @deprecated The facts say it: `ConnectionFact.called`.
+ */
 export const generatedName = (alias: string, action: string): string =>
   `${alias}__${action.replace(/[^A-Za-z0-9_]/g, "_")}`.slice(0, MAX_TOOL_NAME);
 
@@ -156,7 +106,7 @@ export function appSteps(connections: readonly ConnectionFact[]): Record<string,
   return Object.fromEntries(
     connections.flatMap((connection) =>
       connection.actions.map((action) => [
-        generatedName(connection.name, action),
+        connection.called[action] ?? generatedName(connection.name, action),
         `${toolTitle(connection, action)} (${appTitle(connection)})`,
       ]),
     ),
@@ -165,85 +115,33 @@ export function appSteps(connections: readonly ConnectionFact[]): Record<string,
 
 export type ChannelKind = "whatsapp" | "instagram" | "email" | "sms" | "web" | "phone";
 
-export interface ChannelFact {
-  kind: ChannelKind;
-  name: string;
-  status: string;
-}
+export type ChannelFact = C.FactChannel;
 
 /** A file the agent can read: its own, or one of the organization's, shared with every agent. */
-export interface FileFact {
-  path: string;
-  size: number;
-  /** Text, Markdown, JSON, YAML or PDF, read by `search_files`; anything else is only kept. */
-  searchable: boolean;
-  /** The organization's, not the agent's own. */
-  shared: boolean;
-}
+export type FileFact = C.FactFile;
 
-/** A line the agent kept with `remember`. */
-export interface MemoryFact {
-  id: string;
-  /** The agent that keeps it; the contact it is about, when it is about one. */
-  agent_id?: string | undefined;
-  contact_id?: string | null | undefined;
-  text: string;
-  created_at: string;
-}
+/** A line the agent kept with `remember`: its own, or about the contact it names. */
+export type MemoryFact = C.MemoryOut;
 
-/** A key the agent may use: its own, or one of the organization's, shared with every agent. */
-export interface VaultFact {
-  name: string;
-  /** The hosts it may be sent to. */
-  hosts?: string[] | undefined;
-  /** The organization's, not the agent's own. */
-  shared?: boolean | undefined;
-}
+/** A key the agent may use: its own, or one of the organization's its access gives it. */
+export type VaultFact = C.FactKey;
 
 /** A table of the organization's the agent may read or write (an agenda, the clients). */
-export interface DataFact {
-  table: string;
-  /** Its name for people, when it has one. */
-  title?: string | null | undefined;
-  can: string[];
-}
+export type DataFact = C.FactTable;
 
-export interface AskFact {
-  agent_id: string;
-  name: string;
-}
+export type AskFact = C.FactAsk;
 
-export type DeviceKind = "extension" | "installer";
+export type DeviceKind = C.FactDevice["kind"];
 
-export interface DeviceFact {
-  kind: DeviceKind;
-  name: string;
-  status: string;
-}
+export type DeviceFact = C.FactDevice;
 
-/** What the agent has, every list present from day one; one whose phase has not come is empty. */
-export interface Facts {
-  actions: ActionFact[];
-  automations: AutomationFact[];
-  connections: ConnectionFact[];
-  channels: ChannelFact[];
-  /** Its own first, then the organization's shared. */
-  files: FileFact[];
-  /** Newest first. */
-  memories: MemoryFact[];
-  vault: VaultFact[];
-  data: DataFact[];
-  asks: AskFact[];
-  devices: DeviceFact[];
-}
+/** What the agent has, every list present from day one; one whose phase has not come is empty:
+ * its files its own first, its memories newest first. */
+export type Facts = C.Facts;
 
-export interface AboutOut {
-  /** Null until the agent has written about itself once. */
-  about: About | null;
-  /** When the words were written; null when the folder changed since, so they are stale. */
-  about_at: string | null;
-  facts: Facts;
-}
+/** What it says (null until written once; `about_at` null when the folder changed since, so the
+ * words are stale) and the facts. */
+export type AboutOut = C.AboutOut;
 
 /**
  * What the panel lists of the facts beside what the agent does on its own, gathered into a few

package/src/automation/cron.ts

@@ -1,5 +1,5 @@
 /**
- * A schedule's cron line, read into what it fires at: the moments of a day (a squad's day, an
+ * A schedule's cron line, read into what it fires at: the moments of a day (the agents' day, an
  * automation's next runs) and the sentence that says it (`whenOf`). Five fields (minute, hour,
  * day of the month, month, day of the week) with `*`, lists, ranges, steps and English names, as
  * the API's croniter reads them; anything past that is not read (null).

package/src/automation/marks.tsx

@@ -1,4 +1,5 @@
 import {
+  ArrowBendDownRightIcon,
   BellIcon,
   BrainIcon,
   ChatCircleIcon,
@@ -8,7 +9,9 @@ import {
   FileTextIcon,
   FlaskIcon,
   GlobeIcon,
+  HandTapIcon,
   LightningIcon,
+  PlugsConnectedIcon,
   SparkleIcon,
   TableIcon,
   WebhooksLogoIcon,
@@ -51,9 +54,13 @@ export function AppMark({
 const KINDS: Readonly<Record<Exclude<Trigger["kind"], "event">, Icon>> = {
   schedule: ClockIcon,
   webhook: WebhooksLogoIcon,
+  platform: ChatCircleIcon,
+  manual: HandTapIcon,
+  after: ArrowBendDownRightIcon,
 };
 
-/** What starts an automation, as a mark: a clock, a webhook, the app whose event it waits for. */
+/** What starts an automation, as a mark: a clock, a webhook, a message, the app whose event it
+ * waits for. */
 export function TriggerMark({
   trigger,
   size,
@@ -69,12 +76,16 @@ export function TriggerMark({
   return <AppMark name={name} icon={trigger.icon} size={size} apps={apps} />;
 }
 
-/** What started a run: its time, a call, its app's event, a chat with the agent, a test. */
+/** What started a run: its time, a call, its app's event, a message, a chat with the agent, a
+ * test. */
 const BY: Readonly<Record<Exclude<RunBy, "event">, Icon>> = {
   schedule: ClockIcon,
   webhook: WebhooksLogoIcon,
+  platform: ChatCircleIcon,
   agent: ChatCircleIcon,
   test: FlaskIcon,
+  api: PlugsConnectedIcon,
+  after: ArrowBendDownRightIcon,
 };
 
 export function ByMark({

package/src/automation/messages.ts

@@ -66,6 +66,12 @@ export interface AutomationMessages {
   /** What another kind of trigger waits for. */
   webhook: string;
   event: (app: string | null, event: string | null) => string;
+  /** One of the platform's events: a contact's message stored on a channel. */
+  platform: string;
+  /** Only started by hand: the agent, the business's app, a button. */
+  manual: string;
+  /** When another of the agent's automations ends well, by its name. */
+  after: (automation: string | null) => string;
   /** When it runs next, after when it runs: the day, and the time when the line doesn't say it. */
   next: (day: DayRef, time: string | null) => string;
   /** How it stands, on its pill. */
@@ -124,6 +130,9 @@ export const AUTOMATION_MESSAGES: AutomationMessages = {
   on: (often, days) => `${often}, ${days.charAt(0).toLowerCase()}${days.slice(1)}`,
   custom: "On a schedule of its own",
   webhook: "When another system calls it",
+  platform: "When a message arrives",
+  manual: "When someone starts it",
+  after: (automation) => (automation ? `After “${automation}”` : "After another automation"),
   event: (app, event) =>
     event ? `When ${event} in ${app ?? "an app"}` : `On an event in ${app ?? "an app"}`,
   next: (day, time) => {
@@ -171,8 +180,11 @@ export const AUTOMATION_MESSAGES: AutomationMessages = {
       schedule: "scheduled",
       webhook: "webhook",
       event: app ? `${app} event` : "event",
+      platform: "a message",
       agent: "you asked in the chat",
       test: "test",
+      api: "your app",
+      after: "after another",
     })[by],
   statuses: {
     running: "Running",