dsh-session-guard 0.1.2 → 0.2.0-beta.1

package/src/client/pause-button-text.ts

@@ -0,0 +1,60 @@
+/**
+ * dsh-session-guard — 暂停/继续按钮文案与状态投影（纯函数，零依赖，可单测）。
+ *
+ * 交互（v0.2.0 修订）：
+ * - 未暂停 → 「暂停会话」（**可点**：点击 = 在下一次 step 边界手动暂停该会话）；
+ * - 已暂停（step 门已拉 / 已请求但未到边界）→ 「继续会话」（点击 = 放行并本峰不再拦）。
+ * 按钮不置灰：step 暂停虽然会自动发生，但按钮同时是**手动暂停**入口。
+ */
+
+/** 按钮状态。 */
+export interface PauseButtonState {
+  /** 是否处于暂停态（step 门已挂起，或已请求暂停但还没到边界） */
+  paused: boolean
+  /** 挂起起始时间戳（毫秒）；未知为 null */
+  heldSince?: number | null
+  /** 暂停是否来自用户手动请求（而非高峰自动拉门） */
+  manual?: boolean
+}
+
+/** 按钮文案。 */
+export function pauseButtonLabel(state: PauseButtonState): string {
+  return state.paused === true ? '继续会话' : '暂停会话'
+}
+
+/** 悬浮说明：写清当前状态与点击后的语义。 */
+export function pauseButtonTitle(state: PauseButtonState): string {
+  if (state.paused !== true) {
+    return '暂停会话：在下一次 step 的模型请求前暂停（高峰 + 官方源时会自动暂停）'
+  }
+  const since = typeof state.heldSince === 'number' && Number.isFinite(state.heldSince) ? new Date(state.heldSince) : null
+  const at = since === null ? null : `${String(since.getHours()).padStart(2, '0')}:${String(since.getMinutes()).padStart(2, '0')}`
+  const why = state.manual === true ? '手动暂停' : '高峰自动暂停'
+  const base = at === null ? `已暂停（${why}）` : `已暂停（${why}，自 ${at}）`
+  return `${base} · 点击继续：放行当前 step，且本高峰内不再拦该会话`
+}
+
+/** 把 `/session-guard/state` 的响应体投影为按钮状态（形状异常 → 未暂停，fail-open）。 */
+export function readPauseState(body: unknown): PauseButtonState {
+  const b = (body ?? {}) as {
+    ok?: unknown
+    paused?: { step?: unknown; manual?: unknown }
+    stepGate?: { since?: unknown; manual?: unknown }
+    state?: { pausedStep?: unknown; stepHeldSince?: unknown; stepManual?: unknown }
+  }
+  if (b.ok !== true) return { paused: false, heldSince: null, manual: false }
+  const manual = b.paused?.manual === true || b.stepGate?.manual === true || b.state?.stepManual === true
+  const paused = b.paused?.step === true || b.state?.pausedStep === true || manual
+  const raw = b.stepGate?.since ?? b.state?.stepHeldSince ?? null
+  const heldSince = typeof raw === 'number' && Number.isFinite(raw) ? raw : null
+  return { paused, heldSince, manual }
+}
+
+/** 把 SSE `/session-guard/events` 的 `state` 快照投影为按钮状态。 */
+export function readStepSnapshot(snapshot: unknown): PauseButtonState {
+  const s = (snapshot ?? {}) as { held?: unknown; since?: unknown; manual?: unknown }
+  const manual = s.manual === true
+  const paused = s.held === true || manual
+  const heldSince = typeof s.since === 'number' && Number.isFinite(s.since) ? s.since : null
+  return { paused, heldSince, manual }
+}

package/src/client/pause-button.tsx

@@ -0,0 +1,129 @@
+/**
+ * dsh-session-guard — 「暂停会话 / 继续会话」按钮（`conversation.input.right`，order 20）。
+ *
+ * 交互（v0.2.0 修订）：
+ * - 未暂停 → 「暂停会话」，**可点**：点击 POST `{action:'stepPause'}`，在**下一次 step 边界**暂停
+ *   （不打断当前 step；step 1 也拦，不受峰谷 / provider 限制）；
+ * - 已暂停（高峰自动拉门 **或** 手动请求已登记）→ 「继续会话」，点击 POST `{action:'stepResume'}`；
+ * - 状态更新双通道：① SSE `/session-guard/events?session=<id>` 即时推送；② 10s 轮询兜底
+ *   （SSE 不可用 / 断线时仍能收敛）。全部 fail-open，绝不抛错。
+ *
+ * 与 input-traffic 的「❄ 冻结追加 / 恢复追加」并列（order 30 在其右侧），互不取代：
+ * 本按钮控 step 门，冻结按钮控回合级冻结 + 队列摘除。
+ */
+import { useEffect, useState } from 'react'
+import {
+  pauseButtonLabel,
+  pauseButtonTitle,
+  readPauseState,
+  readStepSnapshot,
+  type PauseButtonState,
+} from './pause-button-text'
+import { injectClientCss } from './styles'
+
+/** slot 运行时注入的会话级 props。 */
+export interface PauseButtonProps {
+  sessionId?: string
+}
+
+/** SSE 不可用时的兜底轮询间隔（正常路径由事件驱动，几乎不触发）。 */
+const POLL_MS = 10_000
+
+const IDLE: PauseButtonState = { paused: false, heldSince: null, manual: false }
+
+/** 暂停 / 继续会话按钮。 */
+export function PauseButton({ sessionId }: PauseButtonProps) {
+  const [state, setState] = useState<PauseButtonState>(IDLE)
+  const [busy, setBusy] = useState(false)
+
+  injectClientCss()
+
+  useEffect(() => {
+    if (sessionId === undefined || sessionId === '') return
+    let cancelled = false
+
+    const poll = async (): Promise<void> => {
+      try {
+        const res = await fetch(`/session-guard/state?session=${encodeURIComponent(sessionId)}`)
+        const body = await res.json().catch(() => null)
+        if (cancelled) return
+        setState(readPauseState(body))
+      } catch {
+        // fail-open：路由不存在 / 网络失败 → 保持上一次状态。
+      }
+    }
+    void poll()
+    const timer = setInterval(() => {
+      void poll()
+    }, POLL_MS)
+
+    let source: EventSource | undefined
+    try {
+      source = new EventSource(`/session-guard/events?session=${encodeURIComponent(sessionId)}`)
+      source.onmessage = (ev: MessageEvent<string>) => {
+        try {
+          const msg = JSON.parse(ev.data) as { type?: string; state?: unknown }
+          if (cancelled || msg?.type !== 'step') return
+          setState(readStepSnapshot(msg.state))
+        } catch {
+          /* 非法负载：忽略，等下一次推送或轮询 */
+        }
+      }
+      // onerror：EventSource 会自行重连；轮询同时兜底。
+      source.onerror = () => undefined
+    } catch {
+      // 浏览器不支持 EventSource → 只靠轮询。
+    }
+
+    return () => {
+      cancelled = true
+      clearInterval(timer)
+      try {
+        source?.close()
+      } catch {
+        /* ignore */
+      }
+    }
+  }, [sessionId])
+
+  if (sessionId === undefined || sessionId === '') return null
+
+  const paused = state.paused === true
+  const onClick = async (): Promise<void> => {
+    if (busy) return
+    setBusy(true)
+    try {
+      const action = paused ? 'stepResume' : 'stepPause'
+      const res = await fetch('/session-guard/rpc', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ sessionId, action }),
+      })
+      const body = await res.json().catch(() => null)
+      if (body?.ok === true) {
+        // 立即乐观更新；SSE / 轮询随后校正。
+        setState(paused ? IDLE : { paused: true, heldSince: null, manual: true })
+      }
+    } catch {
+      // fail-open：下一轮轮询会纠正显示。
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      className="sg-pause"
+      disabled={busy}
+      aria-pressed={paused || undefined}
+      title={pauseButtonTitle(state)}
+      data-sg-step-paused={paused ? 'on' : 'off'}
+      onClick={() => {
+        void onClick()
+      }}
+    >
+      {pauseButtonLabel(state)}
+    </button>
+  )
+}