dsh-smooth-stream 0.3.3 → 0.4.0

package/src/client/useSmoothStreamContent.ts

@@ -14,6 +14,8 @@
  */
 
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { DEFAULT_STREAM_DEBUG_TUNING, type StreamDebugTuning } from '../settings.ts'
+import { debugRuntime } from './debugRuntime.ts'
 
 export type StreamSmoothingPreset = 'realtime' | 'balanced' | 'silky'
 
@@ -117,13 +119,14 @@ export function computeAdaptiveQueueStep(
   dtMs: number,
   debt: number,
   revealScale = 1,
+  tuning: StreamDebugTuning = DEFAULT_STREAM_DEBUG_TUNING,
 ): AdaptiveQueueStep {
   if (backlog <= 0 || dtMs <= 0) return { revealChars: 0, debt: 0, speedCps: 0 }
   const speedCps = Math.min(
-    QUEUE_MAX_SPEED_CPS,
-    QUEUE_BASE_SPEED_CPS + Math.pow(backlog, QUEUE_ACCEL_EXPONENT) * QUEUE_PRESSURE_FACTOR,
+    tuning.maxRevealCps,
+    QUEUE_BASE_SPEED_CPS + Math.pow(backlog, QUEUE_ACCEL_EXPONENT) * tuning.queuePressure,
   )
-  const effectiveScale = clamp(revealScale, 0.05, 1)
+  const effectiveScale = clamp(revealScale * tuning.revealScale, 0.05, 2)
   const accumulated = Math.max(0, debt) + speedCps * effectiveScale * (dtMs / 1000)
   const revealChars = Math.min(backlog, Math.floor(accumulated))
   return { revealChars, debt: revealChars >= backlog ? 0 : accumulated - revealChars, speedCps }
@@ -313,6 +316,7 @@ export function useSmoothStreamContent(
   revealScaleOutRef.current = revealScaleRef
   const inputCompleteRef = useRef(inputComplete)
   inputCompleteRef.current = inputComplete
+  const streamIdRef = useRef(`stream-${Math.random().toString(36).slice(2)}`)
 
   useEffect(() => {
     holdBackRef.current = shouldHoldBack
@@ -374,6 +378,7 @@ export function useSmoothStreamContent(
         settleCpsRef.current = null
         const speedOut = speedOutRef.current
         if (speedOut !== undefined) speedOut.current = seedCps
+        debugRuntime.reportStream(streamIdRef.current, null)
         stopFrameLoop()
         return
       }
@@ -390,6 +395,7 @@ export function useSmoothStreamContent(
 
       const idleMs = now - lastInputTsRef.current
       const producerComplete = inputCompleteRef.current
+      const debugTuning = debugRuntime.activeTuning()
       const inputActive = !producerComplete && idleMs <= config.activeInputWindowMs
       const settling = producerComplete || (!inputActive && idleMs >= config.settleAfterMs)
       if (!producerComplete) settleCpsRef.current = null
@@ -422,7 +428,7 @@ export function useSmoothStreamContent(
           },
           dtSeconds,
         )
-        revealChars = Math.min(step.revealChars, backlog)
+        revealChars = Math.min(Math.round(step.revealChars * debugTuning.revealScale), backlog)
         revealSpeedCps = frameIntervalMs > 0 ? (revealChars * 1000) / frameIntervalMs : 0
       } else {
         const step = computeAdaptiveQueueStep(
@@ -430,12 +436,21 @@ export function useSmoothStreamContent(
           frameIntervalMs,
           queueDebtRef.current,
           revealScaleOutRef.current?.current ?? 1,
+          debugTuning,
         )
         revealChars = step.revealChars
         revealSpeedCps = step.speedCps
         nextQueueDebt = step.debt
       }
 
+      debugRuntime.reportStream(streamIdRef.current, {
+        backlog,
+        speedCps: revealSpeedCps,
+        targetChars: targetCount,
+        displayedChars: displayedCount,
+        active: !producerComplete,
+      })
+
       // Performance guard: while degraded and the reply is offscreen, skip
       // the DOM commit — the backlog keeps accumulating and flushes when the
       // guard clears or the reply scrolls into view.
@@ -527,6 +542,7 @@ export function useSmoothStreamContent(
   useEffect(() => {
     return () => {
       stopFrameLoop()
+      debugRuntime.reportStream(streamIdRef.current, null)
     }
   }, [stopFrameLoop])
 

package/src/plugin.ts

@@ -7,8 +7,18 @@ import { DEFAULT_STREAM_CONFIG, type StreamConfig } from './config.ts'
 import { injectStreamConfig } from './boot-config.ts'
 import { STREAM_PACKAGE_NAME, STREAM_PACKAGE_VERSION } from './package-meta.ts'
 import { inspectProfileInstallation, updateNpmProfilePackage } from './profile-installation.ts'
-import { STREAM_SETTINGS_RPC, STREAM_SETTINGS_RPC_CHANNEL, type StreamSettingsView } from './settings-api.ts'
-import { DEFAULT_STREAM_SETTINGS, STREAM_SETTINGS_NS, type StreamSettings } from './settings.ts'
+import {
+  STREAM_SETTINGS_RPC,
+  STREAM_SETTINGS_RPC_CHANNEL,
+  type StreamDebugSettingsView,
+  type StreamSettingsView,
+} from './settings-api.ts'
+import {
+  DEFAULT_STREAM_SETTINGS,
+  STREAM_SETTINGS_NS,
+  type StreamDebugTuning,
+  type StreamSettings,
+} from './settings.ts'
 
 /** Display name shown by the Host loader while the plugin is mounted. */
 export const name = 'dsh-smooth-stream'
@@ -42,7 +52,21 @@ export const Config: Schema<Config> = Schema.object({
  * settings provider while the browser edits it through the plugin RPC below.
  */
 export const StreamSettingsSchema: Schema<StreamSettings> = Schema.object({
+  enabled: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.enabled),
   thinkAutoExpand: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.thinkAutoExpand),
+  autoCollapse: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.autoCollapse),
+  debugEnabled: Schema.boolean().default(DEFAULT_STREAM_SETTINGS.debugEnabled),
+  debugTuning: Schema.object({
+    revealScale: Schema.number().min(0.25).max(2).default(DEFAULT_STREAM_SETTINGS.debugTuning.revealScale),
+    queuePressure: Schema.number().min(0).max(2).default(DEFAULT_STREAM_SETTINGS.debugTuning.queuePressure),
+    maxRevealCps: Schema.number().min(120).max(1000).default(DEFAULT_STREAM_SETTINGS.debugTuning.maxRevealCps),
+    springStiffness: Schema.number().min(40).max(320).default(DEFAULT_STREAM_SETTINGS.debugTuning.springStiffness),
+    springDamping: Schema.number().min(8).max(80).default(DEFAULT_STREAM_SETTINGS.debugTuning.springDamping),
+    springMass: Schema.number().min(0.5).max(3).default(DEFAULT_STREAM_SETTINGS.debugTuning.springMass),
+    runwayPx: Schema.number().min(0).max(120).default(DEFAULT_STREAM_SETTINGS.debugTuning.runwayPx),
+    reserveResponseMs: Schema.number().min(60).max(600).default(DEFAULT_STREAM_SETTINGS.debugTuning.reserveResponseMs),
+    backpressureMinScale: Schema.number().min(0.25).max(1).default(DEFAULT_STREAM_SETTINGS.debugTuning.backpressureMinScale),
+  }),
 })
 
 /**
@@ -79,25 +103,61 @@ export function apply(ctx: Context, config: Config): void {
 
       const view = (): StreamSettingsView => {
         const installation = inspectProfileInstallation(connectionCtx.baseUrl, STREAM_PACKAGE_NAME)
+        const settings = scope.get()
         return {
           version: STREAM_PACKAGE_VERSION,
           installation: installation.kind,
           writable: connectionCtx.settings.writable,
-          thinkAutoExpand: scope.get().thinkAutoExpand,
+          enabled: settings.enabled,
+          thinkAutoExpand: settings.thinkAutoExpand,
+          autoCollapse: settings.autoCollapse,
           canUpgrade: installation.kind === 'npm',
         }
       }
 
+      const debugView = (): StreamDebugSettingsView => {
+        const settings = scope.get()
+        return {
+          debugEnabled: settings.debugEnabled,
+          tuning: { ...settings.debugTuning },
+        }
+      }
+
+      const validDebugTuning = (value: unknown): value is StreamDebugTuning => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+        const tuning = value as Record<string, unknown>
+        return typeof tuning.revealScale === 'number'
+          && tuning.revealScale >= 0.25 && tuning.revealScale <= 2
+          && typeof tuning.queuePressure === 'number'
+          && tuning.queuePressure >= 0 && tuning.queuePressure <= 2
+          && typeof tuning.maxRevealCps === 'number'
+          && tuning.maxRevealCps >= 120 && tuning.maxRevealCps <= 1000
+          && typeof tuning.springStiffness === 'number'
+          && tuning.springStiffness >= 40 && tuning.springStiffness <= 320
+          && typeof tuning.springDamping === 'number'
+          && tuning.springDamping >= 8 && tuning.springDamping <= 80
+          && typeof tuning.springMass === 'number'
+          && tuning.springMass >= 0.5 && tuning.springMass <= 3
+          && typeof tuning.runwayPx === 'number'
+          && tuning.runwayPx >= 0 && tuning.runwayPx <= 120
+          && typeof tuning.reserveResponseMs === 'number'
+          && tuning.reserveResponseMs >= 60 && tuning.reserveResponseMs <= 600
+          && typeof tuning.backpressureMinScale === 'number'
+          && tuning.backpressureMinScale >= 0.25 && tuning.backpressureMinScale <= 1
+      }
+
       const handle: ConnectionRpcHandler = async (endpoint, payload) => {
         if (endpoint === STREAM_SETTINGS_RPC.read) return { ok: true, value: view() }
         if (endpoint === STREAM_SETTINGS_RPC.write) {
-          if (typeof payload !== 'object' || payload === null
-            || typeof (payload as { thinkAutoExpand?: unknown }).thinkAutoExpand !== 'boolean') {
+          if (typeof payload !== 'object' || payload === null || Array.isArray(payload)
+            || typeof (payload as { enabled?: unknown }).enabled !== 'boolean'
+            || typeof (payload as { thinkAutoExpand?: unknown }).thinkAutoExpand !== 'boolean'
+            || typeof (payload as { autoCollapse?: unknown }).autoCollapse !== 'boolean') {
             return {
               ok: false,
               error: {
                 code: 'settings-rejected',
-                message: 'thinkAutoExpand must be a boolean',
+                message: 'enabled, thinkAutoExpand and autoCollapse must be booleans',
                 details: { ns: STREAM_SETTINGS_NS },
               },
             }
@@ -113,7 +173,30 @@ export function apply(ctx: Context, config: Config): void {
             }
           }
           try {
-            await scope.update({ thinkAutoExpand: (payload as { thinkAutoExpand: boolean }).thinkAutoExpand })
+            const next = payload as {
+              enabled: boolean
+              thinkAutoExpand: boolean
+              autoCollapse: boolean
+              debugEnabled?: unknown
+              debugTuning?: unknown
+            }
+            const hasDebug = next.debugEnabled !== undefined || next.debugTuning !== undefined
+            if (hasDebug && (typeof next.debugEnabled !== 'boolean' || !validDebugTuning(next.debugTuning))) {
+              return {
+                ok: false,
+                error: {
+                  code: 'settings-rejected',
+                  message: 'debugEnabled and debugTuning must be provided together and be valid',
+                  details: { ns: STREAM_SETTINGS_NS },
+                },
+              }
+            }
+            await scope.update({
+              enabled: next.enabled,
+              thinkAutoExpand: next.thinkAutoExpand,
+              autoCollapse: next.autoCollapse,
+              ...(hasDebug ? { debugEnabled: next.debugEnabled, debugTuning: next.debugTuning } : {}),
+            })
           } catch {
             return {
               ok: false,
@@ -126,6 +209,53 @@ export function apply(ctx: Context, config: Config): void {
           }
           return { ok: true, value: view() }
         }
+        if (endpoint === STREAM_SETTINGS_RPC.debugRead) return { ok: true, value: debugView() }
+        if (endpoint === STREAM_SETTINGS_RPC.debugWrite) {
+          if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+            return {
+              ok: false,
+              error: {
+                code: 'settings-rejected',
+                message: 'debug settings must be an object',
+                details: { ns: STREAM_SETTINGS_NS },
+              },
+            }
+          }
+          const next = payload as { debugEnabled?: unknown; tuning?: unknown }
+          if (typeof next.debugEnabled !== 'boolean' || !validDebugTuning(next.tuning)) {
+            return {
+              ok: false,
+              error: {
+                code: 'settings-rejected',
+                message: 'debugEnabled and tuning are malformed',
+                details: { ns: STREAM_SETTINGS_NS },
+              },
+            }
+          }
+          if (!connectionCtx.settings.writable) {
+            return {
+              ok: false,
+              error: {
+                code: 'settings-rejected',
+                message: 'smooth-stream debug settings are read-only',
+                details: { ns: STREAM_SETTINGS_NS },
+              },
+            }
+          }
+          try {
+            await scope.update({ debugEnabled: next.debugEnabled, debugTuning: next.tuning })
+          } catch {
+            return {
+              ok: false,
+              error: {
+                code: 'settings-rejected',
+                message: 'smooth-stream debug settings update failed',
+                details: { ns: STREAM_SETTINGS_NS },
+              },
+            }
+          }
+          return { ok: true, value: debugView() }
+        }
         if (endpoint === STREAM_SETTINGS_RPC.upgrade) {
           const installation = inspectProfileInstallation(connectionCtx.baseUrl, STREAM_PACKAGE_NAME)
           if (installation.kind !== 'npm') {

package/src/settings-api.ts

@@ -7,6 +7,8 @@ export const STREAM_SETTINGS_RPC_CHANNEL = '/smooth-stream'
 export const STREAM_SETTINGS_RPC = {
   read: 'settings.read',
   write: 'settings.write',
+  debugRead: 'debug.read',
+  debugWrite: 'debug.write',
   upgrade: 'plugin.upgrade',
 } as const
 
@@ -21,12 +23,22 @@ export interface StreamSettingsView {
   installation: StreamInstallationKind
   /** Whether the Host settings provider permits a write. */
   writable: boolean
+  /** Whether smooth-stream currently owns conversation rendering. */
+  enabled: boolean
   /** Current resolved preference. */
   thinkAutoExpand: boolean
+  /** Whether finished turns fold their work process behind a summary row. */
+  autoCollapse: boolean
   /** Whether a fixed npm update command is safe to offer. */
   canUpgrade: boolean
 }
 
+/** Debug-only settings returned by the diagnostics RPC. */
+export interface StreamDebugSettingsView {
+  debugEnabled: boolean
+  tuning: import('./settings.ts').StreamDebugTuning
+}
+
 /** Successful package update acknowledgement; loading the new code needs a restart. */
 export interface StreamUpgradeView {
   restartRequired: true

package/src/settings.ts

@@ -10,21 +10,76 @@
 /** Settings namespace registered by the Host and served through the plugin RPC. */
 export const STREAM_SETTINGS_NS = 'smooth-stream'
 
+/** Runtime knobs exposed only while the diagnostics switch is enabled. */
+export interface StreamDebugTuning {
+  /** Multiplier applied to the reveal cadence (1 = preset default). */
+  revealScale: number
+  /** Multiplier for backlog pressure in the adaptive reveal queue. */
+  queuePressure: number
+  /** Upper bound for reveal cadence, in characters per second. */
+  maxRevealCps: number
+  /** Spring stiffness used by the conversation follower. */
+  springStiffness: number
+  /** Spring damping used by the conversation follower. */
+  springDamping: number
+  /** Spring mass used by the conversation follower. */
+  springMass: number
+  /** Predictive runway before the fixed conversation chrome, in pixels. */
+  runwayPx: number
+  /** Response time for opening/closing the predictive runway, in ms. */
+  reserveResponseMs: number
+  /** Lowest reveal multiplier when visual lag fills the safe paint room. */
+  backpressureMinScale: number
+}
+
+/** Defaults preserve the production engine exactly. */
+export const DEFAULT_STREAM_DEBUG_TUNING: StreamDebugTuning = {
+  revealScale: 1,
+  queuePressure: 0.85,
+  maxRevealCps: 600,
+  springStiffness: 130,
+  springDamping: 24,
+  springMass: 1,
+  runwayPx: 48,
+  reserveResponseMs: 180,
+  backpressureMinScale: 0.55,
+}
+
 /**
  * Preferences a user may set. Deliberately separate from {@link StreamConfig}
  * because the two change at different times: composition-time values go
  * through the boot global, a live UI edit goes through the protected plugin RPC.
  */
 export interface StreamSettings {
+  /**
+   * Whether this plugin replaces and wraps Harness conversation renderers.
+   * Off returns all rendering ownership to the built-in UI.
+   */
+  enabled: boolean
   /**
    * Whether a reasoning ("Think") block auto-expands while it is the
    * streaming tail. Off keeps the block collapsed — the user can still open
    * it by hand — and stops the running state from re-owning the disclosure.
    */
   thinkAutoExpand: boolean
+  /**
+   * Whether a finished turn folds its work process (thinking, tool calls,
+   * context injection, intermediate replies) behind one "已处理" summary row,
+   * leaving only the final answer visible. The summary row can always be
+   * toggled by hand, and turns still expand live while they stream.
+   */
+  autoCollapse: boolean
+  /** Whether the live renderer diagnostics panel is enabled. */
+  debugEnabled: boolean
+  /** Values edited by the diagnostics panel. */
+  debugTuning: StreamDebugTuning
 }
 
 /** Defaults shared by the Host schema and the client-side fallback. */
 export const DEFAULT_STREAM_SETTINGS: StreamSettings = {
+  enabled: true,
   thinkAutoExpand: true,
+  autoCollapse: true,
+  debugEnabled: false,
+  debugTuning: DEFAULT_STREAM_DEBUG_TUNING,
 }