code-coordinator 0.5.46__py3-none-any.whl

coord/dashboard/webapp/src/realtime/connection.ts

@@ -0,0 +1,227 @@
+/**
+ * Framework-agnostic SSE client: owns one `EventSource`-shaped connection,
+ * reconnects with exponential backoff + jitter, and reports an honest
+ * connection state so the UI never shows stale data as if it were live
+ * (#1549).
+ *
+ * Deliberately decoupled from React and from `@tanstack/react-query` — this
+ * module only knows how to keep a stream open and tell you what it's typed
+ * events say and what state the stream is in. `RealtimeProvider.tsx` is the
+ * thin layer that wires those events to query-key invalidation.
+ *
+ * ## The StrictMode double-mount trap
+ *
+ * React 18 `<StrictMode>` mounts every component twice in dev: mount → effect
+ * → cleanup → mount → effect. A naive `useEffect(() => { const es = new
+ * EventSource(url); return () => es.close() }, [])` is fine on its own, but
+ * once reconnect/backoff state lives outside the effect (as it must, to
+ * survive a single real disconnect) two failure modes appear:
+ *
+ * 1. A "closed" flag set by the first cleanup is never cleared by the second
+ *    mount's `start()`, so the second, real connection silently never
+ *    retries after its first drop.
+ * 2. The first `EventSource`'s `onerror`/`onopen` fires *after* the second
+ *    `start()` has already begun (both are async), stomping the real
+ *    connection's state with a stale one.
+ *
+ * `start()` fixes (1) by unconditionally resetting all intent/backoff state
+ * — "intent flags reset in `connect()`", not read from whatever the last
+ * `stop()` left behind. `stop()`/`start()` fix (2) by minting a new `token`
+ * on every call and closing over it in each socket's callbacks; a callback
+ * whose captured token no longer matches the connection's current token
+ * belongs to a superseded socket and is dropped ("onclose guarded"). This is
+ * the same shape whether the second `start()` comes from StrictMode's replay
+ * or from a real remount, so there is exactly one code path to test.
+ */
+
+// ── Public types ─────────────────────────────────────────────────────────────
+
+/**
+ * `disconnected` and `reconnecting` are deliberately distinct: the instant a
+ * live stream drops we know only that it's stale (`disconnected`); once a
+ * retry attempt is actually in flight the UI can say so (`reconnecting`).
+ * `connecting` is the pre-first-connect state, shown only until the very
+ * first `open` (or first failure, which moves to `disconnected` too).
+ */
+export type ConnectionState = 'connecting' | 'live' | 'disconnected' | 'reconnecting'
+
+export interface ConnectionStatus {
+  state: ConnectionState
+  /** epoch ms the stream was last confirmed open, or null before the first successful connect. */
+  lastLiveAt: number | null
+  /** consecutive failed attempts since the last live connection (0 while live or before the first attempt has failed). */
+  attempt: number
+}
+
+/** The slice of the browser `EventSource` API this module depends on. */
+export interface SseHandle {
+  close(): void
+  addEventListener(type: string, listener: (ev: { data: string }) => void): void
+  onopen: ((ev: unknown) => void) | null
+  onerror: ((ev: unknown) => void) | null
+}
+
+export type EventSourceFactory = (url: string) => SseHandle
+
+export interface SseConnectionOptions {
+  url: string
+  /** SSE `event:` names to subscribe to; anything else on the stream is ignored. */
+  eventTypes: readonly string[]
+  /** Called for each received event, already JSON-parsed (raw string if parsing fails). */
+  onEvent: (type: string, data: unknown) => void
+  /** Called whenever the connection state machine transitions. */
+  onStatusChange: (status: ConnectionStatus) => void
+  /** Defaults to the browser's native `EventSource`; overridable for tests. */
+  createEventSource?: EventSourceFactory
+  /** Backoff delays in ms, one per consecutive failed attempt; the last entry repeats. */
+  backoffScheduleMs?: readonly number[]
+  /** Fractional +/- jitter applied to each backoff delay. Default 0.2; tests pass 0 for exact timing. */
+  jitterFraction?: number
+  now?: () => number
+  setTimeoutFn?: typeof setTimeout
+  clearTimeoutFn?: typeof clearTimeout
+}
+
+export interface SseConnection {
+  /** (Re)start the connection, resetting all backoff/intent state. Safe to call while already running. */
+  start(): void
+  /** Stop for good: closes the socket, cancels any pending retry, no further callbacks fire. */
+  stop(): void
+}
+
+// ── Defaults ─────────────────────────────────────────────────────────────────
+
+/** 1s, 2s, 4s, 8s, 15s, then capped at 30s — gentle enough for a single tab, fast enough to feel alive. */
+export const DEFAULT_BACKOFF_MS: readonly number[] = [1_000, 2_000, 4_000, 8_000, 15_000, 30_000]
+
+/** +/- 20% jitter so a daemon restart doesn't get every tab retrying in lockstep. */
+const DEFAULT_JITTER_FRACTION = 0.2
+
+function withJitter(baseMs: number, jitterFraction: number): number {
+  const jitter = baseMs * jitterFraction * (Math.random() * 2 - 1)
+  return Math.max(0, Math.round(baseMs + jitter))
+}
+
+function defaultEventSourceFactory(url: string): SseHandle {
+  return new EventSource(url) as unknown as SseHandle
+}
+
+// ── Implementation ───────────────────────────────────────────────────────────
+
+export function createSseConnection(options: SseConnectionOptions): SseConnection {
+  const {
+    url,
+    eventTypes,
+    onEvent,
+    onStatusChange,
+    createEventSource = defaultEventSourceFactory,
+    backoffScheduleMs = DEFAULT_BACKOFF_MS,
+    jitterFraction = DEFAULT_JITTER_FRACTION,
+    now = () => Date.now(),
+    setTimeoutFn = setTimeout,
+    clearTimeoutFn = clearTimeout,
+  } = options
+
+  // Bumped by every start()/stop(); a socket's callbacks close over the token
+  // in effect when they were wired up and no-op once it's stale. This is what
+  // makes a superseded (StrictMode-cleaned-up, or genuinely replaced) socket
+  // inert instead of racing the current one.
+  let token = 0
+  let socket: SseHandle | null = null
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let attempt = 0
+  let lastLiveAt: number | null = null
+
+  function emitStatus(state: ConnectionState): void {
+    onStatusChange({ state, lastLiveAt, attempt })
+  }
+
+  function clearPendingRetry(): void {
+    if (timer !== null) {
+      clearTimeoutFn(timer)
+      timer = null
+    }
+  }
+
+  function closeSocket(): void {
+    if (socket !== null) {
+      socket.close()
+      socket = null
+    }
+  }
+
+  function scheduleRetry(myToken: number): void {
+    // `attempt` counts consecutive failures and was just incremented by
+    // handleFailure(), so attempt 1 (the first retry) indexes schedule[0].
+    const scheduleIndex = Math.min(attempt - 1, backoffScheduleMs.length - 1)
+    const delay = withJitter(backoffScheduleMs[scheduleIndex], jitterFraction)
+    timer = setTimeoutFn(() => {
+      timer = null
+      if (myToken !== token) return
+      openSocket(myToken)
+    }, delay)
+  }
+
+  function handleFailure(myToken: number): void {
+    if (myToken !== token) return
+    closeSocket()
+    attempt += 1
+    emitStatus('disconnected')
+    scheduleRetry(myToken)
+  }
+
+  function openSocket(myToken: number): void {
+    if (myToken !== token) return
+    emitStatus(attempt > 0 ? 'reconnecting' : 'connecting')
+
+    let handle: SseHandle
+    try {
+      handle = createEventSource(url)
+    } catch {
+      handleFailure(myToken)
+      return
+    }
+    socket = handle
+
+    handle.onopen = () => {
+      if (myToken !== token) return
+      attempt = 0
+      lastLiveAt = now()
+      emitStatus('live')
+    }
+    handle.onerror = () => {
+      handleFailure(myToken)
+    }
+    for (const type of eventTypes) {
+      handle.addEventListener(type, (ev) => {
+        if (myToken !== token) return
+        onEvent(type, parsePayload(ev.data))
+      })
+    }
+  }
+
+  return {
+    start(): void {
+      token += 1
+      const myToken = token
+      attempt = 0
+      clearPendingRetry()
+      closeSocket()
+      openSocket(myToken)
+    },
+    stop(): void {
+      token += 1
+      clearPendingRetry()
+      closeSocket()
+    },
+  }
+}
+
+function parsePayload(raw: string): unknown {
+  if (!raw) return null
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return raw
+  }
+}

coord/dashboard/webapp/src/realtime/events.ts

@@ -0,0 +1,100 @@
+/**
+ * The SSE wire vocabulary + which react-query keys each event type affects.
+ *
+ * NOT just a mirror of `coord/events.py`'s `KNOWN_EVENT_TYPES` — the
+ * dashboard server publishes three more event types of its own
+ * (`coord/dashboard/server.py`: `ASSIGNMENT_CANCELLED`, `ASSIGNMENT_ADVISORY`,
+ * `ASSIGNMENT_NEEDS_ATTENTION`, all pre-existing, not `coord.events`
+ * constants). `openSocket()` in `connection.ts` only registers a listener
+ * for the `event:` names in `EVENT_TYPES`, so any real server event type
+ * missing from this list is simply never delivered to a handler — it is
+ * *not* caught by `board_updated`'s catch-all invalidation, because that
+ * catch-all only fires for events the client actually subscribed to. This
+ * list must therefore cover every event type the dashboard server can
+ * publish, not just `coord.events.KNOWN_EVENT_TYPES`. Keep it in sync by
+ * hand — neither source is a `scripts/codegen.py` (#750) target (both are
+ * sets of string constants, not dataclasses).
+ *
+ * Query-key granularity here matches what the webapp already has: there is
+ * no per-assignment `['pipeline', id]` key (Detail.tsx reads the same
+ * `['pipeline']` list Home.tsx does), so "the precise query keys an event
+ * affects" bottoms out at `['pipeline']` and `['sessions']` — the two lists
+ * every event type below can change the shape of.
+ *
+ * TODO: once a per-assignment key (`['pipeline', id]`) or `['diff', id]`
+ * gets folded into SSE invalidation, revisit every entry below — today they
+ * all just invalidate the coarse lists.
+ */
+
+export const ASSIGNMENT_STARTED = 'assignment_started'
+export const ASSIGNMENT_COMPLETED = 'assignment_completed'
+export const ASSIGNMENT_FAILED = 'assignment_failed'
+// The three below are dashboard-server-only (coord/dashboard/server.py),
+// not coord.events.KNOWN_EVENT_TYPES -- see the module doc comment above.
+export const ASSIGNMENT_CANCELLED = 'assignment_cancelled'
+export const ASSIGNMENT_ADVISORY = 'assignment_advisory'
+export const ASSIGNMENT_NEEDS_ATTENTION = 'assignment_needs_attention'
+export const MACHINE_CONNECTED = 'machine_connected'
+export const MACHINE_DISCONNECTED = 'machine_disconnected'
+export const BOARD_UPDATED = 'board_updated'
+
+/** Every event type the client subscribes to on `/events`. */
+export const EVENT_TYPES = [
+  ASSIGNMENT_STARTED,
+  ASSIGNMENT_COMPLETED,
+  ASSIGNMENT_FAILED,
+  ASSIGNMENT_CANCELLED,
+  ASSIGNMENT_ADVISORY,
+  ASSIGNMENT_NEEDS_ATTENTION,
+  MACHINE_CONNECTED,
+  MACHINE_DISCONNECTED,
+  BOARD_UPDATED,
+] as const
+
+/** A react-query `queryKey`. */
+export type QueryKey = readonly unknown[]
+
+const PIPELINE: QueryKey = ['pipeline']
+const SESSIONS: QueryKey = ['sessions']
+
+/**
+ * Event type -> the query keys it invalidates.
+ *
+ * - `assignment_*` (including the dashboard-server-only `_cancelled` /
+ *   `_advisory` / `_needs_attention` variants) changes an item's
+ *   stage/verdict/needs-attention flag (-> pipeline) and can start/stop a
+ *   live `coord-*` tmux session (-> sessions).
+ * - `machine_*` only affects session reachability/attach state (-> sessions).
+ * - `board_updated` is the background poller's coarse "something may have
+ *   changed" heartbeat (every 30s server-side, `coord/dashboard/server.py`
+ *   `_POLL_INTERVAL`) — treated as a catch-all for both lists so a change
+ *   this event vocabulary doesn't yet name specifically still surfaces
+ *   within one heartbeat instead of never. It is a catch-all for *unnamed*
+ *   changes only, not a substitute for subscribing to a named event type —
+ *   a type missing from `EVENT_TYPES` above never reaches this map at all
+ *   (see that constant's doc comment).
+ */
+export const EVENT_QUERY_KEYS: Readonly<Record<string, readonly QueryKey[]>> = {
+  [ASSIGNMENT_STARTED]: [PIPELINE, SESSIONS],
+  [ASSIGNMENT_COMPLETED]: [PIPELINE, SESSIONS],
+  [ASSIGNMENT_FAILED]: [PIPELINE, SESSIONS],
+  [ASSIGNMENT_CANCELLED]: [PIPELINE, SESSIONS],
+  [ASSIGNMENT_ADVISORY]: [PIPELINE, SESSIONS],
+  [ASSIGNMENT_NEEDS_ATTENTION]: [PIPELINE],
+  [MACHINE_CONNECTED]: [SESSIONS],
+  [MACHINE_DISCONNECTED]: [SESSIONS],
+  [BOARD_UPDATED]: [PIPELINE, SESSIONS],
+}
+
+/**
+ * Invalidated on every `disconnected`/`reconnecting` -> `live` recovery,
+ * regardless of which events fired.
+ *
+ * The server's event history ring buffer (`EventSource` in `coord/events.py`,
+ * `DEFAULT_HISTORY_SIZE = 256`) lets a reconnecting client backfill via
+ * `Last-Event-ID` — but a long enough drop can overflow it, and a daemon
+ * restart resets it (and the id sequence) entirely. Backfill is best-effort;
+ * an explicit resync on recovery is what makes "live" mean "correct", not
+ * just "the socket is open again".
+ */
+export const RESYNC_QUERY_KEYS: readonly QueryKey[] = [PIPELINE, SESSIONS]

coord/dashboard/webapp/src/routes/__tests__/paths.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Unit tests for the route tree's path builders (#1548).
+ *
+ * `paths` and `shellViewFromPath` are the trust boundary between "what the
+ * URL says" and "what the shell renders" — `ShellLayout` and every list
+ * panel import from here rather than templating strings themselves, so a bug
+ * here is a bug everywhere at once. Worth its own focused coverage.
+ */
+import { describe, it, expect } from 'vitest'
+import { RAIL_VIEW_PATH, isDetailTab, paths, shellViewFromPath } from '../paths'
+
+describe('paths.pipelineItem', () => {
+  it('builds the two-segment form with no tab', () => {
+    expect(paths.pipelineItem('myrepo', 42)).toBe('/pipeline/myrepo/42')
+  })
+
+  it('collapses the default "overview" tab back to the two-segment form', () => {
+    expect(paths.pipelineItem('myrepo', 42, 'overview')).toBe('/pipeline/myrepo/42')
+  })
+
+  it('appends a non-default tab as a third segment', () => {
+    expect(paths.pipelineItem('myrepo', 42, 'log')).toBe('/pipeline/myrepo/42/log')
+  })
+
+  it('encodes a repo name that needs escaping (an owner/name slug)', () => {
+    expect(paths.pipelineItem('owner/name', 42)).toBe('/pipeline/owner%2Fname/42')
+  })
+
+  it('accepts a string issue number unchanged', () => {
+    expect(paths.pipelineItem('myrepo', '42')).toBe('/pipeline/myrepo/42')
+  })
+})
+
+describe('paths.session / paths.terminal', () => {
+  it('encodes the session id', () => {
+    expect(paths.session('a b')).toBe('/sessions/a%20b')
+    expect(paths.terminal('a b')).toBe('/terminal/a%20b')
+  })
+})
+
+describe('isDetailTab', () => {
+  it('accepts every member of the detail tab set', () => {
+    for (const tab of ['overview', 'issue', 'log', 'findings', 'summary']) {
+      expect(isDetailTab(tab)).toBe(true)
+    }
+  })
+
+  it('rejects an unknown or missing value', () => {
+    expect(isDetailTab('bogus')).toBe(false)
+    expect(isDetailTab(undefined)).toBe(false)
+  })
+})
+
+describe('shellViewFromPath', () => {
+  it('resolves the base path for every rail-selectable view', () => {
+    expect(shellViewFromPath(paths.pipeline())).toBe('pipeline')
+    expect(shellViewFromPath(paths.sessions())).toBe('sessions')
+    expect(shellViewFromPath(paths.board())).toBe('board')
+    expect(shellViewFromPath(paths.machines())).toBe('machines')
+    expect(shellViewFromPath(paths.mergeQueue())).toBe('merge-queue')
+    expect(shellViewFromPath(paths.milestones())).toBe('milestones')
+    expect(shellViewFromPath(paths.audit())).toBe('audit')
+    expect(shellViewFromPath(paths.spend())).toBe('spend')
+    expect(shellViewFromPath(paths.settings())).toBe('settings')
+  })
+
+  it('resolves an item route under its view', () => {
+    expect(shellViewFromPath(paths.pipelineItem('myrepo', 42))).toBe('pipeline')
+    expect(shellViewFromPath(paths.pipelineItem('myrepo', 42, 'log'))).toBe('pipeline')
+    expect(shellViewFromPath(paths.session('sess-1'))).toBe('sessions')
+  })
+
+  it('does not let one view path prefix-match another', () => {
+    // '/merge-queue' is not a sub-path of anything else in the map, but this
+    // guards the general case: a prefix match must respect the segment
+    // boundary (a trailing '/'), not just string startsWith.
+    expect(shellViewFromPath('/pipelines')).toBeNull()
+    expect(shellViewFromPath('/sessionsx')).toBeNull()
+  })
+
+  it('returns null for root, terminal, and unknown paths', () => {
+    expect(shellViewFromPath('/')).toBeNull()
+    expect(shellViewFromPath('/terminal/sess-1')).toBeNull()
+    expect(shellViewFromPath('/nope')).toBeNull()
+  })
+
+  it('every RAIL_VIEW_PATH entry round-trips through shellViewFromPath', () => {
+    for (const [view, base] of Object.entries(RAIL_VIEW_PATH)) {
+      expect(shellViewFromPath(base as string)).toBe(view)
+    }
+  })
+})

coord/dashboard/webapp/src/routes/paths.ts

@@ -0,0 +1,92 @@
+/**
+ * The route tree, in one place (#1548).
+ *
+ * Every screen the app can show has exactly one URL shape, built here rather
+ * than string-templated at each call site — a repo name with a `/` in it (a
+ * `owner/name` slug) or an id that needs escaping is a bug every hand-rolled
+ * template has to remember on its own; a path builder only has to get it
+ * right once. `Home`, `Detail`, `SessionsList`, `ShellLayout` and the e2e
+ * specs all import from here instead of writing template literals.
+ *
+ * `PipelineView` (see `src/api/generated.ts`) has no stable per-assignment
+ * URL-friendly id worth betting a bookmark on — `assignment_id` is one
+ * *attempt* at an issue (work, then a fix, then another fix carry different
+ * assignment ids for the same issue) — so the pipeline item route keys on
+ * `repo_name` + `issue_number`, which is what a human means by "that issue"
+ * and what a link pasted into a GitHub comment or Slack would naturally
+ * carry.
+ */
+import { type ShellView } from '@/shell/shellState'
+
+/** The `PipelineDetailTab` set (`docs/mocks/web/issue-detail.html`), minus
+ * Terminal — the tab *content* is M-W2 scope; this route tree only needs to
+ * know the tab is addressable and round-trips. `overview` is the default and
+ * is never present in a generated URL (see `pipelineItem` below). */
+export const DETAIL_TABS = ['overview', 'issue', 'log', 'findings', 'summary'] as const
+export type DetailTab = (typeof DETAIL_TABS)[number]
+
+export function isDetailTab(value: string | undefined): value is DetailTab {
+  return !!value && (DETAIL_TABS as readonly string[]).includes(value)
+}
+
+/** Path builders. Every one returns an absolute, already-encoded path. */
+export const paths = {
+  pipeline: () => '/pipeline',
+  /** `tab` omitted (or `'overview'`) collapses to the two-segment form —
+   * `/pipeline/repo/42`, not `/pipeline/repo/42/overview` — so the common
+   * case stays the short, shareable URL. */
+  pipelineItem: (repo: string, issue: number | string, tab?: DetailTab): string => {
+    const base = `/pipeline/${encodeURIComponent(repo)}/${encodeURIComponent(String(issue))}`
+    return tab && tab !== 'overview' ? `${base}/${tab}` : base
+  },
+  sessions: () => '/sessions',
+  session: (id: string) => `/sessions/${encodeURIComponent(id)}`,
+  terminal: (sessionId: string) => `/terminal/${encodeURIComponent(sessionId)}`,
+  board: () => '/board',
+  machines: () => '/machines',
+  mergeQueue: () => '/merge-queue',
+  milestones: () => '/milestones',
+  audit: () => '/audit',
+  spend: () => '/spend',
+  settings: () => '/settings',
+} as const
+
+/**
+ * Base path (no `:id`/`:tab`) for every rail-selectable view — what
+ * `ActivityRail`'s `onSelect` navigates to. Views with no route of their own
+ * (`terminal` is opened *from* a session, never navigated to directly) are
+ * omitted; `ActivityRail` never offers them as clickable (see
+ * `railItems.ts`'s `'soon'`/no-nav entries) so there is nothing to look up
+ * for those, but `Partial` keeps that honest here too rather than papering
+ * over it with a route that doesn't exist.
+ */
+export const RAIL_VIEW_PATH: Partial<Record<ShellView, string>> = {
+  pipeline: paths.pipeline(),
+  board: paths.board(),
+  sessions: paths.sessions(),
+  machines: paths.machines(),
+  'merge-queue': paths.mergeQueue(),
+  milestones: paths.milestones(),
+  audit: paths.audit(),
+  spend: paths.spend(),
+  settings: paths.settings(),
+}
+
+/**
+ * The inverse of `RAIL_VIEW_PATH` — which rail view a URL belongs to, for
+ * highlighting the right rail entry and picking the right list panel on cold
+ * load. `null` means the path doesn't belong to any known view (root `/`,
+ * `/terminal/...`, or a genuinely unknown route) — callers decide what that
+ * means for them rather than this function guessing a fallback.
+ */
+export function shellViewFromPath(pathname: string): ShellView | null {
+  const entries = Object.entries(RAIL_VIEW_PATH) as Array<[ShellView, string]>
+  // Longest prefix first: without this, '/merge-queue' would never win
+  // because nothing here is a prefix of it *except* itself, but this guards
+  // future entries where one path is a literal prefix of another.
+  const sorted = entries.sort((a, b) => b[1].length - a[1].length)
+  for (const [view, base] of sorted) {
+    if (pathname === base || pathname.startsWith(`${base}/`)) return view
+  }
+  return null
+}