@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/src/automation/record.ts

@@ -0,0 +1,206 @@
+/**
+ * A run's record in words: each call as what it did ("Buscó en Gmail", "Añadió una fila a
+ * Citas"; a test's writes as what it would have done), gathered under the step it ran in, the same
+ * call made several times in a row said once with how many. Pure, so it is tested without a page.
+ */
+
+import { toolName } from "../about";
+import type { CallMessages, Verb } from "./messages";
+import type { Automation, RunStep } from "./types";
+
+/** The words in a tool's name that say what it does, first match wins; the rest only use it. */
+const VERBS: readonly (readonly [Verb, ReadonlySet<string>])[] = [
+  ["send", new Set(["send", "post", "reply", "forward", "notify", "publish"])],
+  ["remove", new Set(["delete", "remove", "trash", "archive", "cancel"])],
+  ["update", new Set(["update", "edit", "patch", "modify", "move", "mark", "set", "rename"])],
+  ["create", new Set(["create", "add", "insert", "new", "upload", "book", "schedule", "draft"])],
+  [
+    "search",
+    new Set(["search", "fetch", "list", "get", "find", "read", "query", "retrieve", "lookup"]),
+  ],
+];
+
+/**
+ * What a tool does, from its name (`GMAIL_SEND_EMAIL`, `Gmail.SendEmail`): the first of its
+ * words that says so; none, it only uses the app.
+ */
+export function verbOf(tool: string): Verb {
+  const words = tool
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[^A-Za-z0-9]+/)
+    .map((word) => word.toLowerCase())
+    .filter(Boolean);
+  for (const word of words) {
+    for (const [verb, names] of VERBS) if (names.has(word)) return verb;
+  }
+  return "use";
+}
+
+/** How a record names an app and a table: the app by its display name, the table by its title. */
+export interface Names {
+  app: (alias: string) => string;
+  /** The app's logo, when the automation knows it. */
+  icon: (alias: string) => string | null;
+  table: (name: string) => string;
+}
+
+/**
+ * The names an automation knows: its apps' (from its steps' uses and its event's trigger) and
+ * its board's table; anything else by its own name, in words.
+ */
+export function namingOf(
+  automation: Pick<Automation, "steps" | "trigger" | "board"> | null,
+): Names {
+  const apps = new Map<string, { title: string; icon: string | null }>();
+  const trigger = automation?.trigger;
+  if (trigger?.app && trigger.app_title) {
+    apps.set(trigger.app, { title: trigger.app_title, icon: trigger.icon });
+  }
+  for (const step of automation?.steps ?? []) {
+    for (const use of step.uses) {
+      if (use.kind === "app" && use.app !== null && use.title !== null) {
+        apps.set(use.app, { title: use.title, icon: use.icon });
+      }
+    }
+  }
+  const board = automation?.board ?? null;
+  return {
+    app: (alias) => apps.get(alias)?.title ?? toolName(alias),
+    icon: (alias) => apps.get(alias)?.icon ?? null,
+    table: (name) => (board !== null && board.table === name ? board.title : toolName(name)),
+  };
+}
+
+/** The app an app's tool call reached (`tool:gmail.GMAIL_SEND_EMAIL` is `gmail`); null for the rest. */
+export function appOf(call: string): string | null {
+  if (!call.startsWith("tool:")) return null;
+  const target = call.slice(5);
+  const dot = target.indexOf(".");
+  return dot === -1 ? target : target.slice(0, dot);
+}
+
+const field = (value: unknown, name: string): string | null => {
+  if (typeof value !== "object" || value === null || !(name in value)) return null;
+  const found: unknown = (value as Record<string, unknown>)[name];
+  return typeof found === "string" ? found : null;
+};
+
+function hostOf(url: string | null): string {
+  if (url === null) return "";
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * The channel a `send` went out on: what the record says it reached (a test's stand-in names the
+ * one asked for), else the one asked for; null when neither says.
+ */
+export function sentOn(step: RunStep): string | null {
+  return field(step.output, "channel") ?? field(step.input, "via");
+}
+
+/** Who a `send` went to, as words can say it: a number as it was given; a contact's id, "". */
+const recipientOf = (contact: string | null): string =>
+  contact === null || /^ctc_/.test(contact) ? "" : contact;
+
+/** A file's name from its path, as a call names it; "" when the call didn't say. */
+const nameOf = (path: string | null): string =>
+  (path ?? "").slice((path ?? "").lastIndexOf("/") + 1);
+
+/** One call of a run in words; a call the package doesn't know keeps its own name. */
+export function callWords(step: RunStep, words: CallMessages, names: Names): string {
+  const { call, would } = step;
+  const app = appOf(call);
+  if (app !== null) {
+    return words.tool(verbOf(call.slice(5 + app.length + 1)), names.app(app), would);
+  }
+  const table = () => names.table(field(step.input, "table") ?? "");
+  switch (call) {
+    case "ai":
+      return words.ai;
+    case "notify":
+      return words.notify(would);
+    case "send":
+      return words.send(sentOn(step), recipientOf(field(step.input, "contact")), would);
+    case "agent.start":
+      return words.start(would);
+    case "data.find":
+      return words.find(table());
+    case "data.add":
+      return words.add(table(), would);
+    case "data.update":
+      return words.change(table(), would);
+    case "http":
+      return words.http(hostOf(field(step.input, "url")), would);
+    case "files.search":
+      return words.files;
+    case "files.read":
+      return words.read(nameOf(field(step.input, "path")));
+    case "files.write":
+      return words.wrote(nameOf(field(step.input, "path")), would);
+    case "files.list":
+      return words.listed;
+    case "memory.remember":
+      return words.remember(would);
+    case "memory.recall":
+      return words.recall;
+    default:
+      return call;
+  }
+}
+
+/** One line of a step: what was done, how many times in a row, and why it failed when it did. */
+export interface CallLine {
+  /** The first call's place in the record. */
+  seq: number;
+  text: string;
+  count: number;
+  error: string | null;
+  would: boolean;
+  /** Every call the line stands for: their inputs and outputs, for whoever reads them. */
+  calls: RunStep[];
+}
+
+/** The calls made in one step, in their order; `step` null for those made outside any. */
+export interface StepGroup {
+  step: string | null;
+  lines: CallLine[];
+}
+
+/**
+ * A run's calls under the step each ran in, in the record's order: a new group each time the
+ * step changes, and in a group the same words in a row (none failed) as one line with a count.
+ */
+export function groupsOf(
+  steps: readonly RunStep[],
+  words: CallMessages,
+  names: Names,
+): StepGroup[] {
+  const groups: StepGroup[] = [];
+  for (const step of [...steps].sort((a, b) => a.seq - b.seq)) {
+    let group = groups[groups.length - 1];
+    if (group === undefined || group.step !== step.step) {
+      group = { step: step.step, lines: [] };
+      groups.push(group);
+    }
+    const text = callWords(step, words, names);
+    const last = group.lines[group.lines.length - 1];
+    if (last !== undefined && last.text === text && last.error === null && step.error === null) {
+      last.count += 1;
+      last.calls.push(step);
+    } else {
+      group.lines.push({
+        seq: step.seq,
+        text,
+        count: 1,
+        error: step.error,
+        would: step.would,
+        calls: [step],
+      });
+    }
+  }
+  return groups;
+}

package/src/automation/types.ts

@@ -0,0 +1,146 @@
+/**
+ * An agent's automations and their runs, as the API gives them (v3/AUTOMATIONS.md): what starts
+ * each one, the steps its code names, the table it moves, and every run with its record. Written
+ * by hand, one to one with the API's answers; times are ISO 8601 in UTC.
+ */
+
+/**
+ * What a step uses, as the manifest reads it from the code before any run: an app, the model,
+ * the agent, the owner's inbox, a message to a contact on a channel (`sc.send`), a table, the web.
+ */
+export interface Use {
+  kind: "app" | "ai" | "agent" | "notify" | "send" | "data" | "http";
+  /** An app's: the connection's name (its alias). */
+  app: string | null;
+  /** An app's: its display name. */
+  title: string | null;
+  /** An app's: its logo (https), when known. */
+  icon: string | null;
+}
+
+/** A step of the code (`sc.step("…")`), in the code's order, with what it uses. */
+export interface Step {
+  name: string;
+  uses: Use[];
+}
+
+/** What starts an automation: a time (cron, on a zone's clock), a call to its URL, an app's event. */
+export interface Trigger {
+  kind: "schedule" | "webhook" | "event";
+  /** Five-field cron. */
+  schedule: string | null;
+  /** IANA zone. */
+  timezone: string | null;
+  /** The webhook's full URL. */
+  url: string | null;
+  /** An event's app: the connection's name, its display name, its logo. */
+  app: string | null;
+  app_title: string | null;
+  /** The provider's event slug, and the event in words when the provider gives them. */
+  event: string | null;
+  event_title: string | null;
+  icon: string | null;
+}
+
+/** The table an automation moves, as counts of its rows per value of one field. */
+export interface Board {
+  table: string;
+  /** The table's title. */
+  title: string;
+  /** The field the rows are counted by. */
+  field: string;
+  /** Per value, biggest first, at most 8. */
+  counts: { value: string; count: number }[];
+}
+
+export type RunStatus = "running" | "waiting" | "done" | "failed" | "skipped";
+
+/** What started a run: its time, a call, an app's event, the agent in a chat, a test. */
+export type RunBy = "schedule" | "webhook" | "event" | "agent" | "test";
+
+/** One start of an automation, whatever started it. */
+export interface Run {
+  id: string;
+  agent_id: string;
+  /** The automation's name. */
+  automation: string;
+  /** The automation's title when it ran. */
+  title: string;
+  by: RunBy;
+  /** Started by the agent: the conversation it was asked in. */
+  conversation_id: string | null;
+  status: RunStatus;
+  /** What the code returned: the run's one line. */
+  summary: string | null;
+  /** Why it failed, in words, naming the step: "Paró en «…»: …". */
+  error: string | null;
+  /** A test: what would change the world was recorded, not done. */
+  dry: boolean;
+  started_at: string;
+  ended_at: string | null;
+  tokens_in: number;
+  tokens_out: number;
+  /** The conversations it opened. */
+  opened: string[];
+}
+
+/** One call of a run's record, in the order it was made. */
+export interface RunStep {
+  seq: number;
+  /** The `sc.step` it ran in. */
+  step: string | null;
+  /**
+   * `tool:<app>.<TOOL>` · `ai` · `notify` · `send` · `agent.start` · `data.find` · `data.add` ·
+   * `data.update` · `http` · `files.search` · `memory.remember` · `memory.recall`.
+   */
+  call: string;
+  /** Both trimmed. */
+  input: unknown;
+  output: unknown;
+  error: string | null;
+  ms: number;
+  at: string;
+  /** A test's write: recorded, not done. */
+  would: boolean;
+}
+
+/** A run with its record (`GET /runs/{id}`). */
+export type RunRecord = Run & { steps: RunStep[] };
+
+export type AutomationState = "active" | "paused" | "failing";
+
+/** One automation: `automations/<name>.py` in the agent's folder, with its trigger and its state. */
+export interface Automation {
+  /** Its trigger's id. */
+  id: string;
+  agent_id: string;
+  /** Its file's name; unique per agent. */
+  name: string;
+  title: string;
+  /** What it does, in the owner's words. */
+  summary: string;
+  trigger: Trigger;
+  on: boolean;
+  next_run_at: string | null;
+  steps: Step[];
+  board: Board | null;
+  /** `failing`: its last finished real run failed. */
+  state: AutomationState;
+  /** Its newest run, tests included. */
+  last_run: Run | null;
+}
+
+/** An automation with its newest runs (`GET /agents/{id}/automations/{name}`: 20; in a block: 5). */
+export type AutomationView = Automation & { runs: Run[] };
+
+/**
+ * A task the agent runs for one contact (`GET /agents/{id}/tasks`): set up in words in a
+ * conversation with them, read as an automation is (its instruction is its `summary`, its trigger
+ * a schedule: a cron line, or none for a task once at `next_run_at`), with its newest five runs.
+ */
+export type Task = AutomationView & {
+  contact_id: string;
+  /** The conversation it runs in: the one it was set up in. */
+  conversation_id: string | null;
+  created_at: string;
+};

package/src/automation/when.ts

@@ -0,0 +1,195 @@
+/**
+ * When an automation runs, and when one ran, as a person says it: its trigger in a sentence
+ * ("Cada día laborable a las 9:00"), its next run ("próxima mañana"), the moment a run started
+ * ("Ayer 16:12"), how long it took. The words are the host's (`AutomationMessages`); the locale's
+ * code writes the times, the days and the lists. Pure, so it is tested without a page.
+ */
+
+import { parseCron, type Cron } from "./cron";
+import type { AutomationMessages, DayRef } from "./messages";
+import type { Automation, Trigger } from "./types";
+
+/** A time of day as the locale writes it ("9:00", "9:00 AM"), from a cron line's hour and minute. */
+export function clockOf(hour: number, minute: number, code: string): string {
+  return new Intl.DateTimeFormat(code, {
+    hour: "numeric",
+    minute: "2-digit",
+    timeZone: "UTC",
+  }).format(new Date(Date.UTC(2026, 0, 1, hour, minute)));
+}
+
+/** A trigger in words, and whether it names the one time of day it runs (so the next needs none). */
+export interface When {
+  text: string;
+  timed: boolean;
+}
+
+/** A trigger in words: its schedule as a sentence, a webhook's call, an app's event. */
+export function whenOf(trigger: Trigger, words: AutomationMessages, code: string): When {
+  switch (trigger.kind) {
+    case "schedule":
+      return trigger.schedule === null
+        ? { text: words.custom, timed: false }
+        : scheduleOf(trigger.schedule, words, code);
+    case "webhook":
+      return { text: words.webhook, timed: false };
+    case "event":
+      return {
+        text: words.event(trigger.app_title ?? trigger.app, trigger.event_title),
+        timed: false,
+      };
+  }
+}
+
+const sorted = (values: ReadonlySet<number>): number[] => [...values].sort((a, b) => a - b);
+
+/** Whether the values are every `step`-th one from `from` up to `to`: 0, 15, 30, 45. */
+function stepOf(values: number[]): number | null {
+  if (values.length < 2) return null;
+  const step = (values[1] ?? 0) - (values[0] ?? 0);
+  return values.every((value, at) => value === (values[0] ?? 0) + at * step) ? step : null;
+}
+
+/** Monday first, as a week is read; Sunday is 0 in cron. */
+const weekOrder = (day: number) => (day + 6) % 7;
+
+function weekdayName(day: number, code: string): string {
+  // 4 January 2026 is a Sunday.
+  return new Intl.DateTimeFormat(code, { weekday: "long", timeZone: "UTC" }).format(
+    new Date(Date.UTC(2026, 0, 4 + day)),
+  );
+}
+
+/** The days a line runs on, in words; null for what a sentence can't say. */
+function daysOf(cron: Cron, words: AutomationMessages, code: string): string | null {
+  if (cron.months.size !== 12) return null;
+  if (cron.anyDay && cron.anyWeekday) return words.daily;
+  if (cron.anyDay) {
+    const days = [...cron.weekdays].sort((a, b) => weekOrder(a) - weekOrder(b));
+    const key = days.join(",");
+    if (days.length === 7) return words.daily;
+    if (key === "1,2,3,4,5") return words.weekdays;
+    if (key === "6,0") return words.weekends;
+    return words.weekly(days.map((day) => weekdayName(day, code)));
+  }
+  if (cron.anyWeekday) return words.monthly(sorted(cron.days));
+  return null;
+}
+
+/** At most this many times are listed one by one; more read as a frequency. */
+const LISTED = 4;
+
+/** The times a line runs at in a day: listed ("a las 9:00"), or how often ("cada hora"). */
+function timesOf(
+  cron: Cron,
+  words: AutomationMessages,
+  code: string,
+): { text: string; listed: number } | null {
+  const hours = sorted(cron.hours);
+  const minutes = sorted(cron.minutes);
+  const first = hours[0] ?? 0;
+  const last = hours[hours.length - 1] ?? 0;
+  if (hours.length * minutes.length <= LISTED) {
+    const times = hours.flatMap((hour) => minutes.map((minute) => clockOf(hour, minute, code)));
+    return { text: words.at(times), listed: times.length };
+  }
+  // Once in each of its hours, every few hours; or every few minutes through its hours.
+  const minuteStep = minutes.length === 60 ? 1 : stepOf(minutes);
+  const hourStep = hours.length === 24 || hours.length === 1 ? 1 : stepOf(hours);
+  let often: string;
+  if (minutes.length === 1 && hourStep !== null) {
+    often = words.every(hourStep, "hour");
+  } else if (minuteStep !== null && minutes[0] === 0 && 60 % minuteStep === 0 && hourStep === 1) {
+    often = words.every(minuteStep, "minute");
+  } else {
+    return null;
+  }
+  // The whole day ("cada 2 horas"), or a part of it ("cada hora de 8:00 a 18:00").
+  const whole = hourStep !== null && hours.length * hourStep === 24 && first < hourStep;
+  if (whole) return { text: often, listed: 0 };
+  const from = clockOf(first, minutes[0] ?? 0, code);
+  const to = clockOf(last, minutes[minutes.length - 1] ?? 0, code);
+  return { text: `${often} ${words.between(from, to)}`, listed: 0 };
+}
+
+/** A cron line as a sentence: its days, then its times or how often. */
+export function scheduleOf(line: string, words: AutomationMessages, code: string): When {
+  const cron = parseCron(line);
+  const days = cron && daysOf(cron, words, code);
+  const times = cron && timesOf(cron, words, code);
+  if (!days || !times) return { text: words.custom, timed: false };
+  if (times.listed > 0) return { text: `${days} ${times.text}`, timed: times.listed === 1 };
+  return { text: days === words.daily ? times.text : words.on(times.text, days), timed: false };
+}
+
+/** A calendar day where the person is, as a count of days from the epoch's. */
+const dayNumber = (moment: Date): number =>
+  Math.round(
+    (new Date(moment.getFullYear(), moment.getMonth(), moment.getDate()).getTime() -
+      new Date(1970, 0, 1).getTime()) /
+      86_400_000,
+  );
+
+/**
+ * A moment's day beside `now`, where the person is: today, yesterday, tomorrow, a weekday within
+ * the week, else its date (with its year when not this one).
+ */
+export function dayRefOf(
+  moment: Date,
+  now: Date,
+  code: string,
+  weekday: "short" | "long" = "short",
+): DayRef {
+  const days = dayNumber(moment) - dayNumber(now);
+  if (days === 0) return { kind: "today" };
+  if (days === -1) return { kind: "yesterday" };
+  if (days === 1) return { kind: "tomorrow" };
+  if (Math.abs(days) < 7) {
+    return { kind: "weekday", name: new Intl.DateTimeFormat(code, { weekday }).format(moment) };
+  }
+  return {
+    kind: "date",
+    name: new Intl.DateTimeFormat(code, {
+      day: "numeric",
+      month: "short",
+      ...(moment.getFullYear() === now.getFullYear() ? {} : { year: "numeric" }),
+    }).format(moment),
+  };
+}
+
+/** A moment's time of day where the person is: "9:00". */
+export const timeOf = (moment: Date, code: string): string =>
+  new Intl.DateTimeFormat(code, { hour: "numeric", minute: "2-digit" }).format(moment);
+
+/** When a run started: "Hoy 9:00", "Ayer 16:12", "Lun 9:00", "3 oct 9:00". */
+export function momentOf(at: Date, now: Date, words: AutomationMessages, code: string): string {
+  return words.moment(dayRefOf(at, now, code), timeOf(at, code));
+}
+
+/**
+ * The line under an automation's title: when it runs and, while it is on and has a next run,
+ * when that is ("Cada día laborable a las 9:00, próxima mañana"). The next run's time is said
+ * when the sentence doesn't already say it, and always when it is today.
+ */
+export function lineOf(
+  automation: Pick<Automation, "trigger" | "on" | "next_run_at">,
+  now: Date,
+  words: AutomationMessages,
+  code: string,
+): string {
+  const when = whenOf(automation.trigger, words, code);
+  if (!automation.on || automation.next_run_at === null) return when.text;
+  const next = new Date(automation.next_run_at);
+  const day = dayRefOf(next, now, code, "long");
+  const time = when.timed && day.kind !== "today" ? null : timeOf(next, code);
+  return `${when.text}, ${words.next(day, time)}`;
+}
+
+/** How long a run took, once it ended. */
+export function tookOf(
+  run: { started_at: string; ended_at: string | null },
+  words: AutomationMessages,
+): string | null {
+  if (run.ended_at === null) return null;
+  return words.took(Math.max(0, Date.parse(run.ended_at) - Date.parse(run.started_at)));
+}