cc-viewer 1.9.17 → 1.9.19

package/dist/index.html

@@ -21,7 +21,7 @@
     // 整体显示大小已弃用 CSS zoom：Electron 改用 webFrame.setZoomFactor（首屏抢占见
     // electron/tab-content-preload.js），纯浏览器交由用户用浏览器自带快捷键缩放，故此处不再设 zoom。
   </script>
-  <script type="module" crossorigin src="./assets/index-B4J-uwYG.js"></script>
+  <script type="module" crossorigin src="./assets/index-C4_-ImaE.js"></script>
   <link rel="modulepreload" crossorigin href="./assets/vendor-antd-I6I2F7Rv.js">
   <link rel="modulepreload" crossorigin href="./assets/vendor-codemirror-Zkm6UHQg.js">
   <link rel="modulepreload" crossorigin href="./assets/vendor-mdxeditor-CC09MDyZ.js">

package/dist/voice-packs/default/pack.json

@@ -14,11 +14,22 @@
     "turnEnd": {
       "file": "It_is_done_sir.MP3",
       "size": 45816
+    },
+    "agentLoopStart": {
+      "file": "agentLoopStart.wav",
+      "size": 12394
+    },
+    "agentLoopEnd": {
+      "file": "It_is_done_sir.MP3",
+      "size": 45816
     }
   },
   "voiceLines": {
     "planApproval": "The plan awaits your approval, sir.",
     "askQuestion": "A choice for your consideration, sir.",
     "turnEnd": "It is done, sir."
+  },
+  "cues": {
+    "agentLoopStart": "Dee-dee!  (短促上行双音，\"开工\")"
   }
 }

package/dist/voice-packs/sanguo/pack.json

@@ -14,11 +14,22 @@
     "turnEnd": {
       "file": "end.MP3",
       "size": 70894
+    },
+    "agentLoopStart": {
+      "file": "agentLoopStart.wav",
+      "size": 12394
+    },
+    "agentLoopEnd": {
+      "file": "end.MP3",
+      "size": 70894
     }
   },
   "voiceLines": {
     "planApproval": "请陛下御览。",
     "askQuestion": "请陛下圣裁。",
     "turnEnd": "臣已办妥。"
+  },
+  "cues": {
+    "agentLoopStart": "Dee-dee!  (短促上行双音，\"开工\")"
   }
 }

package/node_modules/@ccv/core/src/voice-pack-events.js

@@ -19,6 +19,8 @@ export const EVENT_KEYS = [
   'planApproval',
   'askQuestion',
   'turnEnd',
+  'agentLoopStart',
+  'agentLoopEnd',
 ];
 
 // Per-event default binding when no user override is set:
@@ -26,11 +28,16 @@ export const EVENT_KEYS = [
 //   - 'sanguo'  → play the bundled sanguo (三国) audio — initial seed for zh/zh-TW
 //   - null      → event is OFF by default (user must opt in)
 // turnEnd defaults to null because firing on every Claude reply is noisy
-//( — frequency overload mitigation).
+//( — frequency overload mitigation). agentLoopStart/agentLoopEnd are likewise
+// per-turn and stay off by default for the same frequency reason. (Enabling both
+// agentLoopEnd and turnEnd does NOT double-ring: the client suppresses the legacy
+// turnEnd cue when agentLoopEnd actually played for the same boundary.)
 export const DEFAULT_BINDINGS = Object.freeze({
   planApproval: 'default',
   askQuestion: 'default',
   turnEnd: null,
+  agentLoopStart: null,
+  agentLoopEnd: null,
 });
 
 // Bundled packs that ship inside the npm tarball under public/voice-packs/<id>/.
@@ -54,13 +61,15 @@ const LOCALE_DEFAULT_SEEDS = Object.freeze({
 });
 
 // Per-event default bindings for a given locale pack. Event keys that should
-// stay off-by-default (turnEnd is noisy on every reply) keep null regardless
-// of which pack the locale prefers.
+// stay off-by-default (turnEnd is noisy on every reply; the agentLoop pair is
+// likewise per-turn) keep null regardless of which pack the locale prefers.
 function bindingsForPack(packId) {
   return Object.freeze({
     planApproval: packId,
     askQuestion: packId,
     turnEnd: null,
+    agentLoopStart: null,
+    agentLoopEnd: null,
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-viewer",
-  "version": "1.9.17",
+  "version": "1.9.19",
   "description": "Claude Code logging, visualization, and management toolkit — launch a web viewer alongside Claude Code with full request/response tracing, proxy, and mobile support",
   "license": "MIT",
   "main": "server.js",
@@ -66,7 +66,7 @@
     "ws": "^8.21.0"
   },
   "optionalDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.91"
+    "@anthropic-ai/claude-agent-sdk": "^0.2.124"
   },
   "//bundledDependencies": "@ccv/core is the private workspace package (packages/core). npm pack follows the pnpm workspace symlink and ships it as real files inside the tarball — no registry publish, no import rewriting.",
   "bundledDependencies": [

package/server/lib/attach-buffer.js

@@ -0,0 +1,164 @@
+// Attach buffer (2026-10): closes the cold-load → clients.push broadcast-loss
+// window on /events.
+//
+// Background: serveEventStream deliberately does NOT register the client into
+// deps.clients until the whole cold history + load_end has been written (see
+// the "do not clients.push here" note in routes/events.js — a live entry
+// arriving mid-load would be overwritten by load_end's setState, causing a
+// show→disappear→reappear flicker). The cost is a real gap: any live v2 delta
+// that lands between the
+// frozen cold snapshot and the registration is neither in that snapshot nor
+// broadcast to this not-yet-registered client, and the server has no retained
+// replay. The FIRST turn of a fresh `ccv --sdk` is the turn most likely to fall
+// into this gap (lazy resident-query construction + first-time session-dir
+// creation slow the cold load while the first turn is already producing
+// entries), so the conversation stalls until a manual refresh re-cold-loads.
+//
+// The fix is a per-connection buffer proxy: while the cold load runs, a
+// stand-in client — stamped with the SAME _ccvViewProject/_ccvViewInstance as
+// the eventual registrable so the existing feed routing delivers exactly the
+// frames this connection is owed — sits in deps.clients and queues every SSE
+// frame instead of writing a socket. After load_end (and kv/context), the
+// queued frames are replayed through the real sink in emission order, then the
+// proxy is swapped for the real registrable in one synchronous block (no
+// broadcast can interleave between the replay and the swap on the single
+// thread). The anti-flicker invariant is preserved because the proxy never
+// writes the socket before load_end.
+//
+// Dedup: rows (v2_requests_delta) and responses lines (v3_resp) upsert
+// client-side by (sessionId, seq) and are therefore idempotent — replay them
+// verbatim. v3_conv is NOT idempotent on the client (createV3Assembler
+// appends conv events and consumes them with a monotonic pointer, so a
+// replayed line that the cold bundle already carried would be applied twice
+// and duplicate messages). The server therefore filters replayed v3_conv
+// frames against the cold bundle's conv coverage (`native.convSeqs` from
+// readV2NativeCold): a frame is skipped when its seq was already sent.
+
+import { reportSwallowed } from './error-report.js';
+
+/** Per-connection cap on buffered bytes (mirrors the mux QUEUE_MAX_BYTES). */
+export const ATTACH_BUFFER_MAX_BYTES = 32 * 1024 * 1024;
+
+const CONV_FRAME_PREFIX = 'event: v3_conv\ndata: ';
+
+/**
+ * Create a buffer client that stands in for one /events connection during its
+ * cold load. Compatible with _safeSseWrite (log-watcher.js): it exposes
+ * destroyed/writable/write, _wireEnc stays undefined so sseWrite routes the raw
+ * (uncompressed) SSE text straight to write(), and write() ALWAYS returns true
+ * so the backpressure-kill branch never fires for a proxy.
+ *
+ * @param {{project?: string, instance?: string, maxBytes?: number,
+ *          onOverflow?: (bytes: number) => void}} opts
+ */
+export function createAttachBufferClient({ project, instance, maxBytes, onOverflow } = {}) {
+  const limit = Number.isFinite(maxBytes) && maxBytes > 0 ? maxBytes : ATTACH_BUFFER_MAX_BYTES;
+  const client = {
+    destroyed: false,
+    writable: true,
+    _wireEnc: undefined,
+    _ccvAttachBuffer: true,
+    frames: [],
+    bytes: 0,
+    overflowed: false,
+    write(text) {
+      if (client.destroyed || client.overflowed) return true;
+      const len = typeof text === 'string' ? text.length : (text ? text.length : 0);
+      if (client.bytes + len > limit) {
+        // Overflow: degrade to today's pre-fix behavior (drop the window's
+        // increments) rather than risk an unbounded queue. Never replay a
+        // partial window — a truncated conv/row sequence would corrupt order.
+        const at = client.bytes + len;
+        client.overflowed = true;
+        client._clear();
+        try { if (onOverflow) onOverflow(at); }
+        catch (err) { reportSwallowed('sse.attach-buffer.overflow-cb', err); }
+        return true;
+      }
+      client.frames.push(text);
+      client.bytes += len;
+      return true;
+    },
+    end() { client._clear(); client.destroyed = true; client.writable = false; },
+    // No-op listener surface: nothing should hang off a proxy, but a stray
+    // .once('drain') from a future code path must not throw.
+    on() {}, once() {}, off() {}, removeListener() {},
+    _clear() { client.frames.length = 0; client.bytes = 0; },
+  };
+  // Stamp the SAME view scope the real registrable will carry, so
+  // filterClientsByViewProject / filterClientsByInstance route this proxy
+  // exactly the frames the eventual client should receive.
+  if (project) client._ccvViewProject = project;
+  if (instance) client._ccvViewInstance = instance;
+  return client;
+}
+
+/**
+ * Extract the seq of a v3_conv frame's line, or null when the frame is not a
+ * conv frame / cannot be parsed. Parses the {sessionId, channel, line}
+ * envelope the live feed forwards (live-feed.js _forwardNative).
+ * @returns {{key: string, seq: number|null} | null}
+ */
+function _parseConvFrame(frameText) {
+  if (typeof frameText !== 'string' || !frameText.startsWith(CONV_FRAME_PREFIX)) return null;
+  const jsonStart = CONV_FRAME_PREFIX.length;
+  const jsonEnd = frameText.indexOf('\n', jsonStart);
+  const json = jsonEnd === -1 ? frameText.slice(jsonStart) : frameText.slice(jsonStart, jsonEnd);
+  let env;
+  try { env = JSON.parse(json); } catch { return null; }
+  if (!env || typeof env.sessionId !== 'string') return null;
+  const channel = typeof env.channel === 'string' ? env.channel : 'main';
+  const seq = env.line && Number.isInteger(env.line.seq) ? env.line.seq : null;
+  return { key: `${env.sessionId}\x00${channel}`, seq };
+}
+
+/**
+ * Should this replayed conv frame be skipped because the cold bundle already
+ * carried it? A frame is covered when its channel's coverage has the seq in
+ * its window set, OR the seq predates the window's base (a snapshot before
+ * baseSeq was already reflected in the cold assembly — replaying it would be
+ * consumed a second time by the monotonic conv pointer).
+ */
+function _isCoveredConvFrame(frameText, convCoverage) {
+  if (!convCoverage) return false;
+  const parsed = _parseConvFrame(frameText);
+  if (!parsed || parsed.seq === null) return false; // fail-open: replay
+  const cov = convCoverage.get(parsed.key);
+  if (!cov) return false;
+  if (cov.seqs && cov.seqs.has(parsed.seq)) return true;
+  if (Number.isInteger(cov.baseSeq) && parsed.seq < cov.baseSeq) return true;
+  return false;
+}
+
+/**
+ * Replay the queued frames through the real sink (in emission order), skipping
+ * any v3_conv frame the cold bundle already covered. Safe to call with a null
+ * or overflowed client (no-op). Stops at the first dead sink or write error.
+ *
+ * @param {{write: (s:string)=>any, alive?: ()=>boolean}} sink
+ * @param {object|null} client - the attach buffer client.
+ * @param {Map<string,{seqs:Set<number>, baseSeq:number}>|null} convCoverage
+ * @returns {{replayed: number, skipped: number}}
+ */
+export function flushAttachBuffer(sink, client, convCoverage) {
+  const result = { replayed: 0, skipped: 0 };
+  if (!client || client.overflowed || client.destroyed) {
+    if (client) client._clear();
+    return result;
+  }
+  const frames = client.frames;
+  for (let i = 0; i < frames.length; i++) {
+    if (typeof sink.alive === 'function' && !sink.alive()) break;
+    const frame = frames[i];
+    if (_isCoveredConvFrame(frame, convCoverage)) { result.skipped++; continue; }
+    try {
+      sink.write(frame);
+      result.replayed++;
+    } catch (err) {
+      reportSwallowed('sse.attach-buffer.flush', err);
+      break;
+    }
+  }
+  client._clear();
+  return result;
+}

package/server/lib/plugin-loader.js

@@ -31,8 +31,17 @@ const HOOK_TYPES = {
   serverStopping: 'parallel',
   onNewEntry: 'parallel',
   onStreamChunk: 'parallel',
+  onAgentLoopStart: 'parallel',
+  onAgentLoopEnd: 'parallel',
 };
 
+// Approval hooks gate an interactive UI modal, so a hung plugin must not park the approval
+// forever: each invocation times out and falls back to the normal approval modal.
+// Non-approval waterfall hooks (beforeRequest/httpsOptions/localUrl) are startup/auth-critical
+// and stay UNTIMED.
+const APPROVAL_HOOK_TIMEOUT_MS = 15 * 1000;
+const APPROVAL_HOOKS = new Set(['onPlanRequest', 'onAskRequest', 'onPermRequest']);
+
 let _plugins = [];
 // Full result of the last loadPlugins (directory service/panel plugins and failures included)
 let _entries = [];
@@ -312,14 +321,39 @@ export async function loadPlugins(opts = {}) {
 
 /**
  * waterfall hook：串行管道执行，前一个的返回值传给下一个
+ * `timeoutMsOverride` is test-only; approval hooks default to APPROVAL_HOOK_TIMEOUT_MS.
  */
-export async function runWaterfallHook(name, initialValue) {
+export async function runWaterfallHook(name, initialValue, timeoutMsOverride) {
   let value = initialValue;
+  // Only approval hooks are timed out; the override is ignored for the other hooks.
+  const timeoutMs = APPROVAL_HOOKS.has(name)
+    ? (timeoutMsOverride ?? APPROVAL_HOOK_TIMEOUT_MS)
+    : undefined;
   for (const plugin of _plugins) {
     const hookFn = plugin.hooks[name];
     if (typeof hookFn !== 'function') continue;
     try {
-      const result = await hookFn(value);
+      let result;
+      if (timeoutMs !== undefined) {
+        // A timed-out hook promise itself is not cancellable (bounded leak: it may keep
+        // running in the background); the timer is cleared as soon as the hook settles.
+        let timer;
+        try {
+          result = await Promise.race([
+            Promise.resolve().then(() => hookFn(value)),
+            new Promise((_, reject) => {
+              timer = setTimeout(
+                () => reject(new Error(`hook timed out after ${timeoutMs} ms`)),
+                timeoutMs
+              );
+            }),
+          ]);
+        } finally {
+          clearTimeout(timer);
+        }
+      } else {
+        result = await hookFn(value);
+      }
       if (result != null && typeof result === 'object') {
         value = { ...value, ...result };
       }

package/server/lib/plugin-runtime.js

@@ -491,7 +491,7 @@ function buildPluginContext(rt) {
       on(event, cb) {
         // Subscriptions go into the runtime dispatcher table (injected into the loader pipeline via
         // getEventDispatcherPlugin); abort on deactivate/unload unsubscribes. No second event bus.
-        const hookName = event === 'new_entry' ? 'onNewEntry' : event === 'stream_chunk' ? 'onStreamChunk' : null;
+        const hookName = EVENT_TO_HOOK[event] || null;
         if (!hookName || typeof cb !== 'function') return () => {};
         const wrapper = (payload) => { if (!signal.aborted) cb(payload); };
         _eventSubs[hookName].add(wrapper);
@@ -508,14 +508,24 @@ function buildPluginContext(rt) {
 
 // Events dispatcher: the subscription table lives in the runtime; getEventDispatcherPlugin()
 // returns the plugin object that bridges into the loader hook pipeline (no second event bus).
+// ctx.events.on('…') event name → the loader hook that feeds it (agent_loop_* are the
+// service-plugin view of the agent-loop lifecycle, same payload as the SSE frames).
+const EVENT_TO_HOOK = {
+  new_entry: 'onNewEntry',
+  stream_chunk: 'onStreamChunk',
+  agent_loop_start: 'onAgentLoopStart',
+  agent_loop_end: 'onAgentLoopEnd',
+};
 const _eventDispatcher = {
   name: 'ccv-plugin-events',
   hooks: {
     onNewEntry(payload) { dispatchEvent('onNewEntry', payload); },
     onStreamChunk(payload) { dispatchEvent('onStreamChunk', payload); },
+    onAgentLoopStart(payload) { dispatchEvent('onAgentLoopStart', payload); },
+    onAgentLoopEnd(payload) { dispatchEvent('onAgentLoopEnd', payload); },
   },
 };
-const _eventSubs = { onNewEntry: new Set(), onStreamChunk: new Set() };
+const _eventSubs = { onNewEntry: new Set(), onStreamChunk: new Set(), onAgentLoopStart: new Set(), onAgentLoopEnd: new Set() };
 function dispatchEvent(hookName, payload) {
   for (const fn of _eventSubs[hookName]) {
     try { fn(payload); } catch (err) { reportSwallowed('plugin-runtime.event', err); }