@davstack/tui 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davstack/tui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "description": "Long-running terminal UI that spawns, owns, and surfaces the davstack daemons (vitest-server, playwright-server, logs-server).",
@@ -18,11 +18,14 @@
     "commander": "^12.0.0",
     "ink": "^5.0.1",
     "react": "^18.3.1",
-    "tsx": "^4.19.0"
+    "tsx": "^4.19.0",
+    "@davstack/open-agents": "1.2.0"
   },
   "devDependencies": {
+    "@types/node": "^25.9.1",
     "@types/react": "^18.3.3",
-    "ink-testing-library": "^4.0.0"
+    "ink-testing-library": "^4.0.0",
+    "typescript": "^5.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/App.tsx

@@ -8,6 +8,7 @@ import { daemonRegistry, type DaemonDescriptor } from "./lib/daemon-registry.ts"
 import { installGlobalTeardown } from "./lib/global-teardown.ts"
 
 import { ViewProvider } from "./state/view-context.tsx"
+import { AgentsProvider } from "./state/agents-context.tsx"
 import { DaemonsProvider } from "./state/daemons-context.tsx"
 import { QuitProvider, useQuit } from "./state/quit-context.tsx"
 
@@ -44,7 +45,8 @@ export function App({
 
   return (
     <ViewProvider>
-      <DaemonsProvider descriptors={filtered}>
+      <AgentsProvider>
+        <DaemonsProvider descriptors={filtered}>
         <QuitProvider>
           <DescriptorSync descriptors={filtered} />
           {filtered.map((d) => (
@@ -61,7 +63,8 @@ export function App({
             )}
           </QuitController>
         </QuitProvider>
-      </DaemonsProvider>
+        </DaemonsProvider>
+      </AgentsProvider>
     </ViewProvider>
   )
 }

package/src/cli.ts

@@ -13,11 +13,31 @@ import { runCheck, formatResult, exitCodeFor } from "./commands/check.ts"
 
 function runStart(opts: { noColor?: boolean }): void {
   if (opts.noColor) process.env.DAVSTACK_NO_COLOR = "1"
-  // Wipe stale shell scrollback so the Ink UI takes over a clean screen.
-  // Sequence: ED(2) clears viewport, ED(3) clears scrollback (xterm/WT),
-  // CUP homes the cursor.
-  process.stdout.write("\x1b[2J\x1b[3J\x1b[H")
-  render(React.createElement(App))
+  // Use the terminal's alternate screen buffer so view transitions
+  // (drill in/back) don't leak prior frames into scrollback when Ink
+  // shrinks its render region. Falls back to a one-shot scrollback
+  // wipe when stdout isn't a TTY or DAVSTACK_NO_ALTSCREEN is set.
+  const altScreen =
+    process.stdout.isTTY === true && process.env.DAVSTACK_NO_ALTSCREEN !== "1"
+  if (altScreen) {
+    process.stdout.write("\x1b[?1049h\x1b[H")
+  } else {
+    process.stdout.write("\x1b[2J\x1b[3J\x1b[H")
+  }
+  const restore = () => {
+    if (altScreen) process.stdout.write("\x1b[?1049l")
+  }
+  process.once("exit", restore)
+  process.once("SIGINT", () => {
+    restore()
+    process.exit(130)
+  })
+  process.once("SIGTERM", () => {
+    restore()
+    process.exit(143)
+  })
+  const ink = render(React.createElement(App))
+  ink.waitUntilExit().finally(restore)
 }
 
 const program = new Command()

package/src/components/BottomBar.tsx

@@ -1,6 +1,5 @@
-// Persistent bottom bar — renders in both list and log views. Reads
-// rows + current view from context to derive pills and which one is
-// focused (highlighted bold + inverse).
+// Persistent bottom bar — daemon pills only. Running-agent pills used
+// to live here too but the dedicated `g` view supersedes them.
 
 import React from "react"
 
@@ -18,11 +17,13 @@ function statusToPill(s: DaemonRow["status"]): PillStatus {
 export function BottomBar(): React.ReactElement {
   const { rows } = useDaemons()
   const { view } = useView()
+
   const pills: DaemonPill[] = rows.map((r, i) => ({
     key: String(i + 1),
     daemonKey: r.descriptor.key,
     label: r.descriptor.label,
     status: statusToPill(r.status),
   }))
+
   return <StatusBar daemons={pills} focusedKey={view.kind === "log" ? view.key : undefined} />
 }

package/src/components/ControlsHint.tsx

@@ -0,0 +1,19 @@
+// Collapsed-by-default keyboard hint row. Default shows `c for controls`;
+// toggled state inlines the full hint string. Toggle is owned by the
+// parent view via useInput so each view decides what `c` means.
+
+import React from "react"
+import { Box, Text } from "ink"
+
+export interface ControlsHintProps {
+  expanded: boolean
+  controls: string
+}
+
+export function ControlsHint({ expanded, controls }: ControlsHintProps): React.ReactElement {
+  return (
+    <Box marginTop={1}>
+      <Text dimColor>{expanded ? controls : "c for controls"}</Text>
+    </Box>
+  )
+}

package/src/components/MainView.tsx

@@ -6,6 +6,8 @@ import { Box, Text, useStdout } from "ink"
 
 import { ServerList } from "../views/ServerList.tsx"
 import { ServerLogView } from "../views/ServerLogView.tsx"
+import { AgentsList } from "../views/AgentsList.tsx"
+import { AgentTimelineView } from "../views/AgentTimelineView.tsx"
 import { useView } from "../state/view-context.tsx"
 import { useDaemons } from "../state/daemons-context.tsx"
 import { getPackageVersion, getRepoRootSafe } from "../lib/package-info.ts"
@@ -20,6 +22,12 @@ export function MainView({ discoveryDone, hasAnyDaemon }: MainViewProps): React.
   const { view } = useView()
   const { rows } = useDaemons()
 
+  if (view.kind === "agent") {
+    return <AgentTimelineView jobId={view.id} />
+  }
+  if (view.kind === "agents") {
+    return <AgentsList />
+  }
   if (!discoveryDone) {
     return <Text dimColor>scanning .davstack/config…</Text>
   }

package/src/components/Markdown.tsx

@@ -0,0 +1,130 @@
+// Tiny markdown renderer for Ink. Handles the subset our agent spec
+// files actually use: headings, bullets, fenced code blocks, inline
+// **bold** and `code`. Anything fancier (tables, links, blockquotes)
+// falls through as plain text rather than blowing up the layout.
+
+import React from "react"
+import { Text } from "ink"
+
+export interface MarkdownProps {
+  source: string
+  maxLines?: number
+}
+
+interface InlineToken {
+  kind: "text" | "bold" | "code"
+  value: string
+}
+
+export function Markdown({ source, maxLines }: MarkdownProps): React.ReactElement {
+  const rawLines = React.useMemo(
+    () => source.replace(/\r\n/g, "\n").split("\n"),
+    [source],
+  )
+  const sliced = maxLines != null ? rawLines.slice(0, maxLines) : rawLines
+  let inCodeFence = false
+  const elements: React.ReactNode[] = []
+  for (let i = 0; i < sliced.length; i += 1) {
+    const line = sliced[i]!
+    if (/^\s*```/.test(line)) {
+      inCodeFence = !inCodeFence
+      elements.push(
+        <Text key={i} dimColor>
+          {line}
+        </Text>,
+      )
+      continue
+    }
+    if (inCodeFence) {
+      elements.push(
+        <Text key={i} color="yellow" dimColor>
+          {line}
+        </Text>,
+      )
+      continue
+    }
+    elements.push(renderLine(i, line))
+  }
+  return <>{elements}</>
+}
+
+function renderLine(key: number, line: string): React.ReactNode {
+  const heading = /^(#{1,6})\s+(.*)$/.exec(line)
+  if (heading) {
+    const level = heading[1]!.length
+    const color = level === 1 ? "cyan" : level === 2 ? "yellow" : undefined
+    return (
+      <Text key={key} bold color={color}>
+        {heading[2]!}
+      </Text>
+    )
+  }
+  if (/^\s*---+\s*$/.test(line)) {
+    return (
+      <Text key={key} dimColor>
+        {"─".repeat(60)}
+      </Text>
+    )
+  }
+  const bullet = /^(\s*)([-*])\s+(.*)$/.exec(line)
+  if (bullet) {
+    return (
+      <Text key={key}>
+        {bullet[1]}
+        <Text color="cyan">• </Text>
+        {renderInline(bullet[3]!)}
+      </Text>
+    )
+  }
+  if (line.trim().length === 0) {
+    return <Text key={key}> </Text>
+  }
+  return <Text key={key}>{renderInline(line)}</Text>
+}
+
+function renderInline(text: string): React.ReactNode {
+  const tokens = tokenizeInline(text)
+  return tokens.map((t, i) => {
+    if (t.kind === "bold")
+      return (
+        <Text key={i} bold>
+          {t.value}
+        </Text>
+      )
+    if (t.kind === "code")
+      return (
+        <Text key={i} color="yellow">
+          {t.value}
+        </Text>
+      )
+    return <Text key={i}>{t.value}</Text>
+  })
+}
+
+function tokenizeInline(text: string): InlineToken[] {
+  const out: InlineToken[] = []
+  let i = 0
+  while (i < text.length) {
+    if (text.startsWith("**", i)) {
+      const end = text.indexOf("**", i + 2)
+      if (end > i + 2) {
+        out.push({ kind: "bold", value: text.slice(i + 2, end) })
+        i = end + 2
+        continue
+      }
+    }
+    if (text[i] === "`") {
+      const end = text.indexOf("`", i + 1)
+      if (end > i + 1) {
+        out.push({ kind: "code", value: text.slice(i + 1, end) })
+        i = end + 1
+        continue
+      }
+    }
+    let j = i + 1
+    while (j < text.length && !text.startsWith("**", j) && text[j] !== "`") j += 1
+    out.push({ kind: "text", value: text.slice(i, j) })
+    i = j
+  }
+  return out
+}

package/src/components/StatusBar.tsx

@@ -18,6 +18,11 @@ export interface DaemonPill {
   status: DaemonStatus
 }
 
+export interface AgentPill {
+  jobId: string
+  label: string
+}
+
 const STATUS_GLYPH: Record<DaemonStatus, string> = {
   "not-running": "○",
   running: "●",
@@ -34,9 +39,11 @@ const STATUS_COLOR: Record<DaemonStatus, string | undefined> = {
 
 interface StatusBarProps {
   daemons: DaemonPill[]
+  agents?: AgentPill[]
   // Daemon key currently being viewed (log view). The matching pill is
   // rendered bold + inverse so users can see which one they're in.
   focusedKey?: string
+  focusedAgentId?: string
 }
 
 // Exported for unit tests — avoids depending on ANSI escape detection
@@ -45,14 +52,24 @@ export function isPillFocused(pill: DaemonPill, focusedKey: string | undefined):
   return focusedKey !== undefined && pill.daemonKey === focusedKey
 }
 
-export function StatusBar({ daemons, focusedKey }: StatusBarProps): React.ReactElement {
+export function isAgentPillFocused(pill: AgentPill, focusedAgentId: string | undefined): boolean {
+  return focusedAgentId !== undefined && pill.jobId === focusedAgentId
+}
+
+export function StatusBar({
+  daemons,
+  agents = [],
+  focusedKey,
+  focusedAgentId,
+}: StatusBarProps): React.ReactElement {
   const noColor = useNoColor()
   return (
     <Box flexDirection="row">
       {daemons.map((d, i) => {
         const focused = isPillFocused(d, focusedKey)
+        const marginRight = i === daemons.length - 1 && agents.length === 0 ? 0 : 2
         return (
-          <Box key={d.key} marginRight={i === daemons.length - 1 ? 0 : 2}>
+          <Box key={d.key} marginRight={marginRight}>
             <Text inverse={focused} bold={focused}>
               {d.key} {d.label}{" "}
               <Text color={colorOrUndef(STATUS_COLOR[d.status], noColor)}>
@@ -62,6 +79,21 @@ export function StatusBar({ daemons, focusedKey }: StatusBarProps): React.ReactE
           </Box>
         )
       })}
+      {agents.length > 0 ? (
+        <Box marginRight={2}>
+          <Text dimColor>|</Text>
+        </Box>
+      ) : null}
+      {agents.map((a, i) => {
+        const focused = isAgentPillFocused(a, focusedAgentId)
+        return (
+          <Box key={a.jobId} marginRight={i === agents.length - 1 ? 0 : 2}>
+            <Text inverse={focused} bold={focused}>
+              <Text color={colorOrUndef("yellow", noColor)}>{a.label}</Text>
+            </Text>
+          </Box>
+        )
+      })}
     </Box>
   )
 }

package/src/hooks/useAdapterFor.ts

@@ -0,0 +1,10 @@
+import type { JobRecord } from "@davstack/open-agents/core/jobs"
+import type { AgentAdapter } from "@davstack/open-agents/adapters/types"
+import { cursorAdapter } from "@davstack/open-agents/adapters/cursor"
+import { geminiAdapter } from "@davstack/open-agents/adapters/gemini"
+
+export function adapterForJob(job: Pick<JobRecord, "model">): AgentAdapter {
+  const m = job.model.toLowerCase()
+  if (m.startsWith("gemini-")) return geminiAdapter
+  return cursorAdapter
+}

package/src/hooks/useAgentJobs.test.tsx

@@ -0,0 +1,149 @@
+// Hook test for useAgentJobs: fixture jobs dir under tmp OPEN_AGENTS_HOME,
+// ink-testing-library probe, mtime poll refresh.
+
+import fs from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import React from "react"
+import { afterEach, beforeEach, expect, test, vi } from "vitest"
+import { render } from "ink-testing-library"
+import { Text } from "ink"
+
+import type { JobRecord } from "@davstack/open-agents/core/jobs"
+import { jobsDir } from "@davstack/open-agents/core/paths"
+
+import { useAgentJobs, type UseAgentJobsResult } from "./useAgentJobs.ts"
+
+const origHome = process.env.OPEN_AGENTS_HOME
+let tmpRoot = ""
+let repoPath = ""
+
+beforeEach(async () => {
+  vi.useFakeTimers()
+  tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "davstack-tui-jobs-"))
+  process.env.OPEN_AGENTS_HOME = tmpRoot
+  repoPath = path.join(tmpRoot, "repo")
+  await fs.mkdir(repoPath, { recursive: true })
+})
+
+afterEach(async () => {
+  vi.useRealTimers()
+  if (origHome === undefined) delete process.env.OPEN_AGENTS_HOME
+  else process.env.OPEN_AGENTS_HOME = origHome
+  await fs.rm(tmpRoot, { recursive: true, force: true })
+})
+
+async function writeJob(opts: {
+  id: string
+  status?: JobRecord["status"]
+  startedAt?: string
+  model?: string
+}): Promise<void> {
+  const dir = jobsDir(repoPath)
+  await fs.mkdir(dir, { recursive: true })
+  const record: JobRecord = {
+    id: opts.id,
+    repoPath,
+    prompt: "fixture prompt",
+    model: opts.model ?? "composer-2.5",
+    status: opts.status ?? "done",
+    startedAt: opts.startedAt ?? new Date().toISOString(),
+    rawLogPath: path.join(dir, "logs", `${opts.id}.ndjson`),
+  }
+  await fs.writeFile(path.join(dir, `${opts.id}.json`), JSON.stringify(record, null, 2))
+}
+
+function Probe({
+  onRender,
+}: {
+  onRender: (r: UseAgentJobsResult) => void
+}): React.ReactElement {
+  const r = useAgentJobs(repoPath)
+  onRender(r)
+  return React.createElement(Text, null, `n=${r.jobs.length}`)
+}
+
+let active: ReturnType<typeof render> | null = null
+afterEach(() => {
+  active?.unmount()
+  active = null
+})
+
+async function flush(): Promise<void> {
+  await Promise.resolve()
+  await vi.runOnlyPendingTimersAsync()
+  await Promise.resolve()
+}
+
+test("lists fixture jobs from tmp OPEN_AGENTS_HOME jobs dir", async () => {
+  await writeJob({ id: "job-a", status: "done", startedAt: "2026-05-26T10:00:00.000Z" })
+  await writeJob({ id: "job-b", status: "running", startedAt: "2026-05-26T11:00:00.000Z" })
+
+  let captured: UseAgentJobsResult | null = null
+  active = render(
+    React.createElement(Probe, {
+      onRender: (r) => {
+        captured = r
+      },
+    }),
+  )
+  await flush()
+
+  expect(captured!.jobs.map((j) => j.id)).toEqual(["job-b", "job-a"])
+})
+
+test("returns empty list when jobs dir does not exist yet", async () => {
+  let captured: UseAgentJobsResult | null = null
+  active = render(
+    React.createElement(Probe, {
+      onRender: (r) => {
+        captured = r
+      },
+    }),
+  )
+  await flush()
+  expect(captured!.jobs).toEqual([])
+})
+
+test("mtime poll picks up a newly written job", async () => {
+  await writeJob({ id: "job-1" })
+  let captured: UseAgentJobsResult | null = null
+  active = render(
+    React.createElement(Probe, {
+      onRender: (r) => {
+        captured = r
+      },
+    }),
+  )
+  await flush()
+  expect(captured!.jobs).toHaveLength(1)
+
+  await writeJob({ id: "job-2", status: "running" })
+  const dir = jobsDir(repoPath)
+  const now = new Date()
+  await fs.utimes(dir, now, now)
+
+  await vi.advanceTimersByTimeAsync(500)
+  await flush()
+
+  expect(captured!.jobs.map((j) => j.id).sort()).toEqual(["job-1", "job-2"])
+})
+
+test("ignores non-job json files in the jobs dir", async () => {
+  const dir = jobsDir(repoPath)
+  await fs.mkdir(dir, { recursive: true })
+  await fs.writeFile(path.join(dir, "README.json"), '{"nope":true}', "utf8")
+  await writeJob({ id: "job-only" })
+
+  let captured: UseAgentJobsResult | null = null
+  active = render(
+    React.createElement(Probe, {
+      onRender: (r) => {
+        captured = r
+      },
+    }),
+  )
+  await flush()
+
+  expect(captured!.jobs.map((j) => j.id)).toEqual(["job-only"])
+})

package/src/hooks/useAgentJobs.ts

@@ -0,0 +1,53 @@
+import fs from "node:fs"
+import { useEffect, useMemo, useRef, useState } from "react"
+
+import { listJobs, type JobRecord } from "@davstack/open-agents/core/jobs"
+import { jobsDir } from "@davstack/open-agents/core/paths"
+
+export interface UseAgentJobsResult {
+  jobs: JobRecord[]
+}
+
+function jobStableKey(j: JobRecord): string {
+  return `${j.id}:${j.status}:${j.finishedAt ?? ""}`
+}
+
+export function useAgentJobs(repoPath: string): UseAgentJobsResult {
+  const [jobs, setJobs] = useState<JobRecord[]>([])
+  const [tick, setTick] = useState(0)
+  const lastMtimeRef = useRef(0)
+  const lastKeysRef = useRef("")
+
+  useEffect(() => {
+    const id = setInterval(() => {
+      try {
+        const st = fs.statSync(jobsDir(repoPath))
+        const m = st.mtimeMs
+        if (m === lastMtimeRef.current) return
+        lastMtimeRef.current = m
+        setTick((t) => t + 1)
+      } catch {
+        /* dir not yet created */
+      }
+    }, 500)
+    return () => clearInterval(id)
+  }, [repoPath])
+
+  useEffect(() => {
+    const next = listJobs(repoPath, { limit: 20 })
+    const keys = next.map(jobStableKey).join("|")
+    if (keys === lastKeysRef.current) return
+    lastKeysRef.current = keys
+    setJobs(next)
+  }, [repoPath, tick])
+
+  const sorted = useMemo(() => sortAgentJobs(jobs), [jobs])
+
+  return { jobs: sorted }
+}
+
+function sortAgentJobs(jobs: JobRecord[]): JobRecord[] {
+  const running = jobs.filter((j) => j.status === "running")
+  const rest = jobs.filter((j) => j.status !== "running")
+  return [...running, ...rest]
+}