@shendeguize/dsh-agent-sidecar 0.1.0

package/src/client/controller.ts

@@ -0,0 +1,360 @@
+/**
+ * SidecarController — the browser half's one data controller (T2.4).
+ *
+ * Owns the live feed (a {@link StateStream}, default 'sse' mode on the
+ * plugin's stream route) and folds it into two externally-subscribable
+ * stores consumed via `useSyncExternalStore`:
+ *
+ * - view state: the host `StateSnapshot` mapped onto the board view models
+ *   (wire `updated_at` epoch SECONDS → `updatedAtMs` epoch MILLISECONDS at
+ *   this boundary, per board/logic.ts's contract), plus the composite
+ *   stream health (browser stream status overrides the host-reported
+ *   subscribe health — see {@link combineStreamHealth});
+ * - filters: board filter state persisted to localStorage under a
+ *   package-name-prefixed key; until the user touches them, the ui.*
+ *   settings defaults may be adopted ({@link SidecarController.adoptConfigDefaults}).
+ *
+ * Pure mapping functions are exported for unit tests. Browser primitives
+ * (stream, storage) are injectable so the whole controller runs under
+ * plain node. No React, no slots SDK.
+ *
+ * @module
+ */
+
+import {
+  fetchState,
+  type PingInfo,
+  type SessionView,
+  type StateSnapshot,
+  type StreamHealth,
+} from './api.ts'
+import { StateStream, STREAM_PATH, type StreamMode, type StreamStatus } from './sse.ts'
+import {
+  DEFAULT_TIME_WINDOW_HOURS,
+  type BoardFilterState,
+  type DaemonStateToken,
+  type SessionCardVM,
+  type StreamHealthToken,
+} from './board/logic.ts'
+
+/**
+ * Package name, used as the localStorage key prefix and the style-tag owner
+ * mark. Mirrors package.json `name` (client code cannot read package.json at
+ * runtime); pinned against it by test/client-integration.test.ts.
+ */
+export const PLUGIN_ID = '@shendeguize/dsh-agent-sidecar'
+
+/** localStorage key for the persisted board filters. */
+export const FILTERS_STORAGE_KEY = `${PLUGIN_ID}:board-filters`
+
+// ---------------------------------------------------------------------------
+// View state and pure mapping (exported for tests).
+// ---------------------------------------------------------------------------
+
+/** Everything the three mounted surfaces render from. */
+export interface SidecarViewState {
+  daemonState: DaemonStateToken
+  /** Last successful daemon ping, if any. */
+  lastPing: PingInfo | null
+  /** Hover detail for the daemon badge, e.g. "pid 123 · v0.6.0". */
+  daemonDetail: string | undefined
+  /** Composite health: browser stream status folded over host-reported health. */
+  streamHealth: StreamHealthToken
+  /** Raw browser-side stream status. */
+  streamStatus: StreamStatus
+  lastReconcileAtMs: number | null
+  sessions: SessionCardVM[]
+  /** Host capabilities.inject (M2 write surface; informational in M1). */
+  injectCapability: boolean
+  /** False until the first snapshot arrives in this page life. */
+  hasSnapshot: boolean
+}
+
+/** Pre-first-snapshot state: probing daemon, unknown health, empty board. */
+export function initialViewState(): SidecarViewState {
+  return {
+    daemonState: 'probe',
+    lastPing: null,
+    daemonDetail: undefined,
+    streamHealth: 'unknown',
+    streamStatus: 'connecting',
+    lastReconcileAtMs: null,
+    sessions: [],
+    injectCapability: false,
+    hasSnapshot: false,
+  }
+}
+
+/**
+ * Wire sessions → board card view models. The one place the epoch-seconds
+ * `updated_at` becomes the epoch-milliseconds `updatedAtMs` (board/logic.ts
+ * consumes milliseconds everywhere).
+ */
+export function mapSessions(sessions: readonly SessionView[]): SessionCardVM[] {
+  return sessions.map((session) => ({
+    agent: session.agent,
+    sessionId: session.session_id,
+    status: session.status,
+    title: session.title,
+    project: session.project,
+    updatedAtMs: session.updated_at * 1000,
+    lastEvent:
+      session.last_event === null
+        ? null
+        : { kind: session.last_event.kind, text: session.last_event.text },
+    gap: session.gap,
+  }))
+}
+
+/** Daemon badge hover detail from the last ping ("pid 123 · v0.6.0"). */
+export function daemonDetailOf(ping: PingInfo | null): string | undefined {
+  if (ping === null) return undefined
+  return `pid ${ping.pid} · v${ping.version}`
+}
+
+/**
+ * Composite stream health for the UI:
+ * - before the first snapshot nothing is known → 'unknown';
+ * - a degraded BROWSER stream overrides (the host may still be healthy,
+ *   but what this page shows is stale);
+ * - otherwise the host-reported daemon-subscribe health stands ('connecting'
+ *   during a native EventSource reconnect keeps the last host verdict —
+ *   the reconcile timestamp already conveys staleness).
+ */
+export function combineStreamHealth(
+  hostHealth: StreamHealth | null,
+  browserStatus: StreamStatus,
+  hasSnapshot: boolean,
+): StreamHealthToken {
+  if (!hasSnapshot || hostHealth === null) return 'unknown'
+  if (browserStatus === 'degraded') return 'degraded'
+  return hostHealth
+}
+
+/** Full snapshot → view state fold (pure; exported for tests). */
+export function mapSnapshot(
+  snapshot: StateSnapshot,
+  browserStatus: StreamStatus,
+): SidecarViewState {
+  return {
+    daemonState: snapshot.daemon.state,
+    lastPing: snapshot.daemon.lastPing,
+    daemonDetail: daemonDetailOf(snapshot.daemon.lastPing),
+    streamHealth: combineStreamHealth(snapshot.board.streamHealth, browserStatus, true),
+    streamStatus: browserStatus,
+    lastReconcileAtMs: snapshot.board.lastReconcileAt,
+    sessions: mapSessions(snapshot.board.sessions),
+    injectCapability: snapshot.capabilities.inject,
+    hasSnapshot: true,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Filter persistence.
+// ---------------------------------------------------------------------------
+
+/** Structural localStorage face (node tests inject a Map-backed fake). */
+export interface StorageLike {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+}
+
+/** Resolve the real localStorage; some privacy modes throw on access. */
+function defaultStorage(): StorageLike | null {
+  try {
+    const storage = (globalThis as { localStorage?: StorageLike }).localStorage
+    return storage ?? null
+  } catch {
+    return null
+  }
+}
+
+/** Parse + validate persisted filters; anything malformed reads as absent. */
+export function readStoredFilters(storage: StorageLike | null): BoardFilterState | null {
+  if (storage === null) return null
+  try {
+    const raw = storage.getItem(FILTERS_STORAGE_KEY)
+    if (raw === null) return null
+    const parsed: unknown = JSON.parse(raw)
+    if (typeof parsed !== 'object' || parsed === null) return null
+    const candidate = parsed as { timeWindowHours?: unknown; showDead?: unknown }
+    if (
+      typeof candidate.timeWindowHours !== 'number'
+      || !Number.isFinite(candidate.timeWindowHours)
+      || candidate.timeWindowHours <= 0
+      || typeof candidate.showDead !== 'boolean'
+    ) {
+      return null
+    }
+    return { timeWindowHours: candidate.timeWindowHours, showDead: candidate.showDead }
+  } catch {
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Controller.
+// ---------------------------------------------------------------------------
+
+/** Structural stream face ({@link StateStream} satisfies it; tests fake it). */
+export interface StateStreamLike {
+  readonly status: StreamStatus
+  readonly mode: StreamMode
+  start(): void
+  stop(): void
+  onSnapshot(cb: (snapshot: StateSnapshot) => void): () => void
+  onStatus(cb: (status: StreamStatus) => void): () => void
+  pollNow(): void
+}
+
+export interface SidecarControllerOptions {
+  /** Live feed; default: `new StateStream({url: STREAM_PATH, mode: 'sse'})`. */
+  stream?: StateStreamLike
+  /** Filter persistence; `null` disables, absent resolves real localStorage. */
+  storage?: StorageLike | null
+  /** Manual-refresh fetch; default api.fetchState. */
+  fetchStateFn?: typeof fetchState
+  /** Visibility gate handed to the default stream (poll-mode pause). */
+  visible?: () => boolean
+}
+
+const defaultVisible = (): boolean =>
+  typeof document === 'undefined' || !document.hidden
+
+/**
+ * One instance per plugin apply. `start()` wires the stream, `stop()` is
+ * terminal (the underlying StateStream cannot restart — a re-apply builds
+ * a fresh controller).
+ */
+export class SidecarController {
+  private readonly stream: StateStreamLike
+  private readonly storage: StorageLike | null
+  private readonly fetchFn: typeof fetchState
+  private readonly listeners = new Set<() => void>()
+
+  private state: SidecarViewState = initialViewState()
+  private filters: BoardFilterState
+  /** True once filters came from storage or a user gesture (config defaults then stop adopting). */
+  private filtersTouched: boolean
+  private lastHostHealth: StreamHealth | null = null
+  private started = false
+
+  constructor(opts: SidecarControllerOptions = {}) {
+    this.storage = opts.storage === undefined ? defaultStorage() : opts.storage
+    this.fetchFn = opts.fetchStateFn ?? fetchState
+    this.stream =
+      opts.stream
+      ?? new StateStream({
+        url: STREAM_PATH,
+        mode: 'sse',
+        visible: opts.visible ?? defaultVisible,
+      })
+    const stored = readStoredFilters(this.storage)
+    this.filters = stored ?? { timeWindowHours: DEFAULT_TIME_WINDOW_HOURS, showDead: false }
+    this.filtersTouched = stored !== null
+  }
+
+  /** Wire stream listeners and begin streaming (idempotent). */
+  start(): void {
+    if (this.started) return
+    this.started = true
+    this.stream.onSnapshot((snapshot) => {
+      this.applySnapshot(snapshot)
+    })
+    this.stream.onStatus((status) => {
+      this.applyStatus(status)
+    })
+    this.stream.start()
+  }
+
+  /** Terminal teardown of the live feed. */
+  stop(): void {
+    this.stream.stop()
+  }
+
+  /** Forward the visibility resume to the stream (poll-mode immediate fetch). */
+  pollNow(): void {
+    this.stream.pollNow()
+  }
+
+  /** Change notifications for BOTH stores (state and filters). */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  /** Stable-reference view state (uSES getSnapshot source). */
+  getState(): SidecarViewState {
+    return this.state
+  }
+
+  /** Stable-reference filters (uSES getSnapshot source). */
+  getFilters(): BoardFilterState {
+    return this.filters
+  }
+
+  /** User filter change: persist (package-prefixed key) and notify. */
+  setFilters(next: BoardFilterState): void {
+    this.filters = { ...next }
+    this.filtersTouched = true
+    if (this.storage !== null) {
+      try {
+        this.storage.setItem(FILTERS_STORAGE_KEY, JSON.stringify(this.filters))
+      } catch {
+        // Quota/privacy failures degrade to session-only filters.
+      }
+    }
+    this.notify()
+  }
+
+  /**
+   * Adopt ui.* settings defaults as the filter values — only while the user
+   * has never touched the filters (no stored value, no gesture). Not
+   * persisted: an untouched board keeps following the settings defaults.
+   */
+  adoptConfigDefaults(ui: { timeWindowHours: number; showDead: boolean }): void {
+    if (this.filtersTouched) return
+    if (
+      this.filters.timeWindowHours === ui.timeWindowHours
+      && this.filters.showDead === ui.showDead
+    ) {
+      return
+    }
+    this.filters = { timeWindowHours: ui.timeWindowHours, showDead: ui.showDead }
+    this.notify()
+  }
+
+  /** Manual refresh (board's refresh button): one out-of-band snapshot pull. */
+  async refresh(): Promise<void> {
+    try {
+      const snapshot = await this.fetchFn({})
+      this.applySnapshot(snapshot)
+    } catch (err) {
+      // The stream (and its status surface) remains the health authority;
+      // a failed manual pull only logs.
+      console.error('agent-sidecar: manual refresh failed', err)
+    }
+  }
+
+  private applySnapshot(snapshot: StateSnapshot): void {
+    this.lastHostHealth = snapshot.board.streamHealth
+    this.state = mapSnapshot(snapshot, this.stream.status)
+    this.notify()
+  }
+
+  private applyStatus(status: StreamStatus): void {
+    if (status === this.state.streamStatus) return
+    this.state = {
+      ...this.state,
+      streamStatus: status,
+      streamHealth: combineStreamHealth(this.lastHostHealth, status, this.state.hasSnapshot),
+    }
+    this.notify()
+  }
+
+  private notify(): void {
+    for (const listener of [...this.listeners]) listener()
+  }
+}

package/src/client/css-modules.d.ts

@@ -0,0 +1,11 @@
+/**
+ * CSS Modules ambient declaration for the client TS program (same shape as
+ * the dsh-web-ui blueprint packages). The build side is handled by the
+ * `dsh-css-modules-inline` plugin in tsdown.client.ts, which compiles
+ * `*.module.css` with lightningcss into a hashed class map and a
+ * self-injecting `<style data-plugin>` tag.
+ */
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}

package/src/client/detail/SessionDetail.tsx

@@ -0,0 +1,270 @@
+/**
+ * Session-detail view: header + merged event timeline (design §5.1 view 2).
+ *
+ * Presentation-only and fully controlled: no data fetching, no api/sse
+ * imports. The integration layer (S7) owns transport and accumulation —
+ * it feeds the {@link TimelineVM} built via logic.ts (`applyTimelinePage`
+ * for history pages, `applyListenPage` for listen-mode refetches) and
+ * handles `onLoadMore` / `onToggleListen`.
+ *
+ * Long-list posture (task report): no full virtualization — history only
+ * grows page-by-page on explicit 加载更多, and rendering is additionally
+ * capped at {@link DEFAULT_MAX_RENDER_ROWS} newest rows behind a collapse
+ * notice with a 全部显示 escape hatch. View-local concerns (expanded
+ * bodies, the lift-cap flag, auto-scroll) are component state; everything
+ * else comes through props.
+ */
+
+import { useEffect, useRef, useState, type ReactElement } from 'react'
+import {
+  buildTimelineRows,
+  deriveDetailBodyState,
+  deriveDetailStatus,
+  deriveSourceBadges,
+  agentGlyph,
+  limitTimelineRows,
+  DEFAULT_MAX_RENDER_ROWS,
+  type TimelineRowVM,
+  type TimelineVM,
+} from './logic.ts'
+import { DETAIL_STRINGS } from './strings.ts'
+import styles from './detail.module.css'
+
+export interface SessionDetailHeaderVM {
+  agent: string
+  title: string
+  project: string
+  /** Raw observed status string (open vocabulary, normalized in logic.ts). */
+  status: string
+}
+
+export interface SessionDetailProps {
+  sessionId: string
+  header: SessionDetailHeaderVM
+  /** Accumulated timeline state (logic.ts createTimelineVM/apply* output). */
+  timeline: TimelineVM
+  /** True while the owner has a fetch in flight (initial or older page). */
+  loading: boolean
+  /** Machine reason code of the last failure, or null. */
+  error: string | null
+  /** True when an older history page can still be fetched. */
+  hasMore: boolean
+  /** Listen mode (SSE-triggered newest-page refetch) currently on. */
+  listening: boolean
+  onLoadMore: () => void
+  onToggleListen: () => void
+  onClose?: () => void
+  /** Clock injection for deterministic rendering; defaults to Date.now(). */
+  nowMs?: number
+  /** Render cap override (segmented rendering); mostly for tests/tuning. */
+  maxRenderRows?: number
+}
+
+function EventRow(props: {
+  row: Extract<TimelineRowVM, { type: 'event' }>
+  expanded: boolean
+  onToggleExpand: (key: string) => void
+}): ReactElement {
+  const { row, expanded, onToggleExpand } = props
+  const entry = row.entry
+  return (
+    <li
+      className={styles['event']}
+      data-kind={entry.kind}
+      data-new={row.isNew || undefined}
+      data-testid="agent-sidecar-detail-event"
+    >
+      <div className={styles['eventHead']} title={row.hoverTitle}>
+        <span className={styles['eventGlyph']} aria-hidden>
+          {entry.glyph}
+        </span>
+        <span className={styles['eventLabel']}>{entry.label}</span>
+        {entry.seq !== null && (
+          <span className={styles['eventSeq']}>
+            {DETAIL_STRINGS.timeline.seq.replace('{n}', String(entry.seq))}
+          </span>
+        )}
+        {row.isNew && <span className={styles['eventNew']}>{DETAIL_STRINGS.timeline.newBadge}</span>}
+        <span className={styles['eventSpacer']} />
+        <span className={styles['eventTime']}>{row.relativeTime}</span>
+      </div>
+      {entry.summary !== '' && <div className={styles['eventSummary']}>{entry.summary}</div>}
+      {entry.expandable && (
+        <button
+          type="button"
+          className={styles['expandButton']}
+          onClick={() => onToggleExpand(entry.key)}
+        >
+          {expanded ? DETAIL_STRINGS.timeline.collapse : DETAIL_STRINGS.timeline.expand}
+        </button>
+      )}
+      {entry.expandable && expanded && entry.body !== null && (
+        <pre className={styles['eventBody']}>{entry.body}</pre>
+      )}
+    </li>
+  )
+}
+
+/** The session-detail view. Pure render of the logic.ts pipelines over props. */
+export function SessionDetail(props: SessionDetailProps): ReactElement {
+  const nowMs = props.nowMs ?? Date.now()
+  const [expandedKeys, setExpandedKeys] = useState<ReadonlySet<string>>(new Set())
+  const [renderAll, setRenderAll] = useState(false)
+  const listRef = useRef<HTMLOListElement | null>(null)
+
+  const status = deriveDetailStatus(props.header.status)
+  const sourceBadges = deriveSourceBadges(props.timeline.sources)
+  const bodyState = deriveDetailBodyState({
+    loading: props.loading,
+    error: props.error,
+    entryCount: props.timeline.entries.length,
+  })
+
+  const allRows = buildTimelineRows(props.timeline, nowMs)
+  const limited = renderAll
+    ? { rows: allRows, hiddenCount: 0, notice: null }
+    : limitTimelineRows(allRows, props.maxRenderRows ?? DEFAULT_MAX_RENDER_ROWS)
+
+  const entryCount = props.timeline.entries.length
+  const listening = props.listening
+  useEffect(() => {
+    // Listen mode appends at the tail: keep the newest events in view.
+    if (!listening) return
+    const list = listRef.current
+    if (list !== null) list.scrollTop = list.scrollHeight
+  }, [listening, entryCount])
+
+  const toggleExpand = (key: string): void => {
+    setExpandedKeys((prev) => {
+      const next = new Set(prev)
+      if (next.has(key)) next.delete(key)
+      else next.add(key)
+      return next
+    })
+  }
+
+  return (
+    <div className={styles['root']} data-testid="agent-sidecar-detail">
+      <header className={styles['header']}>
+        <div className={styles['headerTop']}>
+          {props.onClose !== undefined && (
+            <button type="button" className={styles['closeButton']} onClick={props.onClose}>
+              {DETAIL_STRINGS.header.close}
+            </button>
+          )}
+          <span className={styles['agent']}>
+            <span className={styles['agentGlyph']} aria-hidden>
+              {agentGlyph(props.header.agent)}
+            </span>
+            {props.header.agent}
+          </span>
+          <span className={styles['badge']} data-tone={status.tone} title={DETAIL_STRINGS.header.observedDisclaimer}>
+            <span className={styles['dot']} data-tone={status.tone} />
+            {status.label}
+          </span>
+          <span className={styles['spacer']} />
+          <button
+            type="button"
+            className={styles['listenButton']}
+            aria-pressed={props.listening}
+            data-active={props.listening || undefined}
+            title={DETAIL_STRINGS.header.listenHint}
+            onClick={props.onToggleListen}
+          >
+            {props.listening ? DETAIL_STRINGS.header.listenOn : DETAIL_STRINGS.header.listenOff}
+          </button>
+        </div>
+        <div className={styles['title']} title={props.header.title}>
+          {props.header.title.trim() === '' ? DETAIL_STRINGS.header.untitled : props.header.title}
+        </div>
+        <div className={styles['meta']}>
+          <span className={styles['project']} title={props.header.project}>
+            {props.header.project.trim() === ''
+              ? DETAIL_STRINGS.header.unknownProject
+              : props.header.project}
+          </span>
+          <span className={styles['sessionId']} title={props.sessionId}>
+            {props.sessionId}
+          </span>
+        </div>
+        <div className={styles['metaRow']}>
+          <span className={styles['disclaimer']}>{DETAIL_STRINGS.header.observedDisclaimer}</span>
+          {sourceBadges.length > 0 && (
+            <span className={styles['sourceList']} title={DETAIL_STRINGS.sources.title}>
+              {sourceBadges.map((badge) => (
+                <span key={badge.id} className={styles['sourceBadge']} data-tone={badge.tone}>
+                  {badge.label}
+                </span>
+              ))}
+            </span>
+          )}
+        </div>
+      </header>
+
+      {bodyState.errorBanner !== null && (
+        <div className={styles['banner']} role="status">
+          {bodyState.errorBanner}
+        </div>
+      )}
+
+      {bodyState.kind !== 'list' ? (
+        <div className={styles['bodyState']} data-kind={bodyState.kind}>
+          <div className={styles['bodyStateTitle']}>{bodyState.title}</div>
+          {bodyState.hint !== null && <div className={styles['bodyStateHint']}>{bodyState.hint}</div>}
+        </div>
+      ) : (
+        <>
+          <div className={styles['pager']}>
+            {props.hasMore ? (
+              <button
+                type="button"
+                className={styles['loadMoreButton']}
+                disabled={props.loading}
+                onClick={props.onLoadMore}
+              >
+                {props.loading
+                  ? DETAIL_STRINGS.timeline.loadingMore
+                  : DETAIL_STRINGS.timeline.loadMore}
+              </button>
+            ) : (
+              <span className={styles['pagerNote']}>{DETAIL_STRINGS.timeline.noMore}</span>
+            )}
+          </div>
+          {limited.notice !== null && (
+            <div className={styles['hiddenNotice']}>
+              {limited.notice}
+              <button
+                type="button"
+                className={styles['showAllButton']}
+                onClick={() => setRenderAll(true)}
+              >
+                {DETAIL_STRINGS.timeline.showAll}
+              </button>
+            </div>
+          )}
+          <ol className={styles['timeline']} ref={listRef}>
+            {limited.rows.map((row) =>
+              row.type === 'gap' ? (
+                <li
+                  key={row.key}
+                  className={styles['gap']}
+                  role="note"
+                  data-testid="agent-sidecar-detail-gap"
+                >
+                  {row.label}
+                </li>
+              ) : (
+                <EventRow
+                  key={row.key}
+                  row={row}
+                  expanded={expandedKeys.has(row.key)}
+                  onToggleExpand={toggleExpand}
+                />
+              ),
+            )}
+          </ol>
+        </>
+      )}
+    </div>
+  )
+}