@hncode/hncode 0.4.2 → 0.5.1

package/src/side-thread.js

@@ -0,0 +1,240 @@
+// Side conversations (/btw) and recaps.
+//
+// A side conversation is a FORK of the main thread: it carries the SAME conversation
+// history, so a question like "what does this error mean" has the context to be
+// answered rather than bounced back as "which file?". What it must not do is affect
+// the main thread — the main agent keeps running, and nothing said in the side thread
+// is written back to the session or to disk.
+//
+// That is how the two references do it, and the split is deliberate:
+//   * kimi's `startBtw` calls `agentLifecycle.fork(main)`, and `fork` copies the
+//     whole message list into the child agent; its system reminder tells the side
+//     model to "prefer answering from what you already know from the conversation".
+//   * codex forks the thread with `ephemeral = true`, and its snapshot comment says
+//     it outright: "The forked history remains available to the model through core
+//     state, but side conversations should visually start at the side boundary."
+//
+// So history is a FEATURE of the side thread, not baggage. What the user sees is a
+// clean question and answer; what the model has is the full context. Those two are
+// separable, and this module keeps them separate:
+//
+//   forkMessages(session)   -> the history handed to the side model
+//   thread.transcript()     -> only what happened since the fork, for the panel
+//
+// Tools are cut to the read-only three (Read / Grep / Glob): a side question may
+// inspect a file to answer, and must not edit one. The model still sees the other
+// tool DEFINITIONS in the request — that is what keeps the prompt cache shared with
+// the main thread — so a call to anything else is refused rather than hidden. See
+// SIDE_TOOL_REFUSAL: kimi does exactly this, and for the same reason.
+//
+// A RECAP is the opposite kind of read: it is a summary OF the main conversation, so
+// it takes a digest rather than the history. The two live together because they share
+// the "read-only, secondary model, must not disturb the session" shape.
+
+/** The only tools a side question may actually use. */
+export const SIDE_RO_TOOLS = ['Read', 'Grep', 'Glob', 'FileLines'];
+
+
+
+/**
+ * The system prompt for a side thread: the session's prompt plus the side-thread
+ * framing.
+ *
+ * The framing has to do three jobs, and each line below exists because dropping it
+ * causes a specific failure:
+ *   * say it is a side channel, so the model does not treat the user's question as a
+ *     new task and start a multi-step effort;
+ *   * say the main agent is still RUNNING, so it does not say "let me stop what I was
+ *     doing" or otherwise narrate an interruption that did not happen;
+ *   * say which tools actually work, so the model does not waste a step on one that is
+ *     absent from the request.
+ */
+export function sideSystemPrompt(basePrompt, opts = {}) {
+  const tools = Array.isArray(opts.tools) && opts.tools.length ? opts.tools : SIDE_RO_TOOLS;
+  const lines = [String(basePrompt || '')];
+  lines.push(
+    '',
+    '## This is a side question',
+    'The user asked you something off to the side of the main conversation. Answer it',
+    'directly and briefly.',
+    '',
+    'You are a separate, lightweight instance. You have the conversation so far, so',
+    'answer from what you already know; the main agent continues independently, so do',
+    'not refer to being interrupted or to pausing anything.',
+    '',
+    `Only these tools work here: ${tools.join(', ')}. Use them when the answer depends`,
+    'on the current contents of a file. Do not attempt to edit, write or run anything —',
+    'those tools are not available in a side question.',
+    '',
+    'Your reply is shown to the user but is NOT added to their conversation, so do not',
+    'assume the main model will ever see it. If the answer calls for a code change, say',
+    'what should be done and let the user decide to bring it up in the main thread.',
+  );
+  return lines.join('\n');
+}
+
+/** The refusal a side thread gets for a tool outside its set (kimi's wording, ours). */
+export const SIDE_TOOL_REFUSAL =
+  'Only reading tools are available in a side question (Read, Grep, Glob, FileLines). '
+  + 'Ask in the main thread if this needs to change something.';
+
+/**
+ * The history a side thread forks from a session.
+ *
+ * A COPY, and only the roles a model can be given: `system` is rebuilt by the caller
+ * from the current prompt, and a `tool` row without its matching call would be an
+ * orphan the protocol rejects. Tool CALLS are kept — dropping them would break the
+ * pairing with their results and lose the record of what was already done, which is
+ * exactly the context a side question needs.
+ */
+export function forkMessages(session, opts = {}) {
+  const limit = Number.isFinite(opts.limit) ? opts.limit : 0;   // 0 = no limit
+  const list = Array.isArray(session && session.messages) ? session.messages : [];
+  const out = [];
+  for (const m of list) {
+    if (!m || typeof m !== 'object') continue;
+    if (m.role === 'system') continue;
+    if (m.role !== 'user' && m.role !== 'assistant' && m.role !== 'tool') continue;
+    const text = typeof m.content === 'string' ? m.content : '';
+    const calls = Array.isArray(m.toolCalls) ? m.toolCalls : [];
+    if (!text.trim() && !calls.length) continue;
+    out.push({ ...m });
+  }
+  // `limit` keeps the most RECENT entries when set: a very long session does not need
+  // its opening messages to answer a question about the work in progress.
+  return limit > 0 && out.length > limit ? out.slice(-limit) : out;
+}
+
+/**
+ * One side thread: a fork of the main conversation.
+ *
+ * Two message lists, and the split is the whole design:
+ *   `history`  — the main conversation, handed to the model as context
+ *   `messages` — ONLY what was said in the side thread
+ *
+ * `payload()` sends history + messages, so the side model answers with full context.
+ * `transcript()` returns ONLY `messages`, so the panel shows a clean question and
+ * answer rather than the entire session again. That is codex's "history remains
+ * available to the model, but side conversations visually start at the side boundary".
+ */
+export class SideThread {
+  /**
+   * @param {object} opts
+   *   basePrompt  the system prompt the main session uses
+   *   history     the messages forked from the session (see forkMessages)
+   *   tools       the tool names that actually work here (defaults to the read-only set)
+   *   model       label of the model the side answers run on (for display)
+   */
+  constructor(opts = {}) {
+    this.basePrompt = String(opts.basePrompt || '');
+    this.model = String(opts.model || '');
+    this.tools = Array.isArray(opts.tools) && opts.tools.length ? [...opts.tools] : [...SIDE_RO_TOOLS];
+    // A COPY, never the session's array: appending here must not reach the session.
+    this.history = (Array.isArray(opts.history) ? opts.history : []).map((m) => ({ ...m }));
+    this.messages = [];
+    this.error = null;
+  }
+
+  /** How many entries were forked in — for the panel, so the context is visible. */
+  get forked() {
+    return this.history.length;
+  }
+
+  /** The request payload. Exposed so a test can assert exactly what would be sent. */
+  payload(text) {
+    return [
+      { role: 'system', content: sideSystemPrompt(this.basePrompt, { tools: this.tools }) },
+      ...this.history,
+      ...this.messages,
+      { role: 'user', content: String(text || '') },
+    ];
+  }
+
+  /** Record an exchange. Kept separate from the request so a failed ask is not kept. */
+  record(text, reply) {
+    this.messages.push({ role: 'user', content: String(text || '') });
+    this.messages.push({ role: 'assistant', content: String(reply == null ? '' : reply) });
+  }
+
+  /** How many exchanges have happened, for the header and the tests. */
+  get turns() {
+    return Math.floor(this.messages.length / 2);
+  }
+
+  /**
+   * ONLY the side thread's own exchanges — not the forked history.
+   *
+   * The reason is the one codex states: the history is context for the MODEL, and
+   * repeating it in the panel would bury the two lines the user actually asked for.
+   */
+  transcript() {
+    const rows = [];
+    for (const m of this.messages) {
+      rows.push({ role: m.role === 'user' ? 'user' : 'assistant', text: m.content });
+    }
+    return rows;
+  }
+}
+
+/** Is `name` a tool a side question may use? */
+export function sideToolAllowed(name) {
+  return SIDE_RO_TOOLS.includes(String(name || ''));
+}
+
+/**
+ * The recap prompt. A recap answers "where was I", so the instruction pins the
+ * three things that answer it and forbids the two that do not.
+ *
+ * Deliberately not a summary of the transcript: /compact already does that, and its
+ * output REPLACES the history. This one is read by a human coming back to the
+ * terminal and changes nothing.
+ */
+export const RECAP_PROMPT = `You are writing a short recap of a coding session the user is returning to.
+
+State, in at most six short lines:
+  1. What the user asked for (the goal, not the wording).
+  2. What has been done so far, naming the files that changed.
+  3. What is NOT done yet, or what is uncertain.
+
+Rules: no greeting, no praise, no restating the rules you were given, no
+speculation about what the user might want next. Plain sentences, no Markdown
+headings. If the work is finished, say so in one line.`;
+
+/**
+ * Build the messages for a recap request.
+ *
+ * The RECAP gets the forked history as real messages rather than a digest: the model
+ * is being asked what happened, and handing it the actual conversation beats handing
+ * it a lossy summary of one. `limit` bounds it so a very long session stays cheap.
+ */
+export function recapMessages(history, opts = {}) {
+  const list = Array.isArray(history) ? history : [];
+  const limit = Number.isFinite(opts.limit) ? opts.limit : 0;
+  const tail = limit > 0 && list.length > limit ? list.slice(-limit) : list;
+  if (!tail.length) {
+    return [
+      { role: 'system', content: RECAP_PROMPT },
+      { role: 'user', content: 'The conversation is empty. Say so in one line.' },
+    ];
+  }
+  return [
+    { role: 'system', content: RECAP_PROMPT },
+    ...tail,
+    // The instruction comes LAST, as the final user turn, so it is the most recent
+    // thing the model reads — a recap is an instruction about the history above it.
+    { role: 'user', content: 'Write the recap of the session above, per the rules.' },
+  ];
+}
+
+/** Counts for a panel header: how much conversation is being summarised. */
+export function digestStats(messages) {
+  const list = Array.isArray(messages) ? messages : [];
+  const users = list.filter((m) => m && m.role === 'user').length;
+  const assistants = list.filter((m) => m && m.role === 'assistant').length;
+  return { users, assistants, total: list.length };
+}
+
+export default {
+  sideSystemPrompt, SideThread, SIDE_RO_TOOLS, SIDE_TOOL_REFUSAL,
+  forkMessages, sideToolAllowed, recapMessages, digestStats, RECAP_PROMPT,
+};

package/src/skills.js

@@ -127,6 +127,33 @@ export function importSkill(file, name) {
   return { ok: true, name: skillName, path: dest, replaced };
 }
 
+// Register (write or overwrite) a skill from an in-memory Markdown string rather
+// than a file on disk. Used by plugins that want to ship a skill as code instead of
+// requiring the user to /import-skill a file. The string must contain a leading
+// `--- … ---` front-matter block with at least a `name` (or pass `name` explicitly);
+// otherwise the name falls back to `name`/`fileName`. Returns the same shape as
+// importSkill: { ok: true, name, path, replaced } or { ok: false, error }.
+export function addSkillFromText(text, name, fileName = 'skill.md') {
+  const content = String(text == null ? '' : text);
+  if (!content.trim()) return { ok: false, error: 'Skill content is empty.' };
+  const destDir = skillsDir();
+  // Derive the name the way importSkill does, so the two paths agree.
+  const { meta } = parseFrontMatter(content);
+  const derived = name || meta.name || String(fileName || 'skill').replace(/\.md$/i, '');
+  const skillName = normalizeSkillName(derived);
+  if (!skillName) return { ok: false, error: 'Could not derive a skill name (pass one explicitly).' };
+  if (/[\\/]/.test(skillName)) return { ok: false, error: `Invalid skill name: ${skillName}` };
+  const dest = path.join(destDir, `${skillName}.md`);
+  const replaced = fs.existsSync(dest);
+  try {
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.writeFileSync(dest, content, 'utf8');
+  } catch (e) {
+    return { ok: false, error: `Cannot write ${dest}: ${e.message}` };
+  }
+  return { ok: true, name: skillName, path: dest, replaced };
+}
+
 export function deleteSkill(name) {
   const n = normalizeSkillName(name);
   if (!n) return false;

package/src/stream-buffer.js

@@ -0,0 +1,350 @@
+// Semantic stream buffer — paces the reveal of streaming text so every provider
+// looks the same.
+//
+// WHY THIS EXISTS
+// ---------------
+// Providers feed text deltas with wildly different cadences. OpenAI emits many tiny
+// token-level deltas (a few characters every ~10-15ms), which already looks smooth.
+// Anthropic coalesces its `content_block_delta` events into larger chunks that arrive
+// in bursts with gaps (say 40 characters every ~100ms). Revealing each burst the
+// instant it arrives makes the UI stair-step: a clump of text pops in, nothing for
+// several frames, then another clump. The same interface therefore looks smooth on one
+// provider and choppy on another, for no reason the user can see.
+//
+// To make every provider look the same, this buffer decouples ARRIVAL from REVEAL.
+// Incoming content accumulates in an ordered backlog and a time-paced proportional
+// controller drips it out: the rate rises with the backlog so a fast model is never
+// left behind, yet a lone burst is spread over several frames instead of dumped in one.
+//
+// This is a port of jcode's `crates/jcode-tui-core/src/stream_buffer.rs`, kept to the
+// same constants and the same shape so the two behave identically. Zero dependencies,
+// like the rest of hncode.
+//
+// THE BACKLOG IS SEGMENT-AWARE
+// ----------------------------
+// Reasoning text and answer text are queued as ordered segments of ONE stream, plus
+// zero-width "close reasoning region" markers. Both kinds therefore share the same
+// smoothing controller and reveal strictly in arrival order. Pacing only the answer
+// text would let reasoning pop in provider-sized clumps, and the ordering flushes
+// needed to fix that would defeat the answer pacing too.
+
+/** Steady-state reveal rate (chars/sec) with an empty backlog. This sets the floor
+ *  cadence and how the trailing characters of a burst drain out. */
+export const BASE_REVEAL_CPS = 180;
+
+/** Additional reveal rate per buffered character. The controller speeds up as the
+ *  backlog grows so a fast model is tracked with bounded latency: at a steady incoming
+ *  rate `R`, the backlog settles near `(R - BASE_REVEAL_CPS) / REVEAL_BACKLOG_GAIN`. */
+export const REVEAL_BACKLOG_GAIN = 3;
+
+/** Hard ceiling for paced output, in characters per second. The proportional
+ *  controller above may ask to catch up much faster when a provider delivers a whole
+ *  response in one burst. Without a ceiling, a 3k-character backlog at a 50ms redraw
+ *  cadence reveals more than 500 characters in one frame, which is several terminal
+ *  rows appearing at once. Capping by ELAPSED TIME rather than by a fixed
+ *  chars-per-frame value keeps a 16ms and a 50ms redraw loop at the same visual rate,
+ *  while still draining a large burst in a few seconds. */
+export const MAX_REVEAL_CPS = 960;
+
+/** Maximum elapsed time credited to a single reveal step. Without this, a long idle
+ *  gap before the next burst would bank a huge budget and dump the whole burst at
+ *  once, reintroducing the choppiness this exists to remove. */
+export const MAX_REVEAL_STEP_MS = 50;
+
+/** Kinds of streamed content moving through the buffer. */
+export const StreamKind = { Text: 'text', Reasoning: 'reasoning' };
+
+/** Revealed operations, in arrival order. Callers apply these to the UI: `text`
+ *  appends answer text, `reasoning` appends reasoning text, and `closeReasoning` ends
+ *  the live reasoning region — exactly after the final buffered reasoning character it
+ *  followed. */
+export const StreamOp = {
+  Text: 'text',
+  Reasoning: 'reasoning',
+  CloseReasoning: 'closeReasoning',
+};
+
+/** Maximum jitter-recorder events retained per series (arrivals / reveals). */
+const JITTER_EVENT_CAP = 4096;
+
+/**
+ * Take at most `n` CODE POINTS off the front of `s`.
+ *
+ * The budget is counted in code points, not UTF-16 units: a surrogate pair is one
+ * character to the model and one column-pair on screen, so counting units would drain
+ * emoji at half rate and could split a pair mid-character.
+ */
+function takeCodePoints(s, n) {
+  if (n <= 0) return ['', s];
+  let count = 0;
+  let i = 0;
+  while (i < s.length && count < n) {
+    const cp = s.codePointAt(i);
+    i += cp > 0xffff ? 2 : 1;
+    count++;
+  }
+  return [s.slice(0, i), s.slice(i)];
+}
+
+function countCodePoints(s) {
+  let n = 0;
+  for (let i = 0; i < s.length;) {
+    const cp = s.codePointAt(i);
+    i += cp > 0xffff ? 2 : 1;
+    n++;
+  }
+  return n;
+}
+
+/**
+ * Records arrival (provider burst) and reveal (paced UI) events so choppiness can be
+ * quantified: a smooth reveal stream has low variance in characters-per-time
+ * regardless of how bursty the arrivals were. This is what lets the smoothing be
+ * verified with a number instead of by eye.
+ */
+class JitterRecorder {
+  constructor() {
+    this.arrivals = [];
+    this.reveals = [];
+  }
+
+  recordArrival(kind, chars, at) { this._record(this.arrivals, kind, chars, at); }
+  recordReveal(kind, chars, at) { this._record(this.reveals, kind, chars, at); }
+
+  _record(series, kind, chars, at) {
+    if (chars === 0) return;
+    if (series.length >= JITTER_EVENT_CAP) series.shift();
+    series.push({ at, chars, kind });
+  }
+
+  /** Characters-per-second samples across a series, plus their spread. */
+  static seriesStats(series) {
+    if (series.length < 2) return { samples: 0, mean: 0, stdev: 0 };
+    const rates = [];
+    for (let i = 1; i < series.length; i++) {
+      const dt = (series[i].at - series[i - 1].at) / 1000;
+      // A zero-length gap would divide by zero; sub-millisecond gaps are noise.
+      if (dt > 0) rates.push(series[i].chars / dt);
+    }
+    if (!rates.length) return { samples: 0, mean: 0, stdev: 0 };
+    const mean = rates.reduce((a, b) => a + b, 0) / rates.length;
+    const variance = rates.reduce((a, b) => a + (b - mean) ** 2, 0) / rates.length;
+    return { samples: rates.length, mean, stdev: Math.sqrt(variance) };
+  }
+
+  profile() {
+    const arrivals = JitterRecorder.seriesStats(this.arrivals);
+    const reveals = JitterRecorder.seriesStats(this.reveals);
+    return {
+      arrivals,
+      reveals,
+      // The headline number: how much steadier the reveal is than the arrivals that
+      // fed it. 1 means "no smoothing", >1 means the UI is smoother than the wire.
+      smoothing: arrivals.stdev > 0 ? arrivals.stdev / Math.max(1e-9, reveals.stdev) : 0,
+    };
+  }
+}
+
+export class StreamBuffer {
+  /**
+   * @param {object} [opts]
+   * @param {() => number} [opts.now] Injectable clock in ms. Tests pin it to make the
+   *   pacing deterministic; production leaves it as `Date.now`.
+   */
+  constructor(opts = {}) {
+    this.now = opts.now || Date.now;
+    this.baseCps = opts.baseCps != null ? opts.baseCps : BASE_REVEAL_CPS;
+    this.backlogGain = opts.backlogGain != null ? opts.backlogGain : REVEAL_BACKLOG_GAIN;
+    this.maxCps = opts.maxCps != null ? opts.maxCps : MAX_REVEAL_CPS;
+    this.maxStepMs = opts.maxStepMs != null ? opts.maxStepMs : MAX_REVEAL_STEP_MS;
+    this.queue = [];
+    this.backlogChars = 0;
+    this.lastReveal = this.now();
+    // Fractional reveal budget carried between steps so slow rates still make progress
+    // instead of rounding down to zero forever.
+    this.carry = 0;
+    // Independent hard-ceiling budget. Kept separate from `carry` so a large
+    // proportional-controller backlog cannot bypass the wall-clock cap when many
+    // provider deltas arrive between redraw ticks.
+    this.ceilingCarry = 0;
+    // Whether reasoning pushed through this buffer is still "open" (no close marker
+    // queued since the last reasoning chunk).
+    this.reasoningOpen = false;
+    this.jitter = new JitterRecorder();
+  }
+
+  /** Push answer text, returning the paced ops ready to apply now. If a reasoning
+   *  region is open in the backlog and this text contains non-whitespace, a
+   *  `closeReasoning` marker is queued first so the region closes (in order) before
+   *  the answer text reveals. */
+  pushText(text) {
+    const s = String(text == null ? '' : text);
+    if (!s) return this._revealNow();
+    if (this.reasoningOpen && s.trim() !== '') {
+      this.queue.push({ marker: true });
+      this.reasoningOpen = false;
+    }
+    this._pushChunk(StreamKind.Text, s);
+    return this._revealNow();
+  }
+
+  /** Push reasoning text, returning the paced ops ready to apply now. Marks the
+   *  reasoning region open until a close marker is queued. */
+  pushReasoning(text) {
+    const s = String(text == null ? '' : text);
+    if (!s) return this._revealNow();
+    this.reasoningOpen = true;
+    this._pushChunk(StreamKind.Reasoning, s);
+    return this._revealNow();
+  }
+
+  /** Queue a reasoning-region close marker (a no-op when no reasoning is open in the
+   *  backlog), returning the paced ops ready to apply now. The marker reveals exactly
+   *  after the final buffered reasoning character. */
+  pushCloseReasoning() {
+    if (this.reasoningOpen) {
+      this.queue.push({ marker: true });
+      this.reasoningOpen = false;
+    }
+    return this._revealNow();
+  }
+
+  /** Force flush the entire backlog. Call this on message end, commit, or interrupt —
+   *  anything that ends the turn must not leave text trickling out afterwards. */
+  flush() {
+    this.carry = 0;
+    this.ceilingCarry = 0;
+    this.lastReveal = this.now();
+    const ops = this._drainOps(this.backlogChars, true);
+    this.backlogChars = 0;
+    this.reasoningOpen = false;
+    return ops;
+  }
+
+  /** Reveal one paced frame worth of buffered content. Called from the periodic redraw
+   *  tick so the backlog drains smoothly even when no new delta arrived this frame.
+   *  Finalization paths should still call `flush()`. */
+  flushSmoothFrame() {
+    return this._revealNow();
+  }
+
+  /** True when nothing is buffered — no chunks and no markers. A caller driving a
+   *  fast tick can stop the tick on this. */
+  get isEmpty() {
+    return this.queue.length === 0;
+  }
+
+  /** Characters still waiting to be revealed. */
+  get backlog() {
+    return this.backlogChars;
+  }
+
+  /** Drop the backlog without returning content. */
+  clear() {
+    this.queue.length = 0;
+    this.backlogChars = 0;
+    this.carry = 0;
+    this.ceilingCarry = 0;
+    this.reasoningOpen = false;
+    this.lastReveal = this.now();
+  }
+
+  /** Arrival-vs-reveal smoothness statistics. */
+  jitterProfile() {
+    return this.jitter.profile();
+  }
+
+  resetJitter() {
+    this.jitter = new JitterRecorder();
+  }
+
+  /** Append a chunk, coalescing with the previous queue entry of the same kind so the
+   *  queue stays short under token-level feeds. */
+  _pushChunk(kind, text) {
+    const n = countCodePoints(text);
+    this.backlogChars += n;
+    this.jitter.recordArrival(kind, n, this.now());
+    const back = this.queue[this.queue.length - 1];
+    if (back && !back.marker && back.kind === kind) {
+      back.text += text;
+      return;
+    }
+    this.queue.push({ kind, text });
+  }
+
+  /** Proportional, time-paced reveal: advance the budget by the (clamped) elapsed time
+   *  times a backlog-scaled rate, then drain that many characters plus any zero-cost
+   *  markers reached along the way. */
+  _revealNow() {
+    const now = this.now();
+    if (this.backlogChars === 0) {
+      // No chunk backlog: reset so an idle gap cannot bank reveal budget. Any queued
+      // entries are markers only, and they emit immediately.
+      this.carry = 0;
+      this.ceilingCarry = 0;
+      this.lastReveal = now;
+      return this._drainOps(0, true);
+    }
+
+    const dt = Math.min(Math.max(0, now - this.lastReveal), this.maxStepMs) / 1000;
+    this.lastReveal = now;
+
+    const cps = this.baseCps + this.backlogChars * this.backlogGain;
+    this.carry += dt * cps;
+    this.ceilingCarry += dt * this.maxCps;
+
+    let reveal = Math.min(Math.floor(this.carry), Math.floor(this.ceilingCarry));
+    if (reveal === 0) {
+      // The budget has not reached a whole character yet; keep accumulating. Leading
+      // markers still emit so region boundaries are not delayed.
+      return this._drainOps(0, false);
+    }
+
+    // The backlog-scaled controller is intentionally aggressive about catching up, but
+    // it must never turn one provider burst into a visible wall of text. Bounding each
+    // step by the same wall-clock rate keeps 16ms and 50ms redraw loops visually
+    // identical, and the independent token bucket means repeated pushes with near-zero
+    // elapsed time cannot mint one free character each.
+    reveal = Math.min(reveal, this.backlogChars);
+    this.carry -= reveal;
+    this.ceilingCarry -= reveal;
+    return this._drainOps(reveal, false);
+  }
+
+/** Drain up to `charCount` characters from the front of the queue, on code-point
+   *  boundaries, emitting markers whenever they reach the front. A marker costs no
+   *  budget, so a queued region boundary is never delayed behind text. */
+  _drainOps(charCount) {
+    const ops = [];
+    let budget = charCount;
+    const at = this.now();
+    for (;;) {
+      const front = this.queue[0];
+      if (!front) break;
+      if (front.marker) {
+        this.queue.shift();
+        ops.push({ op: StreamOp.CloseReasoning });
+        continue;
+      }
+      if (budget === 0) break;
+      // Read the kind BEFORE any shift: the pop below clears the reference.
+      const kind = front.kind;
+      const available = countCodePoints(front.text);
+      const take = Math.min(budget, available);
+      let chunk;
+      if (take === available) {
+        this.queue.shift();
+        chunk = front.text;
+      } else {
+        const [head, rest] = takeCodePoints(front.text, take);
+        front.text = rest;
+        chunk = head;
+      }
+      budget -= take;
+      this.backlogChars = Math.max(0, this.backlogChars - take);
+      this.jitter.recordReveal(kind, take, at);
+      ops.push({ op: kind === StreamKind.Text ? StreamOp.Text : StreamOp.Reasoning, text: chunk });
+    }
+    return ops;
+  }
+}