@shendeguize/dsh-agent-sidecar 0.1.0 → 0.2.0

package/src/client/commands.ts

@@ -18,8 +18,8 @@
  *   `dsh-agent-teams/src/command.ts`).
  * - The only `ui.kind` this dsh version supports is `popupSelect`:
  *   an async `options(session, signal)` provider plus `onSelect`. The
- *   `/sidecar` overview therefore presents as a popup card of rows — a
- *   read-only glance; every row's onSelect is a no-op.
+ *   `/sidecar` overview therefore presents as a popup card of rows; its
+ *   board row opens Agent Center while informational rows remain inert.
  *
  * The `commandUi` service type is NOT part of the published plugin SDK
  * (same situation as `settingsScope` in ./index.ts), so this module keeps
@@ -55,7 +55,12 @@ import type {
   SessionStatusToken,
   WidgetConnection,
 } from './board/logic.ts'
+import {
+  acquireWithHandoff,
+  isRegistrationCollision,
+} from './lifecycle/handoff.ts'
 import { tCommand } from './locales/command.ts'
+import type { CenterNavigation } from './navigation/center.ts'
 
 /** The slash command name (without the leading slash). */
 export const SIDECAR_COMMAND_NAME = 'sidecar'
@@ -399,6 +404,8 @@ export interface SidecarCommandDeps {
   now?: () => number
   /** Session-row cap; defaults to {@link DEFAULT_OVERVIEW_TOP_N}. */
   topN?: number
+  /** Opens Agent Center when the board option is selected. */
+  openCenter?: CenterNavigation
 }
 
 /**
@@ -435,8 +442,8 @@ export function createSidecarCommandContribution(
         if (deps.topN !== undefined) overviewOpts.topN = deps.topN
         return overviewToOptions(buildOverview(snapshot, overviewOpts))
       },
-      onSelect: () => {
-        // Read-only glance: rows are informational, selection is a no-op.
+      onSelect: (option) => {
+        if (option.id === 'board') deps.openCenter?.()
       },
     },
   }
@@ -451,7 +458,10 @@ export function createSidecarCommandContribution(
  * `ClientContext` satisfies it structurally (cordis `ctx.inject`).
  */
 export interface CommandMountContext {
-  inject(deps: readonly string[], callback: (ctx: unknown) => void): unknown
+  inject(
+    deps: readonly string[],
+    callback: (ctx: unknown) => (() => void) | void,
+  ): unknown
 }
 
 /**
@@ -459,11 +469,9 @@ export interface CommandMountContext {
  * the design's `ctx.commands` consumption row — a composition without the
  * slash-menu runtime simply never gains the command).
  *
- * Idempotency: the ui-commands registry throws on a duplicate contribution
- * name; that throw is caught and logged, so a double apply (HMR re-apply
- * before the old fiber unloads) degrades to a no-op instead of taking the
- * client half down. Disposal is owned by the registry's effect on the
- * injected fiber — unloading the plugin unregisters the command.
+ * HMR handoff: a duplicate contribution means the old fiber still owns the
+ * name. The new injected fiber retries briefly, then registers its own fresh
+ * contribution after the old disposer runs. Foreign squatters time out.
  */
 export function registerSidecarCommand(
   ctx: CommandMountContext,
@@ -472,11 +480,18 @@ export function registerSidecarCommand(
   try {
     ctx.inject(['commandUi'], (injected) => {
       const { commandUi } = injected as { commandUi: CommandRegistryFace }
-      try {
-        commandUi.register(createSidecarCommandContribution(deps))
-      } catch (err) {
-        console.error('agent-sidecar: /sidecar command registration skipped', err)
-      }
+      return acquireWithHandoff(
+        () => commandUi.register(createSidecarCommandContribution(deps)),
+        {
+          isCollision: isRegistrationCollision,
+          onError: (error) => {
+            console.error('agent-sidecar: /sidecar command registration failed', error)
+          },
+          onTimeout: () => {
+            console.error('agent-sidecar: /sidecar command handoff timed out')
+          },
+        },
+      )
     })
   } catch (err) {
     console.error('agent-sidecar: commandUi injection failed', err)

package/src/client/controller.ts

@@ -169,7 +169,11 @@ function defaultStorage(): StorageLike | null {
   }
 }
 
-/** Parse + validate persisted filters; anything malformed reads as absent. */
+/**
+ * Parse + validate persisted filters; anything malformed reads as absent.
+ * The optional statusFilter (UX-01) survives only as one of its two legal
+ * values — an unrecognized token is dropped, not the whole record.
+ */
 export function readStoredFilters(storage: StorageLike | null): BoardFilterState | null {
   if (storage === null) return null
   try {
@@ -177,7 +181,11 @@ export function readStoredFilters(storage: StorageLike | null): BoardFilterState
     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 }
+    const candidate = parsed as {
+      timeWindowHours?: unknown
+      showDead?: unknown
+      statusFilter?: unknown
+    }
     if (
       typeof candidate.timeWindowHours !== 'number'
       || !Number.isFinite(candidate.timeWindowHours)
@@ -186,7 +194,14 @@ export function readStoredFilters(storage: StorageLike | null): BoardFilterState
     ) {
       return null
     }
-    return { timeWindowHours: candidate.timeWindowHours, showDead: candidate.showDead }
+    const filters: BoardFilterState = {
+      timeWindowHours: candidate.timeWindowHours,
+      showDead: candidate.showDead,
+    }
+    if (candidate.statusFilter === 'working' || candidate.statusFilter === 'waiting') {
+      filters.statusFilter = candidate.statusFilter
+    }
+    return filters
   } catch {
     return null
   }
@@ -326,15 +341,20 @@ export class SidecarController {
     this.notify()
   }
 
-  /** Manual refresh (board's refresh button): one out-of-band snapshot pull. */
-  async refresh(): Promise<void> {
+  /**
+   * Manual refresh (board's refresh button): one out-of-band snapshot
+   * pull. Resolves true when the snapshot applied, false on failure so
+   * the button can surface honest feedback (UX-07) — never rejects; the
+   * stream (and its status surface) remains the health authority.
+   */
+  async refresh(): Promise<boolean> {
     try {
       const snapshot = await this.fetchFn({})
       this.applySnapshot(snapshot)
+      return true
     } 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)
+      return false
     }
   }
 

package/src/client/detail/SessionDetail.tsx

@@ -5,29 +5,50 @@
  * 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`.
+ * handles `onLoadMore` / `onToggleListen` / `onRefresh`.
+ *
+ * Row pipeline (all pure, logic.ts): buildTimelineRows (gaps on the FULL
+ * entry list) → filterTimelineRows (UX-03 kind filter, conversation-first
+ * by default with an honest hidden count) → aggregateChunkRows (UX-03
+ * adjacent empty streaming chunks collapse into one expandable run) →
+ * limitTimelineRows (render cap with a 全部显示 escape hatch).
  *
  * 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
+ * capped at {@link DEFAULT_MAX_RENDER_ROWS} newest rows. View-local
+ * concerns (expanded bodies/runs, filter mode, the lift-cap flag, the
+ * UX-04 initial landing, copy feedback) are component state; everything
  * else comes through props.
  */
 
-import { useEffect, useRef, useState, type ReactElement } from 'react'
 import {
+  Button,
+  Pill,
+  StateDot,
+  writeClipboard,
+  type StateDotState,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import { Fragment, useEffect, useRef, useState, type ReactElement } from 'react'
+import {
+  aggregateChunkRows,
   buildTimelineRows,
   deriveDetailBodyState,
   deriveDetailStatus,
   deriveSourceBadges,
   agentGlyph,
+  filterTimelineRows,
+  formatTemplate,
   limitTimelineRows,
+  shouldStickToLatest,
   DEFAULT_MAX_RENDER_ROWS,
+  type TimelineEventRowVM,
+  type TimelineFilterMode,
   type TimelineRowVM,
   type TimelineVM,
 } from './logic.ts'
 import { DETAIL_STRINGS } from './strings.ts'
+import { StaticPill } from '../primitives/StaticPill.tsx'
+import { surfaceProps } from '../theme/parts.ts'
 import styles from './detail.module.css'
 
 export interface SessionDetailHeaderVM {
@@ -51,8 +72,12 @@ export interface SessionDetailProps {
   hasMore: boolean
   /** Listen mode (SSE-triggered newest-page refetch) currently on. */
   listening: boolean
+  /** True while a manual newest-window refresh is in flight (UX-07). */
+  refreshing?: boolean
   onLoadMore: () => void
   onToggleListen: () => void
+  /** Manual newest-window refetch; the button renders only when given. */
+  onRefresh?: () => void
   onClose?: () => void
   /** Clock injection for deterministic rendering; defaults to Date.now(). */
   nowMs?: number
@@ -61,7 +86,7 @@ export interface SessionDetailProps {
 }
 
 function EventRow(props: {
-  row: Extract<TimelineRowVM, { type: 'event' }>
+  row: TimelineEventRowVM
   expanded: boolean
   onToggleExpand: (key: string) => void
 }): ReactElement {
@@ -84,19 +109,22 @@ function EventRow(props: {
             {DETAIL_STRINGS.timeline.seq.replace('{n}', String(entry.seq))}
           </span>
         )}
-        {row.isNew && <span className={styles['eventNew']}>{DETAIL_STRINGS.timeline.newBadge}</span>}
+        {row.isNew && <Pill className={styles['eventNew']}>{DETAIL_STRINGS.timeline.newBadge}</Pill>}
         <span className={styles['eventSpacer']} />
-        <span className={styles['eventTime']}>{row.relativeTime}</span>
+        <span className={styles['eventTime']}>{row.timeLabel}</span>
       </div>
       {entry.summary !== '' && <div className={styles['eventSummary']}>{entry.summary}</div>}
       {entry.expandable && (
-        <button
+        <Button
           type="button"
+          size="sm"
+          variant="ghost"
           className={styles['expandButton']}
+          aria-expanded={expanded}
           onClick={() => onToggleExpand(entry.key)}
         >
           {expanded ? DETAIL_STRINGS.timeline.collapse : DETAIL_STRINGS.timeline.expand}
-        </button>
+        </Button>
       )}
       {entry.expandable && expanded && entry.body !== null && (
         <pre className={styles['eventBody']}>{entry.body}</pre>
@@ -105,12 +133,62 @@ function EventRow(props: {
   )
 }
 
+/** Collapsed run of adjacent streaming chunks (UX-03); expandable lossless. */
+function ChunkRunRow(props: {
+  row: Extract<TimelineRowVM, { type: 'chunks' }>
+  expanded: boolean
+  onToggleRun: (key: string) => void
+  expandedKeys: ReadonlySet<string>
+  onToggleExpand: (key: string) => void
+}): ReactElement {
+  const { row } = props
+  return (
+    <Fragment>
+      <li
+        className={styles['chunkRun']}
+        data-new={row.isNew || undefined}
+        title={row.hoverTitle}
+        data-testid="agent-sidecar-detail-chunks"
+      >
+        <span className={styles['chunkRunLabel']}>{row.label}</span>
+        <Button
+          type="button"
+          size="sm"
+          variant="ghost"
+          className={styles['expandButton']}
+          aria-expanded={props.expanded}
+          onClick={() => props.onToggleRun(row.key)}
+        >
+          {props.expanded ? DETAIL_STRINGS.timeline.collapse : DETAIL_STRINGS.timeline.expand}
+        </Button>
+        <span className={styles['eventSpacer']} />
+        <span className={styles['eventTime']}>{row.timeLabel}</span>
+      </li>
+      {props.expanded &&
+        row.members.map((member) => (
+          <EventRow
+            key={member.key}
+            row={member}
+            expanded={props.expandedKeys.has(member.key)}
+            onToggleExpand={props.onToggleExpand}
+          />
+        ))}
+    </Fragment>
+  )
+}
+
 /** 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 [expandedRuns, setExpandedRuns] = useState<ReadonlySet<string>>(new Set())
+  const [filterMode, setFilterMode] = useState<TimelineFilterMode>('conversation')
   const [renderAll, setRenderAll] = useState(false)
+  const [copied, setCopied] = useState(false)
   const listRef = useRef<HTMLOListElement | null>(null)
+  const positionedRef = useRef(false)
+  const copyTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const copyAliveRef = useRef(true)
 
   const status = deriveDetailStatus(props.header.status)
   const sourceBadges = deriveSourceBadges(props.timeline.sources)
@@ -121,19 +199,43 @@ export function SessionDetail(props: SessionDetailProps): ReactElement {
   })
 
   const allRows = buildTimelineRows(props.timeline, nowMs)
+  const filtered = filterTimelineRows(allRows, filterMode)
+  const aggregated = aggregateChunkRows(filtered.rows)
   const limited = renderAll
-    ? { rows: allRows, hiddenCount: 0, notice: null }
-    : limitTimelineRows(allRows, props.maxRenderRows ?? DEFAULT_MAX_RENDER_ROWS)
+    ? { rows: aggregated, hiddenCount: 0, notice: null }
+    : limitTimelineRows(aggregated, 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
+    // UX-04 landing + listen-mode tail pinning (shouldStickToLatest):
+    // first non-empty render lands on the newest events; listen appends
+    // keep them in view; paging back never yanks the viewport.
     const list = listRef.current
-    if (list !== null) list.scrollTop = list.scrollHeight
+    if (list === null) return
+    if (
+      shouldStickToLatest({
+        entryCount,
+        positioned: positionedRef.current,
+        listening,
+      })
+    ) {
+      list.scrollTop = list.scrollHeight
+      positionedRef.current = true
+    }
   }, [listening, entryCount])
 
+  useEffect(() => {
+    copyAliveRef.current = true
+    return () => {
+      copyAliveRef.current = false
+      if (copyTimerRef.current !== null) {
+        clearTimeout(copyTimerRef.current)
+        copyTimerRef.current = null
+      }
+    }
+  }, [])
+
   const toggleExpand = (key: string): void => {
     setExpandedKeys((prev) => {
       const next = new Set(prev)
@@ -143,14 +245,41 @@ export function SessionDetail(props: SessionDetailProps): ReactElement {
     })
   }
 
+  const toggleRun = (key: string): void => {
+    setExpandedRuns((prev) => {
+      const next = new Set(prev)
+      if (next.has(key)) next.delete(key)
+      else next.add(key)
+      return next
+    })
+  }
+
+  const copySessionId = async (): Promise<void> => {
+    if (!(await writeClipboard(props.sessionId))) return
+    if (!copyAliveRef.current) return
+    if (copyTimerRef.current !== null) clearTimeout(copyTimerRef.current)
+    setCopied(true)
+    copyTimerRef.current = setTimeout(() => {
+      copyTimerRef.current = null
+      setCopied(false)
+    }, 2000)
+  }
+
+  const statusDotState: StateDotState | null =
+    status.status === 'working'
+      ? 'ongoing'
+      : status.status === 'waiting'
+        ? 'warning'
+        : null
+
   return (
-    <div className={styles['root']} data-testid="agent-sidecar-detail">
+    <div {...surfaceProps('timeline', 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}>
+            <Button type="button" size="sm" variant="outline" onClick={props.onClose}>
               {DETAIL_STRINGS.header.close}
-            </button>
+            </Button>
           )}
           <span className={styles['agent']}>
             <span className={styles['agentGlyph']} aria-hidden>
@@ -158,21 +287,37 @@ export function SessionDetail(props: SessionDetailProps): ReactElement {
             </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} />
+          <StaticPill className={styles['badge']} title={DETAIL_STRINGS.header.observedDisclaimer}>
+            {statusDotState === null
+              ? <span className={styles['dot']} data-tone={status.tone} />
+              : <StateDot state={statusDotState} size={8} />}
             {status.label}
-          </span>
+          </StaticPill>
           <span className={styles['spacer']} />
-          <button
+          {props.onRefresh !== undefined && (
+            <Button
+              type="button"
+              size="sm"
+              variant="outline"
+              disabled={props.refreshing === true}
+              title={DETAIL_STRINGS.header.refreshHint}
+              onClick={props.onRefresh}
+              data-testid="agent-sidecar-detail-refresh"
+            >
+              {props.refreshing === true
+                ? DETAIL_STRINGS.header.refreshing
+                : DETAIL_STRINGS.header.refresh}
+            </Button>
+          )}
+          <Pill
             type="button"
-            className={styles['listenButton']}
+            active={props.listening}
             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>
+          </Pill>
         </div>
         <div className={styles['title']} title={props.header.title}>
           {props.header.title.trim() === '' ? DETAIL_STRINGS.header.untitled : props.header.title}
@@ -183,18 +328,35 @@ export function SessionDetail(props: SessionDetailProps): ReactElement {
               ? DETAIL_STRINGS.header.unknownProject
               : props.header.project}
           </span>
-          <span className={styles['sessionId']} title={props.sessionId}>
+          <Button
+            type="button"
+            size="sm"
+            variant="ghost"
+            className={styles['sessionId']}
+            title={`${props.sessionId} · ${DETAIL_STRINGS.header.copyIdTitle}`}
+            onClick={() => { void copySessionId() }}
+            data-testid="agent-sidecar-detail-copy-id"
+          >
             {props.sessionId}
-          </span>
+          </Button>
+          {copied && (
+            <StaticPill className={styles['copiedBubble']} role="status">
+              {DETAIL_STRINGS.header.copied}
+            </StaticPill>
+          )}
         </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}>
+                <StaticPill
+                  key={badge.id}
+                  className={styles['sourceBadge']}
+                  data-tone={badge.tone}
+                >
                   {badge.label}
-                </span>
+                </StaticPill>
               ))}
             </span>
           )}
@@ -202,30 +364,55 @@ export function SessionDetail(props: SessionDetailProps): ReactElement {
       </header>
 
       {bodyState.errorBanner !== null && (
-        <div className={styles['banner']} role="status">
+        <div className={styles['banner']} role="alert">
           {bodyState.errorBanner}
         </div>
       )}
 
       {bodyState.kind !== 'list' ? (
-        <div className={styles['bodyState']} data-kind={bodyState.kind}>
+        <div
+          className={styles['bodyState']}
+          data-kind={bodyState.kind}
+          role={bodyState.kind === 'error' ? 'alert' : bodyState.kind === 'loading' ? 'status' : undefined}
+        >
           <div className={styles['bodyStateTitle']}>{bodyState.title}</div>
           {bodyState.hint !== null && <div className={styles['bodyStateHint']}>{bodyState.hint}</div>}
         </div>
       ) : (
         <>
+          <div className={styles['filterRow']} data-testid="agent-sidecar-detail-filter">
+            {(['conversation', 'all'] as const).map((mode) => (
+              <Pill
+                key={mode}
+                type="button"
+                active={filterMode === mode}
+                aria-pressed={filterMode === mode}
+                onClick={() => {
+                  setFilterMode(mode)
+                }}
+              >
+                {DETAIL_STRINGS.filter[mode]}
+              </Pill>
+            ))}
+            {filtered.hiddenCount > 0 && (
+              <span className={styles['filterHiddenNote']}>
+                {formatTemplate(DETAIL_STRINGS.filter.hiddenNotice, { n: filtered.hiddenCount })}
+              </span>
+            )}
+          </div>
           <div className={styles['pager']}>
             {props.hasMore ? (
-              <button
+              <Button
                 type="button"
-                className={styles['loadMoreButton']}
+                size="sm"
+                variant="outline"
                 disabled={props.loading}
                 onClick={props.onLoadMore}
               >
                 {props.loading
                   ? DETAIL_STRINGS.timeline.loadingMore
                   : DETAIL_STRINGS.timeline.loadMore}
-              </button>
+              </Button>
             ) : (
               <span className={styles['pagerNote']}>{DETAIL_STRINGS.timeline.noMore}</span>
             )}
@@ -233,13 +420,14 @@ export function SessionDetail(props: SessionDetailProps): ReactElement {
           {limited.notice !== null && (
             <div className={styles['hiddenNotice']}>
               {limited.notice}
-              <button
+              <Button
                 type="button"
-                className={styles['showAllButton']}
+                size="sm"
+                variant="ghost"
                 onClick={() => setRenderAll(true)}
               >
                 {DETAIL_STRINGS.timeline.showAll}
-              </button>
+              </Button>
             </div>
           )}
           <ol className={styles['timeline']} ref={listRef}>
@@ -253,6 +441,15 @@ export function SessionDetail(props: SessionDetailProps): ReactElement {
                 >
                   {row.label}
                 </li>
+              ) : row.type === 'chunks' ? (
+                <ChunkRunRow
+                  key={row.key}
+                  row={row}
+                  expanded={expandedRuns.has(row.key)}
+                  onToggleRun={toggleRun}
+                  expandedKeys={expandedKeys}
+                  onToggleExpand={toggleExpand}
+                />
               ) : (
                 <EventRow
                   key={row.key}