@shendeguize/dsh-agent-sidecar 0.1.0

package/src/client/detail/strings.ts

@@ -0,0 +1,98 @@
+/**
+ * Centralized user-facing strings for the session-detail view (design §5.1
+ * view 2, §5.3 honesty wording). Deliberately a module-local table — NOT
+ * part of the main locale registry (locales/zh.ts / locales/en.ts): the
+ * locale tables are owned by parallel tasks and the S7 integration wave
+ * folds this table in centrally. Same posture as board/strings.ts.
+ *
+ * Chinese is the primary UI language. Templates use `{name}` placeholders
+ * resolved by `formatTemplate` in `logic.ts`.
+ *
+ * Pure data module: no imports, no logic.
+ *
+ * @module
+ */
+
+export const DETAIL_STRINGS = {
+  /** Header block (session meta + controls). */
+  header: {
+    close: '返回看板',
+    listenOn: '监听中',
+    listenOff: '监听',
+    listenHint: '开启后新事件将实时追加并高亮',
+    untitled: '(无标题)',
+    unknownProject: '未知项目',
+    /** Design §5.3 / SKILL.md wording: statuses are inferred observations. */
+    observedDisclaimer: '状态为从持久化数据推断的观察值,可能滞后',
+  },
+  /** Session status badge labels (observed values, see disclaimer). */
+  status: {
+    working: '工作中',
+    waiting: '等待中',
+    idle: '空闲',
+    dead: '已结束',
+    unknown: '未知',
+  },
+  /** Timeline source badges (provenance of the merged page, honest labels). */
+  sources: {
+    title: '数据来源',
+    dshLive: 'dsh 实时',
+    dshCold: 'dsh 冷读',
+    sidecarReplay: 'sidecar 重放',
+    sidecarBuffer: 'sidecar 缓冲',
+    none: '来源未知',
+  },
+  /** Normalized event-kind labels; unknown kinds keep their raw text. */
+  kind: {
+    user: '用户消息',
+    assistant: '助手回复',
+    thinking: '思考',
+    toolCall: '工具调用',
+    toolResult: '工具结果',
+    turn: '回合',
+    step: '步骤',
+    error: '错误',
+    other: '事件',
+  },
+  /** Seq-discontinuity marker row (design §4.b.3 honest presentation). */
+  gap: {
+    label: '缺口:可能有 {n} 条事件未捕获(256 队列上限或未持久化)',
+  },
+  /** Timeline list chrome. */
+  timeline: {
+    loadMore: '加载更多历史',
+    loadingMore: '加载中…',
+    noMore: '已到时间线起点',
+    expand: '展开',
+    collapse: '收起',
+    newBadge: '新',
+    seq: 'seq {n}',
+    hiddenNotice: '为保持流畅,较早的 {n} 条已折叠',
+    showAll: '全部显示',
+  },
+  /** Loading / empty / error body states. */
+  states: {
+    loadingTitle: '正在加载时间线…',
+    emptyTitle: '暂无事件',
+    emptyHint: '该会话还没有可展示的规范化事件。',
+    errorTitle: '时间线加载失败',
+    /** Fallback template when the reason code has no friendly mapping. */
+    errorFallback: '错误码:{reason}',
+    errors: {
+      session_not_found: '会话不存在或已不可见',
+      invalid_cursor: '分页游标无效,请重新打开详情',
+      fusion_not_wired: '当前 host 未启用时间线能力',
+      network_error: '网络错误,无法联系 dsh host',
+      request_timeout: '请求超时',
+    },
+  },
+  /** Relative time templates (coarse buckets, matches the board wording). */
+  time: {
+    justNow: '刚刚',
+    minutesAgo: '{n} 分钟前',
+    hoursAgo: '{n} 小时前',
+    daysAgo: '{n} 天前',
+  },
+} as const
+
+export type DetailStrings = typeof DETAIL_STRINGS

package/src/client/detail/transport.ts

@@ -0,0 +1,175 @@
+/**
+ * Transport helpers for the detail view's M3 read endpoints. api.ts (T2.1)
+ * predates M3: its `fetchSession` is typed for the M1 placeholder response
+ * and it has no timeline-pagination call — and per the task boundary its
+ * existing exports must not change (the S7 integration wave unifies the
+ * data layer). So this module carries the missing calls with the same
+ * posture as api.ts (same-origin relative paths, bounded timeout,
+ * normalized ApiError, injectable primitives), reusing api.ts's exported
+ * building blocks instead of redefining them.
+ *
+ * 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 SessionView,
+  type TimerHandle,
+} from '../api.ts'
+import type { TimelinePageWire } from './logic.ts'
+
+// ---------------------------------------------------------------------------
+// Wire mirrors of the M3 `GET session/<id>` body (host: routes.ts
+// handleSession with fusion wired; unified row: fusion.ts UnifiedSession).
+// ---------------------------------------------------------------------------
+
+/** One deduplicated cross-agent session row (host: fusion.ts). */
+export interface UnifiedSessionWire {
+  agent: string
+  sessionId: string
+  origin: 'dsh-live' | 'sidecar' | 'merged'
+  live: boolean
+  status: string
+  title: string
+  project: string
+  /** Unix epoch ms of the freshest signal across both sources. */
+  lastActivityAt: number
+  lastEvent: { ts: string; kind: string; text: string } | null
+  lastSeq: number | null
+  gap: boolean
+  parentId: string | null
+  extra: Record<string, unknown>
+}
+
+/** Body of `GET session/<id>` on an M3 host (fusion wired). */
+export interface SessionDetailWire {
+  /** Sidecar board row; null for dsh-live sessions the sidecar has not seen. */
+  session: SessionView | null
+  /** Fused row; null when only the board knows the session. */
+  unified: UnifiedSessionWire | null
+  /** Newest timeline page; null only on a pre-M3 host (placeholder contract). */
+  timeline: TimelinePageWire | null
+}
+
+// ---------------------------------------------------------------------------
+// Bounded same-origin GET (api.ts `request` is module-private; this is the
+// same discipline in miniature: 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>/session/<id>` typed for the M3 body. Unknown ids reject
+ * with an ApiError carrying the server's `session_not_found` reason; a
+ * pre-M3 host answers `timeline: null` (the caller degrades honestly).
+ */
+export async function fetchSessionDetail(
+  sessionId: string,
+  opts: RequestOptions = {},
+): Promise<SessionDetailWire> {
+  const path = `${API_PREFIX}/session/${encodeURIComponent(sessionId)}`
+  return (await getJson(path, opts)) as SessionDetailWire
+}
+
+/**
+ * `GET <prefix>/session/<id>/timeline?cursor=&limit=` — one older history
+ * page. `cursor` is the opaque `nextCursor` token from a previous page,
+ * passed through verbatim (the server rejects tampered tokens with 400
+ * `invalid_cursor`); omit it for the newest window (listen-mode refetch).
+ */
+export async function fetchTimelinePage(
+  sessionId: string,
+  opts: RequestOptions & { cursor?: string | null; limit?: number } = {},
+): Promise<TimelinePageWire> {
+  const params = new URLSearchParams()
+  if (opts.cursor !== undefined && opts.cursor !== null && opts.cursor !== '') {
+    params.set('cursor', opts.cursor)
+  }
+  if (opts.limit !== undefined) params.set('limit', String(opts.limit))
+  const query = params.toString()
+  const path = `${API_PREFIX}/session/${encodeURIComponent(sessionId)}/timeline${
+    query === '' ? '' : `?${query}`
+  }`
+  return (await getJson(path, opts)) as TimelinePageWire
+}

package/src/client/detail-glue.ts

@@ -0,0 +1,397 @@
+/**
+ * Session-detail data glue (T5.10b): one framework-free store per opened
+ * detail view, feeding the controlled SessionDetail / LineageTree
+ * components. Owns transport orchestration only — accumulation and
+ * presentation stay in detail/logic.ts and dsh-tools/logic.ts:
+ *
+ * - initial load via detail/transport.ts `fetchSessionDetail` (header +
+ *   newest timeline page in one round-trip);
+ * - older-history pagination via `fetchTimelinePage(cursor)`;
+ * - listen mode: the controller's SSE `state` frames carry no per-session
+ *   events (ADR-2/ADR-3), so the integration calls {@link
+ *   DetailStore.notifySnapshot} on every frame and the store refetches the
+ *   newest window — coalesced so at most one refetch is in flight and at
+ *   most one more is queued;
+ * - dsh-exclusive lineage: fetched only for dsh sessions; non-dsh agents
+ *   get the client-minted `not_dsh_session` degradation without dialing
+ *   (dsh-tools/logic.ts `externalLineageFallback`).
+ *
+ * Same store discipline as controller.ts: subscribe/getState for
+ * `useSyncExternalStore`, immutable state snapshots, `dispose()` makes
+ * late settlements no-ops. All transport is injectable for node tests.
+ *
+ * @module
+ */
+
+import { isApiError, type RequestOptions } from './api.ts'
+import {
+  fetchSessionDetail,
+  fetchTimelinePage,
+  type SessionDetailWire,
+} from './detail/transport.ts'
+import { fetchLineage } from './m3-transport.ts'
+import {
+  applyListenPage,
+  applyTimelinePage,
+  createTimelineVM,
+  type TimelinePageWire,
+  type TimelineVM,
+} from './detail/logic.ts'
+import {
+  externalLineageFallback,
+  type LineageResponseVM,
+  type LineageTraceVM,
+} from './dsh-tools/logic.ts'
+
+// ---------------------------------------------------------------------------
+// State shapes.
+// ---------------------------------------------------------------------------
+
+/**
+ * Header seed carried from the surface that opened the detail view (board
+ * card / project row); structurally SessionDetailHeaderVM. The
+ * authoritative header comes from the fetched detail body — the hint just
+ * paints the first frame and covers degraded loads.
+ */
+export interface DetailHeaderHint {
+  agent: string
+  title: string
+  project: string
+  status: string
+}
+
+/** Lineage panel slice (mirrors LineageTree props). */
+export interface LineageSliceState {
+  /** True until the first resolution (fetch settle or client degrade). */
+  loading: boolean
+  /** Transport/HTTP failure reason code, or null. */
+  error: string | null
+  available: boolean
+  reason: string | null
+  detail: string | null
+  trace: LineageTraceVM | null
+}
+
+/** Everything the detail view renders (mirrors SessionDetail props). */
+export interface DetailGlueState {
+  sessionId: string
+  header: DetailHeaderHint
+  timeline: TimelineVM
+  /** True while the initial load or an older-page fetch is in flight. */
+  loading: boolean
+  /** Machine reason code of the last failure, or null. */
+  error: string | null
+  hasMore: boolean
+  listening: boolean
+  /** True once the initial load succeeded (timeline usable). */
+  ready: boolean
+  lineage: LineageSliceState
+}
+
+const EMPTY_HEADER: DetailHeaderHint = { agent: '', title: '', project: '', status: '' }
+
+const INITIAL_LINEAGE: LineageSliceState = {
+  loading: true,
+  error: null,
+  available: false,
+  reason: null,
+  detail: null,
+  trace: null,
+}
+
+/** Map any settlement failure to a stable machine reason code. */
+function reasonOf(err: unknown): string {
+  return isApiError(err) ? err.reason : 'network_error'
+}
+
+// ---------------------------------------------------------------------------
+// Injectable transport (defaults are the real calls).
+// ---------------------------------------------------------------------------
+
+export interface DetailStoreOptions {
+  /** Header seed from the opening surface; null paints an empty header. */
+  hint?: DetailHeaderHint | null
+  /** Newest-window size for listen-mode refetches (server default if unset). */
+  listenLimit?: number
+  fetchDetailFn?: (sessionId: string, opts?: RequestOptions) => Promise<SessionDetailWire>
+  fetchPageFn?: (
+    sessionId: string,
+    opts?: RequestOptions & { cursor?: string | null; limit?: number },
+  ) => Promise<TimelinePageWire>
+  fetchLineageFn?: (sessionId: string, opts?: RequestOptions) => Promise<LineageResponseVM>
+}
+
+// ---------------------------------------------------------------------------
+// The store.
+// ---------------------------------------------------------------------------
+
+export class DetailStore {
+  private state: DetailGlueState
+  private readonly listeners = new Set<() => void>()
+  private readonly fetchDetailFn: NonNullable<DetailStoreOptions['fetchDetailFn']>
+  private readonly fetchPageFn: NonNullable<DetailStoreOptions['fetchPageFn']>
+  private readonly fetchLineageFn: NonNullable<DetailStoreOptions['fetchLineageFn']>
+  private readonly listenLimit: number | undefined
+  private disposed = false
+  private opened = false
+  private paging = false
+  private listenInFlight = false
+  private listenQueued = false
+  private lineageStarted = false
+
+  constructor(sessionId: string, options: DetailStoreOptions = {}) {
+    this.fetchDetailFn = options.fetchDetailFn ?? fetchSessionDetail
+    this.fetchPageFn = options.fetchPageFn ?? fetchTimelinePage
+    this.fetchLineageFn = options.fetchLineageFn ?? fetchLineage
+    this.listenLimit = options.listenLimit
+    this.state = {
+      sessionId,
+      header: options.hint ?? EMPTY_HEADER,
+      timeline: createTimelineVM(sessionId),
+      loading: false,
+      error: null,
+      hasMore: false,
+      listening: false,
+      ready: false,
+      lineage: INITIAL_LINEAGE,
+    }
+  }
+
+  subscribe = (fn: () => void): (() => void) => {
+    this.listeners.add(fn)
+    return () => { this.listeners.delete(fn) }
+  }
+
+  getState = (): DetailGlueState => this.state
+
+  private setState(patch: Partial<DetailGlueState>): void {
+    if (this.disposed) return
+    this.state = { ...this.state, ...patch }
+    for (const fn of [...this.listeners]) fn()
+  }
+
+  /** Initial load: header + newest timeline page, then lineage. Idempotent. */
+  async open(): Promise<void> {
+    if (this.opened || this.disposed) return
+    this.opened = true
+    this.setState({ loading: true, error: null })
+    try {
+      const wire = await this.fetchDetailFn(this.state.sessionId)
+      if (this.disposed) return
+      const header = headerFromDetailWire(wire) ?? this.state.header
+      if (wire.timeline === null) {
+        // Pre-M3 host placeholder contract: card data only, no timeline.
+        this.setState({ header, loading: false, error: 'fusion_not_wired' })
+      } else {
+        const timeline = applyTimelinePage(
+          createTimelineVM(this.state.sessionId),
+          wire.timeline,
+        )
+        this.setState({
+          header,
+          timeline,
+          loading: false,
+          error: null,
+          hasMore: timeline.nextCursor !== null,
+          ready: true,
+        })
+      }
+      void this.loadLineage(header.agent)
+    } catch (err) {
+      if (this.disposed) return
+      this.setState({ loading: false, error: reasonOf(err) })
+      // The board hint still tells the agent kind; resolve the lineage
+      // slice anyway so the panel degrades instead of spinning forever.
+      void this.loadLineage(this.state.header.agent)
+    }
+  }
+
+  /** Fetch one older history page via the accumulated cursor. */
+  async loadMore(): Promise<void> {
+    const { timeline } = this.state
+    if (this.disposed || this.paging || !this.state.ready) return
+    if (timeline.nextCursor === null) return
+    this.paging = true
+    this.setState({ loading: true, error: null })
+    try {
+      const page = await this.fetchPageFn(this.state.sessionId, {
+        cursor: timeline.nextCursor,
+      })
+      if (this.disposed) return
+      const next = applyTimelinePage(this.state.timeline, page)
+      this.setState({
+        timeline: next,
+        loading: false,
+        hasMore: next.nextCursor !== null,
+      })
+    } catch (err) {
+      if (this.disposed) return
+      // Entries already shown stay visible; the view renders the reason
+      // as an inline banner (deriveDetailBodyState 'list' arm).
+      this.setState({ loading: false, error: reasonOf(err) })
+    } finally {
+      this.paging = false
+    }
+  }
+
+  /** Flip listen mode; turning it on refetches the newest window at once. */
+  toggleListen(): void {
+    const listening = !this.state.listening
+    this.setState({ listening })
+    if (listening) this.scheduleListenRefetch()
+  }
+
+  /**
+   * SSE `state` frame hook (one call per controller notification). Refreshes
+   * the header from the live board card when given, and in listen mode
+   * triggers a coalesced newest-window refetch.
+   */
+  notifySnapshot(card: DetailHeaderHint | null): void {
+    if (this.disposed) return
+    if (card !== null) {
+      const h = this.state.header
+      if (
+        card.agent !== h.agent ||
+        card.title !== h.title ||
+        card.project !== h.project ||
+        card.status !== h.status
+      ) {
+        this.setState({ header: card })
+      }
+    }
+    if (this.state.listening && this.state.ready) this.scheduleListenRefetch()
+  }
+
+  /** At most one refetch in flight; at most one more queued (idempotence). */
+  private scheduleListenRefetch(): void {
+    if (this.disposed || !this.state.ready) return
+    if (this.listenInFlight) {
+      this.listenQueued = true
+      return
+    }
+    this.listenInFlight = true
+    void this.runListenRefetch()
+  }
+
+  private async runListenRefetch(): Promise<void> {
+    try {
+      const page = await this.fetchPageFn(this.state.sessionId, {
+        ...(this.listenLimit !== undefined ? { limit: this.listenLimit } : {}),
+      })
+      if (this.disposed) return
+      this.setState({ timeline: applyListenPage(this.state.timeline, page) })
+    } catch {
+      // Listen refetch is best-effort: the next SSE frame retries; the
+      // already-rendered timeline must not degrade into an error state.
+    } finally {
+      this.listenInFlight = false
+      if (this.listenQueued && !this.disposed) {
+        this.listenQueued = false
+        this.scheduleListenRefetch()
+      }
+    }
+  }
+
+  /** Resolve the lineage slice once (dsh-only capability; see module doc). */
+  private async loadLineage(agent: string): Promise<void> {
+    if (this.lineageStarted || this.disposed) return
+    if (agent.trim() === '') {
+      // Agent unknown (load failed before the header resolved): degrade
+      // as non-dsh rather than dialing a lineage endpoint blind.
+      this.lineageStarted = true
+      this.setState({
+        lineage: {
+          loading: false, error: null, available: false,
+          reason: 'not_dsh_session', detail: null, trace: null,
+        },
+      })
+      return
+    }
+    this.lineageStarted = true
+    const fallback = externalLineageFallback(agent)
+    if (fallback !== null) {
+      this.setState({
+        lineage: {
+          loading: false,
+          error: null,
+          available: fallback.available,
+          reason: fallback.reason,
+          detail: null,
+          trace: fallback.trace,
+        },
+      })
+      return
+    }
+    try {
+      const body = await this.fetchLineageFn(this.state.sessionId)
+      if (this.disposed) return
+      this.setState({
+        lineage: {
+          loading: false,
+          error: null,
+          available: body.available,
+          reason: body.reason,
+          detail: body.detail ?? null,
+          trace: body.trace,
+        },
+      })
+    } catch (err) {
+      if (this.disposed) return
+      this.setState({ lineage: { ...INITIAL_LINEAGE, loading: false, error: reasonOf(err) } })
+    }
+  }
+
+  /** Late settlements become no-ops; subscribers are dropped. Idempotent. */
+  dispose(): void {
+    this.disposed = true
+    this.listeners.clear()
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for tests and for the mount integration).
+// ---------------------------------------------------------------------------
+
+/**
+ * Authoritative header from the M3 detail body: the fused row wins (it
+ * merges both sources), the sidecar board row covers fusion-less hosts;
+ * null when the body carries neither (caller keeps its hint).
+ */
+export function headerFromDetailWire(wire: SessionDetailWire): DetailHeaderHint | null {
+  if (wire.unified !== null) {
+    return {
+      agent: wire.unified.agent,
+      title: wire.unified.title,
+      project: wire.unified.project,
+      status: wire.unified.status,
+    }
+  }
+  if (wire.session !== null) {
+    return {
+      agent: wire.session.agent,
+      title: wire.session.title,
+      project: wire.session.project,
+      status: wire.session.status,
+    }
+  }
+  return null
+}
+
+/**
+ * Find the live board card of a session (controller SessionCardVM rows) →
+ * header hint, or null when off-board.
+ */
+export function findCardHint(
+  sessions: ReadonlyArray<{
+    agent: string
+    sessionId: string
+    title: string
+    project: string
+    status: string
+  }>,
+  sessionId: string,
+): DetailHeaderHint | null {
+  const card = sessions.find((s) => s.sessionId === sessionId)
+  if (card === undefined) return null
+  return { agent: card.agent, title: card.title, project: card.project, status: card.status }
+}