@cat-factory/app 0.6.0

package/app/composables/useStepProse.ts

@@ -0,0 +1,78 @@
+import { ref, reactive, computed, nextTick } from 'vue'
+import { parseOutputOutline } from '~/utils/agentOutput'
+
+/**
+ * The prose reader for an agent step's markdown output: its heading outline, the
+ * per-section collapse state, and the scroll-spy that keeps the ToC in sync.
+ * Owns the scroll container + per-section element refs the template binds; the
+ * details card is always the first anchor. `reset()` re-seeds (all sections
+ * expanded, scrolled to top) whenever a different step opens.
+ */
+export function useStepProse(getOutput: () => string) {
+  const outline = computed(() => parseOutputOutline(getOutput()))
+  const tocSections = computed(() => outline.value.sections.filter((s) => s.depth > 0))
+  const hasOutput = computed(() => !!getOutput().trim())
+
+  const collapsed = reactive<Record<string, boolean>>({})
+  const activeId = ref<string>('step-details')
+  const scrollEl = ref<HTMLElement | null>(null)
+  const sectionEls = reactive<Record<string, HTMLElement | null>>({})
+
+  // Anchors the ToC navigates + the scroll-spy tracks: the details card first, then
+  // every heading section of the prose.
+  const anchors = computed(() => ['step-details', ...tocSections.value.map((s) => s.id)])
+
+  function toggle(id: string) {
+    collapsed[id] = !collapsed[id]
+  }
+  function setAll(value: boolean) {
+    for (const s of outline.value.sections) collapsed[s.id] = value
+  }
+  const allCollapsed = computed(
+    () => outline.value.sections.length > 0 && outline.value.sections.every((s) => collapsed[s.id]),
+  )
+
+  async function goTo(id: string) {
+    if (collapsed[id]) collapsed[id] = false
+    activeId.value = id
+    await nextTick()
+    sectionEls[id]?.scrollIntoView({ behavior: 'smooth', block: 'start' })
+  }
+
+  function onScroll() {
+    const container = scrollEl.value
+    if (!container) return
+    const line = container.getBoundingClientRect().top + 80
+    let current = anchors.value[0] ?? 'step-details'
+    for (const id of anchors.value) {
+      const el = sectionEls[id]
+      if (el && el.getBoundingClientRect().top <= line) current = id
+      else break
+    }
+    activeId.value = current
+  }
+
+  // Re-seed (all sections expanded, scrolled to top) for a freshly-opened step.
+  function reset() {
+    for (const k of Object.keys(collapsed)) delete collapsed[k]
+    activeId.value = 'step-details'
+    void nextTick(() => scrollEl.value?.scrollTo({ top: 0 }))
+  }
+
+  return {
+    outline,
+    tocSections,
+    hasOutput,
+    collapsed,
+    activeId,
+    scrollEl,
+    sectionEls,
+    anchors,
+    toggle,
+    setAll,
+    allCollapsed,
+    goTo,
+    onScroll,
+    reset,
+  }
+}

package/app/composables/useStepTimer.ts

@@ -0,0 +1,63 @@
+import { ref, computed, onMounted, onUnmounted } from 'vue'
+import type { PipelineStep } from '~/types/execution'
+
+/**
+ * Live elapsed-time clock for a single pipeline step. A 1s tick drives the
+ * counting-up duration while the step is actively running; the clock freezes at
+ * the step's finish, the run's failure time, or the moment it parked on a human
+ * (`pausedAt`) so a mid-flight step (no `finishedAt`) doesn't tick up forever.
+ */
+export function useStepTimer(opts: {
+  step: () => PipelineStep | null
+  runFailed: () => boolean
+  failureAt: () => number | null | undefined
+}) {
+  // A 1s tick so a still-running step's elapsed time counts up live while open.
+  const nowTick = ref(0)
+  let timer: ReturnType<typeof setInterval> | undefined
+  onMounted(() => {
+    nowTick.value = Date.now()
+    timer = setInterval(() => (nowTick.value = Date.now()), 1000)
+  })
+  onUnmounted(() => {
+    if (timer) clearInterval(timer)
+  })
+
+  // A step that is finished, failed, or parked on a human is not actively
+  // executing — no ticking clock or spinner. `pausedAt` is the "waiting on input"
+  // freeze.
+  const isRunning = computed(() => {
+    const s = opts.step()
+    return !!s?.startedAt && !s?.finishedAt && s?.pausedAt == null && !opts.runFailed()
+  })
+
+  /** Elapsed/total execution time in ms — null until the step has started. */
+  const durationMs = computed(() => {
+    const s = opts.step()
+    if (s?.startedAt == null) return null
+    // Freeze the clock once the step stops working: at its finish, else at the
+    // failure time once the run has failed, else at the moment it parked on a
+    // human (`pausedAt`). Otherwise it is live, so count up to the current tick.
+    const end =
+      s.finishedAt ??
+      (opts.runFailed() ? (opts.failureAt() ?? s.startedAt) : (s.pausedAt ?? nowTick.value))
+    return Math.max(0, end - s.startedAt)
+  })
+
+  const durationLabel = computed(() =>
+    durationMs.value == null ? null : formatDuration(durationMs.value),
+  )
+
+  return { isRunning, durationMs, durationLabel }
+}
+
+function formatDuration(ms: number): string {
+  const totalSec = Math.round(ms / 1000)
+  if (totalSec < 60) return `${totalSec}s`
+  const m = Math.floor(totalSec / 60)
+  const sec = totalSec % 60
+  if (m < 60) return sec ? `${m}m ${sec}s` : `${m}m`
+  const h = Math.floor(m / 60)
+  const min = m % 60
+  return min ? `${h}h ${min}m` : `${h}h`
+}

package/app/composables/useTaskExpansion.ts

@@ -0,0 +1,92 @@
+import type { Ref } from 'vue'
+import { onMounted, onBeforeUnmount } from 'vue'
+import { useRafFn } from '@vueuse/core'
+import { lodAtLeast } from '~/composables/useSemanticZoom'
+
+type Rect = { left: number; right: number; top: number; bottom: number }
+
+function intersects(a: Rect, b: Rect) {
+  return a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top
+}
+
+function sameSet(a: Set<string>, b: Set<string>) {
+  if (a.size !== b.size) return false
+  for (const id of a) if (!b.has(id)) return false
+  return true
+}
+
+/**
+ * Board-level driver deciding which task cards may expand their full pipeline list
+ * once zoomed in (the deep `steps`/`subtasks` bands). Two gates, recomputed every
+ * frame against live DOM rects so they follow pan / zoom / drag / resize:
+ *
+ *  - visibility: a task expands only while its card overlaps the board viewport.
+ *  - overlap: walking the visible candidates nearest-to-screen-centre first, a task
+ *    expands only if its footprint doesn't collide with one already granted, so the
+ *    centre-most task wins an overlap and the rest stay compact.
+ *
+ * Writes the permitted id set into the `taskExpansion` store; `TaskPipelineMini` reads it.
+ * Only tasks with a running pipeline (steps to show) are candidates — a task that
+ * wouldn't expand never blocks a neighbour.
+ */
+export function useTaskExpansion(container: Ref<HTMLElement | null>) {
+  const board = useBoardStore()
+  const execution = useExecutionStore()
+  const ui = useUiStore()
+  const store = useTaskExpansionStore()
+
+  function rectOf(id: string): DOMRect | null {
+    const el = document.querySelector(`[data-block-id="${id}"]`) as HTMLElement | null
+    return el ? el.getBoundingClientRect() : null
+  }
+
+  function recompute() {
+    // Task cards only expand at the deep zoom bands; clear everything otherwise.
+    if (!lodAtLeast(ui.lod, 'steps')) {
+      if (store.allowed.size) store.setAllowed(new Set())
+      return
+    }
+    const view = container.value?.getBoundingClientRect()
+    if (!view) return
+    const cx = view.left + view.width / 2
+    const cy = view.top + view.height / 2
+
+    const candidates: { id: string; rect: DOMRect; dist: number }[] = []
+    for (const t of board.allTasks) {
+      // Only tasks whose run actually has steps would expand a pipeline list.
+      if (!execution.getByBlock(t.id)?.steps.length) continue
+      const rect = rectOf(t.id)
+      if (!rect) continue
+      // Visibility: the card must intersect the board viewport.
+      if (!intersects(rect, view)) continue
+      // Stable anchor: the card's top-centre. It doesn't move as the card grows
+      // downward, so the ordering can't oscillate as cards expand / collapse.
+      const ax = rect.left + rect.width / 2
+      const ay = rect.top
+      const dist = (ax - cx) ** 2 + (ay - cy) ** 2
+      candidates.push({ id: t.id, rect, dist })
+    }
+    candidates.sort((a, b) => a.dist - b.dist)
+
+    // Greedy by distance to centre: a candidate is granted only if its rect clears
+    // every rect already granted, so the centre-most card wins any overlap.
+    const claimed: DOMRect[] = []
+    const next = new Set<string>()
+    for (const c of candidates) {
+      if (claimed.some((r) => intersects(c.rect, r))) continue
+      next.add(c.id)
+      claimed.push(c.rect)
+    }
+    if (!sameSet(next, store.allowed)) store.setAllowed(next)
+  }
+
+  const { pause, resume } = useRafFn(recompute, { immediate: false })
+  onMounted(() => {
+    store.setDriverActive(true)
+    resume()
+  })
+  onBeforeUnmount(() => {
+    pause()
+    store.setDriverActive(false)
+  })
+}

package/app/composables/useWorkspaceStream.ts

@@ -0,0 +1,155 @@
+import { ref, onScopeDispose } from 'vue'
+import type { WorkspaceEvent } from '~/types/domain'
+
+/**
+ * Subscribes to the backend's per-workspace WebSocket event stream and keeps the
+ * board in sync in real time — the replacement for the old polling clock. Mount
+ * once (e.g. on the board page) after the workspace is ready.
+ *
+ * `execution` events patch the run + its block directly; `bootstrap` events patch
+ * a repo-bootstrap run + its service frame (live "bootstrapping…" progress); the
+ * coarse `board` event (module materialised, run cancelled) triggers a debounced
+ * full refresh. On every (re)connect we refresh once to reconcile anything missed
+ * while disconnected, so the server stays the source of truth and a dropped socket
+ * self-heals.
+ */
+export function useWorkspaceStream() {
+  const workspace = useWorkspaceStore()
+  const execution = useExecutionStore()
+  const board = useBoardStore()
+  const agentRuns = useAgentRunsStore()
+  const notifications = useNotificationsStore()
+  const observability = useObservabilityStore()
+  const requirements = useRequirementsStore()
+  const consensus = useConsensusStore()
+  const clarity = useClarityStore()
+  const api = useApi()
+  const apiBase = useRuntimeConfig().public.apiBase
+
+  const connected = ref(false)
+
+  let socket: WebSocket | null = null
+  let stopped = false
+  let attempt = 0
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  let boardDebounce: ReturnType<typeof setTimeout> | null = null
+
+  // http→ws, https→wss (apiBase is an absolute origin, see nuxt.config.ts).
+  const wsBase = String(apiBase).replace(/^http/, 'ws')
+
+  function debouncedBoardRefresh() {
+    if (boardDebounce) clearTimeout(boardDebounce)
+    boardDebounce = setTimeout(() => void workspace.refresh(), 300)
+  }
+
+  function onMessage(raw: string) {
+    let event: WorkspaceEvent
+    try {
+      event = JSON.parse(raw) as WorkspaceEvent
+    } catch {
+      return
+    }
+    if (event.type === 'execution') {
+      // Full instance drives the step-level UI; agentRuns derives its coarse
+      // failure/retry summary from the same store, so no extra call is needed.
+      execution.upsert(event.instance)
+      if (event.block) board.upsert(event.block)
+    } else if (event.type === 'board') {
+      debouncedBoardRefresh()
+    } else if (event.type === 'bootstrap') {
+      // Patch the run's live status/subtasks and its provisional/linked frame so
+      // the "bootstrapping…" card updates in place (then flips to a ready service
+      // or a failed badge) without a full refresh.
+      agentRuns.upsertBootstrap(event.job)
+      if (event.block) board.upsert(event.block)
+    } else if (event.type === 'notification') {
+      // A PR needs a merge decision, a pipeline finished, or CI gave up — patch the
+      // inbox + per-block badge in place (resolved ones drop out of the inbox).
+      notifications.upsert(event.notification)
+    } else if (event.type === 'llmCall') {
+      // A container agent just made a model call — fold the compact summary into the
+      // observability store so an open "Model activity" panel updates live (and keeps
+      // updating even when the durable driver is evicted: the proxy emits these
+      // independently of the run's poll loop).
+      observability.appendCall(event.call)
+    } else if (event.type === 'requirements') {
+      // The async incorporate + re-review cycle changed a review's status — patch the cache
+      // so an open review window / inspector reflects it live ("incorporating…" → the next
+      // cycle / converged). The summons back, when needed, arrives as a `notification`.
+      requirements.upsert(event.review)
+    } else if (event.type === 'consensus') {
+      // A consensus session advanced (a round landed, the synthesis completed, or it
+      // failed) — patch the cache so an open Consensus Session window renders the
+      // multi-model process live, round by round.
+      consensus.upsert(event.session)
+    } else if (event.type === 'clarity') {
+      // The async incorporate + re-review cycle changed a clarity review's status — patch the
+      // cache so an open review window / inspector reflects it live ("incorporating…" → the
+      // next cycle / converged). The summons back, when needed, arrives as a `notification`.
+      clarity.upsert(event.review)
+    }
+  }
+
+  async function connect() {
+    if (stopped || !workspace.workspaceId) return
+    const workspaceId = workspace.workspaceId
+
+    // A browser can't set Authorization on a WS handshake, so mint a short-lived,
+    // workspace-scoped ticket over the authenticated REST channel and pass it as
+    // `?ticket=`. Empty when auth is disabled (dev) — the handshake is open then.
+    let ticket: string
+    try {
+      ticket = (await api.mintEventsTicket(workspaceId)).ticket
+    } catch {
+      // Couldn't mint (offline, token lapsed) — back off and retry.
+      scheduleReconnect()
+      return
+    }
+    // A workspace switch (or stop()) may have happened while awaiting the mint.
+    if (stopped || workspace.workspaceId !== workspaceId) return
+
+    const query = ticket ? `?ticket=${encodeURIComponent(ticket)}` : ''
+    socket = new WebSocket(`${wsBase}/workspaces/${workspaceId}/events${query}`)
+
+    socket.onopen = () => {
+      attempt = 0
+      connected.value = true
+      // Resync on (re)connect: any event missed while disconnected is reconciled.
+      // The snapshot carries `bootstrapJobs` + executions, so one refresh rehydrates
+      // agentRuns too — a missed terminal event (e.g. a container eviction that
+      // failed the run) can't leave a frame stuck on a stale "bootstrapping…" badge.
+      void workspace.refresh()
+    }
+    socket.onmessage = (e) => onMessage(typeof e.data === 'string' ? e.data : '')
+    socket.onclose = () => {
+      connected.value = false
+      scheduleReconnect()
+    }
+    socket.onerror = () => socket?.close()
+  }
+
+  function scheduleReconnect() {
+    if (stopped) return
+    socket = null
+    const delay = Math.min(30_000, 500 * 2 ** attempt) // 0.5s → 30s cap
+    attempt += 1
+    reconnectTimer = setTimeout(connect, delay)
+  }
+
+  function start() {
+    stopped = false
+    connect()
+  }
+
+  function stop() {
+    stopped = true
+    if (reconnectTimer) clearTimeout(reconnectTimer)
+    if (boardDebounce) clearTimeout(boardDebounce)
+    socket?.close()
+    socket = null
+    connected.value = false
+  }
+
+  onScopeDispose(stop)
+  return { start, stop, connected }
+}

package/app/docs/architecture.md

@@ -0,0 +1,31 @@
+# Frontend architecture — state & data flow
+
+How the SPA stays in sync with the backend. The app is a **thin client**: it holds
+no business logic, calls the Worker for every mutation, and hydrates its stores
+from server snapshots plus pushed events. For the high-level tour see
+[`../README.md`](../README.md).
+
+## The three paths
+
+```
+REST (useApi)  ─────────────▶  Worker  ─────────────▶  D1
+   ▲                                                    │
+   │ mutations                                          │ persisted transition
+stores (Pinia)  ◀── patch ──  useWorkspaceStream  ◀── WebSocket push (events hub)
+```
+
+- **Read path** — the `workspace` store loads the full snapshot and fans it into
+  `board`, `pipelines`, `execution`, `spend`, etc.
+- **Write path** — components call `useApi` → Worker; the response (or a pushed
+  event) patches the relevant store. No optimistic business logic.
+- **Live path** — `useWorkspaceStream` opens one WebSocket to
+  `GET /workspaces/:ws/events?token=…`, patches `execution` / `agentRuns` /
+  `board` as events arrive, and refreshes on reconnect to reconcile anything
+  missed.
+
+## Stores
+
+One Pinia store per feature domain: `workspace`, `accounts`, `auth`, `board`,
+`ui`, `pipelines`, `agents`, `execution`, `agentRuns`, `models`, `github`,
+`bootstrap`, `documents`, `tasks`, `requirements`, `scenarios`, `fragments`
+(built-in catalog), `fragmentLibrary` (tenant tiers + sources), and `spend`.

package/app/pages/index.vue

@@ -0,0 +1,141 @@
+<script setup lang="ts">
+import BoardCanvas from '~/components/board/BoardCanvas.vue'
+import SideBar from '~/components/layout/SideBar.vue'
+import BoardToolbar from '~/components/layout/BoardToolbar.vue'
+import SpendWarningBanner from '~/components/layout/SpendWarningBanner.vue'
+import GitHubPatBanner from '~/components/layout/GitHubPatBanner.vue'
+import PipelineBuilder from '~/components/pipeline/PipelineBuilder.vue'
+import InspectorPanel from '~/components/panels/InspectorPanel.vue'
+import DecisionModal from '~/components/panels/DecisionModal.vue'
+import AgentStepDetail from '~/components/panels/AgentStepDetail.vue'
+import StepResultViewHost from '~/components/panels/StepResultViewHost.vue'
+import ObservabilityPanel from '~/components/panels/ObservabilityPanel.vue'
+import BlockFocusView from '~/components/focus/BlockFocusView.vue'
+import DocumentSourceConnectModal from '~/components/documents/DocumentSourceConnectModal.vue'
+import DocumentImportModal from '~/components/documents/DocumentImportModal.vue'
+import SpawnPreviewModal from '~/components/documents/SpawnPreviewModal.vue'
+import TaskSourceConnectModal from '~/components/tasks/TaskSourceConnectModal.vue'
+import TaskImportModal from '~/components/tasks/TaskImportModal.vue'
+import AddTaskModal from '~/components/board/AddTaskModal.vue'
+import RecurringPipelineModal from '~/components/board/RecurringPipelineModal.vue'
+import BootstrapModal from '~/components/bootstrap/BootstrapModal.vue'
+import AddServiceFromRepoModal from '~/components/github/AddServiceFromRepoModal.vue'
+import GitHubPanel from '~/components/github/GitHubPanel.vue'
+import SlackPanel from '~/components/slack/SlackPanel.vue'
+import GitHubOnboarding from '~/components/github/GitHubOnboarding.vue'
+import FragmentLibraryPanel from '~/components/fragments/FragmentLibraryPanel.vue'
+import CommandBar from '~/components/layout/CommandBar.vue'
+import MergeThresholdsPanel from '~/components/settings/MergeThresholdsPanel.vue'
+import WorkspaceSettingsPanel from '~/components/settings/WorkspaceSettingsPanel.vue'
+import DatadogPanel from '~/components/settings/DatadogPanel.vue'
+import ModelDefaultsPanel from '~/components/settings/ModelDefaultsPanel.vue'
+import ServiceFragmentDefaultsPanel from '~/components/settings/ServiceFragmentDefaultsPanel.vue'
+import LocalModelEndpointsPanel from '~/components/settings/LocalModelEndpointsPanel.vue'
+
+const workspace = useWorkspaceStore()
+const github = useGitHubStore()
+
+// Load the board from the backend before rendering it.
+onMounted(() => workspace.init())
+
+// Probe the GitHub integration as soon as a board is active (re-probe per board —
+// connections are per workspace). The result drives the onboarding gate below
+// before the board mounts, so an unconnected user can't slip past it. SideBar
+// re-probes once it mounts; that duplicate is harmless (probe is idempotent).
+watch(
+  () => workspace.workspaceId,
+  (id) => {
+    if (id) void github.probe()
+  },
+  { immediate: true },
+)
+
+// Hard gate: the App is enabled on the backend but this workspace has no
+// installation yet. `available === null` means the probe is still in flight.
+const needsGitHubInstall = computed(() => github.available === true && !github.connected)
+const githubProbePending = computed(() => github.available === null)
+
+// Subscribe to the backend's real-time event stream and (re)connect whenever the
+// active workspace changes. Runs advance durably server-side; progress arrives as
+// pushed events rather than by polling.
+const stream = useWorkspaceStream()
+watch(
+  () => workspace.workspaceId,
+  (id) => {
+    stream.stop()
+    if (id) stream.start()
+  },
+  { immediate: true },
+)
+</script>
+
+<template>
+  <div class="flex h-screen w-screen overflow-hidden bg-slate-950 text-slate-100">
+    <!-- Local-mode setup prompt (missing GitHub PAT); floats over whatever is shown below. -->
+    <GitHubPatBanner />
+
+    <!-- Resolving whether the GitHub App is installed, before we decide what to show. -->
+    <div
+      v-if="workspace.ready && githubProbePending"
+      class="m-auto flex flex-col items-center gap-3 text-slate-400"
+    >
+      <UIcon name="i-lucide-loader" class="h-8 w-8 animate-spin" />
+      <span class="text-sm">Loading…</span>
+    </div>
+
+    <!-- App enabled but not installed on this workspace: hard onboarding gate. -->
+    <GitHubOnboarding v-else-if="workspace.ready && needsGitHubInstall" />
+
+    <template v-else-if="workspace.ready">
+      <SideBar />
+      <main class="relative min-w-0 flex-1">
+        <BoardCanvas />
+        <BoardToolbar />
+        <SpendWarningBanner />
+        <InspectorPanel />
+        <BlockFocusView />
+      </main>
+
+      <PipelineBuilder />
+      <DecisionModal />
+      <AgentStepDetail />
+      <StepResultViewHost />
+      <ObservabilityPanel />
+      <DocumentSourceConnectModal />
+      <DocumentImportModal />
+      <SpawnPreviewModal />
+      <TaskSourceConnectModal />
+      <TaskImportModal />
+      <AddTaskModal />
+      <RecurringPipelineModal />
+      <BootstrapModal />
+      <AddServiceFromRepoModal />
+      <GitHubPanel />
+      <SlackPanel />
+      <FragmentLibraryPanel />
+      <CommandBar />
+      <MergeThresholdsPanel />
+      <WorkspaceSettingsPanel />
+      <DatadogPanel />
+      <ModelDefaultsPanel />
+      <ServiceFragmentDefaultsPanel />
+      <LocalModelEndpointsPanel />
+    </template>
+
+    <!-- Backend unreachable / bootstrap failed -->
+    <div v-else-if="workspace.error" class="m-auto max-w-md p-8 text-center">
+      <UIcon name="i-lucide-plug-zap" class="mx-auto mb-3 h-10 w-10 text-amber-400" />
+      <h1 class="mb-1 text-lg font-semibold">Can’t reach the backend</h1>
+      <p class="mb-4 text-sm text-slate-400">{{ workspace.error }}</p>
+      <UButton color="primary" icon="i-lucide-rotate-ccw" @click="workspace.init()">
+        Retry
+      </UButton>
+    </div>
+
+    <!-- Initial load -->
+    <div v-else class="m-auto flex flex-col items-center gap-3 text-slate-400">
+      <UIcon name="i-lucide-loader" class="h-8 w-8 animate-spin" />
+      <span class="text-sm">Loading board…</span>
+    </div>
+  </div>
+</template>