muonroi-cli 1.3.4 → 1.4.1

package/dist/src/orchestrator/subagent-compactor.d.ts

@@ -62,9 +62,58 @@ export interface SubAgentCompactorOptions {
      * model understand which loop elided the content.
      */
     label?: string;
+    /**
+     * F2 — envelope chars OUTSIDE the messages array that still count toward
+     * the model's billed input on every step (system prompt + tools schema).
+     * The threshold check uses `messagesChars + envelopeChars` so compaction
+     * fires when true prompt size exceeds the limit, not just messages[].
+     */
+    envelopeChars?: number;
+    /**
+     * G1 — model context window in TOKENS. When provided, the compactor
+     * ignores `thresholdChars` and fires when estimated tokens
+     * (`(messagesChars + envelopeChars) / CHARS_PER_TOKEN`) exceed
+     * `contextWindow * contextFillRatio`. Better than a fixed char threshold
+     * because models with different windows (8K vs 128K vs 1M) need
+     * proportional caps.
+     */
+    contextWindowTokens?: number;
+    /**
+     * G1 — fraction of contextWindow at which compaction kicks in. Default
+     * 0.5 — compact once half the window is consumed by prompt. Ignored if
+     * `contextWindowTokens` is not set.
+     */
+    contextFillRatio?: number;
+    /**
+     * Idea 3 (KEEP_TOOL_IDS lighter veto): explicit list of toolCallIds to keep
+     * verbatim this step (from agent emitting "KEEP_TOOL_IDS: id1,id2" in reasoning).
+     * These bypass age-based elision even if older than keepLastTurns.
+     */
+    keepToolIds?: string[];
+    /**
+     * Idea 4: optional side-effect hook called for tool results we are about to
+     * stub (full raw content available here). Fire-and-forget EE persist under
+     * source:"tool-artifact" so layer3/ee.query can later fetch "full tool result id=xxx".
+     */
+    persistArtifact?: (toolCallId: string, toolName: string, fullContent: string, reason: string) => void;
 }
+/**
+ * G1 — coarse char→token conversion. The real ratio is provider/tokenizer
+ * specific (cl100k ≈ 3.5-4 chars/token for English code-heavy content, more
+ * for non-English). 4 is the conservative middle ground; over-estimating
+ * tokens means we compact slightly earlier, which is the safe direction.
+ */
+export declare const CHARS_PER_TOKEN = 4;
 export declare const SUBAGENT_COMPACT_DEFAULT_THRESHOLD = 80000;
 export declare const SUBAGENT_COMPACT_DEFAULT_KEEP_LAST = 3;
+/** Tools whose full outputs are high-value for anti-mù (idea 1). Keep verbatim even if older than keepLast. */
+export declare const IMPORTANT_TOOL_NAMES: readonly ["read_file", "grep", "lsp", "bash"];
+/**
+ * Heuristic: keep full (no stub) for high-signal tool results.
+ * Signals: allowlist tool + (error/todo/plan/keyfile/large output or explicit keep list).
+ * Brief inline per GSD-quick + evidence-first.
+ */
+export declare function isHighValueToolResult(toolName: string, preview: string, explicitKeepIds?: Set<string>, toolCallId?: string): boolean;
 export declare function cumulativeMessageChars(messages: ReadonlyArray<ModelMessage>): number;
 /**
  * Compact a sub-agent message array in place-like fashion. Returns a NEW

package/dist/src/orchestrator/subagent-compactor.js

@@ -47,18 +47,92 @@
  *   MUONROI_SUBAGENT_COMPACT_THRESHOLD_CHARS — 20_000..500_000, default 80_000
  *   MUONROI_SUBAGENT_COMPACT_KEEP_LAST       — 1..20,           default 3
  */
+/**
+ * G1 — coarse char→token conversion. The real ratio is provider/tokenizer
+ * specific (cl100k ≈ 3.5-4 chars/token for English code-heavy content, more
+ * for non-English). 4 is the conservative middle ground; over-estimating
+ * tokens means we compact slightly earlier, which is the safe direction.
+ */
+export const CHARS_PER_TOKEN = 4;
 export const SUBAGENT_COMPACT_DEFAULT_THRESHOLD = 80_000;
 export const SUBAGENT_COMPACT_DEFAULT_KEEP_LAST = 3;
 const DEFAULT_OUTPUT_PREVIEW_CHARS = 200;
 const DEFAULT_LABEL = "sub-agent";
+/** Tools whose full outputs are high-value for anti-mù (idea 1). Keep verbatim even if older than keepLast. */
+export const IMPORTANT_TOOL_NAMES = ["read_file", "grep", "lsp", "bash"];
+/**
+ * Heuristic: keep full (no stub) for high-signal tool results.
+ * Signals: allowlist tool + (error/todo/plan/keyfile/large output or explicit keep list).
+ * Brief inline per GSD-quick + evidence-first.
+ */
+export function isHighValueToolResult(toolName, preview, explicitKeepIds, toolCallId) {
+    if (explicitKeepIds && toolCallId && explicitKeepIds.has(toolCallId))
+        return true;
+    const name = (toolName || "").toLowerCase();
+    // Always preserve terminal response tools — this is the agent's own delivered
+    // work/findings. Truncating it causes the agent to think it lost its answer.
+    if (name.startsWith("respond_"))
+        return true;
+    if (IMPORTANT_TOOL_NAMES.includes(name)) {
+        const p = preview.toLowerCase();
+        if (/error|fail|todo|plan|done|✔|blocked|critical/.test(p))
+            return true;
+        if (/\.(ts|tsx|js|md|json|test|spec)\b/.test(p) || p.includes("src/") || p.includes("PLAN"))
+            return true;
+        if (preview.length > 1500)
+            return true;
+        return true; // read_file/grep etc on source are presumptively high-value
+    }
+    if (toolCallId && explicitKeepIds?.has(toolCallId))
+        return true;
+    return false;
+}
 function resolveOpts(o) {
+    const keepIds = new Set((o?.keepToolIds || []).map((s) => String(s).trim()).filter(Boolean));
     return {
         thresholdChars: o?.thresholdChars ?? SUBAGENT_COMPACT_DEFAULT_THRESHOLD,
         keepLastTurns: Math.max(0, o?.keepLastTurns ?? SUBAGENT_COMPACT_DEFAULT_KEEP_LAST),
         outputPreviewChars: o?.outputPreviewChars ?? DEFAULT_OUTPUT_PREVIEW_CHARS,
         label: o?.label ?? DEFAULT_LABEL,
+        envelopeChars: Math.max(0, o?.envelopeChars ?? 0),
+        contextWindowTokens: Math.max(0, o?.contextWindowTokens ?? 0),
+        contextFillRatio: Math.min(0.95, Math.max(0.1, o?.contextFillRatio ?? 0.5)),
+        keepToolIds: keepIds,
+        persistArtifact: o?.persistArtifact,
     };
 }
+/**
+ * G1 + G2 — compute effective threshold (chars) and dynamic keepLastTurns
+ * based on context-window utilization. When the prompt approaches the
+ * window ceiling we want compaction to fire EARLIER and trim the keep
+ * window AGGRESSIVELY so the next round has room to grow.
+ */
+function computeDynamicParams(promptChars, opts) {
+    const { thresholdChars, keepLastTurns, contextWindowTokens, contextFillRatio } = opts;
+    if (contextWindowTokens <= 0) {
+        return {
+            effectiveThresholdChars: thresholdChars,
+            effectiveKeepLastTurns: keepLastTurns,
+            ctxFill: 0,
+        };
+    }
+    // G1 — token-aware threshold. Convert window×ratio (tokens) to chars
+    // budget, then pick the SMALLER of (env char threshold) and (window
+    // budget) so users opting into a tight env override still wins.
+    const tokenThresholdChars = contextWindowTokens * contextFillRatio * CHARS_PER_TOKEN;
+    const effectiveThresholdChars = Math.min(thresholdChars, tokenThresholdChars);
+    // G2 — dynamic keepLastTurns. Below 60% fill, keep default. Between 60-80%
+    // halve it (or floor at 2). Above 80%, drop to 1. Floor never goes to 0
+    // because that would break the assistant↔tool pairing for the live step.
+    const promptTokensEst = promptChars / CHARS_PER_TOKEN;
+    const ctxFill = contextWindowTokens > 0 ? promptTokensEst / contextWindowTokens : 0;
+    let effectiveKeepLastTurns = keepLastTurns;
+    if (ctxFill >= 0.8)
+        effectiveKeepLastTurns = 1;
+    else if (ctxFill >= 0.6)
+        effectiveKeepLastTurns = Math.max(2, Math.floor(keepLastTurns / 2));
+    return { effectiveThresholdChars, effectiveKeepLastTurns, ctxFill };
+}
 /** Approximate char cost of one ModelMessage's content. Mirrors recording.ts. */
 function messageChars(msg) {
     const content = msg.content;
@@ -150,7 +224,30 @@ function isToolResultMessage(msg) {
     }
     return false;
 }
-function rewriteOlderToolMessage(msg, previewChars, label) {
+/**
+ * F1 + G3 — detect a tool-result whose output is already an elided form:
+ *   - F1 compactor stub: "earlier tool_result for tool=X ... elided by ..."
+ *   - F4 sub-agent dup marker: "[dup of call #N — reuse it]"
+ *   - G3 cross-turn dedup marker: "[dup of <tool> from turn <N> — reuse]"
+ * Used for super-stubbing: re-shrinks the already-elided content down to a
+ * minimal "[elided <tool>]" form so repeated compaction rounds keep
+ * extracting space.
+ */
+const STUB_RE = /elided by (sub-agent|top-level) compactor|\[dup of /;
+function isStubbedToolResult(msg) {
+    if (msg.role !== "tool" || !Array.isArray(msg.content))
+        return false;
+    for (const part of msg.content) {
+        if (part.type !== "tool-result")
+            continue;
+        const out = part.output;
+        const v = (out?.value ?? out);
+        if (typeof v === "string" && STUB_RE.test(v))
+            return true;
+    }
+    return false;
+}
+function rewriteOlderToolMessage(msg, previewChars, label, keepToolIds, persistArtifact) {
     if (!isToolResultMessage(msg) || !Array.isArray(msg.content))
         return msg;
     const rewritten = msg.content.map((part) => {
@@ -159,8 +256,20 @@ function rewriteOlderToolMessage(msg, previewChars, label) {
         const tr = part;
         const rawPreview = extractOutputPreview(tr.output);
         const fullLen = rawPreview.length;
+        const toolCallId = tr.toolCallId;
+        // Idea 1 + 3: high-value or explicit KEEP_TOOL_IDS → keep verbatim (no stub).
+        if (isHighValueToolResult(tr.toolName, rawPreview, keepToolIds, toolCallId)) {
+            return part; // preserve full original output
+        }
         const preview = rawPreview.slice(0, previewChars).replace(/\s+/g, " ").trim();
         const stub = `[earlier tool_result for tool=${tr.toolName} (id=${tr.toolCallId}) — ${fullLen} chars elided by ${label} compactor; output: ${preview}]`;
+        // Idea 4: for the ones we actually elide, give caller a chance to persist full raw to EE for later on-demand fetch.
+        if (persistArtifact && fullLen > 200) {
+            try {
+                persistArtifact(toolCallId, tr.toolName, rawPreview, "elided-by-compactor");
+            }
+            catch { /* fail-open */ }
+        }
         return {
             type: "tool-result",
             toolCallId: tr.toolCallId,
@@ -178,16 +287,28 @@ function rewriteOlderToolMessage(msg, previewChars, label) {
  * reference is returned for cheap identity comparison in tests.
  */
 export function compactSubAgentMessages(messages, opts = {}) {
-    const { thresholdChars, keepLastTurns, outputPreviewChars, label } = resolveOpts(opts);
-    const total = cumulativeMessageChars(messages);
-    if (total < thresholdChars)
+    const resolved = resolveOpts(opts);
+    const { outputPreviewChars, label, envelopeChars } = resolved;
+    // F2 — threshold check uses TRUE prompt size (messages + system + tools).
+    // The envelope (system prompt + JSON-schema for every tool) is re-sent on
+    // every step and was previously invisible to the compactor, so a session
+    // with 20-50K of fixed overhead would never trip the messages-only check.
+    const messagesTotal = cumulativeMessageChars(messages);
+    const total = messagesTotal + envelopeChars;
+    // G1 + G2 — derive effective threshold and keepLastTurns from context
+    // window utilization. Falls back to static char threshold + keepLast
+    // when no contextWindowTokens supplied (preserves old behaviour).
+    const { effectiveThresholdChars, effectiveKeepLastTurns } = computeDynamicParams(total, resolved);
+    if (total < effectiveThresholdChars)
         return messages.slice();
-    const keepFrom = findKeepFromIndex(messages, keepLastTurns);
-    // If everything is in the "keep" tail (not enough turns to compact), bail.
+    const keepFrom = findKeepFromIndex(messages, effectiveKeepLastTurns);
     if (keepFrom <= 0)
         return messages.slice();
-    // Pass through the first user message and all system messages verbatim;
-    // rewrite older tool-result messages; keep the trailing window intact.
+    // Walk older messages; rewrite fresh tool results into stubs, super-shrink
+    // already-stubbed results (F1), and strip args off older assistant
+    // tool-call shells (F1). The 1:1 assistant↔tool pairing required by the AI
+    // SDK is preserved — only the CONTENT of each part is rewritten, never the
+    // structure or count.
     let firstUserSeen = false;
     const out = [];
     for (let i = 0; i < messages.length; i++) {
@@ -206,13 +327,65 @@ export function compactSubAgentMessages(messages, opts = {}) {
             continue;
         }
         if (isToolResultMessage(msg)) {
-            out.push(rewriteOlderToolMessage(msg, outputPreviewChars, label));
+            if (isStubbedToolResult(msg)) {
+                // A3 cache-stability: an already-written stub is TERMINAL — push it
+                // unchanged. The compactor runs once per streamText call in the
+                // agentic loop; the former F1 super-shrink rewrote the stub's bytes on
+                // every pass, which churned the OpenAI prompt-cache prefix (forensics:
+                // 0% cache hit on calls 1-4, only stabilising by call 5). Keeping the
+                // stub byte-identical makes compaction idempotent so the prefix caches
+                // from call 2. The marginal extra shrink is not worth the cache loss.
+                out.push(msg);
+                continue;
+            }
+            out.push(rewriteOlderToolMessage(msg, outputPreviewChars, label, resolved.keepToolIds, resolved.persistArtifact));
+            continue;
+        }
+        if (msg.role === "assistant" && Array.isArray(msg.content)) {
+            // F1 — strip args off older assistant tool-call shells. 50+ of these
+            // accumulate ~10-30K chars of args (file paths, bash commands) that
+            // the model does not need once the matching result has been elided.
+            // We keep toolCallId + toolName so pairing with tool-result is intact.
+            out.push(stripAssistantToolCallArgs(msg));
             continue;
         }
-        // Older assistant text / tool-call shells stay as-is. They are usually
-        // small and the model relies on the call shape for self-consistency.
         out.push(msg);
     }
     return out;
 }
+function stripAssistantToolCallArgs(msg) {
+    if (!Array.isArray(msg.content))
+        return msg;
+    const parts = msg.content;
+    let mutated = false;
+    const next = parts.map((part) => {
+        if (part.type !== "tool-call")
+            return part;
+        const input = part.input;
+        // A3 cache-stability / idempotency: never re-wrap an already-elided marker.
+        // The marker is itself ~95 chars, so without this guard a second pass
+        // re-wrapped it ("…— 200 chars…" → "…— 95 chars…"), changing the bytes and
+        // churning the cached prefix every call. Once elided, leave it terminal.
+        if (typeof input === "string" && input.startsWith("[earlier call args elided"))
+            return part;
+        const sz = typeof input === "string" ? input.length : JSON.stringify(input ?? "").length;
+        if (sz < 80)
+            return part; // tiny calls aren't worth touching
+        mutated = true;
+        // F3b — use a STRING marker, not the legacy `{_elided:true,original_chars:N}`
+        // object. The LLM previously hallucinated the elided object shape as its
+        // NEXT tool input (session 101870b4d9bb: read_file called with
+        // `{_elided:true,original_chars:75}` → "path must be string, got undefined").
+        // A plain string in `input` is impossible to confuse with a valid tool
+        // schema (every tool expects an object), so the model is forced to
+        // synthesize fresh args from the user's actual intent.
+        return {
+            ...part,
+            input: `[earlier call args elided by sub-agent compactor — ${sz} chars; consult the matching tool_result for what came back]`,
+        };
+    });
+    if (!mutated)
+        return msg;
+    return { ...msg, content: next };
+}
 //# sourceMappingURL=subagent-compactor.js.map

package/dist/src/orchestrator/subagent-compactor.spec.js

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { compactSubAgentMessages, cumulativeMessageChars } from "./subagent-compactor.js";
 function bigText(label, kb) {
-    const block = `${label}:` + "x".repeat(kb * 1000);
+    const block = `${label}:${"x".repeat(kb * 1000)}`;
     return block;
 }
 function toolTurn(idx, kb) {
@@ -66,6 +66,12 @@ describe("subagent-compactor: compactSubAgentMessages", () => {
     });
     it("compacts when cumulative chars exceed threshold", () => {
         const msgs = buildHistory(10, 10); // ~100kb of tool output
+        // Neutralize to test pure size-based elision (high-value keep would reduce savings).
+        for (const m of msgs) {
+            if (m.role === "tool" && Array.isArray(m.content)) {
+                m.content[0].toolName = "other_tool";
+            }
+        }
         const before = cumulativeMessageChars(msgs);
         const out = compactSubAgentMessages(msgs);
         const after = cumulativeMessageChars(out);
@@ -88,6 +94,12 @@ describe("subagent-compactor: compactSubAgentMessages", () => {
     });
     it("rewrites older tool-result parts with elision stub", () => {
         const msgs = buildHistory(10, 10);
+        // Neutralize tool so the basic elision test is not affected by high-value auto-keep (idea 1).
+        for (const m of msgs) {
+            if (m.role === "tool" && Array.isArray(m.content)) {
+                m.content[0].toolName = "other_tool";
+            }
+        }
         const out = compactSubAgentMessages(msgs);
         // First tool message is at index 3 (system, user, asst, tool, ...).
         const firstToolMsg = out[3];
@@ -95,7 +107,7 @@ describe("subagent-compactor: compactSubAgentMessages", () => {
         const parts = firstToolMsg.content;
         const tr = parts[0];
         expect(tr.type).toBe("tool-result");
-        expect(tr.output.value).toMatch(/earlier tool_result for tool=read_file/);
+        expect(tr.output.value).toMatch(/earlier tool_result for tool=other_tool/);
         expect(tr.output.value).toMatch(/elided by sub-agent compactor/);
     });
     it("respects custom threshold (no compaction when threshold raised)", () => {
@@ -110,6 +122,12 @@ describe("subagent-compactor: compactSubAgentMessages", () => {
     });
     it("keepLastTurns=0 compacts every tool turn (no trailing window preserved)", () => {
         const msgs = buildHistory(10, 10);
+        // Neutralize so high-value (idea 1) does not override keep=0 for this test's intent.
+        for (const m of msgs) {
+            if (m.role === "tool" && Array.isArray(m.content)) {
+                m.content[0].toolName = "other_tool";
+            }
+        }
         const out = compactSubAgentMessages(msgs, { keepLastTurns: 0 });
         // Every tool message in the output is a compacted stub.
         for (let i = 0; i < out.length; i++) {
@@ -127,5 +145,172 @@ describe("subagent-compactor: compactSubAgentMessages", () => {
         const out = compactSubAgentMessages(msgs, { thresholdChars: 1_000_000 });
         expect(cumulativeMessageChars(out)).toBe(cumulativeMessageChars(msgs));
     });
+    // F2 — envelope counted in threshold
+    it("envelopeChars contributes to threshold check (F2)", () => {
+        const msgs = buildHistory(2, 5); // only ~10kb of messages
+        // Without envelope: well below 80K → no compaction.
+        const noEnv = compactSubAgentMessages(msgs);
+        expect(cumulativeMessageChars(noEnv)).toBe(cumulativeMessageChars(msgs));
+        // With 100K envelope: total > 80K → compactor fires (but only 2 turns
+        // means everything is in the keep window, so still no-op).
+        const withEnvInput = buildHistory(10, 5);
+        for (const m of withEnvInput) {
+            if (m.role === "tool" && Array.isArray(m.content)) {
+                m.content[0].toolName = "other_tool";
+            }
+        }
+        const withEnv = compactSubAgentMessages(withEnvInput, {
+            thresholdChars: 80_000,
+            envelopeChars: 100_000,
+        });
+        // 10 turns × 5kb ≈ 50K + 100K envelope = 150K → fires; older stubs land.
+        let foundStub = false;
+        for (const m of withEnv) {
+            if (m.role !== "tool" || !Array.isArray(m.content))
+                continue;
+            for (const p of m.content) {
+                if (p.type !== "tool-result")
+                    continue;
+                const o = p.output;
+                if (typeof o?.value === "string" && /elided by sub-agent compactor/.test(o.value)) {
+                    foundStub = true;
+                }
+            }
+        }
+        expect(foundStub).toBe(true);
+    });
+    // F1 (revised, A3 cache-stability) — compaction is IDEMPOTENT.
+    //
+    // Previously a second pass super-shrank existing stubs further, mutating
+    // their content every round. In the agentic loop the compactor runs once
+    // per streamText call, so an already-stubbed message changed bytes on every
+    // call → the OpenAI prompt-cache prefix churned (forensics: 0% cache hit on
+    // calls 1-4, only stabilising by call 5). Terminal stubs let the prefix
+    // cache from call 2. The marginal extra shrink is not worth the cache loss.
+    it("is idempotent (fixed point) — compacting twice equals once, keeping the cached prefix stable", () => {
+        const msgs = buildHistory(12, 10);
+        const once = compactSubAgentMessages(msgs);
+        const twice = compactSubAgentMessages(once);
+        expect(twice).toEqual(once);
+    });
+    it("does NOT rewrite an already-written stub on re-compaction (terminal stubs)", () => {
+        const msgs = buildHistory(12, 10);
+        const firstPass = compactSubAgentMessages(msgs);
+        const total = cumulativeMessageChars(firstPass);
+        // Force another pass with a lower threshold; existing stubs must be byte-identical.
+        const secondPass = compactSubAgentMessages(firstPass, { thresholdChars: Math.floor(total / 2) });
+        const stubsOf = (arr) => arr
+            .flatMap((m) => Array.isArray(m.content)
+            ? m.content
+                .filter((p) => p.type === "tool-result")
+                .map((p) => p.output?.value)
+            : [])
+            .filter((v) => typeof v === "string" && /elided by sub-agent compactor/.test(v));
+        // Every stub the first pass produced is present, byte-identical, after re-compaction.
+        for (const s of stubsOf(firstPass)) {
+            expect(stubsOf(secondPass)).toContain(s);
+        }
+    });
+    // G1 — context-window-aware threshold
+    it("contextWindowTokens overrides char threshold to fire earlier (G1)", () => {
+        // 8K window × 0.5 ratio × 4 chars/token = 16K char budget.
+        // Build 30K of messages — char-threshold 80K would NOT fire, but the
+        // tiny window MUST trigger compaction.
+        const msgs = buildHistory(6, 5); // ~30K chars
+        // Neutral tool name so high-value heuristic (idea 1) does not force-keep everything.
+        for (const m of msgs) {
+            if (m.role === "tool" && Array.isArray(m.content)) {
+                m.content[0].toolName = "other_tool";
+            }
+        }
+        const out = compactSubAgentMessages(msgs, {
+            thresholdChars: 80_000, // would normally skip
+            contextWindowTokens: 8_000,
+            contextFillRatio: 0.5,
+        });
+        // Earlier tool results stubbed.
+        let stubbed = 0;
+        for (const m of out) {
+            if (m.role !== "tool" || !Array.isArray(m.content))
+                continue;
+            for (const p of m.content) {
+                if (p.type !== "tool-result")
+                    continue;
+                const o = p.output;
+                if (typeof o?.value === "string" && /elided by sub-agent compactor/.test(o.value)) {
+                    stubbed += 1;
+                }
+            }
+        }
+        expect(stubbed).toBeGreaterThan(0);
+    });
+    // G2 — dynamic keepLastTurns shrinks when context is near full
+    it("shrinks keepLastTurns when context fill ≥ 80% (G2)", () => {
+        // Window 8K, message+envelope chars ≈ 7K tokens × 4 = 28K → 0.875 fill.
+        // keepLastTurns starts at 5; should drop to 1 → more turns get stubbed.
+        const msgs = buildHistory(10, 3); // ~30K chars ≈ 7.5K tokens
+        // Neutral tool so high-value (idea 1) does not interfere with dynamic keepLast count.
+        for (const m of msgs) {
+            if (m.role === "tool" && Array.isArray(m.content)) {
+                m.content[0].toolName = "other_tool";
+            }
+        }
+        const out = compactSubAgentMessages(msgs, {
+            thresholdChars: 10_000,
+            keepLastTurns: 5,
+            contextWindowTokens: 8_000,
+            contextFillRatio: 0.3,
+        });
+        // Count NON-stubbed tool messages (these were kept verbatim).
+        let kept = 0;
+        for (const m of out) {
+            if (m.role !== "tool" || !Array.isArray(m.content))
+                continue;
+            for (const p of m.content) {
+                if (p.type !== "tool-result")
+                    continue;
+                const o = p.output;
+                if (typeof o?.value === "string" && !/elided/.test(o.value)) {
+                    kept += 1;
+                }
+            }
+        }
+        // Effective keepLast was 1 (not 5) → only 1 tool result kept verbatim.
+        expect(kept).toBe(1);
+    });
+    // Idea 1: high-value tool results kept verbatim even when older than keepLast
+    it("keeps high-value tool results (read_file/grep on src + error/PLAN) verbatim (idea 1)", () => {
+        const msgs = buildHistory(8, 4);
+        // Force a high-value marker in an early turn (index ~3-4)
+        const earlyTool = msgs[3];
+        if (earlyTool?.content?.[0]) {
+            earlyTool.content[0].output = { type: "text", value: "PLAN.md\nsrc/index.ts\nerror: critical" };
+        }
+        const out = compactSubAgentMessages(msgs, { thresholdChars: 10_000, keepLastTurns: 2 });
+        // The early high-value one should not be stubbed.
+        const earlyOut = out[3];
+        const val = earlyOut?.content?.[0]?.output?.value || "";
+        expect(val).not.toMatch(/elided by .* compactor/);
+    });
+    // Idea 3: explicit keepToolIds bypasses elision
+    it("respects keepToolIds (idea 3) — specific ids kept even if old", () => {
+        const msgs = buildHistory(6, 5);
+        const targetId = "call_2"; // early turn
+        const out = compactSubAgentMessages(msgs, {
+            thresholdChars: 10_000,
+            keepLastTurns: 1,
+            keepToolIds: [targetId],
+        });
+        let keptExplicit = false;
+        for (const m of out) {
+            if (m.role !== "tool" || !Array.isArray(m.content))
+                continue;
+            const tr = m.content[0];
+            if (tr?.toolCallId === targetId && typeof tr.output?.value === "string" && !/elided/.test(tr.output.value)) {
+                keptExplicit = true;
+            }
+        }
+        expect(keptExplicit).toBe(true);
+    });
 });
 //# sourceMappingURL=subagent-compactor.spec.js.map

package/dist/src/orchestrator/text-tool-call-detector.d.ts

@@ -0,0 +1,61 @@
+/**
+ * src/orchestrator/text-tool-call-detector.ts
+ *
+ * Detect when a model emitted a TOOL CALL as plain assistant TEXT instead of
+ * using the real tool-calling interface. Some models (esp. cheap ones trained
+ * on other agent harnesses — Cline / Roo / Continue dialects) write tool calls
+ * as XML blocks like:
+ *
+ *     <read_file>
+ *       <path>src/app/foo.ts</path>
+ *     </read_file>
+ *
+ * The OpenAI-compatible layer never recognizes these as tool calls, so the SDK
+ * reports finishReason="stop" with this XML as the final answer — the agentic
+ * loop ends, the intended action never runs, and (live: storyflow_ui A/B,
+ * deepseek-v4-flash session 905d564dbde4) the turn is silently wasted, often
+ * leaving a half-finished edit behind. This detector lets the orchestrator
+ * surface the failure instead of returning the broken text as a "final answer".
+ *
+ * Distinct from tool-args-repair.ts, which repairs the `arguments` JSON of a
+ * tool call the SDK ALREADY recognized. Here there is NO recognized tool call.
+ *
+ * Precision is the priority — a false positive would wrongly flag a legitimate
+ * final answer (e.g. documentation that quotes a tool block). The detector only
+ * fires when a KNOWN tool-name tag appears as a structural invocation: an
+ * opening tag immediately followed (whitespace/newlines allowed) by either a
+ * known nested parameter tag or its own closing tag. A bare inline mention
+ * ("use the <read_file> tool") never matches.
+ */
+export interface TextToolCallDetection {
+    detected: boolean;
+    /** The first matched tool/wrapper name, for telemetry. Null when not detected. */
+    tool: string | null;
+}
+/**
+ * Detect a tool call emitted as plain text. Returns the first matching tool
+ * name (or generic wrapper label) for telemetry. High precision: requires a
+ * structural invocation shape, not a bare tag mention.
+ */
+export declare function detectTextEmittedToolCall(text: string): TextToolCallDetection;
+/**
+ * Parse the DeepSeek-native DSML tool-call markup into a structured list so the
+ * re-steer can restate the model's EXACT intent (much more effective than a
+ * generic "use the tool interface" nudge). Pure — no execution. Recognizes:
+ *   <｜｜DSML｜｜invoke name="read_file">
+ *     <｜｜DSML｜｜parameter name="file_path" string="true">src/app/foo.ts</｜｜DSML｜｜parameter>
+ *   </｜｜DSML｜｜invoke>
+ * Returns one entry per invoke block; args preserve insertion order. Tolerant of
+ * missing close tags (cheap models truncate) — captures whatever parameters are
+ * present. Returns [] when no parseable invoke block exists.
+ */
+export interface ParsedDsmlCall {
+    name: string;
+    args: Record<string, string>;
+}
+export declare function parseDsmlToolCalls(text: string): ParsedDsmlCall[];
+export declare const _internals: {
+    TOOL_TAGS: readonly ["read_file", "write_to_file", "write_file", "edit_file", "apply_diff", "replace_in_file", "search_and_replace", "insert_content", "search_files", "list_files", "list_code_definition_names", "execute_command", "run_command", "browser_action", "use_mcp_tool", "access_mcp_resource", "ask_followup_question", "attempt_completion", "bash", "grep", "glob", "read_multiple_files", "delegate", "task"];
+    PARAM_TAGS: string[];
+    GENERIC_WRAPPER_RE: RegExp;
+};