@clemrig/flow-ui 0.5.0 → 0.6.0

package/dist/static/timeline.js

@@ -1,443 +0,0 @@
-// @ts-check
-/**
- * The dashboard's pure logic: a run's events grouped into one block per stage
- * execution, those blocks grouped into launches, and the formats of durations,
- * costs, tokens and agent settings. Served as is to the browser.
- */
-
-/** @typedef {import("@clemrig/flow").RunEvent} RunEvent */
-/** @typedef {import("@clemrig/flow").AgentActivity} AgentActivity */
-/** @typedef {import("@clemrig/flow").AgentSettings} AgentSettings */
-/** @typedef {import("@clemrig/flow").TokenCounts} TokenCounts */
-/** @typedef {import("@clemrig/flow").AgentUsage} AgentUsage */
-
-/**
- * @typedef {object} Call
- * @property {string} [runtime]
- * @property {string} [model]
- * @property {string} [session]
- * @property {AgentSettings} [settings] Absent from runs recorded before calls recorded their settings.
- * @property {"running" | "completed" | "failed"} status
- * @property {AgentUsage} [usage] As the runtime announced it at the end of the call.
- * @property {"call" | "session"} [scope] Whether `usage` is the call's own or its session's total.
- */
-
-/**
- * @typedef {object} Tool
- * @property {string} id
- * @property {string} name
- * @property {"running" | "completed" | "failed"} status
- * @property {number} [durationMs]
- */
-
-/**
- * @typedef {object} Block
- * @property {string} stage
- * @property {string} kind
- * @property {"running" | "passed" | "failed" | "completed"} status
- * @property {string} startedAt
- * @property {number | null} durationMs
- * @property {{ verdict: string; reason: string; destination: string | null }} [decision]
- * @property {{ key: string; count: number; max: number }} [retry]
- * @property {string} [detail]
- * @property {unknown} [output] What the stage's agent answered.
- * @property {unknown} [feedback] The correction the stage sent back, or could not send past its maximum.
- * @property {Call} [call]
- * @property {Tool[]} tools
- * @property {TokenCounts | null} tokens The call's responses so far.
- * @property {boolean} provisional Whether `tokens` includes figures replaced at the end of the call.
- * @property {string[]} warnings
- * @property {{ at: string; message: string }[]} journal
- */
-
-/**
- * @param {string} stage
- * @param {string} kind
- * @param {string} at
- * @returns {Block}
- */
-const block = (stage, kind, at) => ({
-  stage,
-  kind,
-  status: "running",
-  startedAt: at,
-  durationMs: null,
-  tools: [],
-  tokens: null,
-  provisional: false,
-  warnings: [],
-  journal: [],
-});
-
-/**
- * @param {Block} target
- * @param {AgentActivity} activity
- */
-function apply(target, activity) {
-  switch (activity.kind) {
-    case "call":
-      if (activity.status === "started") {
-        const { runtime, model, session, settings } = activity;
-        target.call = { runtime, model, session, settings, status: "running" };
-      } else
-        target.call = {
-          ...target.call,
-          runtime: activity.runtime,
-          status: activity.status,
-          usage: activity.usage,
-          scope: activity.scope,
-        };
-      break;
-    case "tool": {
-      const tool = target.tools.find(({ id }) => id === activity.id);
-      const update =
-        activity.status === "started"
-          ? { id: activity.id, name: activity.name, status: "running" }
-          : {
-              id: activity.id,
-              name: activity.name,
-              status: activity.status,
-              durationMs: activity.durationMs,
-            };
-      if (tool) Object.assign(tool, update);
-      else target.tools.push(/** @type {Tool} */ (update));
-      break;
-    }
-    case "response": {
-      const sum = target.tokens ?? {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheWrite: 0,
-      };
-      for (const field of /** @type {const} */ ([
-        "input",
-        "output",
-        "cacheRead",
-        "cacheWrite",
-      ]))
-        sum[field] += activity.tokens[field];
-      target.tokens = sum;
-      target.provisional ||= activity.provisional;
-      break;
-    }
-    case "warning":
-      target.warnings.push(activity.message);
-  }
-}
-
-/**
- * One block per stage execution, in order: a stage's journal, agent activity
- * and decision go to its latest block.
- * @param {RunEvent[]} events
- * @returns {Block[]}
- */
-export function timeline(events) {
-  /** @type {Block[]} */
-  const blocks = [];
-  const latest = (/** @type {string} */ stage) =>
-    blocks.findLast((candidate) => candidate.stage === stage);
-  for (const event of events) {
-    if (event.type === "stage" && event.status === "started") {
-      blocks.push(block(event.stage, event.kind, event.at));
-      continue;
-    }
-    let target = latest(event.stage);
-    if (!target || (event.type === "stage" && target.status !== "running")) {
-      // A stage reported without a start, such as one failed by an interruption.
-      target = block(event.stage, event.kind, event.at);
-      blocks.push(target);
-    }
-    if (event.type === "stage") {
-      target.status = event.status === "started" ? "running" : event.status;
-      target.durationMs = Date.parse(event.at) - Date.parse(target.startedAt);
-      if (event.decision) target.decision = event.decision;
-      if (event.retry) target.retry = event.retry;
-      if (event.detail) target.detail = event.detail;
-      if (Object.hasOwn(event, "output")) target.output = event.output;
-      if (event.feedback !== undefined) target.feedback = event.feedback;
-    } else if (event.type === "log")
-      target.journal.push({ at: event.at, message: event.message });
-    else apply(target, event.activity);
-  }
-  return blocks;
-}
-
-/**
- * A stage's answer or correction as text: a string as it is, anything else as
- * indented JSON.
- * @param {unknown} value
- * @returns {string}
- */
-export function outputText(value) {
-  return typeof value === "string" ? value : JSON.stringify(value, null, 2);
-}
-
-/**
- * @param {number | null} ms
- * @returns {string}
- */
-export function duration(ms) {
-  if (ms === null) return "—";
-  const seconds = Math.floor(ms / 1000);
-  const hours = Math.floor(seconds / 3600);
-  const minutes = Math.floor((seconds % 3600) / 60);
-  return `${hours ? `${hours} h ` : ""}${minutes} min ${seconds % 60} s`;
-}
-
-/**
- * A duration in its two largest units: `1 h 07 min`, `7 min 02 s`, `12 s`,
- * `< 1 s`.
- * @param {number | null} ms
- * @returns {string}
- */
-export function brief(ms) {
-  if (ms === null) return "—";
-  const seconds = Math.floor(ms / 1000);
-  if (seconds < 1) return "< 1 s";
-  const hours = Math.floor(seconds / 3600);
-  const minutes = Math.floor((seconds % 3600) / 60);
-  const pad = (/** @type {number} */ n) => String(n).padStart(2, "0");
-  if (hours) return `${hours} h ${pad(minutes)} min`;
-  if (minutes) return `${minutes} min ${pad(seconds % 60)} s`;
-  return `${seconds} s`;
-}
-
-/**
- * A token count: exact below ten thousand, then in thousands or millions.
- * @param {number} count
- * @returns {string}
- */
-export function tokenCount(count) {
-  if (count >= 1e6) return `${(count / 1e6).toFixed(1)} M`;
-  if (count >= 1e4) return `${Math.round(count / 1e3)} k`;
-  return count.toLocaleString("en-US");
-}
-
-/**
- * A call's tokens: read without the cache, written, read from and written to
- * the cache; provisional figures, which the call's end replaces, say so.
- * @param {TokenCounts} tokens
- * @param {boolean} provisional
- * @returns {string}
- */
-export function tokenLine(tokens, provisional) {
-  const { input, output, cacheRead, cacheWrite } = tokens;
-  return `${tokenCount(input)} in · ${tokenCount(output)} out · ${tokenCount(cacheRead)} cache read · ${tokenCount(cacheWrite)} cache write${provisional ? " (provisional)" : ""}`;
-}
-
-/** Setting names that are not plain words. */
-const settingLabels = /** @type {Record<string, string>} */ ({
-  mcpServers: "MCP servers",
-});
-
-/**
- * A setting's name as the operator reads it: `permissionMode` → `permission mode`.
- * @param {string} key
- * @returns {string}
- */
-function settingLabel(key) {
-  return (
-    settingLabels[key] ??
-    key.replace(/[A-Z]/g, (letter) => ` ${letter.toLowerCase()}`)
-  );
-}
-
-/**
- * An agent call's settings as its runtime recorded them, whatever the runtime,
- * as labelled rows: its thinking, other single values and timeout in one, then
- * one per list, its tools even when empty, the others only with items.
- * @param {AgentSettings} settings
- * @returns {{ label: string; value: string }[]}
- */
-export function settingRows(settings) {
-  const entries = Object.entries(settings);
-  const values = entries.flatMap(([key, value]) =>
-    key === "thinking" ||
-    key === "timeoutMs" ||
-    value === undefined ||
-    Array.isArray(value)
-      ? []
-      : [`${settingLabel(key)} ${String(value)}`],
-  );
-  const lists = entries.flatMap(([key, value]) => {
-    if (!Array.isArray(value) || (!value.length && key !== "tools")) return [];
-    const label = key === "tools" ? "allowed tools" : settingLabel(key);
-    return [
-      {
-        label: `${label[0]?.toUpperCase()}${label.slice(1)}`,
-        value: value.join(", ") || "none",
-      },
-    ];
-  });
-  return [
-    {
-      label: "Settings",
-      value: [
-        `thinking ${settings.thinking}`,
-        ...values,
-        `timeout ${brief(settings.timeoutMs)}`,
-      ].join(" · "),
-    },
-    ...lists,
-  ];
-}
-
-/**
- * An estimated cost as the runtimes announced it; unknown without any measure.
- * @param {number | null} usd
- * @param {boolean} partial Some agent call announced no cost.
- * @returns {string}
- */
-export function cost(usd, partial) {
-  const value = usd === null ? "—" : `${usd.toFixed(4)} USD`;
-  return partial ? `${value} (partial)` : value;
-}
-
-/**
- * An estimated cost as the Kanban shows it: in dollars, `≥` while some call
- * announced none, a dash while none announced any.
- * @param {number | null} usd
- * @param {boolean} partial
- * @returns {string}
- */
-export function dollars(usd, partial) {
-  if (usd === null) return "—";
-  return `${partial ? "≥ " : ""}$${usd.toFixed(2)}`;
-}
-
-/** @typedef {"passed" | "correction" | "failed" | "running"} State */
-
-/**
- * How a stage execution went: running, failed, sent back for a correction, or
- * passed (the run's last stage included).
- * @param {Block} block
- * @returns {State}
- */
-export function stateOf(block) {
-  if (block.status === "running" || block.status === "failed")
-    return block.status;
-  return block.decision?.verdict === "correction" ? "correction" : "passed";
-}
-
-/**
- * A stage execution's time so far: its duration once ended.
- * @param {Block} block
- * @param {number} now
- * @returns {number}
- */
-export function spent(block, now) {
-  return block.durationMs ?? Math.max(0, now - Date.parse(block.startedAt));
-}
-
-/**
- * @typedef {object} Launch
- * @property {number} number From 1: the run's first execution, then each resumption.
- * @property {string} startedAt
- * @property {string | null} endedAt Null while it runs.
- * @property {"running" | "failed" | "completed"} status
- * @property {string} [cause] Why a failed launch stopped.
- * @property {{ block: Block; index: number }[]} stages Its stage executions, with their index in the run.
- */
-
-/**
- * The stage execution to show until the operator chooses one: the last, which
- * is the one running or the one where the run stopped, never an earlier
- * launch's failure once the run was resumed.
- * @param {Block[]} blocks
- * @returns {number | null}
- */
-export function shownStage(blocks) {
-  return blocks.length ? blocks.length - 1 : null;
-}
-
-/**
- * The run's launches: its first execution, then one per resumption. A failed
- * stage ends a launch, since it ends the run, and only a failed run is
- * resumed: the next stage starts the following launch. A failure reported
- * once the run completed, when its completed state could not be saved,
- * ends the same launch.
- * @param {Block[]} blocks
- * @returns {Launch[]}
- */
-export function launches(blocks) {
-  /** @type {Launch[]} */
-  const found = [];
-  blocks.forEach((block, index) => {
-    let current = found.at(-1);
-    if (!current || current.status === "failed") {
-      current = {
-        number: found.length + 1,
-        startedAt: block.startedAt,
-        endedAt: null,
-        status: "running",
-        stages: [],
-      };
-      found.push(current);
-    }
-    current.stages.push({ block, index });
-    if (block.status === "failed" || block.status === "completed") {
-      current.status = block.status;
-      current.endedAt =
-        block.durationMs === null
-          ? block.startedAt
-          : new Date(
-              Date.parse(block.startedAt) + block.durationMs,
-            ).toISOString();
-      if (block.detail) current.cause = block.detail;
-    }
-  });
-  return found;
-}
-
-/**
- * What a stage execution did, in one line: its failure, its agent's model,
- * tools and cost, its decision, or its last journal message.
- * @param {Block} block
- * @returns {string}
- */
-export function summary(block) {
-  if (block.status === "failed" && block.detail) return block.detail;
-  if (block.call?.model) {
-    const tools = `${block.tools.length} tool${block.tools.length === 1 ? "" : "s"}`;
-    const usd = block.call.usage?.costUsd;
-    return [
-      block.call.model,
-      tools,
-      ...(usd === undefined ? [] : [dollars(usd, false)]),
-    ].join(" · ");
-  }
-  if (block.decision) {
-    const { verdict, reason, destination } = block.decision;
-    return verdict === "correction"
-      ? `back to ${destination}: ${reason.split("\n")[0]}`
-      : `accepted → ${destination ?? "end"}`;
-  }
-  return block.journal.at(-1)?.message ?? "";
-}
-
-/**
- * The tools a stage execution used, by name, the most used first: how many
- * calls, how long in all and how many failed.
- * @param {Tool[]} tools
- * @returns {{ name: string; count: number; durationMs: number; failed: number }[]}
- */
-export function toolUse(tools) {
-  /** @type {Map<string, { name: string; count: number; durationMs: number; failed: number }>} */
-  const byName = new Map();
-  for (const tool of tools) {
-    const entry = byName.get(tool.name) ?? {
-      name: tool.name,
-      count: 0,
-      durationMs: 0,
-      failed: 0,
-    };
-    entry.count++;
-    entry.durationMs += tool.durationMs ?? 0;
-    if (tool.status === "failed") entry.failed++;
-    byName.set(tool.name, entry);
-  }
-  return [...byName.values()].sort(
-    (a, b) => b.count - a.count || a.name.localeCompare(b.name),
-  );
-}