@quekenao/dsh-auto-continue-community 0.0.0-stage → 0.3.2

package/index.js

@@ -0,0 +1,1024 @@
+/**
+ * dsh-auto-continue-community
+ *
+ * Automatically continues a model response when it is cut off at the output
+ * token limit (finish.kind === "max-tokens"), so the agent loop receives a
+ * complete answer without the user having to type "继续".
+ *
+ * Two operating modes (config `mode`, default "loop"):
+ *
+ *   loop (REALTIME, default)
+ *     The plugin does NOT buffer the model stream.  The agent loop streams
+ *     tokens to the UI in real time (dsh-agent-loop streams chunks live and
+ *     detects max-tokens at the RESULT level).  The plugin observes the
+ *     `agent/assistant-stream` frames; when a step's stream ends with a
+ *     `finish` chunk of kind `max-tokens`, it calls `agent.steer(continuationMsg)`
+ *     to queue a continuation prompt as the NEXT step of the SAME turn.  The
+ *     agent loop's turn loop keeps the turn open while `inbox.nextStep` has
+ *     work, so the continuation runs immediately after the truncated step,
+ *     still streaming in real time.  Truncation detection is by reading the
+ *     finish chunk's `reason.kind` from the stream frames.
+ *
+ *   stream (BUFFERED, fallback / legacy)
+ *     The plugin intercepts the `llm/stream` waterfall, buffers the whole
+ *     upstream stream, detects max-tokens from the final finish chunk,
+ *     re-invokes the model with a continuation prompt, and merges the two
+ *     streams into one.  Because the finish reason only arrives at
+ *     stream-end, the entire upstream stream is held before forwarding, so
+ *     tokens do NOT appear in the UI in real time — they appear all at once
+ *     after the stream (and any continuation) completes.  This is the
+ *     original edition's behavior.
+ *
+ * The loop mode is the "top-tier" upgrade: real-time token display.  The
+ * stream mode is retained as a guaranteed fallback — if the loop mode
+ * misbehaves in a given deployment, set `mode: "stream"` (or
+ * DSH_AUTOCONTINUE_MODE=stream) to fall back to the known-good buffering
+ * path.  The two modes are mutually exclusive at load time; the plugin
+ * registers only the listeners for the active mode.
+ *
+ * Tool-call handling:
+ *  - Complete tool calls (block-end received) are safe: DSH discards them
+ *    on max-tokens finish, so the continuation simply resumes the text
+ *    that was cut off after them.
+ *  - Incomplete tool calls (delta without block-end, i.e. JSON arguments
+ *    truncated mid-stream) are NOT continued — the model cannot repair
+ *    malformed JSON.
+ *
+ * Design invariants:
+ *  - Activates only for the configured provider(s).  Cloud API providers
+ *    have their own pipeline optimizations and must not be intercepted.
+ *    The provider gate is configurable via the patch `config` block or the
+ *    `DSH_AUTOCONTINUE_PROVIDERS` environment variable (comma-separated);
+ *    defaults to "local-vision".
+ *  - Per-session continuation counter resets on every non-truncated
+ *    response; capped at maxContinuations per single response chain.
+ *  - Continuation re-entrancy is detected via a non-enumerable string-key
+ *    property (CONTINUATION_MARK) on the continuation message, invisible to
+ *    JSON.stringify and spread, so it is safe for any downstream serializer.
+ *  - If the continuation fails, the plugin degrades to the original
+ *    truncated response.
+ *
+ * Community edition differences vs the internal `dsh-auto-continue`:
+ *  - Debug log path is portable (OS temp dir + plugin name), never a
+ *    hardcoded absolute path.
+ *  - Provider gate, continuation budget, timeout AND mode are configurable.
+ *  - Real-time loop mode (default) + buffered stream mode (fallback).
+ *  - Pure helper functions (analyzeChunks, mergeChunks, sumUsage, the
+ *    session-counter store, the loop-state store, the continuation-gate
+ *    decision) are named exports so they can be unit-tested in isolation
+ *    (see test/).
+ *
+ * SCOPE / COMPATIBILITY (read before deploying):
+ *
+ *   This plugin is ONLY validated for the following stack.  It will not
+ *   necessarily behave correctly outside it.
+ *
+ *   Topology:   DSH + llama.cpp + a local model
+ *   Versions:   DSH 0.2.1-rc.5  ·  @deepseek-ai/cordis ~4.0.5
+ *               @deepseek-ai/dsh-llm 0.2.1-rc.5
+ *               @deepseek-ai/dsh-agent-loop 0.2.1-rc.5
+ *               @deepseek-ai/dsh-web-app 0.2.1-rc.5
+ *               Node.js >= 24 (developed/tested on v24.18.0)
+ *   Surface:    Web surface ONLY (`dsh web`).  The loop mode observes the
+ *               `agent/assistant-stream` emit event and drives the agent
+ *               driver's `steer()` (next-step inbox) to inject the
+ *               continuation; the stream mode uses the LlmRuntime
+ *               `llm/stream` waterfall.  The client / CLI surface is NOT
+ *               adapted and is NOT supported by this edition — we do not
+ *               ship client support.
+ *
+ *   The `llm/stream` waterfall hook, the BlockAssembler block-indexing
+ *   convention, the `agent/pre-step` decision shape, and the max-tokens
+ *   tool-call discard behavior it relies on are specific to the DSH
+ *   0.2.1-rc.5 line.  A different DSH major version, a non-llama.cpp
+ *   backend, or the client surface are out of scope.
+ */
+
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Defaults (overridable via patch `config` block or environment variables).
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_CONTINUATIONS = 5;
+const DEFAULT_CONTINUATION_TIMEOUT_MS = 120_000;
+const DEFAULT_PROVIDERS = ['local-vision'];
+const DEFAULT_MODE = 'loop'; // 'loop' (realtime, default) | 'stream' (buffered fallback)
+const VALID_MODES = new Set(['loop', 'stream']);
+
+// String-key marker on continuation messages.
+// NOTE: must be ENUMERABLE — DSH's session layer uses Reflect.ownKeys +
+// propertyIsEnumerable (dsh-util-values/walkJsonValue) and rejects any
+// object with non-enumerable own properties as "non-JSON-serializable".
+// The key is a string (not a Symbol) so it survives JSON round-trips and
+// is robust against future DSH serialization changes. It is harmless in
+// the session log: it's a top-level boolean on the message envelope, not
+// inside the content the LLM sees.
+export const CONTINUATION_MARK = '__dsh_auto_continue_continuation__';
+
+const CONTINUE_PROMPT_TEXT =
+  '[CONTINUATION REQUIRED] Your previous response was truncated at the output token limit. ' +
+  'Continue from EXACTLY where you stopped. Do NOT repeat any text, do NOT add a preamble, ' +
+  'do NOT apologize. Simply resume the content that was cut off.';
+
+// Used when the truncated response contained complete tool calls.
+// DSH discards ALL tool-call blocks when finish.kind === "max-tokens"
+// (dsh-llm/lib/index.js: the kept filter drops them before the agent
+// loop sees them), so the agent has no tool blocks in its message
+// history.  The prompt therefore describes the situation factually and
+// asks the model to continue its narrative text without re-issuing
+// tool calls or referring to tool results that do not exist.
+const CONTINUE_PROMPT_TEXT_WITH_TOOLCALLS =
+  '[CONTINUATION REQUIRED] Your previous response was truncated at the output token limit. ' +
+  'You had already emitted one or more tool calls before the text was cut off. ' +
+  'Those tool calls have NOT been executed and are NOT in your context. ' +
+  'Do NOT repeat them, do NOT refer to their results, and do NOT issue new tool calls. ' +
+  'Continue the narrative text that was cut off — resume EXACTLY from where you stopped. ' +
+  'Do NOT add a preamble, do NOT apologize.';
+
+// ---------------------------------------------------------------------------
+// Session continuation counter store (named export for tests).
+//
+// A Map used for LRU ordering: every access (get/set) moves the key to the
+// end, so `prune` can evict from the front (least-recently-used).
+// ---------------------------------------------------------------------------
+
+export const sessionCounters = new Map();
+
+export function counterKey(options) {
+  if (!options || !options.sessionId) return '__default__';
+  return String(options.sessionId);
+}
+
+/**
+ * Get the counter for `key`, touching it (moves to most-recently-used).
+ * Creates an entry at 0 if absent.
+ */
+export function getCounter(key) {
+  let n = sessionCounters.get(key);
+  if (n === undefined) {
+    n = 0;
+    sessionCounters.set(key, n);
+  } else {
+    // Touch: re-insert to move to the MRU end.
+    sessionCounters.delete(key);
+    sessionCounters.set(key, n);
+  }
+  return n;
+}
+
+export function incCounter(key) {
+  const n = getCounter(key) + 1;
+  sessionCounters.set(key, n);
+  return n;
+}
+
+export function resetCounter(key) {
+  const cur = sessionCounters.get(key);
+  if (cur !== undefined) {
+    sessionCounters.delete(key);
+  }
+  sessionCounters.set(key, 0);
+}
+
+/**
+ * Prune stale counters in long-running processes.  At most once per
+ * `minIntervalMs`, only when the map exceeds `maxEntries`.  Evicts from the
+ * front of the Map (least-recently-used), keeping the `keep` most recently
+ * active.  Returns the number of entries evicted.
+ */
+let lastPrune = 0;
+export function pruneCounters(now = Date.now(), { maxEntries = 256, keep = 128, minIntervalMs = 60_000 } = {}) {
+  if (sessionCounters.size <= maxEntries || now - lastPrune < minIntervalMs) return 0;
+  lastPrune = now;
+  const keys = [...sessionCounters.keys()];
+  let evicted = 0;
+  for (let i = 0; i < keys.length - keep; i++) {
+    sessionCounters.delete(keys[i]);
+    evicted++;
+  }
+  return evicted;
+}
+
+// ---------------------------------------------------------------------------
+// Stream analysis / merge helpers (named exports for tests).  Used by the
+// "stream" (buffered) mode.  The "loop" (realtime) mode does not buffer, so
+// it does not call these on the upstream stream.
+// ---------------------------------------------------------------------------
+
+/**
+ * Buffer an async iterable (or sync iterable, for Node 24+ compat) of
+ * StreamChunks into an array.
+ *
+ * Node 24 removed implicit sync-iterable support in `for await...of`.
+ * Some LlmAdapter implementations may return a sync iterable from
+ * `stream()`.  Detect and handle both.
+ */
+export async function collectChunks(stream) {
+  const chunks = [];
+  if (!stream) {
+    throw new TypeError('collectChunks: stream is undefined/null');
+  }
+  if (typeof stream[Symbol.asyncIterator] === 'function') {
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+    return chunks;
+  }
+  if (typeof stream[Symbol.iterator] === 'function') {
+    for (const chunk of stream) {
+      chunks.push(chunk);
+    }
+    return chunks;
+  }
+  if (typeof stream.next === 'function') {
+    let r;
+    do {
+      r = await stream.next();
+      if (r && !r.done) chunks.push(r.value);
+    } while (!(r && r.done));
+    return chunks;
+  }
+  throw new TypeError('collectChunks: not an iterable. keys=' + Object.keys(stream).join(',') + ' proto=' + Object.getOwnPropertyNames(Object.getPrototypeOf(stream) || {}).join(','));
+}
+
+/**
+ * Normalize a finish reason to a canonical kind string.
+ * Handles: { kind: 'max-tokens' }, { reason: 'max_tokens' },
+ * or the plain string 'max-tokens' / 'max_tokens'.
+ */
+export function finishKind(chunk) {
+  const r = chunk.reason;
+  if (typeof r === 'string') return r.replace(/[_-]/g, '-');
+  if (r && typeof r === 'object') {
+    const k = r.kind || r.reason;
+    if (typeof k === 'string') return k.replace(/[_-]/g, '-');
+  }
+  return '';
+}
+
+/**
+ * Scan a chunk array and classify tool-call blocks by completion state.
+ *
+ * Block identity is by `chunk.index`, mirroring BlockAssembler
+ * (dsh-llm/lib/types/assembler.js): a tool-call block is "opened" by its
+ * first tool-call-delta (or block-start) and "closed" by the first
+ * block-end for that index with block.type === 'tool-call'.  Deltas
+ * after close are ignored.
+ *
+ * Returns:
+ *  - truncated: any finish chunk has kind "max-tokens"
+ *  - hasCompleteToolCall: at least one tool-call block was closed
+ *    (block-end received) — DSH discards these on max-tokens finish,
+ *    so a continuation that resumes the following text is safe.
+ *  - hasIncompleteToolCall: at least one tool-call block was opened
+ *    (deltas seen) but never closed — JSON arguments are malformed
+ *    and continuation cannot repair them.
+ *  - hasToolCall: union of the two (kept for log readability).
+ *  - finishIdx: index of the LAST finish chunk, or -1.
+ */
+export function analyzeChunks(chunks) {
+  let truncated = false;
+  let hasCompleteToolCall = false;
+  let hasIncompleteToolCall = false;
+  let finishIdx = -1;
+  let missingIndexDeltas = 0;
+  let missingIndexBlockEnds = 0;
+
+  const closedIndexes = new Set();
+  const openedIndexes = new Set();
+
+  for (let i = 0; i < chunks.length; i++) {
+    const chunk = chunks[i];
+    if (!chunk || typeof chunk !== 'object') continue;
+
+    if (chunk.type === 'block-end') {
+      const block = chunk.block;
+      if (block && block.type === 'tool-call') {
+        if (typeof chunk.index === 'number') {
+          closedIndexes.add(chunk.index);
+          openedIndexes.add(chunk.index);
+        } else {
+          missingIndexBlockEnds++;
+        }
+        hasCompleteToolCall = true;
+      }
+    } else if (chunk.type === 'tool-call-delta') {
+      if (typeof chunk.index === 'number') {
+        openedIndexes.add(chunk.index);
+      } else {
+        missingIndexDeltas++;
+      }
+    } else if (chunk.type === 'block-start') {
+      if (chunk.blockType === 'tool-call' && typeof chunk.index === 'number') {
+        openedIndexes.add(chunk.index);
+      }
+    }
+
+    if (chunk.type === 'finish') {
+      finishIdx = i;
+      if (finishKind(chunk) === 'max-tokens') {
+        truncated = true;
+      }
+    }
+  }
+
+  if (!hasIncompleteToolCall) {
+    for (const idx of openedIndexes) {
+      if (!closedIndexes.has(idx)) {
+        hasIncompleteToolCall = true;
+        break;
+      }
+    }
+  }
+
+  if (!hasIncompleteToolCall && missingIndexDeltas > 0 && missingIndexBlockEnds === 0) {
+    hasIncompleteToolCall = true;
+  }
+
+  return {
+    truncated,
+    hasCompleteToolCall,
+    hasIncompleteToolCall,
+    hasToolCall: hasCompleteToolCall || hasIncompleteToolCall,
+    finishIdx,
+  };
+}
+
+/**
+ * Sum two TokenUsage objects, tolerating missing fields.
+ * llama.cpp reports per-call usage (each call's prompt_tokens covers
+ * only that call's input), so a merged chain's total is the sum of
+ * both calls' completion_tokens.  prompt_tokens takes the continuation's
+ * value (it includes the full message context: original messages +
+ * the continuation prompt), which is a more representative single
+ * number for display.
+ */
+export function sumUsage(a, b) {
+  if (!a) return b || null;
+  if (!b) return a;
+  return {
+    prompt_tokens: (b.prompt_tokens || a.prompt_tokens) || 0,
+    completion_tokens: (a.completion_tokens || 0) + (b.completion_tokens || 0),
+    total_tokens: (a.completion_tokens || 0) + (b.completion_tokens || 0) + (b.prompt_tokens || a.prompt_tokens || 0),
+  };
+}
+
+/**
+ * Build the merged chunk array:
+ *   upstream body (minus finish) + continuation body (minus finish) + terminal finish
+ *
+ * Block indices in the continuation body are offset by the upstream's
+ * max block index + 1 to prevent index collisions when both streams
+ * contain multiple blocks (BlockAssembler keys partials by index; a
+ * collision would cause deltas to be dropped or mis-routed).
+ */
+export function mergeChunks(upstream, contChunks, upstreamInfo, contInfo) {
+  const origBody = upstreamInfo.finishIdx >= 0
+    ? upstream.slice(0, upstreamInfo.finishIdx)
+    : upstream.slice();
+  const origFinish = upstreamInfo.finishIdx >= 0 ? upstream[upstreamInfo.finishIdx] : null;
+
+  const contBody = contInfo.finishIdx >= 0
+    ? contChunks.slice(0, contInfo.finishIdx)
+    : contChunks.slice();
+  const contFinish = contInfo.finishIdx >= 0 ? contChunks[contInfo.finishIdx] : null;
+
+  const terminalFinish = contFinish || origFinish;
+
+  let maxUpstreamBlockIdx = -1;
+  for (const chunk of origBody) {
+    if (chunk && typeof chunk === 'object' && typeof chunk.index === 'number') {
+      if (chunk.index > maxUpstreamBlockIdx) maxUpstreamBlockIdx = chunk.index;
+    }
+  }
+  const blockOffset = maxUpstreamBlockIdx + 1;
+
+  const offsetContBody = contBody.map(chunk => {
+    if (!chunk || typeof chunk !== 'object' || typeof chunk.index !== 'number') return chunk;
+    const t = chunk.type;
+    if (t === 'block-start' || t === 'block-end' ||
+        t === 'text-delta' || t === 'reasoning-delta' || t === 'tool-call-delta') {
+      return { ...chunk, index: chunk.index + blockOffset };
+    }
+    return chunk;
+  });
+
+  const merged = [...origBody, ...offsetContBody];
+
+  const usageChunks = merged.filter(c => c && c.type === 'usage');
+  const nonUsage = merged.filter(c => !c || c.type !== 'usage');
+  let mergedUsage = null;
+  for (const uc of usageChunks) {
+    mergedUsage = sumUsage(mergedUsage, uc && uc.usage);
+  }
+  if (mergedUsage) {
+    nonUsage.push({ type: 'usage', usage: mergedUsage });
+  }
+
+  if (terminalFinish) {
+    const safeFinish = (terminalFinish.replayState !== undefined && terminalFinish.replayState !== null)
+      ? { ...terminalFinish, replayState: undefined }
+      : terminalFinish;
+    nonUsage.push(safeFinish);
+  }
+  return nonUsage;
+}
+
+// ---------------------------------------------------------------------------
+// Loop-mode state store (named exports for tests).
+//
+// Tracks, per agent, whether the PREVIOUS step ended at max-tokens.  The
+// realtime mode detects truncation at the RESULT level (the assistant
+// message's finish reason, observed via the `agent/assistant-stream`
+// frames), not by buffering the stream.  When the next `agent/pre-step`
+// fires and the previous step was truncated, this store decides whether to
+// inject a continuation prompt as a new step.
+// ---------------------------------------------------------------------------
+
+export const loopState = new Map();
+
+export function loopKey(agent) {
+  if (agent && typeof agent === 'object' && agent.id !== undefined) return String(agent.id);
+  return '__default__';
+}
+
+/**
+ * Record the finish kind for an agent after a step's stream settles.
+ * Called from the `agent/assistant-stream` listener when the stream ends
+ * (the finish frame is the last frame emitted).  The value is the normalized
+ * finish kind string ('max-tokens', 'stop', 'tool-calls', 'error',
+ * 'aborted', or '' if unknown).
+ */
+export function recordLoopFinish(agent, finishKindStr) {
+  const key = loopKey(agent);
+  const state = loopState.get(key) || { pending: false, truncated: false, count: 0 };
+  state.pending = false;
+  state.truncated = (finishKindStr === 'max-tokens');
+  // If the step completed cleanly (not max-tokens), the response chain is
+  // done; reset the budget so the next independent response can continue.
+  if (!state.truncated) {
+    state.count = 0;
+  }
+  loopState.set(key, state);
+  return state;
+}
+
+/**
+ * Mark that an agent's stream has started (the first frame is in flight).
+ * `pending` is true until the finish frame is observed, so a concurrent
+ * pre-step (which can only happen after the stream settles) will not
+ * misread a stale truncation flag from a previous step.
+ */
+export function markLoopPending(agent) {
+  const key = loopKey(agent);
+  const state = loopState.get(key) || { pending: false, truncated: false, count: 0 };
+  state.pending = true;
+  loopState.set(key, state);
+  return state;
+}
+
+/**
+ * Decide whether to inject a continuation at the next `agent/pre-step`.
+ *
+ * Returns `{ continue: boolean, reason: string, promptText?: string }`.
+ *
+ * The decision is pure (no I/O) so it can be unit-tested:
+ *  - if the agent has no recorded truncation -> no continuation.
+ *  - if the budget is exhausted -> no continuation (reason 'budget').
+ *  - if the last user message is already a continuation marker -> no
+ *    continuation (re-entrancy guard, reason 'already-continuing').
+ *  - otherwise -> continue, with the appropriate prompt text.
+ *
+ * `hasCompleteToolCall` selects the tool-call-aware prompt (DSH discards
+ * tool-call blocks on max-tokens finish, so the continuation must not
+ * re-issue them).
+ */
+export function continuationDecision(state, { maxContinuations = 5, lastMsg = null, hasCompleteToolCall = false } = {}) {
+  if (!state || !state.truncated) {
+    return { continue: false, reason: 'not-truncated' };
+  }
+  // Re-entrancy guard: if the last user message is already our continuation
+  // prompt, we are already in a continuation chain — do not double-inject.
+  if (lastMsg && lastMsg.role === 'user' && lastMsg[CONTINUATION_MARK]) {
+    return { continue: false, reason: 'already-continuing' };
+  }
+  if (state.count >= maxContinuations) {
+    return { continue: false, reason: 'budget', count: state.count, max: maxContinuations };
+  }
+  const promptText = hasCompleteToolCall ? CONTINUE_PROMPT_TEXT_WITH_TOOLCALLS : CONTINUE_PROMPT_TEXT;
+  return { continue: true, reason: 'truncated', promptText, count: state.count + 1, max: maxContinuations };
+}
+
+/**
+ * Consume a continuation decision: if we are about to inject a
+ * continuation, increment the counter.  Returns the new count.
+ */
+export function consumeContinuation(agent) {
+  const key = loopKey(agent);
+  const state = loopState.get(key) || { pending: false, truncated: false, count: 0 };
+  state.count += 1;
+  loopState.set(key, state);
+  return state.count;
+}
+
+/**
+ * Clear an agent's loop state (e.g. on agent disposal, or to force a clean
+ * slate).  Returns true if an entry was removed.
+ */
+export function clearLoopState(agent) {
+  return loopState.delete(loopKey(agent));
+}
+
+/**
+ * Prune stale loop-state entries in long-running processes.  Uses the same
+ * LRU convention as `pruneCounters`: the Map's insertion order is the LRU
+ * order, evicting from the front.  At most once per `minIntervalMs`, only
+ * when the map exceeds `maxEntries`.
+ */
+let lastLoopPrune = 0;
+export function pruneLoopState(now = Date.now(), { maxEntries = 256, keep = 128, minIntervalMs = 60_000 } = {}) {
+  if (loopState.size <= maxEntries || now - lastLoopPrune < minIntervalMs) return 0;
+  lastLoopPrune = now;
+  const keys = [...loopState.keys()];
+  let evicted = 0;
+  for (let i = 0; i < keys.length - keep; i++) {
+    loopState.delete(keys[i]);
+    evicted++;
+  }
+  return evicted;
+}
+
+// ---------------------------------------------------------------------------
+// Configuration resolution.
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the active configuration from the patch `config` block (preferred)
+ * and environment variables (fallback).  Returns a plain object with
+ * `providers` (string[]), `maxContinuations` (number), `timeoutMs` (number)
+ * and `mode` ('loop' | 'stream').
+ *
+ * Precedence per field: patch config > env var > default.
+ */
+export function resolveConfig(patchConfig) {
+  const cfg = patchConfig && typeof patchConfig === 'object' ? patchConfig : {};
+
+  let providers = DEFAULT_PROVIDERS.slice();
+  if (Array.isArray(cfg.providers) && cfg.providers.length > 0) {
+    providers = cfg.providers.map(String);
+  } else if (typeof cfg.providers === 'string' && cfg.providers.trim()) {
+    providers = cfg.providers.split(',').map(s => s.trim()).filter(Boolean);
+  } else if (process.env.DSH_AUTOCONTINUE_PROVIDERS) {
+    providers = process.env.DSH_AUTOCONTINUE_PROVIDERS.split(',').map(s => s.trim()).filter(Boolean);
+  }
+
+  let maxContinuations = DEFAULT_MAX_CONTINUATIONS;
+  if (Number.isFinite(Number(cfg.maxContinuations)) && Number(cfg.maxContinuations) >= 1) {
+    maxContinuations = Number(cfg.maxContinuations);
+  } else if (process.env.DSH_AUTOCONTINUE_MAX && Number(process.env.DSH_AUTOCONTINUE_MAX) >= 1) {
+    maxContinuations = Number(process.env.DSH_AUTOCONTINUE_MAX);
+  }
+
+  let timeoutMs = DEFAULT_CONTINUATION_TIMEOUT_MS;
+  if (Number.isFinite(Number(cfg.timeoutMs)) && Number(cfg.timeoutMs) > 0) {
+    timeoutMs = Number(cfg.timeoutMs);
+  } else if (process.env.DSH_AUTOCONTINUE_TIMEOUT_MS && Number(process.env.DSH_AUTOCONTINUE_TIMEOUT_MS) > 0) {
+    timeoutMs = Number(process.env.DSH_AUTOCONTINUE_TIMEOUT_MS);
+  }
+
+  let mode = DEFAULT_MODE;
+  if (typeof cfg.mode === 'string' && VALID_MODES.has(cfg.mode)) {
+    mode = cfg.mode;
+  } else if (process.env.DSH_AUTOCONTINUE_MODE && VALID_MODES.has(process.env.DSH_AUTOCONTINUE_MODE)) {
+    mode = process.env.DSH_AUTOCONTINUE_MODE;
+  }
+
+  return { providers, maxContinuations, timeoutMs, mode };
+}
+
+// ---------------------------------------------------------------------------
+// Plugin entry point.
+// ---------------------------------------------------------------------------
+
+export default {
+  name: 'auto-continue-community',
+
+  // Cordis config schema (standard-schema via zod).  Cordis reads this off
+  // the plugin object (cordis lib/index.js plugin.Config) and, before
+  // apply() runs, validates the patch `config` block against it:
+  //   - a missing block (cordis passes `undefined`) resolves to the
+  //     object-level .default() below;
+  //   - a malformed block THROWS cordis's ValidationError at load time,
+  //     so a typo in a provider, a 0 budget, or an invalid mode fails
+  //     loudly instead of the plugin silently doing nothing.
+  // The validated, default-filled object is then passed as apply()'s
+  // second argument.
+  Config: z.object({
+    // Provider ids to intercept.  Cloud API providers manage their own
+    // output limits and must not be forced into continuation.
+    providers: z.array(z.string()).min(1).default(DEFAULT_PROVIDERS),
+    // Max continuation retries per single response chain.
+    maxContinuations: z.number().int().min(1).max(20).default(DEFAULT_MAX_CONTINUATIONS),
+    // Per-continuation stream timeout, in milliseconds (stream mode only;
+    // the loop mode's continuation is a normal agent step with the agent's
+    // own timeout).
+    timeoutMs: z.number().int().min(1).max(3_600_000).default(DEFAULT_CONTINUATION_TIMEOUT_MS),
+    // Operating mode: "loop" (realtime, default) or "stream" (buffered
+    // fallback).  See the module header for the tradeoffs.
+    mode: z.enum(['loop', 'stream']).default(DEFAULT_MODE),
+  }).default({
+    // Object-level default: when the patch has no `config:` block, cordis
+    // passes `undefined` to the schema.  Without this, z.object() rejects
+    // undefined input (field-level .default() only fills in when the input
+    // is an object with missing fields).  With this, undefined resolves to
+    // the full defaults and the plugin activates normally.
+    providers: DEFAULT_PROVIDERS,
+    maxContinuations: DEFAULT_MAX_CONTINUATIONS,
+    timeoutMs: DEFAULT_CONTINUATION_TIMEOUT_MS,
+    mode: DEFAULT_MODE,
+  }),
+
+  async apply(ctx, config, _meta) {
+    const logger = ctx.logger;
+    // `config` is the SECOND apply() argument: cordis resolves the plugin's
+    // `Config` schema against the patch `config` block and passes the
+    // validated, default-filled value here (cordis lib/index.js:
+    // ctx.registry.plugin(plugin, this.options.config, ...) ->
+    // runtime.callback(this.ctx, this.config)).  `ctx.options` does not
+    // exist, so reading it here would silently drop the patch config.
+    //
+    // The schema fills defaults, but resolveConfig is kept as a last-resort
+    // fallback (env vars / hard defaults) so the plugin still degrades
+    // gracefully if cordis ever passes an empty or absent config.
+    const cfg = resolveConfig(config);
+
+    // File-based debug logging is OFF by default (the plugin is stable; the
+    // log grows every LLM call and is only needed when debugging).
+    // Enable by setting DSH_AUTOCONTINUE_DEBUG=1 in the environment before
+    // launching `dsh web`.  The path is portable: OS temp dir + plugin name.
+    const DEBUG_ON = !!process.env.DSH_AUTOCONTINUE_DEBUG;
+    let appendFileSync = null;
+    let DEBUG_LOG = null;
+    if (DEBUG_ON) {
+      try {
+        const fs = await import('node:fs');
+        const os = await import('node:os');
+        const path = await import('node:path');
+        ({ appendFileSync } = fs);
+        DEBUG_LOG = path.join(os.tmpdir(), 'dsh-auto-continue-community-debug.log');
+        appendFileSync(DEBUG_LOG, '[' + new Date().toISOString() + '] ' +
+          'process started (pid ' + process.pid + '); plugin code with file logging is active\n');
+      } catch (_) { /* non-fatal */ }
+    }
+
+    function logSafe(msg) {
+      if (DEBUG_ON && appendFileSync && DEBUG_LOG) {
+        try {
+          const ts = new Date().toISOString();
+          appendFileSync(DEBUG_LOG, `[${ts}] ${msg}\n`);
+        } catch (_) { /* file write failure is non-fatal */ }
+      }
+      if (logger) {
+        logger.info('[auto-continue-community] ' + msg);
+      }
+    }
+
+    logSafe('apply() completed; mode=' + cfg.mode +
+      ' (providers: ' + cfg.providers.join(', ') + ', maxContinuations: ' + cfg.maxContinuations +
+      ', timeoutMs: ' + cfg.timeoutMs + ')');
+
+    const providerSet = new Set(cfg.providers);
+
+    // Dispatch to the active mode.  Each mode registers only its own
+    // waterfall listeners; the two are mutually exclusive at load time.
+    // The loop mode is the default and the "top-tier" realtime path; the
+    // stream mode is the known-good buffering fallback.
+    if (cfg.mode === 'stream') {
+      registerStreamMode(ctx, cfg, logSafe, providerSet);
+    } else {
+      registerLoopMode(ctx, cfg, logSafe, providerSet, _meta);
+    }
+  },
+};
+
+// ---------------------------------------------------------------------------
+// LOOP MODE (realtime, default).
+//
+// Does NOT buffer the model stream.  The agent loop streams tokens to the
+// UI in real time and detects max-tokens at the result level.  This mode:
+//   1. Observes the `agent/assistant-stream` emit frames to learn, per
+//      agent, whether the step's stream ended with a `finish` chunk whose
+//      `reason.kind === "max-tokens"`.  In the DSH 0.2.1-rc.5 line the
+//      finish reason lives on the StreamChunk inside the frame
+//      (frame.type === 'chunk' && frame.chunk.type === 'finish'), NOT on
+//      the frame envelope itself.
+//   2. When a max-tokens finish chunk is observed, it calls
+//      `agent.steer(continuationMsg)`: the agent driver queues the
+//      continuation prompt as the NEXT step of the CURRENT turn and wakes
+//      the driver.  The agent loop's turn loop keeps the turn open while
+//      `inbox.nextStep` is non-empty (turn() only closes the turn when
+//      the inbox is drained), so the continuation step runs immediately
+//      after the truncated step — still streaming in real time.
+//
+// Why NOT `agent/pre-step`: after a max-tokens step-end the turn loop only
+// re-enters `preStep` if `inbox.nextStep` already has work; with an empty
+// inbox the turn closes and no further `agent/pre-step` fires for that
+// turn.  A pre-step listener that only appends a message therefore never
+// runs on the truncation path.  `steer()` from the stream observer is the
+// channel that actually keeps the turn alive.
+//
+// The continuation is a clean, independent agent step — not a splice into
+// the previous stream — so the UI shows two distinct assistant messages
+// (the truncated one, then the continuation), each streamed live.  The
+// agent loop treats the continuation as a normal user-prompted step, which
+// is exactly what a human typing "继续" would produce, but automated.
+// ---------------------------------------------------------------------------
+
+function registerLoopMode(ctx, cfg, logSafe, providerSet, meta) {
+  // Track which agents are in a continuation chain so we do not re-trigger
+  // on the continuation's own max-tokens (the re-entrancy guard uses the
+  // message marker; this set is a secondary safety net).
+  const activeChains = new Set();
+
+  // Provider gate: only continue for agents whose provider is configured.
+  //
+  // The `agent` object (dsh-agent-loop's ReactLoopAgent) does NOT expose a
+  // top-level `provider` or `route` field on the 0.2.1-rc.5 line — its
+  // constructor sets id / options / session / inbox / phase / scope / ctx /
+  // dispatch only.  Reading `agent.provider` here would therefore ALWAYS
+  // return false and silently disable the whole loop mode.  The authoritative
+  // provider id is the plugin's route: the agent runs through the LLM route
+  // that this plugin was attached to (the `llm-pi-ai` route, e.g.
+  // "local-vision").  We read it from the plugin `meta` (cordis
+  // plugin-context metadata, present when the plugin is attached to a route)
+  // and fall back to the agent's own fields (future-proofing) and finally to
+  // a fail-open default when no provider can be determined.
+  function pluginProvider() {
+    const p = meta && (meta.provider || (meta.route && meta.route.provider) || meta.id);
+    return (typeof p === 'string' && p) ? p : null;
+  }
+  function providerOk(agent) {
+    // 1) The plugin's own route provider (authoritative in this deployment).
+    const pp = pluginProvider();
+    if (pp && providerSet.has(pp)) return true;
+    // 2) A provider id exposed directly on the agent (future-proofing).
+    const ap = agent && (agent.provider || (agent.route && agent.route.provider));
+    if (typeof ap === 'string' && ap && providerSet.has(ap)) return true;
+    // 3) Fail open only when we could determine no provider at all: the
+    //    plugin is already attached to exactly one route, so an undetermined
+    //    provider almost certainly IS the configured one.  When we DID
+    //    determine a provider but it is not configured (e.g. a cloud
+    //    provider), we gate it out.
+    if (!pp && !(typeof ap === 'string' && ap)) return true;
+    return false;
+  }
+  // One-shot diagnostic: log which provider-gate branch resolves the first
+  // time we see an agent.  Confirms whether cordis passes a `meta` with a
+  // route/provider id (branch 1) or whether we are relying on the fail-open
+  // default (branch 3).  Fires at most once per process.
+  let loggedGate = false;
+  function logGateOnce(agent) {
+    if (loggedGate) return;
+    loggedGate = true;
+    const pp = pluginProvider();
+    const ap = agent && (agent.provider || (agent.route && agent.route.provider));
+    const branch = (pp && providerSet.has(pp)) ? 'plugin-meta'
+      : (typeof ap === 'string' && ap && providerSet.has(ap)) ? 'agent-field'
+      : (!pp && !(typeof ap === 'string' && ap)) ? 'fail-open'
+      : 'gated-out';
+    logSafe('loop: providerOk branch=' + branch +
+      ' (meta.provider=' + JSON.stringify(pp) + ', agent.provider=' + JSON.stringify(ap) +
+      ', providerSet=[' + [...providerSet].join(',') + '])');
+  }
+
+  // Observe assistant stream frames to detect the finish reason per agent.
+  //
+  // The `agent/assistant-stream` emit event payload is { agent, frame }
+  // (cordis runtime-types, mode "emit").  `frame` is an AssistantStreamFrame:
+  //   { type: 'start', attemptId, revision, turn, step }
+  //   { type: 'chunk', attemptId, revision, index, time, chunk: StreamChunk }
+  //   { type: 'end',   attemptId, revision, index, outcome: {...} }
+  // The finish reason lives on the StreamChunk INSIDE a 'chunk' frame
+  // (frame.chunk = { type: 'finish', reason: { kind, ... } }); the frame
+  // envelope itself carries NO finish reason.  We mark pending on the
+  // 'start' frame and read `reason.kind` from the finish chunk.
+  const disposeStream = ctx.on('agent/assistant-stream', ({ agent, frame }) => {
+    if (!providerOk(agent)) return;
+    logGateOnce(agent);
+    if (!frame || typeof frame !== 'object') return;
+
+    // First frame of this step: mark pending so a concurrent observer does
+    // not misread a stale truncation flag from a previous step.
+    if (frame.type === 'start' || frame.kind === 'start') {
+      markLoopPending(agent);
+      return;
+    }
+
+    // The finish reason is carried by a StreamChunk of type 'finish' inside
+    // a 'chunk' frame.  Normalize the kind.
+    const chunk = (frame.type === 'chunk' || frame.kind === 'chunk') ? frame.chunk : null;
+    if (!chunk || chunk.type !== 'finish') return;
+    const finishReason = chunk.reason;
+    const kind = (typeof finishReason === 'string')
+      ? finishReason.replace(/[_-]/g, '-')
+      : ((finishReason && (finishReason.kind || finishReason.reason) || '').replace(/[_-]/g, '-'));
+    recordLoopFinish(agent, kind);
+    // Observability: log clean (non-truncated) finishes too, so "why did the
+    // chain stop?" is answerable from the debug log alone — without having to
+    // mine the durable session event log for finish chunks.  A `stop` finish
+    // here means the model emitted EOS on its own (possibly mid-response, a
+    // model-side false stop); by design the plugin only continues on
+    // `max-tokens`, so the absence of a continuation line for this step is
+    // expected — this line just makes that explicit.
+    if (kind && kind !== 'max-tokens') {
+      logSafe('loop: agent ' + (agent && agent.id) +
+        ' step ended ' + kind + ' (not max-tokens; chain ends, no continuation)');
+    }
+    if (kind === 'max-tokens') {
+      logSafe('loop: agent ' + (agent && agent.id) + ' step ended max-tokens (continuation candidate)');
+      // Decide whether to continue and, if so, queue the continuation as the
+      // next step of the CURRENT turn via agent.steer().  steer() appends to
+      // the agent's inbox.nextStep and wakes the driver; the agent loop's
+      // turn() keeps the turn open while inbox.nextStep is non-empty, so the
+      // continuation runs immediately after this truncated step.
+      const state = loopState.get(loopKey(agent));
+      const lastMsg = (agent && Array.isArray(agent.inbox && agent.inbox.messages))
+        ? agent.inbox.messages[agent.inbox.messages.length - 1] : null;
+      const decision = continuationDecision(state, {
+        maxContinuations: cfg.maxContinuations,
+        lastMsg,
+      });
+      if (decision.continue) {
+        const continuationMsg = {
+          id: randomUUID(),
+          role: 'user',
+          content: [{ type: 'text', text: decision.promptText }],
+          source: { kind: 'user' },
+        };
+        Object.defineProperty(continuationMsg, CONTINUATION_MARK, {
+          value: true,
+          enumerable: true,
+        });
+        try {
+          if (agent && typeof agent.steer === 'function') {
+            agent.steer(continuationMsg);
+            consumeContinuation(agent);
+            if (agent && agent.id !== undefined) activeChains.add(agent.id);
+            logSafe('loop: agent ' + (agent && agent.id) + ' injecting continuation ' +
+              decision.count + '/' + decision.max + ' via steer()');
+          } else {
+            logSafe('loop: agent ' + (agent && agent.id) + ' agent.steer unavailable; cannot continue');
+          }
+        } catch (err) {
+          logSafe('loop: agent ' + (agent && agent.id) + ' steer() failed: ' + (err && err.message));
+        }
+      } else {
+        logSafe('loop: agent ' + (agent && agent.id) + ' max-tokens, no continuation (' + decision.reason + ')');
+        clearLoopState(agent);
+        if (agent && agent.id !== undefined) activeChains.delete(agent.id);
+      }
+    }
+    pruneLoopState();
+  });
+
+  // Clean up loop state when an agent is disposed, so we do not leak state
+  // for agents that no longer exist.
+  ctx.on('agent/dispose', ({ agent }) => {
+    clearLoopState(agent);
+    if (agent && agent.id !== undefined) activeChains.delete(agent.id);
+  });
+
+  // No return value needed: DSH auto-disposes plugin listeners on plugin
+  // unload (cordis lifecycle).  The disposeStream function is called by the
+  // framework, not by us.  `activeChains` is cleared per-agent on dispose.
+}
+
+// ---------------------------------------------------------------------------
+// STREAM MODE (buffered, fallback / legacy).
+//
+// The original edition's behavior: intercept the `llm/stream` waterfall,
+// buffer the whole upstream stream, detect max-tokens from the final finish
+// chunk, re-invoke the model with a continuation prompt, and merge the two
+// streams into one.  Tokens do NOT appear in the UI in real time because
+// the finish reason only arrives at stream-end.  This mode is retained as a
+// guaranteed fallback when the loop mode misbehaves in a given deployment.
+// ---------------------------------------------------------------------------
+
+function registerStreamMode(ctx, cfg, logSafe, providerSet) {
+  ctx.on('llm/stream', (options, next) => {
+    const provider = options && options.provider;
+    if (!provider || !providerSet.has(provider)) {
+      return next(); // pass-through: let the next listener / built-in handler run
+    }
+
+    const key = counterKey(options);
+    const runtime = ctx.runtime;
+
+    if (!runtime || typeof runtime.stream !== 'function') {
+      logSafe('stream: runtime or runtime.stream unavailable; passing through');
+      return next();
+    }
+
+    return (async function* streamHandler() {
+      // Buffer the entire upstream stream so we can inspect the finish
+      // reason.  This is what makes the display non-realtime.
+      let upstream;
+      try {
+        upstream = await next();
+      } catch (err) {
+        logSafe('stream: next() failed: ' + (err && err.message) + '; rethrowing');
+        throw err;
+      }
+      const chunks = await collectChunks(upstream);
+      const info = analyzeChunks(chunks);
+
+      logSafe('stream: provider=' + provider + ' sessionId=' + (options.sessionId || '?') +
+        ' chunks=' + chunks.length + ' truncated=' + info.truncated +
+        ' hasCompleteToolCall=' + info.hasCompleteToolCall +
+        ' hasIncompleteToolCall=' + info.hasIncompleteToolCall);
+
+      // No truncation: forward as-is (reset the counter).
+      if (!info.truncated) {
+        for (const chunk of chunks) yield chunk;
+        resetCounter(key);
+        pruneCounters();
+        return;
+      }
+
+      // Incomplete tool call: cannot continue (malformed JSON).
+      if (info.hasIncompleteToolCall) {
+        logSafe('stream: incomplete tool call present; NOT continuing, forwarding truncated stream');
+        for (const chunk of chunks) yield chunk;
+        // Keep the counter so the chain is considered active, but do not
+        // increment (we are not actually continuing).
+        pruneCounters();
+        return;
+      }
+
+      // Budget exhausted.
+      const count = getCounter(key);
+      if (count >= cfg.maxContinuations) {
+        logSafe('stream: budget exhausted (' + count + '/' + cfg.maxContinuations + '); forwarding truncated stream');
+        for (const chunk of chunks) yield chunk;
+        pruneCounters();
+        return;
+      }
+
+      // Build the continuation prompt.
+      const contText = info.hasCompleteToolCall ? CONTINUE_PROMPT_TEXT_WITH_TOOLCALLS : CONTINUE_PROMPT_TEXT;
+      const continuationMessage = {
+        id: randomUUID(),
+        role: 'user',
+        content: [{ type: 'text', text: contText }],
+      };
+      Object.defineProperty(continuationMessage, CONTINUATION_MARK, {
+        value: true,
+        enumerable: true,
+      });
+
+      // Re-invoke the model with the continuation prompt.
+      const continuationOptions = {
+        ...options,
+        messages: [...(options.messages || []), continuationMessage],
+        maxContinuations: cfg.maxContinuations,
+      };
+
+      let contChunks;
+      try {
+        const contStream = await runtime.stream(continuationOptions);
+        contChunks = await collectChunks(contStream);
+      } catch (err) {
+        logSafe('stream: continuation FAILED: ' + (err && err.message) + '; degrading to truncated stream');
+        for (const chunk of chunks) yield chunk;
+        // Keep counter (chain active) so the next call knows.
+        pruneCounters();
+        return;
+      }
+
+      const contInfo = analyzeChunks(contChunks);
+
+      if (contInfo.hasIncompleteToolCall) {
+        logSafe('stream: continuation had incomplete tool call; forwarding combined (upstream + continuation body)');
+      }
+      if (contInfo.truncated) {
+        logSafe('stream: continuation also truncated at max-tokens; yielding combined stream');
+      }
+
+      const merged = mergeChunks(chunks, contChunks, info, contInfo);
+
+      logSafe('stream: merged ' + (info.finishIdx >= 0 ? info.finishIdx : chunks.length) +
+        ' upstream + ' + (contInfo.finishIdx >= 0 ? contInfo.finishIdx : contChunks.length) +
+        ' continuation chunks');
+
+      for (const chunk of merged) yield chunk;
+
+      // Reset the counter if the chain ended cleanly.
+      if (!contInfo.truncated) {
+        resetCounter(key);
+      }
+      pruneCounters();
+    })();
+  });
+}