@shendeguize/dsh-agent-sidecar 0.1.0

package/src/client/m3-transport.ts

@@ -0,0 +1,151 @@
+/**
+ * Transport helpers for the M3 deep-query read endpoints (lineage /
+ * search / projects), completing what detail/transport.ts started for
+ * `session/<id>` + timeline. Same posture as api.ts: same-origin relative
+ * paths under {@link API_PREFIX}, bounded timeout, normalized ApiError,
+ * injectable browser primitives so node tests run without a DOM.
+ *
+ * Response typing reuses the components' own wire mirrors
+ * (dsh-tools/logic.ts, board/project-view-logic.ts) so the transport and
+ * the render pipelines can never disagree about a shape.
+ *
+ * Read-only surface, no retry policy here (transport, not policy).
+ *
+ * @module
+ */
+
+import {
+  API_PREFIX,
+  ApiError,
+  DEFAULT_TIMEOUT_MS,
+  type AbortControllerLike,
+  type FetchLike,
+  type RequestOptions,
+  type ResponseLike,
+  type TimerHandle,
+} from './api.ts'
+import type { LineageResponseVM, SearchResponseVM } from './dsh-tools/logic.ts'
+import type { ProjectGroupVM } from './board/project-view-logic.ts'
+
+/** Body of `GET <prefix>/projects` (host: routes.ts handleProjects). */
+export interface ProjectsResponseVM {
+  groups: ProjectGroupVM[]
+}
+
+// ---------------------------------------------------------------------------
+// Bounded same-origin GET (api.ts `request` is module-private; this is the
+// same discipline detail/transport.ts uses: timeout, external abort,
+// ApiError taxonomy).
+// ---------------------------------------------------------------------------
+
+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: RequestOptions): FetchLike {
+  if (opts.fetch !== undefined) return opts.fetch
+  return globalThis.fetch as unknown as FetchLike
+}
+
+async function getJson(path: string, opts: RequestOptions): Promise<unknown> {
+  const doFetch = resolveFetch(opts)
+  const controller = (opts.createAbortController ?? defaultCreateAbortController)()
+  const setT = opts.setTimeout ?? defaultSetTimeout
+  const clearT = opts.clearTimeout ?? defaultClearTimeout
+
+  let timedOut = false
+  let externallyAborted = false
+  const timer = setT(() => {
+    timedOut = true
+    controller.abort()
+  }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+
+  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, { method: 'GET', 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) {
+      let reason = `http_${res.status}`
+      try {
+        const body = await res.json()
+        if (typeof body === 'object' && body !== null) {
+          const value = (body as Record<string, unknown>)['reason']
+          if (typeof value === 'string' && value !== '') reason = value
+        }
+      } catch {
+        // Non-JSON error body: the status-derived 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>/lineage/<id>` — dsh lineage trace. Degradation
+ * (sessionQuery absent / trace failed) is DATA: the host answers 200 with
+ * `{available:false, reason}`, so only transport/HTTP failures reject
+ * (e.g. 501 `fusion_not_wired` on a pre-M3 host).
+ */
+export async function fetchLineage(
+  sessionId: string,
+  opts: RequestOptions = {},
+): Promise<LineageResponseVM> {
+  const path = `${API_PREFIX}/lineage/${encodeURIComponent(sessionId)}`
+  return (await getJson(path, opts)) as LineageResponseVM
+}
+
+/**
+ * `GET <prefix>/search?q=&project=&limit=` — cross-agent session search.
+ * At least one of `q` / `project` must be non-blank (the host answers 400
+ * `invalid_request` otherwise — callers gate before dialing). The response
+ * echoes the mode; `filter-only` is the honest degradation, not an error.
+ */
+export async function fetchSearch(
+  opts: RequestOptions & { q?: string; project?: string | null; limit?: number } = {},
+): Promise<SearchResponseVM> {
+  const params = new URLSearchParams()
+  if (opts.q !== undefined && opts.q.trim() !== '') params.set('q', opts.q)
+  if (opts.project !== undefined && opts.project !== null && opts.project.trim() !== '') {
+    params.set('project', opts.project)
+  }
+  if (opts.limit !== undefined) params.set('limit', String(opts.limit))
+  return (await getJson(`${API_PREFIX}/search?${params.toString()}`, opts)) as SearchResponseVM
+}
+
+/** `GET <prefix>/projects` — cross-agent project groups. */
+export async function fetchProjects(opts: RequestOptions = {}): Promise<ProjectsResponseVM> {
+  return (await getJson(`${API_PREFIX}/projects`, opts)) as ProjectsResponseVM
+}

package/src/client/mount.tsx

@@ -0,0 +1,307 @@
+/**
+ * Slot-facing React glue (T2.4): binds the {@link SidecarController} stores
+ * to the three presentational modules via `useSyncExternalStore` and hands
+ * back zero-prop components ready for slot registration. Factories close
+ * over the controller so subscribe/getSnapshot identities stay stable
+ * across renders (uSES resubscribes on identity change).
+ *
+ * The settings card entry additionally owns the staged-edit lifecycle over
+ * a bound `SettingsScope` (browser mirror of the host settings namespace):
+ * resolved values come from the scope snapshot, edits stage locally, save
+ * writes one complete top-level group per changed group (see
+ * settings-glue.ts for the write-granularity rationale), and success is
+ * judged by comparing the post-write snapshot against the staged target —
+ * `scope.set` settles without rejecting even when the host declines the
+ * write (it recovers by reloading host state instead).
+ */
+
+import { useEffect, useState, useSyncExternalStore } from 'react'
+import type { ReactElement } from 'react'
+import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client'
+import { Board } from './board/Board.tsx'
+import { ProjectView } from './board/project-view.tsx'
+import { SidecarWidget } from './widget.tsx'
+import { SettingsCard, type SettingsCardValues, type SidecarDaemonStatus } from './settings-card.tsx'
+import { countWorking, deriveWidgetConnection } from './board/logic.ts'
+import type { BoardFilterState } from './board/logic.ts'
+import type { SidecarController, SidecarViewState } from './controller.ts'
+import type { InjectMode } from './inject/logic.ts'
+import type { InjectActions } from './inject-glue.ts'
+import { SidecarDetailView, type SidecarUiIntegration } from './detail-view.tsx'
+import { findCardHint, type DetailHeaderHint } from './detail-glue.ts'
+import { findProjectSessionHint, type ProjectsStore } from './project-glue.ts'
+import { detailErrorText } from './detail/logic.ts'
+import { t } from './locales/index.ts'
+import css from './detail-view.module.css'
+import {
+  DEFAULT_CONFIG_VIEW,
+  cardValuesEqual,
+  configToValues,
+  diffGroups,
+  type SidecarConfigView,
+} from './settings-glue.ts'
+
+/**
+ * What the board tab needs to host the inject panel (S5 wiring, T4.9).
+ * Since T5.10b the panel opens from the detail view's 注入 button; this
+ * shape rides {@link SidecarUiIntegration.inject} unchanged.
+ */
+export interface BoardInjectIntegration {
+  /** onPrepare/onExecute over the action transport (inject-glue.ts). */
+  actions: InjectActions
+  /**
+   * Late-bound `inject.default-mode` reader: the settings scope resolves
+   * after the tab mounts, so the value is read at panel-open time.
+   */
+  getDefaultMode: () => InjectMode
+}
+
+/** Board-tab main views (detail is an overlay route on top of either). */
+type MainView = 'board' | 'projects'
+
+/**
+ * Project-correlation view bound to its store: refresh on entry, then
+ * throttled SSE-driven refreshes for as long as the view is on screen.
+ */
+function ProjectsContainer(props: {
+  controller: SidecarController
+  store: ProjectsStore
+  onSelectSession: (sessionId: string) => void
+}): ReactElement {
+  const { controller, store } = props
+  useEffect(() => {
+    void store.refresh()
+    return controller.subscribe(() => { store.notifySnapshot() })
+  }, [controller, store])
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState)
+  return (
+    <ProjectView
+      groups={state.groups}
+      loading={state.loading}
+      error={state.error === null ? null : detailErrorText(state.error)}
+      onSelectSession={props.onSelectSession}
+    />
+  )
+}
+
+/**
+ * Cross-agent board tab (the "Sidecar" conversation tab), since T5.10b the
+ * shell of the whole M3 information architecture (design §5.1):
+ *
+ * - view 1: the session board, with a 「会话看板 / 项目视图」 switcher
+ *   (ProjectView over `GET projects`);
+ * - view 2: clicking a session card in EITHER view routes to the full-tab
+ *   session-detail view (timeline + 注入 + AI 分析 + dsh 谱系/检索);
+ *   detail-internal jumps (lineage nodes, search hits) re-route in place;
+ * - view 3: the M2 inject panel opens as a modal from the detail view.
+ *
+ * Without an integration the board renders read-only and inert (no detail
+ * routing) — the M1 degradation posture.
+ */
+export function createBoardTab(
+  controller: SidecarController,
+  integration?: SidecarUiIntegration,
+): () => ReactElement {
+  const subscribe = (cb: () => void): (() => void) => controller.subscribe(cb)
+  const getState = (): SidecarViewState => controller.getState()
+  const getFilters = (): BoardFilterState => controller.getFilters()
+
+  return function SidecarBoardTab(): ReactElement {
+    // Third argument (server snapshot) keeps the components renderable under
+    // react-dom/server (DOM-level verification harness); same source.
+    const state = useSyncExternalStore(subscribe, getState, getState)
+    const filters = useSyncExternalStore(subscribe, getFilters, getFilters)
+    const [mainView, setMainView] = useState<MainView>('board')
+    const [detail, setDetail] = useState<{ id: string; hint: DetailHeaderHint | null } | null>(
+      null,
+    )
+    // One ProjectsStore per tab mount, created lazily with the integration
+    // seam; state survives board↔projects↔detail switches within the tab.
+    const [projectsStore] = useState<ProjectsStore | null>(
+      () => integration?.createProjectsStore() ?? null,
+    )
+    useEffect(() => () => { projectsStore?.dispose() }, [projectsStore])
+
+    const openDetail = (sessionId: string): void => {
+      if (integration === undefined) return
+      const hint =
+        findCardHint(state.sessions, sessionId) ??
+        (projectsStore !== null
+          ? findProjectSessionHint(projectsStore.getState().groups, sessionId)
+          : null)
+      setDetail({ id: sessionId, hint })
+    }
+
+    if (integration !== undefined && detail !== null) {
+      return (
+        <SidecarDetailView
+          // key remounts per session: fresh stores, no state bleed on jumps.
+          key={detail.id}
+          sessionId={detail.id}
+          hint={detail.hint}
+          controller={controller}
+          integration={integration}
+          onClose={() => { setDetail(null) }}
+          onSelectSession={openDetail}
+        />
+      )
+    }
+
+    return (
+      <>
+        <div className={css['switcherBar']} data-testid="agent-sidecar-view-switcher">
+          <button
+            type="button"
+            className={css['switcherButton']}
+            data-active={mainView === 'board' || undefined}
+            onClick={() => { setMainView('board') }}
+          >
+            {t('board.viewBoard')}
+          </button>
+          <button
+            type="button"
+            className={css['switcherButton']}
+            data-active={mainView === 'projects' || undefined}
+            onClick={() => { setMainView('projects') }}
+          >
+            {t('board.viewProjects')}
+          </button>
+        </div>
+        {mainView === 'projects' && projectsStore !== null
+          ? (
+            <ProjectsContainer
+              controller={controller}
+              store={projectsStore}
+              onSelectSession={openDetail}
+            />
+          )
+          : (
+            <Board
+              daemonState={state.daemonState}
+              {...state.daemonDetail !== undefined ? { daemonDetail: state.daemonDetail } : {}}
+              streamHealth={state.streamHealth}
+              lastReconcileAtMs={state.lastReconcileAtMs}
+              sessions={state.sessions}
+              filters={filters}
+              onFiltersChange={(next) => {
+                controller.setFilters(next)
+              }}
+              onRefresh={() => {
+                void controller.refresh()
+              }}
+              onSelectSession={openDetail}
+            />
+          )}
+      </>
+    )
+  }
+}
+
+/** Footer connection dot + working counter bound to the controller. */
+export function createFooterWidget(controller: SidecarController): () => ReactElement {
+  const subscribe = (cb: () => void): (() => void) => controller.subscribe(cb)
+  const getState = (): SidecarViewState => controller.getState()
+  return function SidecarFooterWidget(): ReactElement {
+    const state = useSyncExternalStore(subscribe, getState, getState)
+    return (
+      <SidecarWidget
+        connection={deriveWidgetConnection(state.daemonState, state.streamHealth)}
+        workingCount={countWorking(state.sessions)}
+      />
+    )
+  }
+}
+
+/** Fallback card values while the scope snapshot is not ready. */
+const FALLBACK_VALUES: SettingsCardValues = configToValues(DEFAULT_CONFIG_VIEW)
+
+/**
+ * Settings card bound to the controller (daemon status row) and to the
+ * namespace scope (values + persistence). See the module doc for the
+ * staged-edit / save-verification contract.
+ */
+export function createSettingsCardEntry(
+  controller: SidecarController,
+  scope: SettingsScope<SidecarConfigView>,
+): () => ReactElement {
+  const subscribeState = (cb: () => void): (() => void) => controller.subscribe(cb)
+  const getState = (): SidecarViewState => controller.getState()
+  const subscribeScope = (cb: () => void): (() => void) => scope.subscribe(cb)
+  const getSnapshot = (): ReturnType<typeof scope.getSnapshot> => scope.getSnapshot()
+
+  return function SidecarSettingsCardEntry(): ReactElement {
+    const snapshot = useSyncExternalStore(subscribeScope, getSnapshot, getSnapshot)
+    const state = useSyncExternalStore(subscribeState, getState, getState)
+    const [staged, setStaged] = useState<Partial<SettingsCardValues>>({})
+    const [saving, setSaving] = useState(false)
+    const [saveFailed, setSaveFailed] = useState(false)
+
+    const resolved =
+      snapshot.value !== undefined ? configToValues(snapshot.value) : FALLBACK_VALUES
+    const values: SettingsCardValues = { ...resolved, ...staged }
+    const writable =
+      snapshot.status === 'ready' && snapshot.writable && snapshot.mode === 'host'
+    const dirty = !cardValuesEqual(values, resolved)
+
+    const onChange = <K extends keyof SettingsCardValues>(
+      field: K,
+      value: SettingsCardValues[K],
+    ): void => {
+      setSaveFailed(false)
+      setStaged((prev) => {
+        const next = { ...prev }
+        if (resolved[field] === value) delete next[field]
+        else next[field] = value
+        return next
+      })
+    }
+
+    const onSave = (): void => {
+      const target = { ...resolved, ...staged }
+      setSaving(true)
+      setSaveFailed(false)
+      void (async () => {
+        try {
+          for (const { group, patch } of diffGroups(resolved, target)) {
+            await scope.set(group, patch)
+          }
+          const after = scope.getSnapshot().value
+          if (after !== undefined && cardValuesEqual(configToValues(after), target)) {
+            setStaged({})
+          } else {
+            setSaveFailed(true)
+          }
+        } catch (err) {
+          console.error('agent-sidecar: settings save failed', err)
+          setSaveFailed(true)
+        } finally {
+          setSaving(false)
+        }
+      })()
+    }
+
+    const daemon: SidecarDaemonStatus = {
+      state: state.daemonState,
+      ...state.lastPing !== null
+        ? { pid: state.lastPing.pid, version: state.lastPing.version }
+        : {},
+    }
+
+    return (
+      <SettingsCard
+        values={values}
+        onChange={onChange}
+        onSave={onSave}
+        onDiscard={() => {
+          setStaged({})
+          setSaveFailed(false)
+        }}
+        writable={writable}
+        dirty={dirty}
+        saving={saving}
+        saveFailed={saveFailed}
+        daemon={daemon}
+      />
+    )
+  }
+}

package/src/client/project-glue.ts

@@ -0,0 +1,134 @@
+/**
+ * Project-correlation data glue (T5.10b): a framework-free store feeding
+ * the controlled ProjectView with `GET projects` wire groups. Derivation
+ * (normalize/merge/sort) stays in board/project-view-logic.ts — this store
+ * owns transport orchestration and refresh throttling only.
+ *
+ * Refresh model: an explicit `refresh()` on view entry, plus SSE-driven
+ * `notifySnapshot()` refreshes throttled to {@link DEFAULT_MIN_REFRESH_MS}
+ * (state frames arrive per board mutation; the projects endpoint recomputes
+ * groups per call, so hammering it buys nothing). Stale groups stay
+ * rendered through failed refreshes (honest banner, never a blank).
+ *
+ * Same store discipline as controller.ts: subscribe/getState for
+ * `useSyncExternalStore`, immutable snapshots, dispose() = late no-ops.
+ *
+ * @module
+ */
+
+import { isApiError, type RequestOptions } from './api.ts'
+import { fetchProjects, type ProjectsResponseVM } from './m3-transport.ts'
+import type { ProjectGroupVM } from './board/project-view-logic.ts'
+import type { DetailHeaderHint } from './detail-glue.ts'
+
+/** Minimum spacing between SSE-triggered refreshes. */
+export const DEFAULT_MIN_REFRESH_MS = 5_000
+
+export interface ProjectsGlueState {
+  groups: ProjectGroupVM[]
+  /** True while a fetch is in flight AND nothing was loaded yet. */
+  loading: boolean
+  /** Machine reason code of the last failure, or null. */
+  error: string | null
+  /** Epoch ms of the last successful load; null before the first one. */
+  loadedAt: number | null
+}
+
+export interface ProjectsStoreOptions {
+  fetchProjectsFn?: (opts?: RequestOptions) => Promise<ProjectsResponseVM>
+  minRefreshMs?: number
+  /** Clock injection for throttling tests. */
+  now?: () => number
+}
+
+export class ProjectsStore {
+  private state: ProjectsGlueState = { groups: [], loading: false, error: null, loadedAt: null }
+  private readonly listeners = new Set<() => void>()
+  private readonly fetchProjectsFn: NonNullable<ProjectsStoreOptions['fetchProjectsFn']>
+  private readonly minRefreshMs: number
+  private readonly now: () => number
+  private disposed = false
+  private inFlight = false
+  private lastAttemptAt: number | null = null
+
+  constructor(options: ProjectsStoreOptions = {}) {
+    this.fetchProjectsFn = options.fetchProjectsFn ?? fetchProjects
+    this.minRefreshMs = options.minRefreshMs ?? DEFAULT_MIN_REFRESH_MS
+    this.now = options.now ?? Date.now
+  }
+
+  subscribe = (fn: () => void): (() => void) => {
+    this.listeners.add(fn)
+    return () => { this.listeners.delete(fn) }
+  }
+
+  getState = (): ProjectsGlueState => this.state
+
+  private setState(patch: Partial<ProjectsGlueState>): void {
+    if (this.disposed) return
+    this.state = { ...this.state, ...patch }
+    for (const fn of [...this.listeners]) fn()
+  }
+
+  /** Fetch the groups now (deduped while one call is in flight). */
+  async refresh(): Promise<void> {
+    if (this.disposed || this.inFlight) return
+    this.inFlight = true
+    this.lastAttemptAt = this.now()
+    if (this.state.loadedAt === null) this.setState({ loading: true, error: null })
+    try {
+      const body = await this.fetchProjectsFn()
+      if (this.disposed) return
+      this.setState({
+        groups: body.groups,
+        loading: false,
+        error: null,
+        loadedAt: this.now(),
+      })
+    } catch (err) {
+      if (this.disposed) return
+      // Previously loaded groups stay on screen; the view banners the code.
+      this.setState({
+        loading: false,
+        error: isApiError(err) ? err.reason : 'network_error',
+      })
+    } finally {
+      this.inFlight = false
+    }
+  }
+
+  /** SSE `state` frame hook: throttled refresh. */
+  notifySnapshot(): void {
+    if (this.disposed || this.inFlight) return
+    if (this.lastAttemptAt !== null && this.now() - this.lastAttemptAt < this.minRefreshMs) return
+    void this.refresh()
+  }
+
+  dispose(): void {
+    this.disposed = true
+    this.listeners.clear()
+  }
+}
+
+/**
+ * Find a session inside loaded project groups → header hint for the
+ * detail view (project rows carry no board card), or null when unknown.
+ */
+export function findProjectSessionHint(
+  groups: readonly ProjectGroupVM[],
+  sessionId: string,
+): DetailHeaderHint | null {
+  for (const group of groups) {
+    for (const session of group.sessions) {
+      if (session.sessionId === sessionId) {
+        return {
+          agent: session.agent,
+          title: session.title,
+          project: group.project,
+          status: session.status,
+        }
+      }
+    }
+  }
+  return null
+}