@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/src/frames.ts

@@ -0,0 +1,291 @@
+import type { Surface } from "./blocks";
+import type {
+  Action,
+  Attachment,
+  BrowserControl,
+  BrowserFrame,
+  BrowserInput,
+  BrowserState,
+  Decides,
+  Decision,
+  Handover,
+  Holder,
+  Message,
+  Request,
+  Step,
+  StepState,
+  ToolCall,
+} from "./types";
+
+/**
+ * The frames of a conversation's socket, as v3/README.md documents them. Down: a message stored;
+ * a piece of the reply as it streams; a surface the agent shows (`awaits`: the turn stops until
+ * the person acts on it); an action running, told again as its state moves; an action that needs
+ * a yes, the person's (the turn stopped) or the business's (`decides`: the turn went on); the
+ * conversation handed to a person, and why (the agent stays quiet in it
+ * until it is released); the turn over, or stopped by the person; or what went wrong (`code` for
+ * the app to word, `detail` for a log). A socket that opens mid-turn is first told the turn so
+ * far, from the person's message on. Who answers the conversation, after any change of it (`holder`:
+ * who now, and the change); and what was decided of a person's message, when it is stored,
+ * settles or is cleared (`decision`, null then). And the conversation's browser: its state, whole, whenever it changes
+ * (told at once to a socket that opens), and its screen as it paints. And one of the host's own
+ * tools the agent called, for the page to run (`tool`): its step works meanwhile, the turn waits
+ * for its `tool_result`, and a person's socket that opens while it waits is told it again.
+ */
+export type Frame =
+  | { type: "working" }
+  | { type: "message"; message: Message }
+  | { type: "text"; delta: string }
+  | { type: "ui"; id: string; surface: Surface; awaits: boolean }
+  | { type: "step"; id: string; state: StepState; action?: string; output?: string }
+  | ({ type: "request"; id: string } & Request)
+  | ({ type: "tool" } & ToolCall)
+  | { type: "handoff"; reason: string }
+  | { type: "holder"; handled_by: Holder; handover: Handover }
+  | { type: "decision"; message_id: string; decision: Decision | null }
+  | { type: "done" }
+  | { type: "stopped" }
+  | { type: "error"; code: string; detail: string }
+  | ({ type: "browser"; open: true } & BrowserState)
+  | { type: "browser"; open: false }
+  | ({ type: "browser.frame" } & BrowserFrame);
+
+/**
+ * Up: the person says something (words, files they uploaded to the conversation, or both), acts
+ * on a surface, or stops the reply on its way; takes the browser or gives it back, and acts on it
+ * while they hold it. And what a tool of the host's answered, run in the page: its output, or
+ * why it failed.
+ */
+export type UpFrame =
+  | { type: "say"; text: string; files?: string[] }
+  | ({ type: "action" } & Action)
+  | { type: "stop" }
+  | { type: "browser.control"; to: BrowserControl }
+  | { type: "browser.close" }
+  | { type: "browser.input"; event: BrowserInput }
+  | ToolResult;
+
+/** What a host's tool answered: what it gave back (null for nothing), or why it failed. */
+export type ToolResult =
+  | { type: "tool_result"; id: string; output: unknown }
+  | { type: "tool_result"; id: string; error: string };
+
+const STATES: ReadonlySet<string> = new Set(["running", "waiting", "done", "failed"]);
+const HOLDERS: ReadonlySet<string> = new Set(["agent", "person", "nobody"]);
+const DECISIONS: ReadonlySet<string> = new Set(["deciding", "answer", "skip", "hold", "ignore"]);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const isState = (value: unknown): value is StepState =>
+  typeof value === "string" && STATES.has(value);
+
+// The blocks inside are the API's, validated at `show`; the renderer draws what it knows.
+const isSurface = (value: unknown): value is Surface =>
+  isRecord(value) && Array.isArray(value.blocks) && typeof value.text === "string";
+
+const isDecides = (value: unknown): value is Decides => value === "person" || value === "business";
+
+const isRequest = (value: unknown): value is Request =>
+  isRecord(value) &&
+  typeof value.action === "string" &&
+  isRecord(value.input) &&
+  (value.decides === undefined || isDecides(value.decides));
+
+const isStep = (value: unknown): value is Step =>
+  isRecord(value) &&
+  typeof value.id === "string" &&
+  typeof value.action === "string" &&
+  isState(value.state) &&
+  (value.output === null || typeof value.output === "string") &&
+  (value.surface === null || isSurface(value.surface)) &&
+  typeof value.awaits === "boolean" &&
+  (value.request === null || isRequest(value.request));
+
+const isSize = (value: Record<string, unknown>): boolean =>
+  typeof value.width === "number" && typeof value.height === "number";
+
+const orNull = (value: unknown): string | null => (typeof value === "string" ? value : null);
+
+const isHolder = (value: unknown): value is Holder =>
+  typeof value === "string" && HOLDERS.has(value);
+
+/** A change of who answers as told, or null when it is not one: a reason or title left out is none. */
+function handoverOf(value: unknown): Handover | null {
+  if (!isRecord(value) || !isHolder(value.holder)) return null;
+  if (typeof value.by !== "string" || typeof value.at !== "string") return null;
+  const { holder, by, at } = value;
+  return { holder, reason: orNull(value.reason) ?? "", by, title: orNull(value.title), at };
+}
+
+/** A message's decision as told, or null when it is not one; what it leaves out is none. */
+function decisionOf(value: unknown): Decision | null {
+  if (!isRecord(value) || typeof value.kind !== "string" || !DECISIONS.has(value.kind)) return null;
+  return {
+    kind: value.kind as Decision["kind"],
+    reason: orNull(value.reason),
+    automation: orNull(value.automation),
+    title: orNull(value.title),
+    run_id: orNull(value.run_id),
+  };
+}
+
+/** The browser's state as told, or null when it is not one this package can draw. */
+function browserOf(frame: Record<string, unknown>): BrowserState | null {
+  const { url, title, control } = frame;
+  if (typeof url !== "string" || typeof title !== "string" || !isSize(frame)) return null;
+  if (control !== "agent" && control !== "person") return null;
+  return {
+    where: frame.where === "mine" ? "mine" : "hosted",
+    url,
+    title,
+    control,
+    reason: orNull(frame.reason),
+    wait: orNull(frame.wait),
+    width: frame.width as number,
+    height: frame.height as number,
+  };
+}
+
+const isAction = (value: unknown): value is Action =>
+  isRecord(value) &&
+  typeof value.surface === "string" &&
+  typeof value.name === "string" &&
+  isRecord(value.data) &&
+  typeof value.label === "string";
+
+const isAttachment = (value: unknown): value is Attachment =>
+  isRecord(value) &&
+  typeof value.id === "string" &&
+  typeof value.name === "string" &&
+  typeof value.media_type === "string" &&
+  typeof value.size === "number";
+
+const isMessage = (value: unknown): value is Message =>
+  isRecord(value) &&
+  typeof value.id === "string" &&
+  (value.role === "user" || value.role === "assistant") &&
+  typeof value.text === "string" &&
+  (value.action === null || isAction(value.action)) &&
+  Array.isArray(value.steps) &&
+  value.steps.every(isStep) &&
+  (value.files === undefined || (Array.isArray(value.files) && value.files.every(isAttachment))) &&
+  typeof value.created_at === "string";
+
+/** The most files one message carries. */
+export const FILES_PER_MESSAGE = 10;
+
+/**
+ * What saying something sends: the words trimmed, and the ids of the files uploaded for it
+ * beside them (only when there are); null when there is neither.
+ */
+export function sayOf(text: string, files: readonly string[] = []): UpFrame | null {
+  const words = text.trim();
+  if (words === "" && files.length === 0) return null;
+  return files.length === 0
+    ? { type: "say", text: words }
+    : { type: "say", text: words, files: [...files] };
+}
+
+/** The most of a tool's error the API takes: the agent reads the rest of it as cut. */
+export const TOOL_ERROR_MAX = 2000;
+
+/**
+ * What a host's tool call answers up, from how its promise settled: what it gave back (`null` for
+ * nothing, which JSON would leave out), or the reason it threw in words (an error's message; its
+ * kind when it says nothing), as much of it as the API takes.
+ */
+export function toolResultOf(id: string, settled: PromiseSettledResult<unknown>): ToolResult {
+  if (settled.status === "fulfilled") {
+    return { type: "tool_result", id, output: settled.value ?? null };
+  }
+  const reason: unknown = settled.reason;
+  const words = (reason instanceof Error ? reason.message : String(reason)).trim();
+  const error = words || (reason instanceof Error ? reason.name : "Error");
+  return { type: "tool_result", id, error: error.slice(0, TOOL_ERROR_MAX) };
+}
+
+/**
+ * One frame, read without trusting it. Kinds this package does not know yet (more will come:
+ * `audio`) and anything malformed are null, to be let pass.
+ */
+export function frameOf(raw: unknown): Frame | null {
+  if (typeof raw !== "string") return null;
+  let frame: unknown;
+  try {
+    frame = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isRecord(frame)) return null;
+  const { id, action, output } = frame;
+  if (frame.type === "message" && isMessage(frame.message)) {
+    return { type: "message", message: frame.message };
+  }
+  if (frame.type === "text" && typeof frame.delta === "string") {
+    return { type: "text", delta: frame.delta };
+  }
+  if (frame.type === "ui" && typeof id === "string" && isSurface(frame.surface)) {
+    return { type: "ui", id, surface: frame.surface, awaits: frame.awaits === true };
+  }
+  if (frame.type === "step" && typeof id === "string" && isState(frame.state)) {
+    return {
+      type: "step",
+      id,
+      state: frame.state,
+      ...(typeof action === "string" ? { action } : {}),
+      ...(typeof output === "string" ? { output } : {}),
+    };
+  }
+  if (
+    frame.type === "request" &&
+    typeof id === "string" &&
+    typeof action === "string" &&
+    isRecord(frame.input)
+  ) {
+    // Left out by an API from before it: the person on the screen gave every yes then.
+    const decides = isDecides(frame.decides) ? frame.decides : "person";
+    return { type: "request", id, action, input: frame.input, decides };
+  }
+  if (
+    frame.type === "tool" &&
+    typeof id === "string" &&
+    typeof frame.name === "string" &&
+    isRecord(frame.input)
+  ) {
+    return { type: "tool", id, name: frame.name, input: frame.input };
+  }
+  if (frame.type === "handoff" && typeof frame.reason === "string") {
+    return { type: "handoff", reason: frame.reason };
+  }
+  if (frame.type === "holder" && isHolder(frame.handled_by)) {
+    const handover = handoverOf(frame.handover);
+    return handover && { type: "holder", handled_by: frame.handled_by, handover };
+  }
+  if (frame.type === "decision" && typeof frame.message_id === "string") {
+    const { message_id } = frame;
+    if (frame.decision === null) return { type: "decision", message_id, decision: null };
+    const decision = decisionOf(frame.decision);
+    return decision && { type: "decision", message_id, decision };
+  }
+  if (frame.type === "browser") {
+    if (frame.open === false) return { type: "browser", open: false };
+    const browser = frame.open === true ? browserOf(frame) : null;
+    return browser && { type: "browser", open: true, ...browser };
+  }
+  if (frame.type === "browser.frame" && typeof frame.jpeg === "string" && isSize(frame)) {
+    const { jpeg, width, height } = frame as { jpeg: string; width: number; height: number };
+    return { type: "browser.frame", jpeg, width, height };
+  }
+  if (frame.type === "working" || frame.type === "done" || frame.type === "stopped") {
+    return { type: frame.type };
+  }
+  if (
+    frame.type === "error" &&
+    typeof frame.code === "string" &&
+    typeof frame.detail === "string"
+  ) {
+    return { type: "error", code: frame.code, detail: frame.detail };
+  }
+  return null;
+}

package/src/icons.tsx

@@ -0,0 +1,49 @@
+import {
+  BellIcon,
+  CalendarBlankIcon,
+  ChatCircleIcon,
+  CheckCircleIcon,
+  ClockIcon,
+  CodeIcon,
+  CreditCardIcon,
+  EnvelopeSimpleIcon,
+  FileTextIcon,
+  GlobeIcon,
+  HandPalmIcon,
+  LockSimpleIcon,
+  MagnifyingGlassIcon,
+  MapPinIcon,
+  PhoneIcon,
+  ShoppingCartIcon,
+  SparkleIcon,
+  TableIcon,
+  UserIcon,
+  WarningIcon,
+  type Icon as Phosphor,
+} from "@phosphor-icons/react";
+
+import type { Icon } from "./about";
+
+/** The package's glyphs by name, drawn with Phosphor: what a `Mark` holds. */
+export const GLYPHS: Readonly<Record<Icon, Phosphor>> = {
+  message: ChatCircleIcon,
+  phone: PhoneIcon,
+  mail: EnvelopeSimpleIcon,
+  calendar: CalendarBlankIcon,
+  clock: ClockIcon,
+  search: MagnifyingGlassIcon,
+  file: FileTextIcon,
+  table: TableIcon,
+  bell: BellIcon,
+  hand: HandPalmIcon,
+  user: UserIcon,
+  globe: GlobeIcon,
+  code: CodeIcon,
+  lock: LockSimpleIcon,
+  cart: ShoppingCartIcon,
+  card: CreditCardIcon,
+  map: MapPinIcon,
+  check: CheckCircleIcon,
+  warning: WarningIcon,
+  sparkle: SparkleIcon,
+};

package/src/index.ts

@@ -0,0 +1,270 @@
+/**
+ * @signalcore/ui: ready components for an agent, built only on the public API and the
+ * conversation's socket, styled by the host through `--sc-*` tokens, `classNames` and, in the
+ * widget, `::part()` and its own stylesheet. For the
+ * people an agent serves: `AgentChat`, `VoiceCall`, `AgentSpace` (and `<signalcore-chat>`, built
+ * apart as `widget.js`); the hooks under them for a host that draws its own.
+ */
+export {
+  aboutState,
+  actionWords,
+  appSteps,
+  appTitle,
+  automationsOf,
+  countOf,
+  formatSize,
+  generatedName,
+  ICONS,
+  namesOf,
+  toneOf,
+  toolName,
+  toolTitle,
+  TOPICS,
+} from "./about";
+export type {
+  About,
+  AboutOut,
+  AboutState,
+  ActionFact,
+  AskFact,
+  AutomationFact,
+  AutomationKind,
+  ChannelFact,
+  ChannelKind,
+  ConnectionFact,
+  DataFact,
+  DeviceFact,
+  DeviceKind,
+  Does,
+  Facts,
+  FileFact,
+  Icon,
+  MemoryFact,
+  Provider,
+  StatusTone,
+  Told,
+  Topic,
+  VaultFact,
+} from "./about";
+export { ABOUT_HOME, ABOUT_MESSAGES, aboutBack, AgentAbout } from "./AgentAbout";
+export type {
+  AboutControls,
+  AboutMessages,
+  AboutPart,
+  AboutTools,
+  AboutView,
+  AgentAboutProps,
+  AppDirectory,
+} from "./AgentAbout";
+export { AGENT_ICONS, agentGlyph } from "./agentIcons";
+export type { AgentIcon } from "./agentIcons";
+export { Automation } from "./automation/Automation";
+export type { AutomationProps } from "./automation/Automation";
+export { RunView } from "./automation/RunView";
+export type { RunViewProps } from "./automation/RunView";
+export { AUTOMATION_MESSAGES } from "./automation/messages";
+export type { AutomationMessages, CallMessages, DayRef, Verb } from "./automation/messages";
+export { fires, occurrences, offsetOf, parseCron } from "./automation/cron";
+export type { Cron, Wall } from "./automation/cron";
+export {
+  clockOf,
+  dayRefOf,
+  lineOf,
+  momentOf,
+  scheduleOf,
+  timeOf,
+  tookOf,
+  whenOf,
+} from "./automation/when";
+export type { When } from "./automation/when";
+export { appOf, callWords, groupsOf, namingOf, verbOf } from "./automation/record";
+export type { CallLine, Names, StepGroup } from "./automation/record";
+export type {
+  Automation as AutomationData,
+  AutomationState,
+  AutomationView,
+  Board,
+  Run,
+  RunBy,
+  RunRecord,
+  RunStatus,
+  RunStep,
+  Step as AutomationStep,
+  Task,
+  Trigger,
+  Use,
+} from "./automation/types";
+export { AgentTasks, TASK_MESSAGES, TASKS_POLL_MS, useTasks } from "./AgentTasks";
+export type { AgentTasksProps, TaskMessages, TaskPart } from "./AgentTasks";
+export { AgentCard } from "./AgentCard";
+export type { AgentCardProps, CardField, CardPart } from "./AgentCard";
+export { AgentChat, CHAT_MESSAGES } from "./AgentChat";
+export { AgentSpace, captionsOf, SPACE_MESSAGES } from "./AgentSpace";
+export type { AgentSpaceProps, SpaceLayout, SpaceMessages, SpacePart } from "./AgentSpace";
+export type { ModeMessages, ModePart, SpaceMode } from "./Modes";
+export {
+  AUTOMATION_MESSAGES_ES,
+  BROWSER_MESSAGES_ES,
+  CHAT_MESSAGES_ES,
+  KIT_MESSAGES_ES,
+  SPACE_MESSAGES_ES,
+  TASK_MESSAGES_ES,
+  VOICE_CALL_MESSAGES_ES,
+} from "./es";
+export { VOICE_CALL_MESSAGES, VoiceCall } from "./VoiceCall";
+export type { VoiceCallMessages, VoiceCallPart, VoiceCallProps } from "./VoiceCall";
+export { useCall } from "./useCall";
+export type { Call, CallJoin, CallMeter } from "./useCall";
+export { durationOf, endedByReason, lookOf, orbOf } from "./call";
+export type { AgentActivity, CallEnd, CallEndedBy, CallLook, CallProblem, CallState } from "./call";
+export { Orb } from "./voice/Orb";
+export { ORB_STYLES } from "./voice/orbs";
+export type { OrbProps, OrbState, OrbStyle } from "./voice/orbs";
+export { BROWSER_MESSAGES, BrowserView } from "./BrowserView";
+export type { BrowserMessages, BrowserPart, BrowserViewProps } from "./BrowserView";
+export type {
+  AgentChatProps,
+  ChatCompose,
+  ChatLook,
+  ChatMessages,
+  ChatPart,
+  ChatSteps,
+  HandoverBy,
+} from "./AgentChat";
+export type {
+  AutomationBlock,
+  Block,
+  ButtonBlock,
+  CardBlock,
+  ChartBlock,
+  ChartPoint,
+  ChoiceBlock,
+  DividerBlock,
+  Entry,
+  FieldKind,
+  FieldsBlock,
+  FieldValue,
+  FormBlock,
+  FormField,
+  ImageBlock,
+  ListBlock,
+  NoteBlock,
+  Option,
+  StackBlock,
+  StatBlock,
+  Surface as SurfaceData,
+  TableBlock,
+  TextBlock,
+  Tone,
+} from "./blocks";
+export { ApiError, createClient } from "./client";
+export type { Client, ClientOptions, Files, UploadOptions } from "./client";
+export { VISITOR_KEY } from "./credentials";
+export type { Credentials, Speaker } from "./credentials";
+export { FILE_MESSAGES, FileView } from "./FileView";
+export type { FileMessages, FilePart, FileViewProps } from "./FileView";
+export { cleanDocument, previewOf } from "./files";
+export type { Preview } from "./files";
+export { FILES_PER_MESSAGE, TOOL_ERROR_MAX, toolResultOf } from "./frames";
+export type { Frame, ToolResult, UpFrame } from "./frames";
+export { Button } from "./kit/Button";
+export type { ButtonProps } from "./kit/Button";
+export { Card } from "./kit/Card";
+export { Chips, Choices } from "./kit/Choices";
+export { Combobox } from "./kit/Combobox";
+export type { ComboboxProps } from "./kit/Combobox";
+export { KitProvider } from "./kit/context";
+export type { KitClassNames, KitPart } from "./kit/context";
+export { DateField } from "./kit/DateField";
+export type { DateFieldProps } from "./kit/DateField";
+export { Field } from "./kit/Field";
+export type { ControlBase, FieldIds } from "./kit/Field";
+export { FileChip, FileChips, FileField, UploadChips, useUploads } from "./kit/FileField";
+export { FileMark } from "./kit/FileMark";
+export { familyOf } from "./kit/uploads";
+export type { FileFamily } from "./kit/uploads";
+export type { FileChipProps, FileFieldProps, Upload, UploadRules, Uploads } from "./kit/FileField";
+export { accepts, MAX_MB } from "./kit/uploads";
+export type { FileHost, Uploader } from "./kit/uploads";
+export { Checkbox, NumberInput, SecretInput, TextArea, TextInput } from "./kit/Inputs";
+export { List, Row } from "./kit/List";
+export type { RowProps } from "./kit/List";
+export { Mark } from "./kit/Mark";
+export type { MarkProps } from "./kit/Mark";
+export { MarkStack } from "./kit/MarkStack";
+export { KIT_MESSAGES } from "./kit/messages";
+export type { KitLocale, KitMessages } from "./kit/messages";
+export { Note } from "./kit/Note";
+export { RangeField } from "./kit/RangeField";
+export { RatingField } from "./kit/RatingField";
+export { Stat, Stats } from "./kit/Stat";
+export { Switch } from "./kit/Switch";
+export { AudioPlayer } from "./kit/AudioPlayer";
+export type { AudioPlayerProps } from "./kit/AudioPlayer";
+export type { SwitchProps } from "./kit/Switch";
+export { Tag } from "./kit/Tag";
+export { Tile, Tiles } from "./kit/Tile";
+export type { TileProps } from "./kit/Tile";
+export { DateTimeField, TimeField } from "./kit/TimeField";
+export type { DateTimeFieldProps, TimeFieldProps } from "./kit/TimeField";
+export type { BlockProps, SurfaceComponents, SurfacePart } from "./surface/scope";
+export { Surface } from "./surface/Surface";
+export type { SurfaceProps } from "./surface/Surface";
+export { chosen, filled, labelOf, picked, pressed, problemOf } from "./surface/values";
+export type { SurfaceAction, Values } from "./surface/values";
+export { agentTint } from "./tint";
+export type { AgentTint } from "./tint";
+export type {
+  Action,
+  AgentFace,
+  Attachment,
+  Author,
+  CallGlance,
+  CallReason,
+  CallToken,
+  BrowserControl,
+  BrowserWhere,
+  BrowserFrame,
+  BrowserInput,
+  BrowserState,
+  Channel,
+  ChannelGlance,
+  ChannelSettings,
+  ChannelStatus,
+  ChannelWeb,
+  ContactGlance,
+  ConversationPerson,
+  Conversation,
+  ConversationDetail,
+  ConversationFile,
+  Decides,
+  Decision,
+  Delivery,
+  FileAt,
+  FileBlock,
+  FileIndex,
+  FilePreview,
+  Handover,
+  Holder,
+  HoursSpan,
+  Message,
+  Request,
+  Step,
+  StepState,
+  StoredFile,
+  ToolCall,
+  Weekday,
+  WeekHours,
+  WidgetConfig,
+  WidgetFont,
+  WidgetLook,
+} from "./types";
+export { WIDGET_FONTS } from "./types";
+export { useAgentFace } from "./useAgentFace";
+export type { FaceRead } from "./useAgentFace";
+export { NO_TOOL, useConversation } from "./useConversation";
+export type { LiveConversation, ToolHandler } from "./useConversation";
+export { useLive } from "./useLive";
+export type { Live, LiveHandlers } from "./useLive";
+export { useDictation } from "./useDictation";
+export type { Dictate, Dictation } from "./useDictation";