Skip to content

armgit / Orkas

Public Imported from GitHub
0

Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.

Atomically strip agent/agent-input-form/agent-input-submission containers

wytcdafe17e03c0
diff --git a/CLAUDE.md b/CLAUDE.md
index 3668fa19..84f16c91 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -295,7 +295,21 @@ The commit message is **about the change**, not about how it got here. Sync prov
- **Don't write**: functions that are correct by typing alone, thin wrappers, UI/DOM, getter/setter, library-guaranteed behavior.
- **Forbidden**: same-branch repeat assertions with different data, asserting internals, tautologies, just-change-args-not-branches, "type/signature/existence" tests, all-happy-path.
-**Organization**: `test/main/` mirrors `src/main/`; one file per module under test; one level of nested `describe`.
+**Organization**: `test/main/` mirrors `src/main/`; `test/renderer/` mirrors `src/renderer/modules/` for the small set of pure renderer-side functions that have fixture coverage (see below). One file per module under test; one level of nested `describe`.
+
+**Hard rule for LLM-output text munging** (regex / parser / classifier / segmenter / sanitizer that consumes streamed or final assistant text — `<agent>` strippers, `<agent-input-form>` strippers, prose/code splitters, mention parsers, code-fence handlers, etc.): these MUST have fixture tests pinning **set A (real shapes the matcher must handle)** AND **set B (look-alike shapes the matcher must NOT handle)**. Adding a guard / branch / segmentation step requires extending the fixture set with the new motivating shape — the patch isn't done until the new fixture is green AND every previous fixture still passes. Reason: this category is whack-a-mole prone — fixing one shape silently breaks another via guard granularity mismatch (we have shipped the same `<agent>` stripper regression three rounds in a row because each round only verified the new case). Typecheck and review can't catch granularity mismatches; only fixtures can.
+
+To make pure renderer-side functions testable under vitest without violating §8's "no export/import" rule, extract them into a standalone `src/renderer/modules/<name>.js` and end the file with a guarded CommonJS bridge:
+
+```js
+if (typeof module !== 'undefined' && typeof module.exports === 'object') {
+ module.exports = { _fnA, _fnB };
+}
+```
+
+The renderer evaluates `<script>`-loaded files where `module` is undefined, so the guard is a no-op there. Test side `require()`s the file. **This is the only allowed escape from §8's no-import/export rule, and only for pure functions** — anything that touches `window` / DOM / i18n / IPC stays inline.
+
+**Modifying existing code: existing behavior is the spec.** Adding a guard / branch / segmentation to existing code reorders its matrix of accepted inputs. If the previously-accepted shapes aren't actively re-checked, the change silently breaks them — this is the failure mode behind "fix here, break there" cycles. Before changing existing code: read recent `fix` commits on the file (they encode invariants nothing else documents), grep callers, run existing tests; for text-processing functions in particular, "mentally trace" is not enough — extend the fixture set first, then change the code.
### Don't do
diff --git a/src/renderer/index.html b/src/renderer/index.html
index efdd8060..f115327a 100644
--- a/src/renderer/index.html
+++ b/src/renderer/index.html
@@ -743,6 +743,7 @@
<script src="./modules/avatar-picker.js"></script>
<script src="./modules/chat-input-form.js"></script>
<script src="./modules/chat-lightbox.js"></script>
+ <script src="./modules/strip-agent.js"></script>
<script src="./modules/conversation.js"></script>
<script src="./modules/plan-rail.js"></script>
<script src="./modules/queue-draft.js"></script>
diff --git a/src/renderer/modules/conversation.js b/src/renderer/modules/conversation.js
index 98773a10..71bad1bc 100644
--- a/src/renderer/modules/conversation.js
+++ b/src/renderer/modules/conversation.js
@@ -1344,13 +1344,14 @@ function appendChatMessage(message, autoScroll = true, opts = {}) {
// User messages carrying an `<agent-input-submission>` tag (form submit
// replay) strip the XML tag for display — the bullet list above it
// describes the same values, and the LLM still parses the tag from the
- // stored raw text. Assistant messages get the defensive agent-block
- // strip in case the backend's extractor missed a format variant (see
- // `_stripSurvivingAgentBlocks`).
+ // stored raw text. Assistant messages get a defensive structural-block
+ // strip covering `<agent>` / `<agent-input-form>` / `<agent-input-submission>`
+ // in case the backend's extractor missed a format variant (see
+ // `_stripSurvivingStructuralBlocks` in strip-agent.js).
let displayContent = rawContent;
if (!isHtmlSnippet) {
if (role === 'user') displayContent = _stripSubmissionTagForDisplay(rawContent);
- else if (role === 'assistant') displayContent = _stripSurvivingAgentBlocks(rawContent);
+ else if (role === 'assistant') displayContent = _stripSurvivingStructuralBlocks(rawContent);
}
const contentHtml = isHtmlSnippet
? rawContent
@@ -2054,7 +2055,7 @@ function _streamingSetFinal(msg, text, { archive = false } = {}) {
// the final text for reasons unrelated to cleanliness — the safer
// default is to always paint the final text (same DOM node, minor
// reflow, no visible flash in practice).
- const display = _stripSurvivingAgentBlocks(text);
+ const display = _stripSurvivingStructuralBlocks(text);
finalEl.innerHTML = `<div class="markdown-body">${_renderMessageMarkdown(display)}</div>`;
finalEl.style.display = '';
msg.dataset.finalText = display || '';
@@ -2121,7 +2122,7 @@ function _streamingSetError(msg, text) {
const partial = String(msg.dataset.streamBuf || '');
let bodyHtml = '';
if (partial) {
- const display = _stripSurvivingAgentBlocks(partial);
+ const display = _stripSurvivingStructuralBlocks(partial);
if (display) {
bodyHtml = `<div class="markdown-body">${_renderMessageMarkdown(display)}</div>`;
msg.dataset.finalText = display;
@@ -3152,149 +3153,20 @@ function _mountCreatedAgentChip(msg, payload) {
// bulleted summary above it already tells them what they confirmed.
function _stripSubmissionTagForDisplay(text) {
if (!text || text.indexOf('<agent-input-submission') < 0) return text;
- return text
- .replace(/\n*<agent-input-submission\b[^>]*>[\s\S]*?<\/agent-input-submission>\s*/gi, '')
- .replace(/\n{3,}/g, '\n\n')
- .trimEnd();
-}
-
-// Split a markdown buffer into alternating prose / code segments. "Code" =
-// fenced ``` / ~~~ blocks (≤3-space indent, info-string allowed) plus inline
-// backtick spans; everything else is prose. Used by the `<agent>` container
-// strippers so coding scenarios — where the LLM legitimately quotes `<agent>`
-// inside a code sample to explain how this app's structured-output protocol
-// works — don't see the bubble silently truncated. Mid-stream unclosed fences
-// are treated as code through end-of-buffer, matching how the markdown
-// renderer would paint them.
-function _splitMarkdownProseCode(text) {
- const segs = [];
- if (!text) return segs;
- const n = text.length;
- let proseStart = 0;
- const flushProse = (end) => {
- if (end > proseStart) segs.push({ kind: 'prose', text: text.slice(proseStart, end) });
- };
- let i = 0;
- while (i < n) {
- const lineStart = i === 0 || text[i - 1] === '\n';
- if (lineStart) {
- let j = i;
- let indent = 0;
- while (indent < 3 && text[j] === ' ') { j++; indent++; }
- const ch = text[j];
- if (ch === '`' || ch === '~') {
- let count = 0;
- while (text[j + count] === ch) count++;
- if (count >= 3) {
- let k = j + count;
- while (k < n && text[k] !== '\n') k++;
- let scan = k < n ? k + 1 : n;
- let close = -1;
- while (scan < n) {
- let s = scan;
- let pad = 0;
- while (pad < 3 && text[s] === ' ') { s++; pad++; }
- if (text[s] === ch) {
- let cc = 0;
- while (text[s + cc] === ch) cc++;
- if (cc >= count) {
- let lineEnd = s + cc;
- while (lineEnd < n && text[lineEnd] !== '\n') lineEnd++;
- close = lineEnd;
- break;
- }
- }
- while (scan < n && text[scan] !== '\n') scan++;
- if (scan < n) scan++;
- }
- flushProse(i);
- const endIdx = close >= 0 ? close : n;
- segs.push({ kind: 'code', text: text.slice(i, endIdx) });
- proseStart = endIdx;
- i = endIdx;
- continue;
- }
- }
- }
- if (text[i] === '`') {
- let count = 0;
- while (text[i + count] === '`') count++;
- let j = i + count;
- let close = -1;
- while (j < n) {
- if (text[j] === '`') {
- let cc = 0;
- while (text[j + cc] === '`') cc++;
- if (cc === count) { close = j + cc; break; }
- j += cc;
- } else {
- j++;
- }
- }
- if (close > 0) {
- flushProse(i);
- segs.push({ kind: 'code', text: text.slice(i, close) });
- proseStart = close;
- i = close;
- continue;
- }
- // Mid-stream unclosed inline backticks — mirror the fenced-block branch
- // above and tentatively classify [backtick, EOF] as code so a literal
- // `<agent>` typed inside the span isn't stripped while we wait for the
- // closing backtick to stream in.
- flushProse(i);
- segs.push({ kind: 'code', text: text.slice(i, n) });
- proseStart = n;
- i = n;
- continue;
- }
- i++;
- }
- flushProse(n);
- return segs;
-}
-
-// Collapse any ```agent-input-form fenced block in a streaming buffer to a
-// single-line placeholder so the user never sees the raw JSON being typed
-// char-by-char. Closed blocks get the placeholder inline; unclosed blocks
-// (we're still mid-stream inside one) get everything from the fence onward
-// replaced with the placeholder. When `final` arrives main has already
-// stripped the block and mounts the real form widget.
-// Final-time safety strip: drop any surviving `<agent>...</agent>` update
-// container from a message body entirely (no placeholder) before it's
-// rendered into the bubble. Used by `_streamingSetFinal` and the
-// persisted-message renderer to guard against (a) backend extractor missing
-// a format variant and (b) streaming-time placeholders accidentally sticking
-// around. Both closed and unclosed containers get removed; consecutive blank
-// lines collapse to one.
-// Code-fence guard: only strip `<agent>` matches that fall in PROSE segments —
-// matches inside fenced code blocks or inline backtick spans are preserved so
-// the LLM can quote `<agent>` literally when explaining this app's structured-
-// output protocol. Without this guard, a coding-explanation reply that
-// mentioned `<agent>` ate the rest of the bubble (the unclosed-tag fallback
-// would match `<agent>[\s\S]*$` against the literal token and wipe the tail).
-function _stripSurvivingAgentBlocks(text) {
- if (!text || text.indexOf('<agent>') < 0) return text;
- const out = _splitMarkdownProseCode(text)
- .map((s) => s.kind === 'code'
- ? s.text
- : s.text
- .replace(/<agent>[\s\S]*?<\/agent>/g, '')
- .replace(/<agent>[\s\S]*$/, ''))
- .join('');
- return out
- .replace(/\n{3,}/g, '\n\n')
- .trim();
-}
-
-// Collapse the `<agent>...</agent>` update container (closed or mid-stream)
-// in a streaming buffer into **exactly one** italicized placeholder — so the
-// user never sees raw XML-ish tags / workflow JSON / inputs JSON typed
-// char-by-char. Container layout (see `chat_agent_setup.md` / `chat_commander.md`
-// § 创建智能体) is `<agent>...children...</agent>`; the whole container is
-// one unit, so we just replace the closed form with a placeholder and collapse
-// any unclosed trailing container the same way. `_streamingSetFinal` strips
-// the container for real at final time, so no placeholder survives.
+ // Atomic-container strip with prose/code guard via strip-agent.js.
+ // Same class of fragmentation / set-B leak as `<agent>` — see that
+ // file's header for the invariant matrix.
+ const out = _stripOuterTagBlocks(text, 'agent-input-submission');
+ if (out === text) return text;
+ return out.replace(/\n{3,}/g, '\n\n').trimEnd();
+}
+
+// `_splitMarkdownProseCode`, `_findOuterAgentRanges`, `_stripSurvivingAgentBlocks`,
+// `_replaceOuterAgentBlocks` are defined in `./strip-agent.js` (loaded earlier
+// in `index.html`). They live in their own file so vitest can pin the set-A /
+// set-B fixtures (`test/renderer/strip-agent.test.ts`) — see that file for
+// the invariant matrix. Wrap the i18n-aware placeholder here and delegate.
+//
// Wrap placeholder text in an HTML `<em>` instead of markdown `_text_`:
// standard markdown requires word-boundary chars on each side of `_` for
// italic emphasis, and CJK glyphs don't count as word boundaries, so
@@ -3306,18 +3178,7 @@ function _streamPlaceholderHtml(key) {
}
function _stripAgentCreateBlocksForStream(buf) {
- if (!buf || buf.indexOf('<agent>') < 0) return buf;
- const placeholder = _streamPlaceholderHtml('chat.create_agent_streaming_placeholder');
- // Same code-fence guard as `_stripSurvivingAgentBlocks` — leave `<agent>`
- // inside fenced blocks / backtick spans alone so coding explanations stream
- // through verbatim.
- return _splitMarkdownProseCode(buf)
- .map((s) => s.kind === 'code'
- ? s.text
- : s.text
- .replace(/<agent>[\s\S]*?<\/agent>/g, placeholder)
- .replace(/<agent>[\s\S]*$/, placeholder))
- .join('');
+ return _replaceOuterAgentBlocks(buf, _streamPlaceholderHtml('chat.create_agent_streaming_placeholder'));
}
function _stripAgentFormBlockForStream(buf) {
@@ -3325,22 +3186,19 @@ function _stripAgentFormBlockForStream(buf) {
// with submission reply tag, token-stable). Legacy: fenced
// ```agent-input-form block — tolerated with `[\s\-]*` inside the
// header to also catch "```agent\n-input-form" token-split outputs.
- // Both are stripped to the same streaming placeholder; main's final
- // pass mounts the actual form widget.
+ // Both stream to the same placeholder; main's final pass mounts the
+ // actual form widget.
if (!buf) return buf;
- const hasXml = buf.indexOf('<agent-input-form>') >= 0;
- const hasLegacy = /```\s*agent[\s\-]*input[\s\-]*form/.test(buf);
- if (!hasXml && !hasLegacy) return buf;
const placeholder = _streamPlaceholderHtml('chat.form.streaming_placeholder');
- let out = buf;
- if (hasXml) {
- out = out.replace(
- /(?:^|\n)[ \t]*<agent-input-form>[ \t]*\r?\n[\s\S]*?\r?\n[ \t]*<\/agent-input-form>[ \t]*(?=\n|$)/g,
- placeholder,
- );
- out = out.replace(/(?:^|\n)[ \t]*<agent-input-form>[\s\S]*$/, placeholder);
- }
- if (hasLegacy) {
+ // XML branch: atomic-container handling via strip-agent.js — same
+ // prose/code guard as `<agent>` so a fenced ```xml example or inline
+ // backtick mention of `<agent-input-form>` survives instead of being
+ // eaten as a real form.
+ let out = _replaceOuterTagBlocks(buf, 'agent-input-form', placeholder);
+ // Legacy fenced-block branch — kept for old-protocol compatibility.
+ // No prose/code guard here: the legacy fence IS itself a code fence,
+ // and outer fenced quoting of legacy form blocks is implausible.
+ if (/```\s*agent[\s\-]*input[\s\-]*form/.test(out)) {
out = out.replace(
/(?:^|\n)```\s*agent[\s\-]*input[\s\-]*form[ \t]*\r?\n[\s\S]*?\n```(?=\n|$)/g,
placeholder,
diff --git a/src/renderer/modules/strip-agent.js b/src/renderer/modules/strip-agent.js
new file mode 100644
index 00000000..e0b8ee38
--- /dev/null
+++ b/src/renderer/modules/strip-agent.js
@@ -0,0 +1,275 @@
+// Pure string functions for atomic-container stripping of LLM-emitted
+// XML tags surfacing in renderer text. Three tag families share these
+// helpers via `tagName` parameter:
+// - `<agent>` — commander create / edit container
+// - `<agent-input-form>` — agent's form widget (streaming placeholder)
+// - `<agent-input-submission>` — user form-reply tag (display strip)
+//
+// All three need the same prose/code guard — if any of them is mentioned
+// literally inside a fenced code block or inline backtick span (e.g., a
+// protocol explanation), the literal mention must survive; the real
+// container must still be stripped/replaced atomically even when its body
+// contains backticks / fences / quotes (otherwise the prose/code split
+// fragments the container and the post-fragment suffix leaks past — the
+// 34e27fcb / a3110e61 / follow-up cycle on `<agent>`).
+//
+// Lives in a standalone file so vitest can `require()` it under Node and
+// pin the set-A vs set-B invariants — regressions in this category aren't
+// catchable by typecheck or eyeball review. Matching test file:
+// `test/renderer/strip-agent.test.ts`.
+//
+// CommonJS-export tail at the bottom is the ONLY allowed escape from the
+// renderer's "no export/import" rule (PC/CLAUDE.md §8) — it's guarded by
+// `typeof module`, evaluates to a no-op in the browser (where `module` is
+// undefined), and is purely a test bridge for pure functions. Don't
+// extend this convention to non-pure renderer code.
+
+// Split a markdown buffer into alternating prose / code segments. "Code" =
+// fenced ``` / ~~~ blocks (≤3-space indent, info-string allowed) plus inline
+// backtick spans; everything else is prose. Used by the `<agent>` container
+// strippers so coding scenarios — where the LLM legitimately quotes `<agent>`
+// inside a code sample to explain how this app's structured-output protocol
+// works — don't see the bubble silently truncated. Mid-stream unclosed fences
+// and unclosed inline backticks are treated as code through end-of-buffer,
+// matching how the markdown renderer would paint them.
+function _splitMarkdownProseCode(text) {
+ const segs = [];
+ if (!text) return segs;
+ const n = text.length;
+ let proseStart = 0;
+ const flushProse = (end) => {
+ if (end > proseStart) segs.push({ kind: 'prose', text: text.slice(proseStart, end) });
+ };
+ let i = 0;
+ while (i < n) {
+ const lineStart = i === 0 || text[i - 1] === '\n';
+ if (lineStart) {
+ let j = i;
+ let indent = 0;
+ while (indent < 3 && text[j] === ' ') { j++; indent++; }
+ const ch = text[j];
+ if (ch === '`' || ch === '~') {
+ let count = 0;
+ while (text[j + count] === ch) count++;
+ if (count >= 3) {
+ let k = j + count;
+ while (k < n && text[k] !== '\n') k++;
+ let scan = k < n ? k + 1 : n;
+ let close = -1;
+ while (scan < n) {
+ let s = scan;
+ let pad = 0;
+ while (pad < 3 && text[s] === ' ') { s++; pad++; }
+ if (text[s] === ch) {
+ let cc = 0;
+ while (text[s + cc] === ch) cc++;
+ if (cc >= count) {
+ let lineEnd = s + cc;
+ while (lineEnd < n && text[lineEnd] !== '\n') lineEnd++;
+ close = lineEnd;
+ break;
+ }
+ }
+ while (scan < n && text[scan] !== '\n') scan++;
+ if (scan < n) scan++;
+ }
+ flushProse(i);
+ const endIdx = close >= 0 ? close : n;
+ segs.push({ kind: 'code', text: text.slice(i, endIdx) });
+ proseStart = endIdx;
+ i = endIdx;
+ continue;
+ }
+ }
+ }
+ if (text[i] === '`') {
+ let count = 0;
+ while (text[i + count] === '`') count++;
+ let j = i + count;
+ let close = -1;
+ while (j < n) {
+ if (text[j] === '`') {
+ let cc = 0;
+ while (text[j + cc] === '`') cc++;
+ if (cc === count) { close = j + cc; break; }
+ j += cc;
+ } else {
+ j++;
+ }
+ }
+ if (close > 0) {
+ flushProse(i);
+ segs.push({ kind: 'code', text: text.slice(i, close) });
+ proseStart = close;
+ i = close;
+ continue;
+ }
+ flushProse(i);
+ segs.push({ kind: 'code', text: text.slice(i, n) });
+ proseStart = n;
+ i = n;
+ continue;
+ }
+ i++;
+ }
+ flushProse(n);
+ return segs;
+}
+
+// Find every `<TAG>...</TAG>` (or unclosed `<TAG>...EOF`) range whose
+// OPENING tag falls in an outer prose segment. The tagged container is
+// treated as one atomic unit — once the opening tag is in prose, we walk
+// to the matching `</TAG>` (or EOF) regardless of what's inside, so
+// backticks / fences / quotes authored inside the body don't fragment
+// the container and let the post-fragment suffix (often including the
+// closing tag) leak past the stripper. The outer-context check still
+// preserves literal mentions of the tag inside fenced code / inline
+// backtick spans (coding-explanation case).
+//
+// Generalized over `tagName` so the same atomic-container guarantee
+// covers `<agent>` (commander create/edit container), `<agent-input-form>`
+// (agent's form widget), and `<agent-input-submission>` (user form-reply
+// tag). Open form: `<tagName>` OR `<tagName attr="..." attr="...">`.
+// Close form: `</tagName>`. The boundary check (next char must be `>`,
+// whitespace, or `/`) prevents `<agent>` lookup from also matching
+// `<agent-input-form>` and similar siblings.
+//
+// Granularity invariant: the guard (prose/code classification) is
+// evaluated at the entity's OPENING boundary, NOT per-fragment inside.
+// Re-anchoring inside would re-introduce the leak.
+function _findOuterTagRanges(text, tagName) {
+ if (!text || !tagName) return [];
+ const openLeader = `<${tagName}`;
+ const closeLiteral = `</${tagName}>`;
+ if (text.indexOf(openLeader) < 0) return [];
+ const segs = _splitMarkdownProseCode(text);
+ const ranges = [];
+ let pos = 0;
+ for (const seg of segs) {
+ const segStart = pos;
+ pos += seg.text.length;
+ if (seg.kind !== 'prose') continue;
+ let from = segStart;
+ while (from < pos) {
+ const last = ranges.length ? ranges[ranges.length - 1] : null;
+ if (last && from < last[1]) from = last[1];
+ if (from >= pos) break;
+ const openIdx = text.indexOf(openLeader, from);
+ if (openIdx < 0 || openIdx >= pos) break;
+ // Boundary check: next char after `<tagName` must be `>` / whitespace
+ // / `/` so we don't match `<agent>` against `<agent-input-form>`.
+ const next = text.charCodeAt(openIdx + openLeader.length);
+ const isBoundary = next === 62 /* > */ || next === 32 /* space */
+ || next === 9 /* \t */ || next === 10 /* \n */ || next === 13 /* \r */
+ || next === 47 /* / */;
+ if (!isBoundary) {
+ from = openIdx + openLeader.length;
+ continue;
+ }
+ // Walk past attributes to the closing `>` of the open tag, then to
+ // `</tagName>` (or EOF). Unclosed open-tag mid-stream → swallow rest
+ // of buffer atomically.
+ const tagEnd = text.indexOf('>', openIdx + openLeader.length);
+ if (tagEnd < 0) {
+ ranges.push([openIdx, text.length]);
+ from = text.length;
+ break;
+ }
+ const closeIdx = text.indexOf(closeLiteral, tagEnd + 1);
+ const endPos = closeIdx < 0 ? text.length : closeIdx + closeLiteral.length;
+ ranges.push([openIdx, endPos]);
+ from = endPos;
+ }
+ }
+ return ranges;
+}
+
+// Strip every outer `<tagName>` container from `text` entirely. Used at
+// final-render time and at user-message-display time as a safety strip.
+function _stripOuterTagBlocks(text, tagName) {
+ if (!text) return text;
+ const ranges = _findOuterTagRanges(text, tagName);
+ if (!ranges.length) return text;
+ let out = '';
+ let cursor = 0;
+ for (const [s, e] of ranges) {
+ out += text.slice(cursor, s);
+ cursor = e;
+ }
+ out += text.slice(cursor);
+ return out;
+}
+
+// Replace every outer `<tagName>` container with `placeholder`. Used at
+// streaming time to keep the bubble clean while the LLM is still typing
+// the body.
+function _replaceOuterTagBlocks(buf, tagName, placeholder) {
+ if (!buf) return buf;
+ const ranges = _findOuterTagRanges(buf, tagName);
+ if (!ranges.length) return buf;
+ let out = '';
+ let cursor = 0;
+ for (const [s, e] of ranges) {
+ out += buf.slice(cursor, s) + placeholder;
+ cursor = e;
+ }
+ out += buf.slice(cursor);
+ return out;
+}
+
+// `<agent>`-specific wrappers. The final-time variant collapses runs of
+// blank lines and trims — that post-processing matters at the bubble
+// boundary (commander wraps the container in surrounding prose; clean
+// visual gap matters).
+function _findOuterAgentRanges(text) {
+ return _findOuterTagRanges(text, 'agent');
+}
+function _stripSurvivingAgentBlocks(text) {
+ if (!text) return text;
+ const out = _stripOuterTagBlocks(text, 'agent');
+ if (out === text) return text;
+ return out.replace(/\n{3,}/g, '\n\n').trim();
+}
+function _replaceOuterAgentBlocks(buf, placeholder) {
+ return _replaceOuterTagBlocks(buf, 'agent', placeholder);
+}
+
+// Defense-in-depth final-time strip for **every** structural container
+// that may surface in assistant / user message text:
+// - `<agent>` — primary case, commander create/edit
+// - `<agent-input-form>` — agent's form widget; main is supposed to
+// extract the payload + mount the widget so this never reaches final,
+// but if the main extractor misses a variant the raw XML lands in the
+// bubble alongside the widget. Strip silently rather than render raw.
+// - `<agent-input-submission>` — user form-reply tag; user-side render
+// already strips it via _stripSubmissionTagForDisplay, but if it ever
+// leaks into assistant text (LLM hallucination / quoting), strip too.
+//
+// Each tag is removed independently via the same atomic-container helper
+// so the prose/code guard applies uniformly — a literal mention inside a
+// fenced block / inline backtick survives all three. After all three
+// strip passes, collapse blank-line runs and trim, identical to the
+// `<agent>`-only post-processing.
+function _stripSurvivingStructuralBlocks(text) {
+ if (!text) return text;
+ let out = text;
+ for (const tag of ['agent', 'agent-input-form', 'agent-input-submission']) {
+ out = _stripOuterTagBlocks(out, tag);
+ }
+ if (out === text) return text;
+ return out.replace(/\n{3,}/g, '\n\n').trim();
+}
+
+// Test bridge — see file header. No-op in the browser (`module` undefined).
+if (typeof module !== 'undefined' && typeof module.exports === 'object') {
+ module.exports = {
+ _splitMarkdownProseCode,
+ _findOuterTagRanges,
+ _stripOuterTagBlocks,
+ _replaceOuterTagBlocks,
+ _findOuterAgentRanges,
+ _stripSurvivingAgentBlocks,
+ _replaceOuterAgentBlocks,
+ _stripSurvivingStructuralBlocks,
+ };
+}
diff --git a/test/renderer/strip-agent.test.ts b/test/renderer/strip-agent.test.ts
new file mode 100644
index 00000000..c95721c3
--- /dev/null
+++ b/test/renderer/strip-agent.test.ts
@@ -0,0 +1,430 @@
+// Pin the set-A vs set-B invariants for the `<agent>` container strippers.
+// Without these fixtures, the next "fix one shape, regress another" round
+// is invisible to typecheck and reviewer eyeballs — same class of bug has
+// already burned us across 34e27fcb / a3110e61 / a follow-up.
+//
+// Set A — real `<agent>` containers that MUST be stripped (final) /
+// replaced by a single placeholder (streaming):
+// A1. Plain closed container, no special tokens inside.
+// A2. Closed container whose `<workflow>` quotes tool / value names with
+// INLINE BACKTICKS — the shape that broke streaming and forced the
+// most recent rewrite. This is the load-bearing fixture.
+// A3. Closed container whose body has a multi-line FENCED CODE BLOCK
+// inside (e.g., LLM showing an example payload). The container is
+// still atomic at the OUTER level even though its body opens a
+// fence.
+// A4. Unclosed `<agent>` mid-stream — strip / replace from the opener
+// through end-of-buffer.
+// A5. Two closed containers in one buffer — both stripped, prose between
+// them preserved.
+//
+// Set B — literal `<agent>` mentions that MUST be preserved:
+// B1. Inside a fenced ```xml code block (the original 34e27fcb case).
+// B2. Inside an inline backtick span.
+// B3. Inside an UNCLOSED inline backtick (mid-stream code-explanation).
+//
+// Mixed: real container + literal mention coexisting in one buffer — only
+// the real container goes, the literal mention stays put.
+//
+// Adding a new guard / branch to any of these strippers? Add a fixture
+// for the motivating shape AND keep the existing fixtures green. Don't
+// rely on "I checked it manually" — that's the loop these tests exist
+// to break.
+
+import { describe, it, expect } from 'vitest';
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const strip = require('../../src/renderer/modules/strip-agent.js');
+const {
+ _splitMarkdownProseCode,
+ _findOuterTagRanges,
+ _stripOuterTagBlocks,
+ _replaceOuterTagBlocks,
+ _findOuterAgentRanges,
+ _stripSurvivingAgentBlocks,
+ _replaceOuterAgentBlocks,
+ _stripSurvivingStructuralBlocks,
+} = strip as {
+ _splitMarkdownProseCode: (text: string) => Array<{ kind: 'prose' | 'code'; text: string }>;
+ _findOuterTagRanges: (text: string, tagName: string) => Array<[number, number]>;
+ _stripOuterTagBlocks: (text: string, tagName: string) => string;
+ _replaceOuterTagBlocks: (buf: string, tagName: string, placeholder: string) => string;
+ _findOuterAgentRanges: (text: string) => Array<[number, number]>;
+ _stripSurvivingAgentBlocks: (text: string) => string;
+ _replaceOuterAgentBlocks: (buf: string, placeholder: string) => string;
+ _stripSurvivingStructuralBlocks: (text: string) => string;
+};
+
+const PH = '⟨PLACEHOLDER⟩';
+
+// --- Set A: real containers ------------------------------------------------
+
+describe('set A — real <agent> containers must be stripped / replaced', () => {
+ it('A1. plain closed container', () => {
+ const buf = 'preface\n<agent>\n<name>Foo</name>\n</agent>\ntail';
+ expect(_stripSurvivingAgentBlocks(buf)).toBe('preface\n\ntail');
+ expect(_replaceOuterAgentBlocks(buf, PH)).toBe(`preface\n${PH}\ntail`);
+ });
+
+ it('A2. container body contains INLINE BACKTICKS (the screenshot bug)', () => {
+ const buf = [
+ 'before',
+ '<agent>',
+ '<workflow>',
+ '1. Read inputs',
+ ' - `bash` — read user submission',
+ ' - normalize to `agent` / `skill` / `agent_and_skill`',
+ '</workflow>',
+ '</agent>',
+ 'after',
+ ].join('\n');
+ const stripped = _stripSurvivingAgentBlocks(buf);
+ expect(stripped).not.toContain('<agent>');
+ expect(stripped).not.toContain('</agent>');
+ expect(stripped).not.toContain('<workflow>');
+ expect(stripped).not.toContain('`bash`');
+ expect(stripped).not.toContain('agent_and_skill');
+ expect(stripped).toBe('before\n\nafter');
+
+ const replaced = _replaceOuterAgentBlocks(buf, PH);
+ expect(replaced).toBe(`before\n${PH}\nafter`);
+ // Exactly one placeholder — no leak after it.
+ expect(replaced.split(PH).length - 1).toBe(1);
+ });
+
+ it('A3. container body contains a fenced code block', () => {
+ const buf = [
+ 'before',
+ '<agent>',
+ '<description_en>',
+ 'See example:',
+ '```json',
+ '{"k": "v"}',
+ '```',
+ '</description_en>',
+ '</agent>',
+ 'after',
+ ].join('\n');
+ expect(_stripSurvivingAgentBlocks(buf)).toBe('before\n\nafter');
+ expect(_replaceOuterAgentBlocks(buf, PH)).toBe(`before\n${PH}\nafter`);
+ });
+
+ it('A4. unclosed <agent> mid-stream', () => {
+ const buf = 'streaming…\n<agent>\n<name>Foo</name>\n<workflow>step `bash` —';
+ expect(_stripSurvivingAgentBlocks(buf)).toBe('streaming…');
+ expect(_replaceOuterAgentBlocks(buf, PH)).toBe(`streaming…\n${PH}`);
+ });
+
+ it('A5. two closed containers in one buffer', () => {
+ const buf = '<agent><name>A</name></agent>\nmid\n<agent><name>B</name></agent>';
+ expect(_stripSurvivingAgentBlocks(buf)).toBe('mid');
+ const replaced = _replaceOuterAgentBlocks(buf, PH);
+ expect(replaced).toBe(`${PH}\nmid\n${PH}`);
+ expect(replaced.split(PH).length - 1).toBe(2);
+ });
+});
+
+// --- Set B: literal mentions must survive ---------------------------------
+
+describe('set B — literal <agent> in code must be preserved', () => {
+ it('B1. inside a fenced ```xml block', () => {
+ const buf = 'Use this format:\n```xml\n<agent><name>X</name></agent>\n```\nafter';
+ expect(_stripSurvivingAgentBlocks(buf)).toBe(buf.trim());
+ expect(_replaceOuterAgentBlocks(buf, PH)).toBe(buf);
+ });
+
+ it('B2. inside an inline backtick span', () => {
+ const buf = 'Wrap your spec in `<agent>...</agent>` to declare it.';
+ expect(_stripSurvivingAgentBlocks(buf)).toBe(buf);
+ expect(_replaceOuterAgentBlocks(buf, PH)).toBe(buf);
+ });
+
+ it('B3. inside an UNCLOSED inline backtick mid-stream', () => {
+ const buf = 'You write `<agent>';
+ expect(_stripSurvivingAgentBlocks(buf)).toBe(buf);
+ expect(_replaceOuterAgentBlocks(buf, PH)).toBe(buf);
+ });
+});
+
+// --- Mixed: container + literal mention coexisting -------------------------
+
+describe('mixed — real container + literal mention in one buffer', () => {
+ it('only the real container is replaced; quoted example survives', () => {
+ const buf = [
+ 'Example format:',
+ '```xml',
+ '<agent><name>Example</name></agent>',
+ '```',
+ 'And here is the actual one:',
+ '<agent>',
+ '<name>Real</name>',
+ '<workflow>step uses `bash`</workflow>',
+ '</agent>',
+ 'done.',
+ ].join('\n');
+ const stripped = _stripSurvivingAgentBlocks(buf);
+ // Quoted example inside ```xml stays.
+ expect(stripped).toContain('```xml');
+ expect(stripped).toContain('<agent><name>Example</name></agent>');
+ // Real one's tags / interior gone.
+ expect(stripped).not.toContain('<name>Real</name>');
+ expect(stripped).not.toContain('<workflow>');
+ expect(stripped).not.toContain('`bash`');
+
+ const replaced = _replaceOuterAgentBlocks(buf, PH);
+ expect(replaced).toContain('<agent><name>Example</name></agent>');
+ expect(replaced).toContain(PH);
+ expect(replaced).not.toContain('<name>Real</name>');
+ expect(replaced.split(PH).length - 1).toBe(1);
+ });
+});
+
+// --- Granularity invariant ------------------------------------------------
+
+describe('granularity invariant — the guard is anchored at the opening tag', () => {
+ it('range covers from <agent> opener to </agent> close, atomic across interior backticks', () => {
+ const buf = 'x\n<agent>a `b` c</agent>\ny';
+ const ranges = _findOuterAgentRanges(buf);
+ expect(ranges).toHaveLength(1);
+ const [start, end] = ranges[0];
+ expect(buf.slice(start, end)).toBe('<agent>a `b` c</agent>');
+ });
+
+ it('opener inside fenced code → no range produced', () => {
+ const buf = '```\n<agent>x</agent>\n```';
+ expect(_findOuterAgentRanges(buf)).toEqual([]);
+ });
+
+ it('opener inside inline backticks → no range produced', () => {
+ const buf = 'see `<agent>` token';
+ expect(_findOuterAgentRanges(buf)).toEqual([]);
+ });
+});
+
+// --- Empty / no-op inputs --------------------------------------------------
+
+describe('empty / no-op inputs', () => {
+ it('returns input unchanged when no <agent> token present', () => {
+ expect(_stripSurvivingAgentBlocks('hello world')).toBe('hello world');
+ expect(_replaceOuterAgentBlocks('hello world', PH)).toBe('hello world');
+ expect(_findOuterAgentRanges('hello world')).toEqual([]);
+ });
+
+ it('handles empty / falsy input', () => {
+ expect(_stripSurvivingAgentBlocks('')).toBe('');
+ expect(_replaceOuterAgentBlocks('', PH)).toBe('');
+ expect(_findOuterAgentRanges('')).toEqual([]);
+ });
+});
+
+// --- Sanity check on the prose/code splitter (used by the rangefinder) ----
+
+// --- Generic tagName parameter: the same matrix must hold for ----------
+// `<agent-input-form>` and `<agent-input-submission>`. Both currently lack
+// the prose/code guard in their original strippers; these fixtures lock
+// down the unified atomic-container behavior.
+
+describe('<agent-input-form> — set A (real form blocks must be replaced)', () => {
+ it('A1. plain XML form block, JSON body', () => {
+ const buf = 'lead-in\n<agent-input-form>\n[{"name":"topic","type":"text"}]\n</agent-input-form>\ntrail';
+ expect(_replaceOuterTagBlocks(buf, 'agent-input-form', PH))
+ .toBe('lead-in\n' + PH + '\ntrail');
+ });
+
+ it('A2. unclosed mid-stream form block', () => {
+ const buf = 'streaming…\n<agent-input-form>\n[{"name":"topic"';
+ expect(_replaceOuterTagBlocks(buf, 'agent-input-form', PH))
+ .toBe('streaming…\n' + PH);
+ });
+
+ it('A3. body containing inline backticks (label like "Use `bash`")', () => {
+ const buf = '<agent-input-form>\n[{"name":"x","label":"Use `bash` here"}]\n</agent-input-form>';
+ expect(_replaceOuterTagBlocks(buf, 'agent-input-form', PH)).toBe(PH);
+ });
+});
+
+describe('<agent-input-form> — set B (literal mentions must survive)', () => {
+ it('B1. inside a fenced ```xml block (protocol explanation)', () => {
+ const buf = 'Format:\n```xml\n<agent-input-form>\n[]\n</agent-input-form>\n```\nend';
+ expect(_replaceOuterTagBlocks(buf, 'agent-input-form', PH)).toBe(buf);
+ });
+
+ it('B2. inside an inline backtick span', () => {
+ const buf = 'Wrap fields in `<agent-input-form>` — the agent emits this.';
+ expect(_replaceOuterTagBlocks(buf, 'agent-input-form', PH)).toBe(buf);
+ });
+
+ it('B3. UNCLOSED inline backtick mid-stream (the streaming case)', () => {
+ const buf = 'Use `<agent-input-form>';
+ expect(_replaceOuterTagBlocks(buf, 'agent-input-form', PH)).toBe(buf);
+ });
+});
+
+describe('<agent-input-submission> — set A (real submission tags stripped)', () => {
+ it('A1. submission tag with attributes and JSON body', () => {
+ const buf = 'You confirmed:\n<agent-input-submission form_id="abc12345" agent_id="my-agent">\n{"topic":"x"}\n</agent-input-submission>';
+ expect(_stripOuterTagBlocks(buf, 'agent-input-submission'))
+ .toBe('You confirmed:\n');
+ });
+
+ it('A2. body whose JSON value contains backticks', () => {
+ const buf = 'You confirmed:\n<agent-input-submission form_id="abc12345" agent_id="my-agent">\n{"q":"run `bash` and `sh`"}\n</agent-input-submission>\nthanks';
+ const out = _stripOuterTagBlocks(buf, 'agent-input-submission');
+ expect(out).not.toContain('agent-input-submission');
+ expect(out).not.toContain('`bash`');
+ expect(out).toBe('You confirmed:\n\nthanks');
+ });
+});
+
+describe('<agent-input-submission> — set B (literal mentions survive)', () => {
+ it('B1. inside a fenced ```xml block', () => {
+ const buf = 'Reply format:\n```xml\n<agent-input-submission form_id="x" agent_id="y">\n{}\n</agent-input-submission>\n```';
+ expect(_stripOuterTagBlocks(buf, 'agent-input-submission')).toBe(buf);
+ });
+
+ it('B2. inside an inline backtick span', () => {
+ const buf = 'Use `<agent-input-submission ...>` to reply.';
+ expect(_stripOuterTagBlocks(buf, 'agent-input-submission')).toBe(buf);
+ });
+
+ it('B3. UNCLOSED inline backtick (defense-in-depth, even though the tag normally only appears in user messages and not mid-stream)', () => {
+ const buf = 'see `<agent-input-submission';
+ expect(_stripOuterTagBlocks(buf, 'agent-input-submission')).toBe(buf);
+ });
+});
+
+// --- Boundary check: tagName lookup must not bleed across siblings -------
+
+describe('boundary check — `<agent>` lookup must not match `<agent-input-form>`', () => {
+ it('a buffer containing only <agent-input-form> has no <agent> ranges', () => {
+ const buf = '<agent-input-form>\n[]\n</agent-input-form>';
+ expect(_findOuterTagRanges(buf, 'agent')).toEqual([]);
+ expect(_findOuterTagRanges(buf, 'agent-input-form')).toHaveLength(1);
+ });
+
+ it('a buffer containing only <agent-input-submission ...> has no <agent> ranges', () => {
+ const buf = '<agent-input-submission form_id="x" agent_id="y">{}</agent-input-submission>';
+ expect(_findOuterTagRanges(buf, 'agent')).toEqual([]);
+ expect(_findOuterTagRanges(buf, 'agent-input-submission')).toHaveLength(1);
+ });
+
+ it('mixed buffer — each tag matches independently', () => {
+ const buf = [
+ '<agent><name>A</name></agent>',
+ '<agent-input-form>\n[]\n</agent-input-form>',
+ '<agent-input-submission form_id="f" agent_id="a">{}</agent-input-submission>',
+ ].join('\n');
+ expect(_findOuterTagRanges(buf, 'agent')).toHaveLength(1);
+ expect(_findOuterTagRanges(buf, 'agent-input-form')).toHaveLength(1);
+ expect(_findOuterTagRanges(buf, 'agent-input-submission')).toHaveLength(1);
+ });
+});
+
+// --- Final-time defense-in-depth strip ----------------------------------
+// `_stripSurvivingStructuralBlocks` is the safety net at `_streamingSetFinal`
+// + persisted-render time. It must:
+// - strip every real outer container of all three tag families
+// - preserve every literal mention inside fenced code / inline backticks
+// - leave clean prose (no leftover blank-line runs)
+
+describe('_stripSurvivingStructuralBlocks (final-time safety strip)', () => {
+ it('strips a real <agent> container', () => {
+ const buf = 'lead\n<agent><name>X</name></agent>\ntail';
+ expect(_stripSurvivingStructuralBlocks(buf)).toBe('lead\n\ntail');
+ });
+
+ it('strips a surviving <agent-input-form> (main extractor missed it)', () => {
+ const buf = 'lead\n<agent-input-form>\n[]\n</agent-input-form>\ntail';
+ expect(_stripSurvivingStructuralBlocks(buf)).toBe('lead\n\ntail');
+ });
+
+ it('strips a hallucinated <agent-input-submission> in assistant text', () => {
+ const buf = 'lead\n<agent-input-submission form_id="f" agent_id="a">{}</agent-input-submission>\ntail';
+ expect(_stripSurvivingStructuralBlocks(buf)).toBe('lead\n\ntail');
+ });
+
+ it('strips all three tags coexisting in one buffer', () => {
+ const buf = [
+ 'before',
+ '<agent><name>A</name></agent>',
+ 'mid1',
+ '<agent-input-form>\n[]\n</agent-input-form>',
+ 'mid2',
+ '<agent-input-submission form_id="f" agent_id="a">{}</agent-input-submission>',
+ 'after',
+ ].join('\n');
+ const out = _stripSurvivingStructuralBlocks(buf);
+ expect(out).not.toContain('<agent>');
+ expect(out).not.toContain('<agent-input-form>');
+ expect(out).not.toContain('<agent-input-submission');
+ expect(out).toContain('before');
+ expect(out).toContain('mid1');
+ expect(out).toContain('mid2');
+ expect(out).toContain('after');
+ });
+
+ it('preserves every literal mention inside fenced code', () => {
+ const buf = [
+ 'Three protocol tags:',
+ '```xml',
+ '<agent><name>X</name></agent>',
+ '<agent-input-form>\n[]\n</agent-input-form>',
+ '<agent-input-submission form_id="f" agent_id="a">{}</agent-input-submission>',
+ '```',
+ 'end',
+ ].join('\n');
+ const out = _stripSurvivingStructuralBlocks(buf);
+ expect(out).toContain('<agent><name>X</name></agent>');
+ expect(out).toContain('<agent-input-form>');
+ expect(out).toContain('<agent-input-submission');
+ });
+
+ it('preserves every literal mention inside inline backticks', () => {
+ const buf = 'Use `<agent>`, `<agent-input-form>`, `<agent-input-submission ...>` for the three tags.';
+ expect(_stripSurvivingStructuralBlocks(buf)).toBe(buf);
+ });
+
+ it('mixed: real <agent> + literal forms in code → only <agent> stripped', () => {
+ const buf = [
+ 'spec:',
+ '```xml',
+ '<agent-input-form>\n[]\n</agent-input-form>',
+ '```',
+ '<agent><name>Real</name></agent>',
+ 'after',
+ ].join('\n');
+ const out = _stripSurvivingStructuralBlocks(buf);
+ expect(out).toContain('<agent-input-form>');
+ expect(out).not.toContain('<name>Real</name>');
+ expect(out).toContain('after');
+ });
+
+ it('no-op when buffer has none of the three tags', () => {
+ const buf = 'plain prose with no structural tags';
+ expect(_stripSurvivingStructuralBlocks(buf)).toBe(buf);
+ });
+
+ it('handles empty input', () => {
+ expect(_stripSurvivingStructuralBlocks('')).toBe('');
+ });
+});
+
+describe('_splitMarkdownProseCode sanity', () => {
+ it('keeps inline backtick spans as code segments', () => {
+ const segs = _splitMarkdownProseCode('a `b` c');
+ expect(segs.map((s) => s.kind)).toEqual(['prose', 'code', 'prose']);
+ expect(segs[1].text).toBe('`b`');
+ });
+
+ it('treats unclosed inline backtick as code through EOF', () => {
+ const segs = _splitMarkdownProseCode('a `b');
+ expect(segs.map((s) => s.kind)).toEqual(['prose', 'code']);
+ expect(segs[1].text).toBe('`b');
+ });
+
+ it('treats fenced block as code, including info string line', () => {
+ const segs = _splitMarkdownProseCode('intro\n```xml\n<x/>\n```\nend');
+ expect(segs.map((s) => s.kind)).toEqual(['prose', 'code', 'prose']);
+ expect(segs[1].text).toContain('```xml');
+ expect(segs[1].text).toContain('```');
+ });
+});