@spunto/design-system 0.27.0 → 0.30.0

package/src/components/tasks/types.ts

@@ -0,0 +1,220 @@
+// Structural shapes for everything task-related — delegated work (docs/tasks.md), its session
+// (RFC 0020) and its files (RFC 0022).
+//
+// Same rule as `../workers/types.ts`: the package never imports an app's OpenAPI types. These
+// describe the minimum the components read. Where the dashboard's API is the only producer today
+// the shape follows it closely, but every component tolerates a value it doesn't know — an
+// unknown state falls back to a neutral style, an unknown event type to a boundary line — rather
+// than crashing on a payload a newer API sends.
+
+/** The five states a task goes through. Derived at read time by the API, never polled into place. */
+export type TaskState = "queued" | "running" | "in-review" | "done" | "failed"
+
+/**
+ * What the platform is doing to a task *right now*, on a human's behalf.
+ *
+ * Accepting, dropping and answering are `202`s that finish in a durable job minutes later, so a
+ * task can be `in-review` and *being accepted* at the same time — and the second fact is the one
+ * the reader who just clicked is looking for.
+ */
+export type TaskPendingAction = "accepting" | "dropping" | "replying"
+
+/** A task as the list rows, the cockpit and its sidebar draw it. */
+export interface TaskItem {
+  id: string
+  title: string
+  prompt?: string | null
+  state: TaskState
+  branch?: string | null
+  baseBranch?: string | null
+  workerId?: string | null
+  /** Where the work landed — a PR, an MR, a preview deployment. Not forge-specific. */
+  outcomeUrl?: string | null
+  outcomeLabel?: string | null
+  /** Legacy: what a removed status command once reported. Drawn as JSON when present. */
+  meta?: Record<string, unknown> | null
+  error?: string | null
+  createdAt: string
+  /** When the task last moved — a turn, a state change. What lists sort and date rows on. */
+  lastActivityAt?: string | null
+  startedAt?: string | null
+  completedAt?: string | null
+  /** Whether a follow-up can resume the session — a captured `session.started` gave an id. */
+  canResume?: boolean
+  pendingAction?: TaskPendingAction | null
+  /** When that was asked for. What the spinner counts from — across reloads and readers. */
+  pendingSince?: string | null
+}
+
+/** A row of the org-wide conversation list: a task plus the project it belongs to. */
+export interface TaskConversation extends TaskItem {
+  projectId: string
+  projectName?: string | null
+}
+
+/** One normalized event of a session (`task_events`). `payload` is read laxly by type. */
+export interface TaskEvent {
+  seq: number
+  ts: string
+  /** `message` | `thinking` | `plan` | `tool.call` | `tool.result` | `session.started` | `session.ended` | `usage` | `session.title` | `raw` … */
+  type: string
+  payload: Record<string, unknown>
+}
+
+/** A command the platform ran for a task (branch setup, the session, accept…), with its captured tail. */
+export interface TaskCommand {
+  id: string
+  command: string
+  cwd?: string | null
+  mode?: "sync" | "background" | string
+  /** `running` | `succeeded` | `failed` | `timeout` | `canceled` | `lost`. */
+  status: string
+  exitCode?: number | null
+  stdout?: string | null
+  stderr?: string | null
+  truncated?: boolean
+  createdAt: string
+  finishedAt?: string | null
+  label?: string | null
+}
+
+/** What a session has consumed — task-wide, derived by the API from the whole event log. */
+export interface TaskSessionUsageData {
+  model?: string | null
+  contextTokens?: number | null
+  contextWindow?: number | null
+  inputTokens?: number | null
+  outputTokens?: number | null
+  cacheReadTokens?: number | null
+  cacheCreationTokens?: number | null
+  costUsd?: number | null
+  turns?: number | null
+  durationMs?: number | null
+}
+
+/** A file already in the conversation, as an event's payload carries it. */
+export interface TaskFileRef {
+  id: string
+  filename: string | null
+  mediaType: string
+  bytes: number
+}
+
+/** Where one of a task's stored files is served from. Built by the app, which knows the route. */
+export type AttachmentUrl = (attachmentId: string) => string
+
+/** A file prepared in the browser for a turn — see `prepareFile`. */
+export interface DraftFile {
+  /** Local only — React keys and the remove button. */
+  key: string
+  name: string
+  mediaType: string
+  /** Base64, no data-url prefix. */
+  data: string
+  bytes: number
+  /** Object URL for the thumbnail — images only. Revoked by whoever drops the draft. */
+  previewUrl: string | null
+}
+
+/**
+ * A message that has been sent but has not come back yet.
+ *
+ * `sinceSeq` is the timeline's high-water mark at the moment it was sent: matching on text alone
+ * would make a repeated message ("continue", twice) match the *previous* one's event.
+ */
+export interface PendingMessage {
+  text: string
+  sinceSeq: number
+  /** Object URLs of the images going with it, drawn until the stored ones come back. */
+  previews?: string[]
+}
+
+// ── Diff ─────────────────────────────────────────────────────────────────────────────────────
+
+export interface TaskDiffFile {
+  path: string
+  oldPath?: string | null
+  /** `added` | `modified` | `deleted` | `renamed` | `copied` | `type-changed` | `untracked`. */
+  status: string
+  additions: number | null
+  deletions: number | null
+  binary?: boolean
+}
+
+export interface TaskRepoDiff {
+  cwd?: string
+  name: string
+  base?: string | null
+  branch?: string | null
+  files: TaskDiffFile[]
+  additions: number
+  deletions: number
+  error?: string | null
+}
+
+/** What a branch changes, read with git in the task's own machine. */
+export interface TaskDiff {
+  available: boolean
+  /** Why it could not be read: `no-machine` | `machine-stopped` | `node-unreachable` | `unsupported`. */
+  reason?: string | null
+  branch: string
+  baseBranch?: string | null
+  repos: TaskRepoDiff[]
+  additions: number
+  deletions: number
+  files: number
+}
+
+export interface TaskPatchLine {
+  kind: "context" | "add" | "del"
+  old: number | null
+  new: number | null
+  text: string
+}
+
+export interface TaskPatchHunk {
+  header: string
+  context?: string | null
+  lines: TaskPatchLine[]
+}
+
+export interface TaskFilePatch {
+  binary?: boolean
+  truncated?: boolean
+  hunks: TaskPatchHunk[]
+}
+
+// ── Pull request ─────────────────────────────────────────────────────────────────────────────
+
+/** A proposal at the forge for the task's branch — reported, never observed. */
+export interface TaskPullRequestData {
+  /** Short reference, e.g. `#289` or `!42`. */
+  label: string
+  url: string
+  title: string
+  state: "draft" | "open" | "merged" | "closed"
+  checks?: "pending" | "passing" | "failing" | null
+  review?: "approved" | "changes-requested" | "pending" | null
+  comments?: number | null
+  updatedAt?: string | null
+}
+
+export interface TaskPullRequests {
+  /** `false` → nothing connected can answer; the section is absent, not empty. */
+  supported: boolean
+  repos: { repo: string; pullRequest: TaskPullRequestData | null; error?: string | null }[]
+}
+
+// ── Machine ──────────────────────────────────────────────────────────────────────────────────
+
+/** The node a task's worker lives on. */
+export interface TaskMachineNode {
+  name: string
+  online?: boolean
+}
+
+/** A port detected listening inside the task's container. */
+export interface TaskMachinePort {
+  port: number
+  process?: string | null
+}

package/src/components/tasks/worker-link.tsx

@@ -0,0 +1,126 @@
+"use client"
+
+// The pairing a project page is made of, drawn from both ends.
+//
+// A task has a machine and a machine is sometimes held by a task — the same fact, and neither list
+// said it. Each row now names its counterpart and links to it, so the two tabs of a project page
+// (workspaces, tasks) are one story told twice rather than two lists to correlate by hand. Both
+// directions are resolved from the two lists the page already holds: no extra round trip.
+
+import { ServerIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+import type { WorkerCardWorker } from "../workers/types"
+import type { LinkRender } from "../workers/worker-card"
+import { WorkerStatusDot, resolveWorkerStatus } from "../workers/worker-status"
+import { isLiveTaskState, taskStateStyle } from "./task-state"
+import { workerLabel } from "./machine"
+import type { TaskItem } from "./types"
+
+const defaultLink: LinkRender = ({ href, className, children }) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+)
+
+/** The task to show for a worker, and whether it still holds the machine. */
+export type WorkerTask<T extends TaskItem = TaskItem> = { task: T; live: boolean }
+
+/**
+ * Worker id → the task to name in its row.
+ *
+ * A pooled worker is reused across tasks, so "its task" is only unambiguous while one is live: a
+ * task holds its machine until it reaches a terminal state, so a live task wins. Once none is,
+ * the most recent one that ran there is still worth showing — as history — because it is what the
+ * branch checked out in that workspace belongs to.
+ */
+export function indexTasksByWorker<T extends TaskItem>(tasks: T[]): Map<string, WorkerTask<T>> {
+  const byWorker = new Map<string, WorkerTask<T>>()
+  const at = (t: TaskItem) => new Date(t.lastActivityAt ?? t.createdAt).getTime()
+  // Most recently active first, so the first task seen for a worker is already the one to keep
+  // unless a live one turns up behind it.
+  const ordered = [...tasks].sort((a, b) => at(b) - at(a))
+  for (const task of ordered) {
+    if (!task.workerId) continue
+    const live = isLiveTaskState(task.state)
+    const current = byWorker.get(task.workerId)
+    if (!current || (live && !current.live)) byWorker.set(task.workerId, { task, live })
+  }
+  return byWorker
+}
+
+/**
+ * What a workspace row says about the task on it: state as a dot, title as the link. Muted when
+ * the task is over — the machine is free, and the row should not read as busy.
+ */
+export function WorkerTaskChip({
+  entry,
+  href,
+  render,
+  className,
+}: {
+  entry: WorkerTask
+  href: string
+  render?: { link?: LinkRender }
+  className?: string
+}) {
+  const { task, live } = entry
+  const Link = render?.link ?? defaultLink
+  const label = taskStateStyle(task.state).label
+  return (
+    <span title={live ? `${label} — ${task.title}` : `Last task that ran here (${label}) — ${task.title}`} className="inline-flex min-w-0">
+      <Link
+        href={href}
+        className={cn(
+          "inline-flex min-w-0 items-center gap-1.5 text-xs underline-offset-2 transition-colors hover:text-foreground hover:underline",
+          live ? "text-foreground/80" : "text-muted-foreground/50",
+          className,
+        )}
+      >
+        <span className={cn("h-1.5 w-1.5 shrink-0 rounded-full", taskStateStyle(task.state).dotClass, !live && "opacity-50")} />
+        <span className="truncate">{task.title}</span>
+      </Link>
+    </span>
+  )
+}
+
+/**
+ * What a task row says about its machine: the workspace's name and its live status, so a task
+ * sitting in review on a stopped worker says so without being opened.
+ *
+ * `worker` is undefined when the row is gone from the project's list — a deleted machine leaves
+ * `workerId` behind on purpose (the record of the work outlives it), so the link still points
+ * somewhere and just stops claiming a status it can't observe.
+ */
+export function TaskWorkerChip({
+  worker,
+  href,
+  render,
+  className,
+}: {
+  worker?: WorkerCardWorker | null
+  href?: string
+  render?: { link?: LinkRender }
+  className?: string
+}) {
+  const Link = render?.link ?? defaultLink
+  const status = worker ? resolveWorkerStatus(worker) : null
+  const body = (
+    <>
+      {status ? <WorkerStatusDot status={status} /> : <ServerIcon className="h-3 w-3 shrink-0" />}
+      <span className="max-w-[160px] truncate">{worker ? workerLabel(worker) : "workspace"}</span>
+    </>
+  )
+  const cls = cn("flex min-w-0 items-center gap-1.5 transition-colors hover:text-foreground", className)
+  return (
+    <span title={status ? `Workspace — ${status.label}` : "The workspace this task ran on"} className="inline-flex min-w-0">
+      {href ? (
+        <Link href={href} className={cls}>
+          {body}
+        </Link>
+      ) : (
+        <span className={cls}>{body}</span>
+      )}
+    </span>
+  )
+}

package/src/components/workers/index.ts

@@ -27,6 +27,9 @@ export type { SetupProgressProps, StepState } from "./setup-progress"
 export { WorkerSetupTimeline } from "./worker-setup-timeline"
 export { SetupWaterfall } from "./setup-waterfall"
 
+export { WorkerStatusHistory, statusHistorySpans } from "./worker-status-history"
+export type { WorkerStatusHistoryProps, WorkerStatusSpan } from "./worker-status-history"
+
 export { ResourceBars } from "./resource-bars"
 export type { ResourceBarsProps, WorkerStats } from "./resource-bars"
 
@@ -40,8 +43,8 @@ export type { TagPalette } from "./tag-color"
 
 export { CreatorAvatar } from "./creator-avatar"
 
-export type { WorkerCardWorker, WorkerCockpitWorker, WorkerCreator, WorkerSetupStatus } from "./types"
+export type { WorkerCardWorker, WorkerCockpitWorker, WorkerCreator, WorkerSetupStatus, WorkerStatusEvent } from "./types"
 
 // Re-exported here too so a consumer of the worker surface doesn't have to
 // import the root entry just to format the timestamps it feeds these components.
-export { cn, formatDuration, formatRelativeTime } from "../../utils"
+export { cn, formatDuration, formatElapsed, formatRelativeTime } from "../../utils"

package/src/components/workers/types.ts

@@ -68,3 +68,25 @@ export interface WorkerCockpitWorker extends WorkerCardWorker {
   branch?: string | null
   containerId?: string | null
 }
+
+/**
+ * One row of a worker's status history — a transition, as the control plane journaled it.
+ *
+ * Mirrors a `worker_status_events` row of the dashboard (`from`, `to`, `source`, `meta`, `at`),
+ * laxly: `to` and `at` are the only fields the history can't draw without. `source` is a free
+ * string on purpose — the package phrases the ones it knows and shows the others as they come.
+ */
+export interface WorkerStatusEvent {
+  /** Order within the worker. Falls back to `at` when absent. */
+  seq?: number | null
+  /** ISO 8601 — when the worker *entered* `to`. */
+  at: string
+  /** `null` for the very first transition (the worker's creation). */
+  from?: string | null
+  /** Lifecycle state entered — same vocabulary as `WorkerCardWorker.state`. */
+  to: string
+  /** Who wrote it: `spawn` | `agent-event` | `reconciliation` | `command` | `setup-monitor` | `boot-recovery` | `node-disconnect`. */
+  source?: string | null
+  /** The why, same shape as `WorkerCardWorker.statusMeta`. */
+  meta?: WorkerCardWorker["statusMeta"]
+}

package/src/components/workers/worker-cockpit.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 // The full worker page, as one component. Top bar, logs/terminal tabs, and a
-// control panel (setup, resources, repos, ports, tags, actions, info) that
+// control panel (setup, resources, repos, ports, tags, actions, history, info) that
 // lives in a sidebar on desktop and a bottom sheet on mobile — same content,
 // because a phone doesn't need less of it, just a different place to put it.
 //
@@ -44,10 +44,11 @@ import { type GitRepoStatus, repoName } from "./git-branch-chips"
 import { ResourceBars, type WorkerStats } from "./resource-bars"
 import { SetupWaterfall } from "./setup-waterfall"
 import { TagChips } from "./tag-chips"
-import type { WorkerCockpitWorker, WorkerCreator } from "./types"
+import type { WorkerCockpitWorker, WorkerCreator, WorkerStatusEvent } from "./types"
 import { type LinkRender } from "./worker-card"
 import { WorkerSetupTimeline } from "./worker-setup-timeline"
 import { WorkerStatusDot, WorkerStatusPill, resolveWorkerStatus } from "./worker-status"
+import { WorkerStatusHistory } from "./worker-status-history"
 
 type CockpitTab = "logs" | "terminal"
 
@@ -104,6 +105,12 @@ export interface WorkerCockpitProps {
   /** Fetches the one-shot SSH command; the cockpit copies it to the clipboard and owns the button's own idle/loading/copied state. */
   onCopySsh?: () => Promise<string>
 
+  /**
+   * The worker's status transitions, as journaled by the control plane. Omitted or empty → no
+   * History section. The current stay is measured up to `now` at render time.
+   */
+  statusHistory?: WorkerStatusEvent[]
+
   /** A failed mutation, typically. */
   error?: string | null
   onDismissError?: () => void
@@ -180,6 +187,7 @@ export function WorkerCockpit({
   onDelete,
   deleting = false,
   onCopySsh,
+  statusHistory,
   error,
   onDismissError,
   activeTab,
@@ -394,6 +402,13 @@ export function WorkerCockpit({
         </div>
       )}
 
+      {!!statusHistory?.length && (
+        <div>
+          <SectionLabel>History</SectionLabel>
+          <WorkerStatusHistory events={statusHistory} />
+        </div>
+      )}
+
       <div>
         <SectionLabel>Info</SectionLabel>
         <div className="divide-y divide-border/40 rounded-lg border border-border/50 bg-muted/20">

package/src/components/workers/worker-status-history.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest"
+import { formatElapsed } from "../../utils"
+import { statusHistorySpans } from "./worker-status-history"
+
+const T0 = Date.parse("2026-09-22T10:00:00Z")
+const at = (ms: number) => new Date(T0 + ms).toISOString()
+
+describe("statusHistorySpans", () => {
+  it("un séjour dure jusqu'à la transition suivante, le dernier jusqu'à now", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: at(0), from: null, to: "provisioning", source: "spawn" },
+        { seq: 2, at: at(800), from: "provisioning", to: "building", source: "spawn" },
+        { seq: 3, at: at(660_800), from: "building", to: "ready", source: "agent-event" },
+      ],
+      T0 + 3_600_000
+    )
+    expect(spans.map((s) => s.duration)).toEqual([800, 660_000, 3_600_000 - 660_800])
+    expect(spans.map((s) => s.current)).toEqual([false, false, true])
+  })
+
+  it("remet dans l'ordre un journal qui arrive dans le désordre", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 2, at: at(1000), to: "ready" },
+        { seq: 1, at: at(0), to: "starting" },
+      ],
+      T0 + 2000
+    )
+    expect(spans.map((s) => s.event.to)).toEqual(["starting", "ready"])
+  })
+
+  it("ignore une date illisible et ne produit jamais de durée négative", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: "pas une date", to: "starting" },
+        { seq: 2, at: at(5000), to: "ready" },
+      ],
+      T0 // horloge en retard sur le journal
+    )
+    expect(spans).toHaveLength(1)
+    expect(spans[0].duration).toBe(0)
+  })
+
+  it("ne fait battre que le séjour en cours", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: at(0), to: "ready" },
+        { seq: 2, at: at(1000), to: "stopping" },
+        { seq: 3, at: at(2000), to: "stopped" },
+        { seq: 4, at: at(3000), to: "ready" },
+      ],
+      T0 + 4000
+    )
+    expect(spans.map((s) => s.status.running)).toEqual([false, false, false, true])
+  })
+
+  it("dit pourquoi à partir du meta, et retire les points de suspension d'un séjour fini", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: at(0), to: "provisioning" },
+        { seq: 2, at: at(1000), to: "starting" },
+        { seq: 3, at: at(2000), to: "exited", meta: { reason: "oom-killed", exitCode: 137, oomKilled: true } },
+      ],
+      T0 + 3000
+    )
+    expect(spans.map((s) => s.label)).toEqual(["Provisioning", "Setting up", "Exited"])
+    expect(spans[2].status.detail).toBe("Ran out of memory (exit 137)")
+  })
+})
+
+describe("formatElapsed", () => {
+  it.each([
+    [800, "800ms"],
+    [40_000, "40s"],
+    [252_000, "4m 12s"],
+    [660_000, "11m"],
+    [11_520_000, "3h 12m"],
+    [7_200_000, "2h"],
+    [59_800, "1m"],
+    [273_600_000, "3d 4h"],
+  ])("%d ms → %s", (ms, out) => {
+    expect(formatElapsed(ms)).toBe(out)
+  })
+})