@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/about.ts

@@ -0,0 +1,355 @@
+/**
+ * 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.
+ */
+
+/** The marks the package draws (a topic's, an automation's kind, a note's tone). */
+export const ICONS = [
+  "message",
+  "phone",
+  "mail",
+  "calendar",
+  "clock",
+  "search",
+  "file",
+  "table",
+  "bell",
+  "hand",
+  "user",
+  "globe",
+  "code",
+  "lock",
+  "cart",
+  "card",
+  "map",
+  "check",
+  "warning",
+  "sparkle",
+] as const;
+
+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;
+}
+
+/** 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 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 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;
+}
+
+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 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);
+
+/** 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 =>
+  connection.titles?.[action] ?? toolName(action);
+
+/** A tool of an app as a person reads it: `Gmail.SendEmail` is "Send email". */
+export function toolName(action: string): string {
+  const bare = action.slice(action.lastIndexOf(".") + 1);
+  const words = bare
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/_/g, " ")
+    .toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+/**
+ * An action's name made words, for one nobody named: `ver_hoja` is "Ver hoja"; an app's tool
+ * as the model calls it, `gmail__GMAIL_SEND_EMAIL`, is "Send email (Gmail)".
+ */
+export function actionWords(name: string): string {
+  const split = name.indexOf("__");
+  if (split < 0) return toolName(name);
+  const tool = name.slice(split + 2);
+  const bare = tool.slice(tool.indexOf("_") + 1) || tool;
+  return `${toolName(bare)} (${toolName(name.slice(0, split))})`;
+}
+
+/** 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. */
+export const generatedName = (alias: string, action: string): string =>
+  `${alias}__${action.replace(/[^A-Za-z0-9_]/g, "_")}`.slice(0, MAX_TOOL_NAME);
+
+/**
+ * The tools the agent's apps give it, by the names the model calls them, in words: the
+ * provider's for the tool and the app's ("List Events (Google Calendar)"), as a chat's steps
+ * read them (`ChatMessages.steps`).
+ */
+export function appSteps(connections: readonly ConnectionFact[]): Record<string, string> {
+  return Object.fromEntries(
+    connections.flatMap((connection) =>
+      connection.actions.map((action) => [
+        generatedName(connection.name, action),
+        `${toolTitle(connection, action)} (${appTitle(connection)})`,
+      ]),
+    ),
+  );
+}
+
+export type ChannelKind = "whatsapp" | "instagram" | "email" | "sms" | "web" | "phone";
+
+export interface ChannelFact {
+  kind: ChannelKind;
+  name: string;
+  status: string;
+}
+
+/** 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;
+}
+
+/** 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 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 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 interface AskFact {
+  agent_id: string;
+  name: string;
+}
+
+export type DeviceKind = "extension" | "installer";
+
+export interface DeviceFact {
+  kind: DeviceKind;
+  name: string;
+  status: string;
+}
+
+/** 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[];
+}
+
+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 the panel lists of the facts beside what the agent does on its own, gathered into a few
+ * things an owner reads at a glance: the apps it uses, its tools, what it knows (files and
+ * tables), what it has learned, where it works (channels and devices), and its keys.
+ */
+export type Topic = "apps" | "tools" | "knowledge" | "learning" | "channels" | "keys";
+
+/** The topics in the order the panel lists them. */
+export const TOPICS: readonly Topic[] = [
+  "apps",
+  "tools",
+  "knowledge",
+  "learning",
+  "channels",
+  "keys",
+];
+
+/** An automation with what the agent said about it, when it said something. */
+export interface Told {
+  automation: AutomationFact;
+  line: Does | undefined;
+}
+
+/**
+ * The agent's automations, in their order, each with the agent's line about it (matched by id):
+ * one added since the words were written has none yet, and a line for one since removed is
+ * dropped.
+ */
+export function automationsOf(about: About | null, facts: Facts): Told[] {
+  const lines = new Map((about?.does ?? []).map((line) => [line.automation, line]));
+  return facts.automations.map((automation) => ({ automation, line: lines.get(automation.id) }));
+}
+
+/** How many things a topic holds: the tools that are on, the rest whole. */
+export function countOf(topic: Topic, facts: Facts): number {
+  return namesOf(topic, facts, (action) => action.name).length;
+}
+
+/**
+ * The names of what a topic holds, in order, as its row in the panel previews them: an app by its
+ * name, a tool by `label` (the host's words for the shipped ones), a file by its path and a table
+ * by its title, what it learned by the line itself.
+ */
+export function namesOf(
+  topic: Topic,
+  facts: Facts,
+  label: (action: ActionFact) => string,
+): string[] {
+  switch (topic) {
+    case "apps":
+      return facts.connections.map(appTitle);
+    case "tools":
+      return facts.actions.filter((action) => action.on).map(label);
+    case "knowledge":
+      return [
+        ...facts.files.map((file) => file.path),
+        ...facts.data.map((table) => table.title ?? table.table),
+      ];
+    case "learning":
+      return facts.memories.map((memory) => memory.text);
+    case "channels":
+      return [
+        ...facts.channels.map((channel) => channel.name),
+        ...facts.devices.map((device) => device.name),
+      ];
+    case "keys":
+      return facts.vault.map((secret) => secret.name);
+  }
+}
+
+export type AboutState = "writing" | "stale" | "fresh";
+
+/**
+ * Which state the words are in: `writing` while there are none yet or the agent is writing them
+ * anew (`loading`), `stale` when the agent changed since it wrote them, `fresh` otherwise.
+ */
+export function aboutState(
+  about: About | null,
+  aboutAt: string | null,
+  loading: boolean,
+): AboutState {
+  if (about === null || loading) return "writing";
+  return aboutAt === null ? "stale" : "fresh";
+}
+
+/** A file's size as people read it (the kit's, where the file chips draw it). */
+export { formatSize } from "./kit/numbers";
+
+/** How a status reads beside its words: working, broken, or neither. */
+export type StatusTone = "on" | "off" | "quiet";
+
+const ON: ReadonlySet<string> = new Set(["live", "active", "connected", "on", "ready", "online"]);
+const OFF: ReadonlySet<string> = new Set([
+  "failed",
+  "error",
+  "disconnected",
+  "off",
+  "expired",
+  "broken",
+]);
+
+/** The tone of a channel's or a device's status, from the words the platform uses for it. */
+export function toneOf(status: string): StatusTone {
+  const word = status.trim().toLowerCase();
+  if (ON.has(word)) return "on";
+  if (OFF.has(word)) return "off";
+  return "quiet";
+}

package/src/agentIcons.ts

@@ -0,0 +1,56 @@
+import {
+  BriefcaseIcon,
+  CalendarBlankIcon,
+  ChartLineUpIcon,
+  ChatCircleIcon,
+  CodeIcon,
+  CreditCardIcon,
+  EnvelopeSimpleIcon,
+  FileTextIcon,
+  GlobeIcon,
+  HeadsetIcon,
+  HeartIcon,
+  MagnifyingGlassIcon,
+  MapPinIcon,
+  MegaphoneIcon,
+  PhoneIcon,
+  ShoppingCartIcon,
+  SparkleIcon,
+  UserIcon,
+  WrenchIcon,
+  type Icon as Phosphor,
+} from "@phosphor-icons/react";
+
+/**
+ * The marks an agent goes by: a glyph for the work it does (appointments, reception, sales…), on
+ * the tint it keeps everywhere (`agentTint`). It picks one itself the first time it describes
+ * itself; the owner changes it through the builder. One to one with the API's `AgentIcon`.
+ */
+export const AGENT_ICONS = {
+  sparkle: SparkleIcon,
+  calendar: CalendarBlankIcon,
+  headset: HeadsetIcon,
+  message: ChatCircleIcon,
+  phone: PhoneIcon,
+  mail: EnvelopeSimpleIcon,
+  cart: ShoppingCartIcon,
+  card: CreditCardIcon,
+  chart: ChartLineUpIcon,
+  megaphone: MegaphoneIcon,
+  wrench: WrenchIcon,
+  briefcase: BriefcaseIcon,
+  heart: HeartIcon,
+  user: UserIcon,
+  search: MagnifyingGlassIcon,
+  file: FileTextIcon,
+  globe: GlobeIcon,
+  code: CodeIcon,
+  map: MapPinIcon,
+} as const satisfies Record<string, Phosphor>;
+
+export type AgentIcon = keyof typeof AGENT_ICONS;
+
+/** An agent's glyph; a sparkle until it has picked one (or for a mark this package predates). */
+export function agentGlyph(icon: string | null | undefined): Phosphor {
+  return icon != null && icon in AGENT_ICONS ? AGENT_ICONS[icon as AgentIcon] : SparkleIcon;
+}