@shendeguize/dsh-agent-sidecar 0.1.0

package/src/client/api.ts

@@ -0,0 +1,380 @@
+/**
+ * Browser-half data layer: same-origin fetch wrappers for the plugin's
+ * self-registered route namespace (design §5.3; server: src/routes.ts).
+ *
+ * Wire types below are hand-mirrored from the host half (routes.ts /
+ * session-store.ts / supervisor.ts / bridge.ts response shapes): the
+ * client TS program cannot import host modules because they live in the
+ * node-typed host program. The API_PREFIX mirror is pinned against the
+ * routes.ts constant by test/client-data.test.ts.
+ *
+ * Calls are same-origin relative paths with no auth headers (ADR-8 trust
+ * posture). Browser primitives — fetch, AbortController, timers — are
+ * injectable so everything runs under plain node in tests; defaults
+ * resolve from globalThis at call time. Pure data layer: no React, no
+ * slots SDK; the UI half imports its types from here.
+ *
+ * @module
+ */
+
+/** Route namespace; must mirror routes.ts `API_PREFIX` (pinned by test). */
+export const API_PREFIX = '/plugins/agent-sidecar/api'
+
+/** Default overall request deadline (design §5.3: 15s fetch timeout). */
+export const DEFAULT_TIMEOUT_MS = 15_000
+
+// ---------------------------------------------------------------------------
+// Wire types (host source of truth noted per type).
+// ---------------------------------------------------------------------------
+
+/** Daemon supervisor state machine states (host: supervisor.ts). */
+export type SupervisorState =
+  | 'probe'
+  | 'adopted'
+  | 'defer'
+  | 'reprobe'
+  | 'hosting'
+  | 'hosted'
+  | 'backoff'
+  | 'failed'
+
+/** Health of the host↔daemon subscribe stream (host: bridge.ts). */
+export type StreamHealth = 'ok' | 'degraded' | 'unknown'
+
+/** Daemon self-description from the Unix-socket ping (host: supervisor.ts). */
+export interface PingInfo {
+  pid: number
+  version: string
+  http: { enabled: boolean; host?: string; port?: number }
+}
+
+/** Compact most-recent-event summary per session (host: session-store.ts). */
+export interface SessionEventSummary {
+  ts: string
+  kind: string
+  text: string
+}
+
+/** One board row (host: session-store.ts). */
+export interface SessionView {
+  agent: string
+  session_id: string
+  status: string
+  title: string
+  project: string
+  updated_at: number
+  last_event: SessionEventSummary | null
+  /** True when a dsh seq discontinuity was observed since the last snapshot. */
+  gap: boolean
+}
+
+/** Full board state (host: session-store.ts). */
+export interface BoardState {
+  sessions: SessionView[]
+  streamHealth: StreamHealth
+  lastReconcileAt: number | null
+}
+
+/** Body of `GET state` and of every SSE `state` event (host: routes.ts). */
+export interface StateSnapshot {
+  daemon: { state: SupervisorState; lastPing: PingInfo | null }
+  board: BoardState
+  capabilities: { inject: boolean }
+}
+
+/** Body of `GET session/<id>` (host: routes.ts, M1 shape). */
+export interface SessionDetail {
+  session: SessionView
+  /** Always null in M1; the event timeline lands in M3. */
+  timeline: null
+  timelineNote: string
+}
+
+/** `POST action` body for injection phase one (host: routes.ts `handlePrepare`). */
+export interface PrepareActionBody {
+  type: 'inject.prepare'
+  target: { agent: string; sessionId: string }
+  mode: 'queue' | 'steer'
+  message: string
+}
+
+/** `POST action` body for injection phase two (host: routes.ts `handleExecute`). */
+export interface ExecuteActionBody {
+  type: 'inject.execute'
+  requestId: string
+  confirmToken: string
+  message: string
+}
+
+/** `POST action` body for daemon management (host: routes.ts `handleAction`). */
+export interface DaemonRetryActionBody {
+  type: 'daemon.retry'
+}
+
+/** Analysis target selector (host: routes.ts `AnalysisTargetRequest`). */
+export type AnalysisTargetKind = 'session' | 'project' | 'cross-agent'
+
+/** `POST action` body starting one analysis (host: routes.ts, M3). */
+export interface AnalysisRequestActionBody {
+  type: 'analysis.request'
+  targetKind: AnalysisTargetKind
+  /** Session id / project path; required for session and project kinds. */
+  targetId?: string
+  question?: string
+}
+
+/** `POST action` body asking a follow-up in a live analysis session. */
+export interface AnalysisFollowupActionBody {
+  type: 'analysis.followup'
+  analysisSessionId: string
+  question: string
+}
+
+/** `POST action` body releasing an analysis session (idempotent). */
+export interface AnalysisCancelActionBody {
+  type: 'analysis.cancel'
+  analysisSessionId: string
+}
+
+/**
+ * The action dispatcher envelope (host: routes.ts `handleAction`):
+ * a `{type, ...}` union with the phase fields at the top level. M2 inject
+ * phases + daemon management + the M3 `analysis.*` trio.
+ */
+export type ActionEnvelope =
+  | PrepareActionBody
+  | ExecuteActionBody
+  | DaemonRetryActionBody
+  | AnalysisRequestActionBody
+  | AnalysisFollowupActionBody
+  | AnalysisCancelActionBody
+
+// ---------------------------------------------------------------------------
+// Injectable browser primitives (structural, so node tests can fake them).
+// ---------------------------------------------------------------------------
+
+/** Opaque timer handle so DOM numbers and fake-timer handles interoperate. */
+export type TimerHandle = unknown
+
+export interface AbortSignalLike {
+  readonly aborted: boolean
+  addEventListener(type: 'abort', listener: () => void): void
+  removeEventListener(type: 'abort', listener: () => void): void
+}
+
+export interface AbortControllerLike {
+  readonly signal: AbortSignalLike
+  abort(): void
+}
+
+export interface ResponseLike {
+  ok: boolean
+  status: number
+  json(): Promise<unknown>
+}
+
+export interface RequestInitLike {
+  method: string
+  headers?: Record<string, string>
+  body?: string
+  signal?: AbortSignalLike
+}
+
+export type FetchLike = (url: string, init: RequestInitLike) => Promise<ResponseLike>
+
+/** Injectable primitives; every field defaults to the globalThis flavor. */
+export interface ApiDeps {
+  fetch?: FetchLike
+  createAbortController?: () => AbortControllerLike
+  setTimeout?: (fn: () => void, ms: number) => TimerHandle
+  clearTimeout?: (handle: TimerHandle) => void
+}
+
+/** Per-call options for the request helpers. */
+export interface RequestOptions extends ApiDeps {
+  /** Overall deadline; default {@link DEFAULT_TIMEOUT_MS}. */
+  timeoutMs?: number
+  /** Caller-side cancellation; aborting it aborts the underlying fetch. */
+  signal?: AbortSignalLike
+}
+
+// ---------------------------------------------------------------------------
+// Normalized errors.
+// ---------------------------------------------------------------------------
+
+export type ApiErrorKind = 'timeout' | 'aborted' | 'network' | 'http' | 'parse'
+
+/**
+ * Single normalized failure shape for every request path, so the UI has
+ * one catch surface. `reason` carries the server `{reason}` envelope for
+ * kind 'http' and a stable local code otherwise.
+ */
+export class ApiError extends Error {
+  readonly kind: ApiErrorKind
+  readonly reason: string
+  /** HTTP status when a response was received, else null. */
+  readonly status: number | null
+
+  constructor(
+    kind: ApiErrorKind,
+    reason: string,
+    status: number | null = null,
+    cause?: unknown,
+  ) {
+    super(
+      status === null ? `api ${kind}: ${reason}` : `api ${kind}: ${reason} (http ${status})`,
+      cause === undefined ? undefined : { cause },
+    )
+    this.name = 'ApiError'
+    this.kind = kind
+    this.reason = reason
+    this.status = status
+  }
+}
+
+export function isApiError(value: unknown): value is ApiError {
+  return value instanceof ApiError
+}
+
+// ---------------------------------------------------------------------------
+// Defaults (resolved lazily so late-stubbed globals and fake timers work).
+// ---------------------------------------------------------------------------
+
+const defaultSetTimeout = (fn: () => void, ms: number): TimerHandle =>
+  globalThis.setTimeout(fn, ms)
+
+const defaultClearTimeout = (handle: TimerHandle): void => {
+  globalThis.clearTimeout(handle as ReturnType<typeof globalThis.setTimeout>)
+}
+
+const defaultCreateAbortController = (): AbortControllerLike => new AbortController()
+
+function resolveFetch(opts: ApiDeps): FetchLike {
+  if (opts.fetch !== undefined) return opts.fetch
+  // DOM fetch is only nominally stricter than FetchLike (its RequestInit
+  // wants a branded AbortSignal); every value this module actually passes
+  // is a real one when the default controller factory is in play.
+  return globalThis.fetch as unknown as FetchLike
+}
+
+// ---------------------------------------------------------------------------
+// Core request helper.
+// ---------------------------------------------------------------------------
+
+interface RequestInitInput {
+  method: string
+  headers?: Record<string, string>
+  body?: string
+}
+
+async function request(
+  path: string,
+  init: RequestInitInput,
+  opts: RequestOptions,
+): Promise<unknown> {
+  const doFetch = resolveFetch(opts)
+  const controller = (opts.createAbortController ?? defaultCreateAbortController)()
+  const setT = opts.setTimeout ?? defaultSetTimeout
+  const clearT = opts.clearTimeout ?? defaultClearTimeout
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+  let timedOut = false
+  let externallyAborted = false
+  const timer = setT(() => {
+    timedOut = true
+    controller.abort()
+  }, timeoutMs)
+
+  const external = opts.signal
+  const onExternalAbort = (): void => {
+    externallyAborted = true
+    controller.abort()
+  }
+  if (external !== undefined) {
+    if (external.aborted) onExternalAbort()
+    else external.addEventListener('abort', onExternalAbort)
+  }
+
+  try {
+    let res: ResponseLike
+    try {
+      res = await doFetch(path, { ...init, signal: controller.signal })
+    } catch (err) {
+      if (timedOut) throw new ApiError('timeout', 'request_timeout', null, err)
+      if (externallyAborted) throw new ApiError('aborted', 'request_aborted', null, err)
+      throw new ApiError('network', 'network_error', null, err)
+    }
+    if (!res.ok) {
+      // routes.ts answers most failures with a `{reason}` envelope; the M2
+      // inject.execute failure answers the result view itself ({outcome:
+      // 'failed', errorCode}) with no reason key, so the vocabulary code is
+      // read as the fallback. Status-derived reason covers non-JSON bodies.
+      let reason = `http_${res.status}`
+      try {
+        const body = await res.json()
+        if (typeof body === 'object' && body !== null) {
+          const record = body as Record<string, unknown>
+          const value = record['reason']
+          const code = record['errorCode']
+          if (typeof value === 'string' && value !== '') reason = value
+          else if (typeof code === 'string' && code !== '') reason = code
+        }
+      } catch {
+        // Non-JSON error body: the fallback reason stands.
+      }
+      throw new ApiError('http', reason, res.status)
+    }
+    try {
+      return await res.json()
+    } catch (err) {
+      if (timedOut) throw new ApiError('timeout', 'request_timeout', null, err)
+      throw new ApiError('parse', 'invalid_json', res.status, err)
+    }
+  } finally {
+    clearT(timer)
+    if (external !== undefined) external.removeEventListener('abort', onExternalAbort)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public surface.
+// ---------------------------------------------------------------------------
+
+/** `GET <prefix>/state` — full board snapshot. */
+export async function fetchState(opts: RequestOptions = {}): Promise<StateSnapshot> {
+  return (await request(`${API_PREFIX}/state`, { method: 'GET' }, opts)) as StateSnapshot
+}
+
+/**
+ * `GET <prefix>/session/<id>` — single-session detail. Unknown ids reject
+ * with an ApiError carrying the server's `session_not_found` reason.
+ */
+export async function fetchSession(
+  sessionId: string,
+  opts: RequestOptions = {},
+): Promise<SessionDetail> {
+  const path = `${API_PREFIX}/session/${encodeURIComponent(sessionId)}`
+  return (await request(path, { method: 'GET' }, opts)) as SessionDetail
+}
+
+/**
+ * `POST <prefix>/action` — transport layer only: the envelope is passed
+ * through verbatim, failures are normalized, and there is deliberately NO
+ * retry here — requestId idempotency and the `delivery:unknown` no-retry
+ * rule (S6) are gateway/UI policy, not transport policy.
+ */
+export async function postAction(
+  body: ActionEnvelope,
+  opts: RequestOptions = {},
+): Promise<unknown> {
+  return request(
+    `${API_PREFIX}/action`,
+    {
+      method: 'POST',
+      // The guard requires application/json on POST (415 otherwise).
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    },
+    opts,
+  )
+}

package/src/client/board/Board.tsx

@@ -0,0 +1,214 @@
+/**
+ * Cross-agent session board (design §5.1 view 1).
+ *
+ * Presentation-only: no data fetching, no api/sse imports. Everything
+ * arrives through props already shaped as the view models of `logic.ts`;
+ * the integration layer (T2.4) owns state, transport, and the mapping
+ * from the host wire types (epoch-seconds → epoch-ms conversion included).
+ *
+ * Interaction surface handed back to the owner:
+ * - `onFiltersChange` — time-window select / show-dead checkbox (controlled);
+ * - `onRefresh`      — manual snapshot pull button;
+ * - `onSelectSession` — card click, pass-through for the M3 detail view.
+ */
+
+import type { ReactElement } from 'react'
+import {
+  buildBoardViewModel,
+  timeWindowLabel,
+  formatTemplate,
+  type BoardFilterState,
+  type DaemonStateToken,
+  type DerivedSessionCardVM,
+  type ProjectGroupVM,
+  type SessionCardVM,
+  type StreamHealthToken,
+} from './logic.ts'
+import { BOARD_STRINGS } from './strings.ts'
+import styles from './board.module.css'
+
+/** Time-window choices offered by the top bar (hours). */
+export const TIME_WINDOW_OPTIONS: readonly number[] = [6, 12, 24, 48, 168]
+
+export interface BoardProps {
+  daemonState: DaemonStateToken
+  /** Optional raw detail for the daemon badge hover (e.g. "pid 123 · v0.6.0"). */
+  daemonDetail?: string
+  streamHealth: StreamHealthToken
+  /** Epoch ms of the last authoritative snapshot reconcile, or null. */
+  lastReconcileAtMs: number | null
+  sessions: SessionCardVM[]
+  /** Controlled filter state (owner persists it to the settings namespace). */
+  filters: BoardFilterState
+  onFiltersChange: (next: BoardFilterState) => void
+  onRefresh: () => void
+  onSelectSession: (sessionId: string) => void
+  /** Clock injection for deterministic rendering; defaults to Date.now(). */
+  nowMs?: number
+}
+
+function SessionCard(props: {
+  card: DerivedSessionCardVM
+  onSelect: (sessionId: string) => void
+}): ReactElement {
+  const { card, onSelect } = props
+  return (
+    <button
+      type="button"
+      className={styles['card']}
+      onClick={() => onSelect(card.sessionId)}
+      data-testid="agent-sidecar-card"
+    >
+      <div className={styles['cardHead']}>
+        <span className={styles['agent']}>
+          <span className={styles['glyph']} aria-hidden>
+            {card.glyph}
+          </span>
+          {card.agent}
+        </span>
+        <span className={styles['badge']} data-tone={card.badge.tone} title={card.hoverTitle}>
+          <span className={styles['dot']} data-tone={card.badge.tone} />
+          {card.badge.label}
+          {card.badge.attention !== null && (
+            <span className={styles['attention']} data-kind={card.badge.attention}>
+              {card.badge.attentionLabel}
+            </span>
+          )}
+        </span>
+      </div>
+      <div className={styles['cardTitle']} title={card.title}>
+        {card.title.trim() === '' ? BOARD_STRINGS.card.untitled : card.title}
+      </div>
+      <div className={styles['cardId']} title={card.sessionId}>
+        {card.shortId}
+      </div>
+      <div className={styles['cardEvent']}>
+        {card.lastEvent === null
+          ? BOARD_STRINGS.card.noEvent
+          : `${card.lastEvent.kind} · ${card.lastEvent.text}`}
+      </div>
+      <div className={styles['cardTime']}>{card.relativeTime}</div>
+    </button>
+  )
+}
+
+function ProjectGroup(props: {
+  group: ProjectGroupVM<DerivedSessionCardVM>
+  onSelect: (sessionId: string) => void
+}): ReactElement {
+  const { group, onSelect } = props
+  return (
+    <section className={styles['group']}>
+      <div className={styles['groupHead']}>
+        <span
+          className={styles['groupName']}
+          title={group.fullPath === '' ? undefined : group.fullPath}
+        >
+          {group.label}
+        </span>
+        <span className={styles['groupCount']}>
+          {formatTemplate(BOARD_STRINGS.groupCount, { n: group.cards.length })}
+        </span>
+      </div>
+      <div className={styles['grid']}>
+        {group.cards.map((card) => (
+          <SessionCard key={`${card.agent}:${card.sessionId}`} card={card} onSelect={onSelect} />
+        ))}
+      </div>
+    </section>
+  )
+}
+
+/** The board view. Pure render of `buildBoardViewModel` over the props. */
+export function Board(props: BoardProps): ReactElement {
+  const nowMs = props.nowMs ?? Date.now()
+  const vm = buildBoardViewModel({
+    sessions: props.sessions,
+    filters: props.filters,
+    daemonState: props.daemonState,
+    streamHealth: props.streamHealth,
+    lastReconcileAtMs: props.lastReconcileAtMs,
+    nowMs,
+  })
+  // Keep the select renderable even when the persisted setting is not one
+  // of the stock options (e.g. a hand-edited settings.yaml value).
+  const windowOptions = TIME_WINDOW_OPTIONS.includes(props.filters.timeWindowHours)
+    ? TIME_WINDOW_OPTIONS
+    : [...TIME_WINDOW_OPTIONS, props.filters.timeWindowHours].sort((a, b) => a - b)
+
+  return (
+    <div className={styles['root']} data-testid="agent-sidecar-board">
+      <header className={styles['topbar']}>
+        <span className={styles['title']}>{BOARD_STRINGS.topbar.title}</span>
+        <span className={styles['badge']} data-tone={vm.daemonBadge.tone} title={props.daemonDetail}>
+          <span className={styles['dot']} data-tone={vm.daemonBadge.tone} />
+          {vm.daemonBadge.label}
+        </span>
+        <span className={styles['badge']} data-tone={vm.streamTone}>
+          <span className={styles['dot']} data-tone={vm.streamTone} />
+          {vm.streamLabel}
+        </span>
+        <span className={styles['spacer']} />
+        <label className={styles['control']}>
+          {BOARD_STRINGS.topbar.timeWindow}
+          <select
+            className={styles['select']}
+            value={String(props.filters.timeWindowHours)}
+            onChange={(ev) =>
+              props.onFiltersChange({
+                ...props.filters,
+                timeWindowHours: Number(ev.target.value),
+              })
+            }
+          >
+            {windowOptions.map((hours) => (
+              <option key={hours} value={String(hours)}>
+                {timeWindowLabel(hours)}
+              </option>
+            ))}
+          </select>
+        </label>
+        <label className={styles['control']}>
+          <input
+            type="checkbox"
+            className={styles['checkbox']}
+            checked={props.filters.showDead}
+            onChange={(ev) =>
+              props.onFiltersChange({ ...props.filters, showDead: ev.target.checked })
+            }
+          />
+          {BOARD_STRINGS.topbar.showDead}
+        </label>
+        <button
+          type="button"
+          className={styles['refresh']}
+          title={BOARD_STRINGS.topbar.refreshTitle}
+          onClick={props.onRefresh}
+        >
+          {BOARD_STRINGS.topbar.refresh}
+        </button>
+      </header>
+
+      {vm.banner !== null && (
+        <div className={styles['banner']} data-tone={vm.banner.tone} role="status">
+          {vm.banner.text}
+        </div>
+      )}
+
+      {vm.emptyState !== null ? (
+        <div className={styles['empty']} data-kind={vm.emptyState.kind}>
+          <div className={styles['emptyTitle']}>{vm.emptyState.title}</div>
+          <div className={styles['emptyHint']}>{vm.emptyState.hint}</div>
+        </div>
+      ) : (
+        vm.groups.map((group) => (
+          <ProjectGroup
+            key={group.key === '' ? '\u0000unknown' : group.key}
+            group={group}
+            onSelect={props.onSelectSession}
+          />
+        ))
+      )}
+    </div>
+  )
+}