{
  "schemaVersion": 1,
  "target": "react",
  "name": "run-timeline",
  "version": "0.3.0",
  "category": "agent",
  "title": "Run Timeline",
  "description": "A run's state in an Agent State pill, a progress hairline, and its steps in order on a rail, with start times, durations, and errors.",
  "tags": [
    "agent",
    "run",
    "timeline",
    "steps",
    "status"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {},
  "registryDependencies": [
    {
      "name": "agent-run",
      "version": "0.1.2"
    },
    {
      "name": "step-list",
      "version": "0.3.0"
    },
    {
      "name": "agent-state",
      "version": "0.1.0"
    }
  ],
  "docsPath": "/components/run-timeline",
  "props": [
    {
      "name": "run",
      "type": "Pick<AgentRun, \"title\" | \"status\" | \"steps\" | \"error\" | \"createdAt\" | \"finishedAt\">",
      "description": "The run to show. Times are shown in UTC so server and client render the same text."
    },
    {
      "name": "activity",
      "type": "\"thinking\" | \"searching\" | \"working\" | \"planning\" | \"listening\" | \"shaping\"",
      "default": "\"working\"",
      "description": "Which Agent State mark animates in the header while the run is running."
    }
  ],
  "accessibility": [
    "The run status pill is a live region whose text is exactly the status (Running, Needs approval, Succeeded, Failed, Cancelled), so changes are announced.",
    "Each step includes its status as screen-reader text and as a visible label; the progress line and glyphs are decorative.",
    "Failures are shown as text, not only red.",
    "With reduced motion the running marks hold a still frame and status changes are instant."
  ],
  "states": [
    "queued",
    "running",
    "waiting-for-approval",
    "succeeded",
    "failed",
    "cancelled"
  ],
  "files": [
    {
      "path": "agent/run-timeline.tsx",
      "content": "import type { ComponentProps } from \"react\";\nimport type { AgentRun, RunStatus } from \"./agent-run\";\nimport { type AgentActivity, type AgentPhase, AgentState } from \"./agent-state\";\nimport { StepList } from \"./step-list\";\n\nconst runStatus: Record<RunStatus, { label: string; phase: AgentPhase }> = {\n  queued: { label: \"Queued\", phase: \"idle\" },\n  running: { label: \"Running\", phase: \"active\" },\n  \"waiting-for-approval\": { label: \"Needs approval\", phase: \"waiting\" },\n  succeeded: { label: \"Succeeded\", phase: \"done\" },\n  failed: { label: \"Failed\", phase: \"failed\" },\n  cancelled: { label: \"Cancelled\", phase: \"cancelled\" },\n};\n\nconst ease = \"ease-[cubic-bezier(0.23,1,0.32,1)]\";\n\nexport interface RunTimelineProps extends Omit<ComponentProps<\"section\">, \"children\"> {\n  run: Pick<AgentRun, \"title\" | \"status\" | \"steps\" | \"error\" | \"createdAt\" | \"finishedAt\">;\n  /** Which Agent State mark animates while the run is running. Defaults to working. */\n  activity?: AgentActivity;\n}\n\n/**\n * The run's state and its steps in order on a hairline rail, with start times and durations.\n * The divider under the header doubles as a progress line.\n */\nexport function RunTimeline({ run, activity = \"working\", className, ...props }: RunTimelineProps) {\n  const meta = runStatus[run.status];\n  const done = run.steps.filter((step) => step.status === \"succeeded\").length;\n  const settled = run.steps.filter((step) => step.status !== \"queued\" && step.status !== \"running\").length;\n  const progress = run.status === \"succeeded\" ? 1 : run.steps.length ? settled / run.steps.length : 0;\n  const total = run.createdAt && run.finishedAt ? formatDuration(run.createdAt, run.finishedAt) : \"\";\n\n  return (\n    <section\n      aria-label={`${run.title} timeline`}\n      data-status={run.status}\n      className={[\n        \"rounded-xl border bg-white text-zinc-950 shadow-[0_1px_2px_rgb(0_0_0/0.04)] transition-[border-color] duration-200 motion-reduce:transition-none\",\n        \"dark:bg-black dark:text-white dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.06)]\",\n        run.status === \"failed\" ? \"border-red-500/35\" : \"border-zinc-950/10 dark:border-white/10\",\n        className,\n      ]\n        .filter(Boolean)\n        .join(\" \")}\n      {...props}\n    >\n      <header className=\"flex items-start justify-between gap-3 px-4 pt-3.5 pb-3\">\n        <div className=\"min-w-0\">\n          <h3 className=\"truncate text-sm leading-6 font-semibold\">{run.title}</h3>\n          <p className=\"text-xs text-zinc-500 tabular-nums\">\n            {run.steps.length ? `${done} of ${run.steps.length} steps done` : \"No steps yet\"}\n            {total ? ` · ${total}` : \"\"}\n          </p>\n        </div>\n        {/* A live region whose text is exactly the status label; the mark is decorative. */}\n        <AgentState status size=\"sm\" activity={activity} phase={meta.phase} label={meta.label} className=\"mt-0.5\" />\n      </header>\n\n      {/* The divider is the progress line: it fills as steps settle. */}\n      <div aria-hidden=\"true\" className=\"relative h-px overflow-hidden bg-zinc-950/[0.07] dark:bg-white/[0.08]\">\n        <span\n          className={[\n            \"absolute inset-0 origin-left transition-[scale,background-color] duration-500 motion-reduce:transition-none\",\n            ease,\n            run.status === \"failed\" ? \"bg-red-500/70\" : run.status === \"waiting-for-approval\" ? \"bg-amber-500/70\" : \"bg-zinc-950/40 dark:bg-white/50\",\n          ].join(\" \")}\n          style={{ scale: `${progress} 1` }}\n        />\n      </div>\n\n      {run.status === \"failed\" && run.error ? (\n        <p className=\"mx-4 mt-4 rounded-lg border border-red-500/35 bg-red-500/[0.08] px-3 py-2 text-sm text-red-700 dark:text-red-300\">{run.error}</p>\n      ) : null}\n\n      <div className=\"px-4 py-4\">\n        {run.steps.length ? (\n          <StepList\n            steps={run.steps.map((step) => ({\n              id: step.id,\n              status: step.status,\n              label: step.kind === \"tool\" ? <span className=\"font-mono text-[13px]\">{step.name}</span> : step.name,\n              detail: step.status === \"failed\" && step.error ? step.error : step.summary,\n              meta: step.startedAt ? (\n                <>\n                  <time dateTime={step.startedAt}>{formatTime(step.startedAt)}</time>\n                  {step.finishedAt ? ` · ${formatDuration(step.startedAt, step.finishedAt)}` : \"\"}\n                </>\n              ) : undefined,\n            }))}\n          />\n        ) : (\n          <p className=\"text-sm text-zinc-500\">Steps appear here as the agent works.</p>\n        )}\n      </div>\n    </section>\n  );\n}\n\nfunction formatTime(iso: string): string {\n  const date = new Date(iso);\n  return Number.isNaN(date.getTime()) ? \"\" : date.toISOString().slice(11, 19);\n}\n\nfunction formatDuration(start: string, end: string): string {\n  const ms = new Date(end).getTime() - new Date(start).getTime();\n  if (!Number.isFinite(ms) || ms < 0) return \"\";\n  return ms < 1000 ? `${ms} ms` : `${(ms / 1000).toFixed(1)} s`;\n}\n"
    }
  ],
  "example": {
    "content": "import { RunTimeline } from \"@/components/shaken/agent/run-timeline\";\n\nexport default function RunTimelineExample() {\n  return (\n    <RunTimeline\n      className=\"w-full max-w-md\"\n      run={{\n        title: \"Update the rate-limit docs\",\n        status: \"running\",\n        steps: [\n          { id: \"1\", name: \"search_docs\", kind: \"tool\", status: \"succeeded\", summary: \"Found 3 pages\", startedAt: \"2026-11-14T10:00:00.600Z\", finishedAt: \"2026-11-14T10:00:01.400Z\" },\n          { id: \"2\", name: \"edit_files\", kind: \"tool\", status: \"running\", summary: \"Update the limits table\", startedAt: \"2026-11-14T10:00:01.600Z\" },\n          { id: \"3\", name: \"open_pull_request\", kind: \"tool\", status: \"queued\" },\n        ],\n      }}\n    />\n  );\n}\n"
  }
}
