@anchrd/intel-ui 0.13.0 → 0.15.0

package/src/agent/agent-profile/agent-profile.tsx

@@ -1,14 +1,34 @@
 import {
+  type AgentCosts,
+  type AgentCostWindow,
   type AgentDefinition,
   type AgentReference,
+  AgentReferenceKinds,
   AgentReferenceRole,
   type AgentSchedule,
+  agentReferenceRolesFor,
   type Node,
+  type NodeKind,
 } from "@anchrd/intel-contract";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { Check, Copy, Info, KeyRound, MessageSquare, Plus, Trash2, Wrench } from "lucide-react";
+import {
+  Bot,
+  Check,
+  Copy,
+  FileText,
+  Folder,
+  KeyRound,
+  MessageSquare,
+  Paperclip,
+  Plus,
+  Table2,
+  Trash2,
+  Wrench,
+} from "lucide-react";
 import { useState } from "react";
+import { costWindow, formatCost, useAgentCosts } from "@/agent/agent-costs/agent-costs.ts";
 import { type AgentDefinitionHandle, asDraft } from "@/agent/agent-definition/agent-definition.ts";
+import { delegationNotice } from "@/agent/agent-delegation-notice/agent-delegation-notice.ts";
 import { useEntryTitle } from "@/agent/agent-entry-title/agent-entry-title.ts";
 import {
   formatContextTokens,
@@ -29,11 +49,14 @@ import {
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
 import { agentMcpAddress } from "@/data/agent-runtime/agent-runtime.ts";
 import { EntryPicker, type PickerKind } from "@/entry-picker/entry-picker.tsx";
+import { useModelCatalog } from "@/hooks/use-model-catalog.ts";
 import { useI18n } from "@/i18n/i18n-context.tsx";
 import { Modal } from "@/modal/modal.tsx";
 import { useIntelRouterContext } from "@/router/router-context.ts";
-import { availableTimezones } from "@/timezone/timezone.ts";
+import { SectionHint } from "@/section-hint/section-hint.tsx";
+import { TimezoneCombobox } from "@/timezone/timezone-combobox/timezone-combobox.tsx";
 import { useTimezone } from "@/timezone/timezone-context.tsx";
+import { useSessionUser, useUserName } from "@/user-name/user-name.ts";
 
 // No dividers between sections — the space is the separation (#204). The explanation sits behind
 // the icon rather than under the title, so the page shows what the agent IS and keeps the prose
@@ -58,26 +81,6 @@ function Section({
   );
 }
 
-// ⚠️ The hint is the trigger's accessible name, not only the tooltip's content: Radix describes the
-// trigger by the content only while it is open, and a listener who tabs past a nameless icon button
-// would never learn there is anything behind it.
-function SectionHint({ hint }: { hint: string }) {
-  return (
-    <TooltipProvider delayDuration={300}>
-      <Tooltip>
-        <TooltipTrigger
-          type="button"
-          aria-label={hint}
-          className="rounded-full text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
-        >
-          <Info aria-hidden="true" className="size-3.5" />
-        </TooltipTrigger>
-        <TooltipContent className="max-w-xs">{hint}</TooltipContent>
-      </Tooltip>
-    </TooltipProvider>
-  );
-}
-
 /**
  * Everything an agent is, on one page: how to reach it, what it reads, what it may call, when it
  * acts on its own, which model does the thinking, and who it is in Gate.
@@ -131,7 +134,7 @@ export function AgentProfile({ node, agent }: { node: Node; agent: AgentDefiniti
       <KnowledgeSection definition={definition} agent={agent} />
       <ToolsSection definition={definition} agent={agent} />
       <ScheduleSection definition={definition} agent={agent} />
-      <ModelSection definition={definition} agent={agent} />
+      <ModelSection definition={definition} agent={agent} agentId={node.id} />
       <IdentitySection node={node} agent={agent} />
     </div>
   );
@@ -310,6 +313,24 @@ function ContactSection({ node }: { node: Node }) {
   );
 }
 
+// Everything any role accepts, which is what the picker may offer. Derived from the contract's one
+// table rather than written out again — a second list here would drift.
+const pickableKinds: NodeKind[] = [
+  ...new Set(Object.values(AgentReferenceKinds).flat()),
+] as NodeKind[];
+
+/**
+ * The role a freshly picked entry starts as — the widest thing that kind can honestly be.
+ *
+ * A folder starts as search space, the way it always has; a document or a table starts as the
+ * system message, which is the only role that reads a single node at all. `null` for a flow and for
+ * a kind no role accepts, and the caller then adds nothing rather than inventing a role.
+ */
+function defaultRoleFor(kind: PickerKind): AgentReferenceRole | null {
+  if (kind === "flow") return null;
+  return kind === "folder" ? "semantic-context" : (agentReferenceRolesFor(kind)[0] ?? null);
+}
+
 /**
  * What the agent reads, and in which capacity.
  *
@@ -317,6 +338,10 @@ function ContactSection({ node }: { node: Node }) {
  * explicitly, and the reason is that the three roles do very different things — a folder read as
  * the system message becomes instructions, one read as memory is written back to. Something that
  * changes what a document MEANS to an agent must look changeable.
+ *
+ * ⚠️ Since #255 a row can also be a single document or table, and the role select shows only the
+ * roles that kind can carry. `memory` and `semantic-context` stay folders — the agent WRITES into
+ * one and SEARCHES the other — so a document simply never offers them.
  */
 function KnowledgeSection({
   definition,
@@ -370,12 +395,20 @@ function KnowledgeSection({
       </button>
       {adding ? (
         <Modal title={i18n.t("agent.addReference")} close={() => setAdding(false)}>
+          {/* ⚠️ The picker offers the UNION of what any role accepts, and the row's role select
+              then offers only the roles that accept what was picked (#255). The rule is asked in
+              this direction because the thing is chosen first: a role chosen up front would mean a
+              second dialog before the picker, and a picker that let anything be chosen and refused
+              afterwards is worse than one that never offered it. Either way no illegal pair is
+              reachable — `agentReferenceKinds` is the one list both sides read. */}
           <EntryPicker
-            kind="folder"
+            kind={pickableKinds}
             value=""
-            label={i18n.t("agent.pickFolder")}
-            onSelect={(nodeId) => {
-              write([...definition.references, { nodeId, role: "semantic-context" }]);
+            label={i18n.t("agent.pickEntry")}
+            onSelect={(nodeId, entryKind) => {
+              const role = defaultRoleFor(entryKind);
+              if (role === null) return;
+              write([...definition.references, { nodeId, role }]);
               setAdding(false);
             }}
           />
@@ -385,13 +418,31 @@ function KnowledgeSection({
   );
 }
 
+// What each kind looks like at a glance. An `attachment` and an `agent` cannot be picked, but an
+// older definition may still name one, so every kind has a mark rather than a fallback that would
+// draw two different things the same way.
+const KindIcon: Record<NodeKind, typeof Folder> = {
+  folder: Folder,
+  document: FileText,
+  table: Table2,
+  attachment: Paperclip,
+  agent: Bot,
+};
+
 /**
- * One folder the agent reads, and what it counts as.
+ * One thing the agent reads, where it sits, and what it counts as.
+ *
+ * ⚠️ Its own component so the select can be NAMED after the entry. Three rows carrying the same
+ * "What this counts as" are three identical controls to anybody listening rather than looking — the
+ * name is beside them on screen, and the screen is exactly what that reader does not have. It needs
+ * the resolved title, which is why the lookup is a hook rather than a component here.
+ *
+ * ⚠️ The path is not decoration (#255). Two folders called `Notes` in different corners of the tree
+ * were indistinguishable here, and this is the screen on which somebody decides what an agent may
+ * read and write into.
  *
- * ⚠️ Its own component so the select can be NAMED after the folder. Three rows carrying the same
- * "What this folder counts as" are three identical controls to anybody listening rather than
- * looking — the name is beside them on screen, and the screen is exactly what that reader does not
- * have. It needs the resolved title, which is why the lookup is a hook rather than a component here.
+ * ⚠️ The kind is a symbol AND a word. The symbol is for the eye and the `sr-only` word is for
+ * everyone else — an icon with no text is a row that says "Notes" three times to a screen reader.
  */
 function ReferenceRow({
   reference,
@@ -403,11 +454,31 @@ function ReferenceRow({
   remove(): void;
 }) {
   const i18n = useI18n();
-  const { title, known } = useEntryTitle(reference.nodeId);
+  const { title, known, kind, path } = useEntryTitle(reference.nodeId);
+  const Icon = kind === null ? null : KindIcon[kind];
+  // ⚠️ Only the roles this kind can carry, so an impossible pair is never offered — and the current
+  // role is kept in the list whatever it is, or an older definition would open on an empty select
+  // and the first touch of the control would silently change what the agent does.
+  const roles = [
+    ...new Set([
+      ...(kind === null ? AgentReferenceRole.options : agentReferenceRolesFor(kind)),
+      reference.role,
+    ]),
+  ];
+
   return (
     <li className="flex flex-wrap items-center gap-3 rounded-lg border bg-card px-4 py-3">
-      <span className={`min-w-0 flex-1 truncate text-sm${known ? "" : " text-muted-foreground"}`}>
-        {title}
+      {Icon ? <Icon aria-hidden="true" className="size-4 shrink-0 text-muted-foreground" /> : null}
+      <span className={`min-w-0 flex-1${known ? "" : " text-muted-foreground"}`}>
+        <span className="block truncate text-sm">
+          {title}
+          {kind === null ? null : <span className="sr-only"> — {i18n.t(`node.kind.${kind}`)}</span>}
+        </span>
+        {path.length > 0 ? (
+          <span className="block truncate text-xs text-muted-foreground" title={path.join(" / ")}>
+            {path.join(" / ")}
+          </span>
+        ) : null}
       </span>
       <Select
         value={reference.role}
@@ -420,7 +491,7 @@ function ReferenceRow({
           <SelectValue />
         </SelectTrigger>
         <SelectContent>
-          {AgentReferenceRole.options.map((role) => (
+          {roles.map((role) => (
             <SelectItem key={role} value={role}>
               {i18n.t(`agent.role.${role}`)}
             </SelectItem>
@@ -459,9 +530,10 @@ function EntryTitle({ entryId, flow = false }: { entryId: string; flow?: boolean
  *
  * ⚠️ The notice is not decoration, and it stands whether or not anything is listed yet. A shared
  * agent runs on the DELEGATOR's connection whoever starts it, which is a real widening of who can
- * act as this person — so it belongs where somebody reads it BEFORE clicking `+ Add tool`, not as a
- * footnote that appears once the first server is already given away. The empty list itself stays
- * wordless, the way the other sections' do (#204): the button says what belongs here.
+ * act as this person. It is no longer a paragraph under the list (#254) — it said the same thing on
+ * every visit at the place where somebody was doing something else — but it is not gone either: it
+ * is the second half of this section's own hint, so it is in the trigger's accessible name and a
+ * keyboard reaches it, and it still stands in the picker where the delegation actually happens.
  */
 function ToolsSection({
   definition,
@@ -472,6 +544,9 @@ function ToolsSection({
 }) {
   const { data } = useIntelRouterContext();
   const i18n = useI18n();
+  const me = useSessionUser();
+  const delegatedBy = definition.tools?.delegatedBy ?? null;
+  const delegatorName = useUserName(delegatedBy);
   const [adding, setAdding] = useState(false);
   const servers = useQuery({ queryKey: ["tool-servers"], queryFn: () => data.listToolServers() });
   const selected = definition.tools?.servers ?? [];
@@ -488,8 +563,17 @@ function ToolsSection({
     (server) => !selected.includes(server.handle),
   );
 
+  // Two whole sentences joined, never one sentence built from two fragments: each stays its own
+  // catalog entry and each translates on its own. What the join fixes is only their order.
+  const notice = delegationNotice(i18n, {
+    delegatedBy,
+    viewerId: me?.id ?? null,
+    delegatorName,
+  });
+  const hint = `${i18n.t("agent.toolsHint")} ${notice}`;
+
   return (
-    <Section title={i18n.t("agent.tools")} hint={i18n.t("agent.toolsHint")}>
+    <Section title={i18n.t("agent.tools")} hint={hint}>
       {selected.length === 0 ? null : (
         <ul className="space-y-2">
           {selected.map((handle) => {
@@ -534,7 +618,6 @@ function ToolsSection({
         <Plus aria-hidden="true" className="size-4" />
         {i18n.t("agent.addTool")}
       </button>
-      <p className="mt-3 text-xs text-muted-foreground">{i18n.t("agent.toolsDelegationNotice")}</p>
       {adding ? (
         <Modal title={i18n.t("agent.addTool")} close={() => setAdding(false)}>
           {servers.isPending ? (
@@ -569,9 +652,10 @@ function ToolsSection({
               ))}
             </ul>
           )}
-          <p className="mt-4 text-xs text-muted-foreground">
-            {i18n.t("agent.toolsDelegationNotice")}
-          </p>
+          {/* ⚠️ Here it stays a visible paragraph, unlike the section's own (#254). This is the
+              moment the delegation is actually made, and a consequence that is only reachable by
+              hovering an icon somewhere behind the dialog is a consequence nobody reads. */}
+          <p className="mt-4 text-xs text-muted-foreground">{notice}</p>
         </Modal>
       ) : null}
     </Section>
@@ -660,8 +744,6 @@ function ScheduleDialog({ close, add }: { close(): void; add(schedule: AgentSche
   // means the same hour to everybody else reading the agent.
   const preferred = useTimezone();
   const [timezone, setTimezone] = useState(preferred);
-  const zones = availableTimezones();
-  const options = zones.includes(timezone) ? zones : [timezone, ...zones];
   const [target, setTarget] = useState<{ id: string; kind: "document" | "flow" } | null>(null);
 
   return (
@@ -689,23 +771,24 @@ function ScheduleDialog({ close, add }: { close(): void; add(schedule: AgentSche
             {i18n.t("agent.cronHint")}
           </span>
         </label>
-        <label className="block text-sm font-medium" htmlFor="agent-schedule-timezone">
-          {i18n.t("agent.scheduleTimezone")}
-        </label>
-        <select
+        {/* ⚠️ The hint is behind the ⓘ (#249) and ALSO `sr-only` below. The two are not a
+            duplicate: the tooltip's content is in the accessibility tree only while it is open, so
+            the field would lose the description `aria-describedby` promises the moment the sentence
+            became a hover. Route (1) of the ticket, and the cheaper of the two — nothing has to be
+            argued about a description that is simply still there. */}
+        <div className="flex items-center gap-1.5">
+          <label className="block text-sm font-medium" htmlFor="agent-schedule-timezone">
+            {i18n.t("agent.scheduleTimezone")}
+          </label>
+          <SectionHint hint={i18n.t("agent.scheduleTimezoneHint")} />
+        </div>
+        <TimezoneCombobox
           id="agent-schedule-timezone"
           value={timezone}
-          onChange={(event) => setTimezone(event.target.value)}
-          aria-describedby="agent-timezone-hint"
-          className="-mt-2 w-full rounded-md border bg-background px-3 py-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
-        >
-          {options.map((zone) => (
-            <option key={zone} value={zone}>
-              {zone.replace(/_/g, " ")}
-            </option>
-          ))}
-        </select>
-        <span id="agent-timezone-hint" className="-mt-2 block text-xs text-muted-foreground">
+          onChange={setTimezone}
+          describedBy="agent-timezone-hint"
+        />
+        <span id="agent-timezone-hint" className="sr-only">
           {i18n.t("agent.scheduleTimezoneHint")}
         </span>
         <EntryPicker
@@ -730,18 +813,39 @@ function ScheduleDialog({ close, add }: { close(): void; add(schedule: AgentSche
   );
 }
 
-// Which model does the thinking. Changing it writes a new definition version like every other edit
-// here — the runtime picks the provider up on its next read (its definition cache is 60 seconds).
+/**
+ * Which model does the thinking, what it costs per million tokens — and what this agent has
+ * actually cost with it.
+ *
+ * ⚠️ Changing it writes a new definition version like every other edit here; the runtime picks the
+ * provider up on its next read (its definition cache is 60 seconds).
+ *
+ * ⚠️ The figures come from intel's catalog since #257 and no longer from a table in this bundle.
+ * The table was a copy that aged silently, and the reason it stayed one — "a token does not belong
+ * in a SPA" — was correct and is exactly why the fetch moved to intel rather than into this
+ * component.
+ *
+ * ⚠️ The two numbers beside each other are a price and a bill, and they must not read as one thing.
+ * A price per million tokens answers "what does this model cost"; the thirty-day figure answers
+ * "what has this agent cost", it is money already spent on runs that used whatever model was chosen
+ * AT THE TIME, and the sentence under it says so. Without that, switching the model would make the
+ * old figure read as a forecast for the new one.
+ */
 function ModelSection({
   definition,
   agent,
+  agentId,
 }: {
   definition: AgentDefinition;
   agent: AgentDefinitionHandle;
+  agentId: string;
 }) {
   const i18n = useI18n();
+  const catalog = useModelCatalog();
+  const costs = useAgentCosts(agentId);
   const models = selectableModels(definition.model);
-  const current = modelFacts(definition.model);
+  const current = modelFacts(definition.model, catalog.data?.entries);
+  const spent = costWindow(costs.data, 30);
 
   return (
     <Section title={i18n.t("agent.model")} hint={i18n.t("agent.modelHint")}>
@@ -762,7 +866,7 @@ function ModelSection({
           </SelectTrigger>
           <SelectContent>
             {models.map((model) => {
-              const facts = modelFacts(model);
+              const facts = modelFacts(model, catalog.data?.entries);
               return (
                 <SelectItem key={modelKey(model)} value={modelKey(model)}>
                   {/* ⚠️ The space is not formatting. The option's accessible name is its text run
@@ -776,10 +880,79 @@ function ModelSection({
         </Select>
         <ModelFigures facts={current} />
       </div>
+      {/* ⚠️ Said once, under the row, and only when something on screen actually came off the
+          table. A silent fallback to typed-out prices is the state this feature replaced. */}
+      {current.stale ? (
+        <p className="mt-2 text-xs text-muted-foreground">{i18n.t("agent.modelFiguresStale")}</p>
+      ) : null}
+      <AgentSpend
+        spent={spent}
+        status={costs.data?.status}
+        partial={costs.data?.partial ?? false}
+      />
     </Section>
   );
 }
 
+/**
+ * What this agent has actually cost in the last thirty days (#257).
+ *
+ * ⚠️ Written in the past tense and labelled with the models that produced it, because it is the
+ * only thing standing between "$0.23" and a reader taking it for what the model above will cost.
+ * The models are named from the gateway's own log lines, so a period spent on a different model
+ * says so by itself.
+ *
+ * ⚠️ Nothing is rendered where the figure is not known. The Runs tab is where the reason belongs —
+ * it is the screen about runs — and repeating "no read token" beside a model select would be an
+ * error message in the middle of an unrelated decision.
+ *
+ * ⚠️ `partial` is the one exception to that division, and it has to be repeated here. It does not
+ * say the figure is missing — it says the figure shown IS NOT THE TOTAL, because the gateway read
+ * stopped at its page limit. A lower bound printed as if it were a sum is the same lie as a zero
+ * printed as if it were free, and this is where somebody reads it while deciding what to spend.
+ * An agent on a frequent schedule crosses that limit within thirty days as a matter of course; the
+ * seven-day figure practically never does, which makes the case rarer and therefore easier to miss.
+ */
+function AgentSpend({
+  spent,
+  status,
+  partial,
+}: {
+  spent: AgentCostWindow | null;
+  status: AgentCosts["status"] | undefined;
+  partial: boolean;
+}) {
+  const i18n = useI18n();
+  if (status !== "read" || !spent) return null;
+
+  return (
+    <p className="mt-3 text-sm">
+      <span className="font-medium">
+        {i18n.t("agent.costsSpent", {
+          amount: formatCost(spent.cost, i18n.locale),
+          days: String(spent.days),
+        })}
+      </span>
+      {spent.models.length > 0 ? (
+        <span className="text-muted-foreground">
+          {" "}
+          {i18n.t("agent.costsSpentWith", { models: spent.models.join(", ") })}
+        </span>
+      ) : null}
+      <span className="mt-0.5 block text-xs text-muted-foreground">
+        {i18n.t("agent.costsSpentPast")}
+      </span>
+      {/* The Runs tab's own wording, deliberately the same key: two different sentences for one
+          fact would leave a reader wondering whether they are the same fact. */}
+      {partial ? (
+        <span className="mt-0.5 block text-xs text-muted-foreground">
+          {i18n.t("agent.costPartial")}
+        </span>
+      ) : null}
+    </p>
+  );
+}
+
 // Brand first, then the model's own name — "Claude Sonnet 5", not "claude-sonnet-5 · anthropic". The
 // provider stays in the definition; it names who serves the model, which is not what anybody reads a
 // list of models for.

package/src/agent/agent-state/agent-state.ts

@@ -60,6 +60,23 @@ export function agentRuntimeMissing(error: unknown): boolean {
  * deployment's master secret was replaced — but the reader's move is identical, and a second
  * sentence saying the same thing differently would only be a second thing to keep in step.
  */
+/**
+ * The refusal in the words the refusal itself used (#201).
+ *
+ * ⚠️ Only for an answer that carried a problem document — `code` is what proves it did. Everything
+ * else that reaches here is a timeout, a proxy page or a parse failure, whose `message` is
+ * `Intel responded with 502`: true, and no help to anybody. Those keep the generic sentence.
+ *
+ * The reason has to reach the screen because `Resume` can fail for reasons only the runtime knows —
+ * "none of this agent's schedules has a next fire time" is one, and it is not something a reader
+ * can guess from `That did not work. Try again.` The runtime words its problems to be read (see
+ * `packages/agent`'s guard on model-facing errors), and the log tab already shows a run's failure
+ * verbatim for the same reason.
+ */
+export function agentProblemDetail(error: unknown): string | null {
+  return error instanceof IntelRequestError && error.code !== null ? error.message : null;
+}
+
 export function agentKeyMissing(error: unknown): boolean {
   return (
     error instanceof IntelRequestError &&

package/src/agent/agent-status-dot/agent-status-dot.ts

@@ -0,0 +1,73 @@
+import type { AgentRun } from "@/data/agent-runtime/agent-runtime.ts";
+
+/**
+ * The five things an agent's head can have to say. There is deliberately no "idle": the absence of
+ * a state is not a state, and writing it out at the most prominent place on the page was what #253
+ * removed.
+ */
+export type AgentStatusKind = "unknown" | "paused" | "running" | "failed" | "waiting";
+
+export interface AgentStatusReading {
+  kind: AgentStatusKind;
+  /** When the newest finished run ended — `null` while the agent has never finished one. */
+  lastRunAt: string | null;
+}
+
+export interface AgentStatusInput {
+  /** The run list could not be read. NOT the same as "no runs". */
+  runsUnreadable: boolean;
+  /** Newest first, the way the runtime answers. */
+  runs: AgentRun[];
+  paused: boolean;
+  /** Whether any schedule will fire — derived from the cron expressions, never asked. */
+  scheduled: boolean;
+}
+
+/**
+ * What the head says about this agent, or `null` when it has nothing to say (#253).
+ *
+ * ⚠️ `null` is the ordinary case and the whole point of the ticket: an agent with no schedule, no
+ * run in flight and no failure behind it is not "Idle · no scheduled run", it is a name. Two
+ * sentences spelling out the same absence stood at the most prominent place on the page.
+ *
+ * ⚠️ It is NOT simply "has a schedule". An agent somebody drives from the chat can be running, can
+ * be switched off, and can have failed its last run without ever carrying a schedule — hiding any
+ * of those would trade two useless sentences for one missing fact. What disappears is the absence,
+ * not the presence.
+ *
+ * ⚠️ An unreadable run list outranks everything and is its own state. A runtime that cannot be
+ * reached says nothing about what the agent is doing, and reporting "waiting" for it would be wrong
+ * exactly when something is wrong.
+ *
+ * ⚠️ Paused outranks running, the way the status line has always read it: a run still finishing
+ * while the agent is switched off does not make the agent switched on, and the reader's next
+ * question is why nothing starts afterwards.
+ */
+export function agentStatus(input: AgentStatusInput): AgentStatusReading | null {
+  const finished = input.runs.find((run) => run.status !== "running") ?? null;
+  const lastRunAt = finished?.finishedAt ?? finished?.startedAt ?? null;
+
+  if (input.runsUnreadable) return { kind: "unknown", lastRunAt: null };
+  if (input.paused) return { kind: "paused", lastRunAt };
+  if (input.runs.some((run) => run.status === "running")) return { kind: "running", lastRunAt };
+  if (finished?.status === "failed") return { kind: "failed", lastRunAt };
+  if (input.scheduled) return { kind: "waiting", lastRunAt };
+  return null;
+}
+
+/**
+ * How each state is drawn.
+ *
+ * ⚠️ Shape carries what colour cannot. This theme is monochrome apart from `destructive` (see
+ * `styles.css`), so five states cannot be five hues without inventing colours the customer's own
+ * theme would then fight — and colour alone is no information for a reader who cannot separate two
+ * greys. Filled, hollow, dashed and moving are told apart without any hue at all, and the state is
+ * in the trigger's accessible name regardless.
+ */
+export const statusDotClass: Record<AgentStatusKind, string> = {
+  unknown: "border border-dashed border-muted-foreground",
+  paused: "bg-muted-foreground",
+  running: "bg-primary motion-safe:animate-pulse",
+  failed: "bg-destructive",
+  waiting: "border border-muted-foreground",
+};