@shendeguize/dsh-agent-sidecar 0.1.0

package/src/client/sse.ts

@@ -0,0 +1,366 @@
+/**
+ * StateStream — the browser half's live data feed (design §5.3 / ADR-3).
+ *
+ * One class, two modes, one UI-facing surface (onSnapshot/onStatus):
+ *
+ * - 'sse' (main channel): EventSource on `GET <prefix>/stream`. Every
+ *   `state` event carries a full StateSnapshot (routes.ts pushes full
+ *   snapshots; heartbeats are comment frames the browser never surfaces).
+ *   On top of EventSource's native auto-reconnect, consecutive errors
+ *   beyond the threshold — or a CLOSED readyState — degrade the stream:
+ *   the instance is torn down and manually rebuilt on a 5s→30s capped
+ *   exponential backoff. `degraded` is a visible status, never a circuit
+ *   break; a successful reconnect resets the ladder.
+ * - 'poll' (settings fallback, stream.mode=poll): pollFn (defaults to
+ *   api.fetchState) on a dual cadence — 3s while the latest snapshot has
+ *   a `working` session, 15s otherwise. `visible()` returning false
+ *   pauses fetching (ticks keep running as cheap visibility checks), and
+ *   {@link StateStream.pollNow} gives the visibilitychange handler an
+ *   immediate resume fetch.
+ *
+ * The status vocabulary is unified across modes:
+ * 'connecting' | 'open' | 'degraded'. stop() is terminal and tears
+ * everything down: timers, the EventSource, the in-flight poll fetch
+ * (aborted), and both listener sets.
+ *
+ * Pure data layer: no React, no slots SDK, injectable primitives only.
+ *
+ * @module
+ */
+
+import {
+  API_PREFIX,
+  fetchState,
+  type AbortControllerLike,
+  type AbortSignalLike,
+  type StateSnapshot,
+  type TimerHandle,
+} from './api.ts'
+
+/** SSE endpoint within the plugin route namespace (host: routes.ts). */
+export const STREAM_PATH = `${API_PREFIX}/stream`
+
+export type StreamMode = 'sse' | 'poll'
+
+/** Unified connection status shown to the UI in both modes. */
+export type StreamStatus = 'connecting' | 'open' | 'degraded'
+
+export type SnapshotListener = (snapshot: StateSnapshot) => void
+export type StatusListener = (status: StreamStatus) => void
+
+/** Minimal shape of a named SSE message event. */
+export interface EventSourceMessageLike {
+  data?: unknown
+}
+
+/** Structural EventSource, so node tests can fake it and DOM satisfies it. */
+export interface EventSourceLike {
+  readonly readyState: number
+  addEventListener(type: string, listener: (ev: EventSourceMessageLike) => void): void
+  close(): void
+}
+
+export type EventSourceFactory = (url: string) => EventSourceLike
+
+/** Poll-mode snapshot source; receives an abort signal wired to stop(). */
+export type PollFn = (opts: { signal?: AbortSignalLike }) => Promise<StateSnapshot>
+
+/** EventSource.CLOSED (numeric literal so fakes need no DOM constants). */
+const EVENTSOURCE_CLOSED = 2
+
+const DEFAULT_POLL_ACTIVE_MS = 3_000
+const DEFAULT_POLL_IDLE_MS = 15_000
+const DEFAULT_ERROR_THRESHOLD = 3
+const DEFAULT_BACKOFF_BASE_MS = 5_000
+const DEFAULT_BACKOFF_CAP_MS = 30_000
+
+export interface StateStreamOptions {
+  /** Stream endpoint for 'sse' mode; see {@link STREAM_PATH}. */
+  url: string
+  mode: StreamMode
+  /** SSE transport factory. Default: `new EventSource(url)`. */
+  eventSourceFactory?: EventSourceFactory
+  /** Poll-mode snapshot source. Default: api.fetchState. */
+  pollFn?: PollFn
+  /** Poll cadence while some session is `working`. Default 3000. */
+  pollActiveMs?: number
+  /** Poll cadence while everything is idle. Default 15000. */
+  pollIdleMs?: number
+  /** Visibility gate (inverse of document.hidden); absent = always visible. */
+  visible?: () => boolean
+  setTimeout?: (fn: () => void, ms: number) => TimerHandle
+  clearTimeout?: (handle: TimerHandle) => void
+  /** Abort factory for in-flight poll fetches. Default: real AbortController. */
+  createAbortController?: () => AbortControllerLike
+  /** Consecutive SSE errors tolerated before degrading. Default 3. */
+  errorThreshold?: number
+  /** First manual-rebuild backoff delay. Default 5000. */
+  backoffBaseMs?: number
+  /** Manual-rebuild backoff ceiling. Default 30000. */
+  backoffCapMs?: number
+}
+
+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()
+
+const defaultEventSourceFactory: EventSourceFactory = (url) => {
+  const Ctor = (globalThis as { EventSource?: new (url: string) => unknown }).EventSource
+  if (Ctor === undefined) {
+    throw new Error('EventSource unavailable: inject eventSourceFactory or use poll mode')
+  }
+  return new Ctor(url) as EventSourceLike
+}
+
+const defaultPollFn: PollFn = (opts) => fetchState({ signal: opts.signal })
+
+export class StateStream {
+  private readonly url: string
+  private readonly streamMode: StreamMode
+  private readonly esFactory: EventSourceFactory
+  private readonly pollFn: PollFn
+  private readonly pollActiveMs: number
+  private readonly pollIdleMs: number
+  private readonly visibleFn: (() => boolean) | undefined
+  private readonly setT: (fn: () => void, ms: number) => TimerHandle
+  private readonly clearT: (handle: TimerHandle) => void
+  private readonly createController: () => AbortControllerLike
+  private readonly errorThreshold: number
+  private readonly backoffBaseMs: number
+  private readonly backoffCapMs: number
+
+  private currentStatus: StreamStatus = 'connecting'
+  private started = false
+  private stopped = false
+  private readonly snapshotListeners = new Set<SnapshotListener>()
+  private readonly statusListeners = new Set<StatusListener>()
+
+  // --- sse state ---
+  private es: EventSourceLike | null = null
+  private sseErrors = 0
+  private rebuildAttempts = 0
+  private rebuildTimer: TimerHandle | null = null
+
+  // --- poll state ---
+  private pollTimer: TimerHandle | null = null
+  private inFlight: AbortControllerLike | null = null
+  private lastSnapshot: StateSnapshot | null = null
+
+  constructor(opts: StateStreamOptions) {
+    this.url = opts.url
+    this.streamMode = opts.mode
+    this.esFactory = opts.eventSourceFactory ?? defaultEventSourceFactory
+    this.pollFn = opts.pollFn ?? defaultPollFn
+    this.pollActiveMs = opts.pollActiveMs ?? DEFAULT_POLL_ACTIVE_MS
+    this.pollIdleMs = opts.pollIdleMs ?? DEFAULT_POLL_IDLE_MS
+    this.visibleFn = opts.visible
+    this.setT = opts.setTimeout ?? defaultSetTimeout
+    this.clearT = opts.clearTimeout ?? defaultClearTimeout
+    this.createController = opts.createAbortController ?? defaultCreateAbortController
+    this.errorThreshold = opts.errorThreshold ?? DEFAULT_ERROR_THRESHOLD
+    this.backoffBaseMs = opts.backoffBaseMs ?? DEFAULT_BACKOFF_BASE_MS
+    this.backoffCapMs = opts.backoffCapMs ?? DEFAULT_BACKOFF_CAP_MS
+  }
+
+  get mode(): StreamMode {
+    return this.streamMode
+  }
+
+  get status(): StreamStatus {
+    return this.currentStatus
+  }
+
+  /** Begin streaming. One-shot: calling again (or after stop) is a no-op. */
+  start(): void {
+    if (this.started || this.stopped) return
+    this.started = true
+    if (this.streamMode === 'sse') this.connectSse()
+    else this.pollTick()
+  }
+
+  /**
+   * Terminal teardown: clears every timer, closes the EventSource, aborts
+   * the in-flight poll fetch, and drops all listeners. Idempotent; a
+   * stopped stream cannot be restarted (build a fresh instance instead).
+   */
+  stop(): void {
+    if (this.stopped) return
+    this.stopped = true
+    if (this.rebuildTimer !== null) {
+      this.clearT(this.rebuildTimer)
+      this.rebuildTimer = null
+    }
+    if (this.pollTimer !== null) {
+      this.clearT(this.pollTimer)
+      this.pollTimer = null
+    }
+    const es = this.es
+    this.es = null
+    if (es !== null) es.close()
+    const inFlight = this.inFlight
+    this.inFlight = null
+    if (inFlight !== null) inFlight.abort()
+    this.snapshotListeners.clear()
+    this.statusListeners.clear()
+  }
+
+  /** Subscribe to snapshots; returns the unsubscribe function. */
+  onSnapshot(cb: SnapshotListener): () => void {
+    if (this.stopped) return () => {}
+    this.snapshotListeners.add(cb)
+    return () => {
+      this.snapshotListeners.delete(cb)
+    }
+  }
+
+  /**
+   * Subscribe to status changes; fires synchronously with the current
+   * status on subscription, then on every transition. Returns the
+   * unsubscribe function.
+   */
+  onStatus(cb: StatusListener): () => void {
+    if (this.stopped) return () => {}
+    this.statusListeners.add(cb)
+    cb(this.currentStatus)
+    return () => {
+      this.statusListeners.delete(cb)
+    }
+  }
+
+  /**
+   * Immediate out-of-cadence poll (poll mode only). This is the
+   * visibility-resume hook: wire the document's `visibilitychange` event
+   * to call this when the page becomes visible again, so "resume → fetch
+   * immediately" holds without waiting for the next scheduled tick. Any
+   * pending tick is cancelled first, so cadence never doubles up.
+   */
+  pollNow(): void {
+    if (!this.started || this.stopped || this.streamMode !== 'poll') return
+    if (this.pollTimer !== null) {
+      this.clearT(this.pollTimer)
+      this.pollTimer = null
+    }
+    this.pollTick()
+  }
+
+  // ------------------------------------------------------------------ sse
+
+  private connectSse(): void {
+    if (this.stopped) return
+    const es = this.esFactory(this.url)
+    this.es = es
+    es.addEventListener('open', () => {
+      if (this.stopped || this.es !== es) return
+      this.sseErrors = 0
+      this.rebuildAttempts = 0
+      this.setStatus('open')
+    })
+    es.addEventListener('state', (ev) => {
+      if (this.stopped || this.es !== es) return
+      if (typeof ev.data !== 'string') return
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(ev.data)
+      } catch {
+        return
+      }
+      if (typeof parsed !== 'object' || parsed === null) return
+      this.emitSnapshot(parsed as StateSnapshot)
+    })
+    es.addEventListener('error', () => {
+      if (this.stopped || this.es !== es) return
+      this.sseErrors += 1
+      if (es.readyState === EVENTSOURCE_CLOSED || this.sseErrors > this.errorThreshold) {
+        this.scheduleRebuild()
+      } else {
+        // EventSource's native auto-reconnect is still in charge.
+        this.setStatus('connecting')
+      }
+    })
+  }
+
+  /**
+   * Take over from native auto-reconnect: close the instance, surface
+   * `degraded`, and rebuild after a doubling delay capped at
+   * backoffCapMs. Never gives up — the ladder just stays at the cap.
+   */
+  private scheduleRebuild(): void {
+    const es = this.es
+    this.es = null
+    if (es !== null) es.close()
+    this.setStatus('degraded')
+    const delay = Math.min(this.backoffBaseMs * 2 ** this.rebuildAttempts, this.backoffCapMs)
+    this.rebuildAttempts += 1
+    this.rebuildTimer = this.setT(() => {
+      this.rebuildTimer = null
+      this.connectSse()
+    }, delay)
+  }
+
+  // ----------------------------------------------------------------- poll
+
+  private hasWorkingSession(): boolean {
+    const snap = this.lastSnapshot
+    if (snap === null) return false
+    return snap.board.sessions.some((s) => s.status === 'working')
+  }
+
+  private scheduleNextPoll(): void {
+    if (this.stopped) return
+    const delay = this.hasWorkingSession() ? this.pollActiveMs : this.pollIdleMs
+    this.pollTimer = this.setT(() => {
+      this.pollTimer = null
+      this.pollTick()
+    }, delay)
+  }
+
+  private pollTick(): void {
+    if (this.stopped) return
+    if (this.visibleFn !== undefined && !this.visibleFn()) {
+      // Hidden: pause fetching but keep ticking as a cheap visibility
+      // check, so a tab left hidden resumes by itself at the next tick.
+      this.scheduleNextPoll()
+      return
+    }
+    if (this.inFlight !== null) {
+      // A slow previous poll is still running; never overlap fetches.
+      this.scheduleNextPoll()
+      return
+    }
+    const controller = this.createController()
+    this.inFlight = controller
+    this.pollFn({ signal: controller.signal }).then(
+      (snapshot) => {
+        if (this.stopped || this.inFlight !== controller) return
+        this.inFlight = null
+        this.lastSnapshot = snapshot
+        this.setStatus('open')
+        this.emitSnapshot(snapshot)
+        this.scheduleNextPoll()
+      },
+      () => {
+        if (this.stopped || this.inFlight !== controller) return
+        this.inFlight = null
+        this.setStatus('degraded')
+        this.scheduleNextPoll()
+      },
+    )
+  }
+
+  // ------------------------------------------------------------- plumbing
+
+  private setStatus(status: StreamStatus): void {
+    if (this.currentStatus === status) return
+    this.currentStatus = status
+    for (const cb of [...this.statusListeners]) cb(status)
+  }
+
+  private emitSnapshot(snapshot: StateSnapshot): void {
+    for (const cb of [...this.snapshotListeners]) cb(snapshot)
+  }
+}

package/src/client/widget.tsx

@@ -0,0 +1,80 @@
+/**
+ * Footer status widget (design §5.1 view 4, `sidebar.footer.action` slot).
+ *
+ * Presentation-only: connection state and working count arrive as props
+ * (derive them with `deriveWidgetConnection` / `countWorking` from
+ * `board/logic.ts`); the click callback is wired to the board tab by the
+ * integration layer.
+ *
+ * Quiet by design: at zero working sessions only the connection dot shows,
+ * no counter, no animation — the DOM stays stable so the footer never
+ * flickers or shifts (task spec: 零数据时安静).
+ */
+
+import type { CSSProperties, ReactElement } from 'react'
+import { widgetTitle, type WidgetConnection } from './board/logic.ts'
+
+export interface SidecarWidgetProps {
+  connection: WidgetConnection
+  workingCount: number
+  /** Opens the board tab; wired by the integration layer. */
+  onOpen?: () => void
+}
+
+const DOT_COLORS: Record<WidgetConnection, string> = {
+  ok: 'var(--dsw-alias-state-success-primary, #1a7f37)',
+  degraded: 'var(--dsw-alias-state-warn-primary, #9a6700)',
+  off: 'var(--dsw-alias-label-dimmed, #8c959f)',
+}
+
+const rootStyle: CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 4,
+  padding: '2px 6px',
+  border: 'none',
+  borderRadius: 6,
+  background: 'transparent',
+  cursor: 'pointer',
+  font: 'inherit',
+  color: 'var(--dsw-alias-label-secondary, #57606a)',
+}
+
+const countStyle: CSSProperties = {
+  fontSize: 11,
+  fontVariantNumeric: 'tabular-nums',
+  lineHeight: '14px',
+  whiteSpace: 'nowrap',
+}
+
+/** Connection dot + working-session counter (e.g. `▸2`) for the footer. */
+export function SidecarWidget(props: SidecarWidgetProps): ReactElement {
+  const title = widgetTitle(props.connection, props.workingCount)
+  return (
+    <button
+      type="button"
+      style={rootStyle}
+      title={title}
+      aria-label={title}
+      onClick={props.onOpen}
+      data-testid="agent-sidecar-widget"
+      data-connection={props.connection}
+    >
+      <span
+        aria-hidden
+        style={{
+          width: 8,
+          height: 8,
+          borderRadius: '50%',
+          flex: 'none',
+          background: DOT_COLORS[props.connection],
+        }}
+      />
+      {props.workingCount > 0 && (
+        <span style={countStyle} data-testid="agent-sidecar-widget-count">
+          {`▸${props.workingCount}`}
+        </span>
+      )}
+    </button>
+  )
+}

package/src/config.ts

@@ -0,0 +1,193 @@
+/**
+ * Composition config for the dsh-agent-sidecar host half (design §6, scoped
+ * to the task-approved field set). schemastery-validated by the cordis
+ * Loader; every field carries a default so a bare patch row (no `config:`
+ * block) mounts with zero configuration, and `.description()` strings feed
+ * the dsh settings pane renderer.
+ *
+ * Grouping mirrors the runtime module it feeds:
+ * - `daemon`   → DaemonSupervisor (src/supervisor.ts)
+ * - `sidecar`  → CLI/daemon invocation (command + runtime dir redirect)
+ * - `stream`   → Reconciler cadences (src/bridge.ts)
+ * - `inject`   → the guard's write gate (src/guard.ts); M2 consumes the rest
+ * - `analysis` / `ui` / `skill` → M3/M4 surfaces, contractual today so the
+ *   config face does not churn per milestone.
+ *
+ * @module
+ */
+
+import z from '@deepseek-ai/schemastery'
+import type { SupervisorPolicy } from './supervisor.ts'
+
+/** Daemon lifecycle governance (design §4.a). */
+export interface DaemonConfig {
+  /** adopt-or-host: probe→adopt→else spawn; adopt-only: never spawn; off: no lifecycle management (read-only reconcile still runs). */
+  policy: SupervisorPolicy
+  /** Consecutive hosting failures before the supervisor trips FAILED. */
+  backoffLimit: number
+}
+
+/** How to reach/launch the sidecar itself. */
+export interface SidecarInvocationConfig {
+  /** argv prefix of the sidecar executable (PATH name, absolute path, or e.g. python3+zipapp as multiple entries). */
+  command: string[]
+  /** Empty = default `~/.agent_sidecar` (honoring AGENT_SIDECAR_RUNTIME_DIR); non-empty redirects via env for spawned daemons. */
+  runtimeDir: string
+}
+
+/** Reconciler snapshot cadences (design §4.b / ADR-2). */
+export interface StreamConfig {
+  /** `status` snapshot cadence while any session is working (ms). */
+  reconcileActiveMs: number
+  /** `status` snapshot cadence otherwise (ms). */
+  reconcileIdleMs: number
+}
+
+/** Write-path master switch and defaults (M2 consumes defaultMode). */
+export interface InjectConfig {
+  /** Master gate: false hides all inject affordances and 403s write actions server-side. */
+  enabled: boolean
+  /** Default injection mode offered by the inject panel. */
+  defaultMode: 'queue' | 'steer'
+}
+
+/** AI bypass-analysis switch and model routing (M3). */
+export interface AnalysisConfig {
+  enabled: boolean
+  /**
+   * Explicit provider route for the dedicated analysis agents. Empty (the
+   * default) reuses the host's default model selection (`agentDefaultModel`
+   * service, the same source dsh's own entry points read). Takes effect
+   * only together with a non-empty `model`.
+   */
+  provider: string
+  /** Explicit model id for the analysis agents; see {@link provider}. */
+  model: string
+}
+
+/** Board rendering knobs (client half). */
+export interface UiConfig {
+  /** Session recency window shown on the board (hours). */
+  timeWindowHours: number
+  /** Whether dead sessions are listed. */
+  showDead: boolean
+}
+
+/** Skill provider switch (design §6/§7 path two; wired in M4/T6.2). */
+export interface SkillConfig {
+  /** Register the embedded agent-sidecar skill on ctx.skills (read at apply; restart semantics). */
+  provide: boolean
+}
+
+/** Validated composition config (all defaults filled by the schema). */
+export interface Config {
+  daemon: DaemonConfig
+  sidecar: SidecarInvocationConfig
+  stream: StreamConfig
+  inject: InjectConfig
+  analysis: AnalysisConfig
+  ui: UiConfig
+  skill: SkillConfig
+}
+
+export const Config: z<Config> = z.object({
+  daemon: z
+    .object({
+      policy: z
+        .union([z.const('adopt-or-host'), z.const('adopt-only'), z.const('off')])
+        .default('adopt-or-host')
+        .description(
+          'daemon 托管策略:adopt-or-host=探测并领养既有 daemon,否则自行拉起;adopt-only=只领养绝不拉起;off=不管理 daemon 生命周期(仍只读对账既有 daemon 的数据)',
+        ),
+      backoffLimit: z
+        .natural()
+        .min(1)
+        .default(5)
+        .description('托管失败熔断阈值:连续失败达到该次数后停止重启并进入 FAILED'),
+    })
+    .description('daemon 生命周期治理'),
+  sidecar: z
+    .object({
+      command: z
+        .array(String)
+        .default(['agent-sidecar'])
+        .description(
+          'sidecar 可执行命令(argv 前缀):PATH 名、绝对路径,或多段命令(如 ["python3", "/path/to/agent-sidecar.pyz"]);插件绝不代装',
+        ),
+      runtimeDir: z
+        .string()
+        .default('')
+        .description(
+          '运行时目录:留空用默认 ~/.agent_sidecar(尊重 AGENT_SIDECAR_RUNTIME_DIR 环境变量);非空时经环境变量传给受托管的 daemon',
+        ),
+    })
+    .description('sidecar 调用方式'),
+  stream: z
+    .object({
+      reconcileActiveMs: z
+        .natural()
+        .min(100)
+        .default(2000)
+        .description('对账快照周期(有会话工作中,毫秒)'),
+      reconcileIdleMs: z
+        .natural()
+        .min(100)
+        .default(10000)
+        .description('对账快照周期(空闲,毫秒)'),
+    })
+    .description('数据流对账节奏'),
+  inject: z
+    .object({
+      enabled: z
+        .boolean()
+        .default(false)
+        .description(
+          '注入总开关:关闭时看板隐藏全部注入入口,写接口在服务端同步拒绝(默认关闭;多用户主机不建议开启)',
+        ),
+      defaultMode: z
+        .union([z.const('queue'), z.const('steer')])
+        .default('queue')
+        .description('注入面板默认模式:queue=排队下一轮,steer=中途注入'),
+    })
+    .description('消息注入'),
+  analysis: z
+    .object({
+      enabled: z
+        .boolean()
+        .default(false)
+        .description('AI 旁路分析开关(M3;消耗模型 token,默认关闭)'),
+      provider: z
+        .string()
+        .default('')
+        .description(
+          '分析代理的 provider 路由:留空(默认)复用宿主默认模型(agentDefaultModel 服务);与 model 同时非空才生效',
+        ),
+      model: z
+        .string()
+        .default('')
+        .description(
+          '分析代理的模型 id:留空(默认)复用宿主默认模型;与 provider 同时非空才生效',
+        ),
+    })
+    .description('旁路分析'),
+  ui: z
+    .object({
+      timeWindowHours: z
+        .natural()
+        .min(1)
+        .default(24)
+        .description('看板会话时间窗(小时)'),
+      showDead: z.boolean().default(false).description('是否显示 dead 会话'),
+    })
+    .description('看板界面'),
+  skill: z
+    .object({
+      provide: z
+        .boolean()
+        .default(true)
+        .description(
+          '是否经 registerProvider 内嵌提供 agent-sidecar skill(设计 §6 默认开;文件系统已装的同名 skill 自动优先;改动需重载插件生效)',
+        ),
+    })
+    .description('skill 模式'),
+})