muonroi-cli 1.8.3 → 1.8.5

package/dist/src/orchestrator/sub-agent-cap.js

@@ -18,13 +18,28 @@
  * returns a fresh wrapper with its own counters. Don't share across
  * sub-agent runs.
  *
- * Tiers (default 120_000 chars cumulative ≈ ~30k tokens):
+ * BUDGET SOURCE — do not read the 120_000 below as "the sub-agent budget".
+ * DEFAULT_MAX_CUMULATIVE_CHARS (120_000) is only the fallback used when
+ * wrapToolSetWithCap() is called WITHOUT maxCumulativeChars. The wired
+ * budgets come from settings, not this constant:
+ *   - sub-agent (`task`) turns: getSubAgentBudgetChars() → default 240_000
+ *     (settings.ts), passed at stream-runner.ts.
+ *   - top-level orchestrator turn: getTopLevelToolBudgetChars() → default
+ *     400_000, wired at tool-engine.ts with looser 0.5/0.8 tier ratios.
+ * See docs/agent-harness/CONTEXT-CONTROL-LAYERS.md for how this cap relates
+ * to the other four context-control layers (compactor, rotation, reactive
+ * sub-session, top-level cap).
+ *
+ * Tiers (percentages of whichever budget is in effect, NOT of 120_000):
  *   < 30%   → pass through (A1's 32KB per-call cap already applied)
  *   30-70%  → truncate each new result to 8_000 chars head/tail
  *   70-100% → truncate to 2_000 chars head + "[budget low, finalize work]" note
  *   ≥ 100%  → return error stub that signals the agent to stop expanding scope
  */
 import { createHash } from "node:crypto";
+// Fallback ONLY — used when wrapToolSetWithCap gets no maxCumulativeChars.
+// Real wired budgets are 240_000 (sub-agent) / 400_000 (top-level) from
+// settings; see the header note. Keep this in sync only as the no-arg floor.
 const DEFAULT_MAX_CUMULATIVE_CHARS = 120_000;
 const DEFAULT_DEDUP_MIN_CHARS = 500;
 const DEFAULT_MID_TIER_RATIO = 0.3;

package/dist/src/orchestrator/sub-agent-model-tier.d.ts

@@ -9,5 +9,17 @@ export type TierLookup = (tier: "fast" | "balanced" | "premium", preferProvider?
  * Resolve the model id for a task kind on a given provider. Walks the tier
  * preference list, accepting only same-provider matches, and falls back to
  * `fallbackModelId` (the parent model) when nothing matches.
+ *
+ * `opts.parentTier` (the top-level / parent model's tier) acts as a ceiling:
+ * a delegated sub-task never runs on a HIGHER tier than the parent. Without
+ * this cap, a `verify` sub-agent (prefs `["premium","balanced"]`) spawned from
+ * a flash (fast) parent silently promotes to premium — e.g. on a DeepSeek-only
+ * setup (no balanced model) every verify sub-agent lands on deepseek-v4-pro.
+ * The parent already did the hard thinking; the sub-task should not exceed it.
+ *
+ * The cap is skipped when `parentTier` is omitted (preserves legacy behavior
+ * for callers that have not been threaded yet).
  */
-export declare function resolveModelForTask(task: ModelTaskKind, providerId: string, fallbackModelId: string, lookup?: TierLookup): string;
+export declare function resolveModelForTask(task: ModelTaskKind, providerId: string, fallbackModelId: string, lookup?: TierLookup, opts?: {
+    parentTier?: "fast" | "balanced" | "premium";
+}): string;

package/dist/src/orchestrator/sub-agent-model-tier.js

@@ -16,7 +16,7 @@
  *  - verify          : validation/verification → premium first; rigor matters
  *                      more than cost here, so we do NOT downgrade by default.
  */
-import { getModelByTier } from "../models/registry.js";
+import { getRoutedModelByTier } from "../router/peak-hour.js";
 export const TASK_TIER_PREFS = {
     compact: ["fast", "balanced"],
     title: ["fast", "balanced"],
@@ -29,13 +29,27 @@ export const TASK_TIER_PREFS = {
     // exists to perform. Mirrors council `verify` role preference.
     verify: ["premium", "balanced"],
 };
+const TIER_RANK = { fast: 0, balanced: 1, premium: 2 };
 /**
  * Resolve the model id for a task kind on a given provider. Walks the tier
  * preference list, accepting only same-provider matches, and falls back to
  * `fallbackModelId` (the parent model) when nothing matches.
+ *
+ * `opts.parentTier` (the top-level / parent model's tier) acts as a ceiling:
+ * a delegated sub-task never runs on a HIGHER tier than the parent. Without
+ * this cap, a `verify` sub-agent (prefs `["premium","balanced"]`) spawned from
+ * a flash (fast) parent silently promotes to premium — e.g. on a DeepSeek-only
+ * setup (no balanced model) every verify sub-agent lands on deepseek-v4-pro.
+ * The parent already did the hard thinking; the sub-task should not exceed it.
+ *
+ * The cap is skipped when `parentTier` is omitted (preserves legacy behavior
+ * for callers that have not been threaded yet).
  */
-export function resolveModelForTask(task, providerId, fallbackModelId, lookup = getModelByTier) {
+export function resolveModelForTask(task, providerId, fallbackModelId, lookup = getRoutedModelByTier, opts) {
+    const ceilingRank = opts?.parentTier ? TIER_RANK[opts.parentTier] : undefined;
     for (const tier of TASK_TIER_PREFS[task] ?? ["balanced"]) {
+        if (ceilingRank !== undefined && TIER_RANK[tier] > ceilingRank)
+            continue;
         const m = lookup(tier, providerId);
         if (m?.provider === providerId)
             return m.id;

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

@@ -95,7 +95,7 @@ export interface SubAgentCompactorOptions {
      * 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;
+    persistArtifact?: (toolCallId: string, toolName: string, fullContent: string, reason: string, summary?: string) => void;
     /**
      * T1.1 — strip reasoning parts from old assistant turns (older than
      * keepLastTurns). Reasoning tokens (CoT / <think>) from prior turns are
@@ -104,6 +104,18 @@ export interface SubAgentCompactorOptions {
      * models, false otherwise.
      */
     stripOldReasoning?: boolean;
+    /**
+     * O2 — max cumulative chars of the verbatim tail (the last keepLastTurns
+     * turns). The G2 shrink is FILL-ratio based, so on a large-context model a
+     * read-heavy tail (five 8-30k tool results) stays verbatim at only ~50%
+     * fill — pinning every tool round at 60-80k input (measured: July-8 message
+     * calls, 83 in the 60-80k bucket = 44% of message-fresh). When set, keepLast
+     * is reduced further (floor 2) until the kept tail fits this budget,
+     * regardless of fill ratio. High-value results (isHighValueToolResult) are
+     * still kept verbatim independently, so only bulk dumps get stubbed.
+     * Undefined = off (sub-agent path unchanged).
+     */
+    tailBudgetChars?: number;
 }
 /**
  * G1 — coarse char→token conversion. The real ratio is provider/tokenizer
@@ -136,6 +148,7 @@ export declare const HIGH_VALUE_MCP_PREFIXES: readonly ["mcp_muonroi-docs__"];
  */
 export declare function isHighValueToolResult(toolName: string, preview: string, explicitKeepIds?: Set<string>, toolCallId?: string): boolean;
 export declare function cumulativeMessageChars(messages: ReadonlyArray<ModelMessage>): number;
+export declare function buildSlimContext(msgs: ModelMessage[]): ModelMessage[];
 /**
  * Compact a sub-agent message array in place-like fashion. The input is never
  * mutated. When compaction actually elides something a NEW array is returned.
@@ -148,6 +161,45 @@ export declare function cumulativeMessageChars(messages: ReadonlyArray<ModelMess
  * step.
  */
 export declare function compactSubAgentMessages(messages: ReadonlyArray<ModelMessage>, opts?: SubAgentCompactorOptions): ModelMessage[];
+/**
+ * O3 — compaction hysteresis state, threaded across `prepareStep` calls within
+ * a single top-level turn. `frozenCompacted` is the compacted history captured
+ * at the last real compaction; `frozenStrippedLen` is the message count of the
+ * (un-compacted) history at that moment, so the append delta can be recovered.
+ */
+export interface CompactionHysteresisState {
+    frozenCompacted: ModelMessage[] | null;
+    frozenStrippedLen: number;
+    lastCompactTriggerChars: number;
+}
+export declare function initCompactionHysteresisState(): CompactionHysteresisState;
+/**
+ * Decide whether to hold the frozen compacted prefix or (re)compact.
+ *
+ * Re-running the compactor on every step slides the keepLast boundary forward
+ * one tool result per step, flipping that result verbatim→stub and breaking the
+ * provider prompt-cache prefix at its position — measured as 63% of a real
+ * session's FRESH input (session 1afb2728e67a). Between compactions we instead
+ * reuse the frozen compacted prefix and append only the messages added since
+ * (history is append-only within a turn), keeping the cached prefix byte-stable
+ * until cumulative size grows past `lastCompactTriggerChars * hysteresis`.
+ *
+ * Pure: returns the next state rather than mutating. `hysteresis <= 1.0`
+ * disables the freeze (legacy per-step compaction). The delta slice uses the
+ * ORIGINAL (pre-compaction) length, so it is correct whether or not the
+ * compactor preserves message count.
+ */
+export declare function applyCompactionHysteresis(args: {
+    stripped: ModelMessage[];
+    currChars: number;
+    hysteresis: number;
+    state: CompactionHysteresisState;
+    runCompaction: () => ModelMessage[];
+}): {
+    compacted: ModelMessage[];
+    didRecompact: boolean;
+    state: CompactionHysteresisState;
+};
 /**
  * Injects Anthropic prompt caching (cacheControl) into the last message's content
  * block(s) if the model is Claude (starts with 'claude').

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

@@ -47,6 +47,9 @@
  *   MUONROI_SUBAGENT_COMPACT_THRESHOLD_CHARS — 20_000..500_000, default 80_000
  *   MUONROI_SUBAGENT_COMPACT_KEEP_LAST       — 1..20,           default 3
  */
+/** O2 — floor for the tail-budget keepLast shrink; never break the live step's
+ * assistant↔tool pairing (that needs at least the current turn). */
+const TAIL_BUDGET_MIN_KEEP = 2;
 /**
  * G1 — coarse char→token conversion. The real ratio is provider/tokenizer
  * specific (cl100k ≈ 3.5-4 chars/token for English code-heavy content, more
@@ -96,6 +99,10 @@ export function isHighValueToolResult(toolName, preview, explicitKeepIds, toolCa
     // work/findings. Truncating it causes the agent to think it lost its answer.
     if (name.startsWith("respond_"))
         return true;
+    // Plan context bias (user-halt + "tiếp tục" resume): keep plan text verbatim so
+    // compaction does not drop the APPROVED PLAN the user just approved.
+    if (/APPROVED PLAN|plan v|khuyến nghị hành động|sprint plan|work plan/i.test(preview))
+        return true;
     // Authoritative ecosystem-docs MCP results: the agent is nudged to fetch these
     // FIRST, so eliding them strands it (session 584ba476c07a). Keep verbatim.
     if (HIGH_VALUE_MCP_PREFIXES.some((p) => name.startsWith(p)))
@@ -128,8 +135,31 @@ function resolveOpts(o) {
         keepToolIds: keepIds,
         persistArtifact: o?.persistArtifact,
         stripOldReasoning: o?.stripOldReasoning ?? false,
+        tailBudgetChars: Math.max(0, o?.tailBudgetChars ?? 0),
     };
 }
+/**
+ * O2 — given the fill-ratio-derived keepLast, shrink it further so the kept
+ * verbatim tail (the last N tool turns) fits `tailBudgetChars`. Walks keepLast
+ * down from its input value, measuring the actual chars of the tail each step,
+ * and stops at the first count that fits (or the TAIL_BUDGET_MIN_KEEP floor).
+ * Off (returns keepLast unchanged) when tailBudgetChars <= 0.
+ */
+function shrinkKeepLastToTailBudget(messages, keepLast, tailBudgetChars) {
+    if (tailBudgetChars <= 0 || keepLast <= TAIL_BUDGET_MIN_KEEP)
+        return keepLast;
+    let k = keepLast;
+    while (k > TAIL_BUDGET_MIN_KEEP) {
+        const keepFrom = findKeepFromIndex(messages, k);
+        let tailChars = 0;
+        for (let i = keepFrom; i < messages.length; i++)
+            tailChars += messageChars(messages[i]);
+        if (tailChars <= tailBudgetChars)
+            return k;
+        k -= 1;
+    }
+    return TAIL_BUDGET_MIN_KEEP;
+}
 /**
  * G1 + G2 — compute effective threshold (chars) and dynamic keepLastTurns
  * based on context-window utilization. When the prompt approaches the
@@ -276,6 +306,36 @@ function isStubbedToolResult(msg) {
     }
     return false;
 }
+function generateShortSummary(toolName, content) {
+    if (content.length < 500)
+        return `${toolName}: ${content.length} chars`;
+    const clean = content.trim().replace(/\s+/g, " ");
+    if (!clean)
+        return `Empty ${toolName} output`;
+    const fileMatch = content.match(/File Path: `file:\/\/\/(.+?)`/);
+    if (fileMatch) {
+        const parts = fileMatch[1].split(/[/\\]/);
+        const filename = parts[parts.length - 1];
+        return `Read ${filename} (${clean.length} chars)`;
+    }
+    const grepMatch = content.match(/"LineContent"/);
+    if (grepMatch) {
+        try {
+            const lines = content.trim().split("\n");
+            let count = 0;
+            for (const line of lines) {
+                if (line.includes(`"LineContent"`))
+                    count++;
+            }
+            return `Grep found ${count} matches`;
+        }
+        catch {
+            // fallback
+        }
+    }
+    const excerpt = clean.slice(0, 60);
+    return `${toolName}: ${excerpt}${clean.length > 60 ? "..." : ""}`;
+}
 function rewriteOlderToolMessage(msg, previewChars, label, keepToolIds, persistArtifact) {
     if (!isToolResultMessage(msg) || !Array.isArray(msg.content))
         return msg;
@@ -292,10 +352,11 @@ function rewriteOlderToolMessage(msg, previewChars, label, keepToolIds, persistA
         }
         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}]`;
+        const summary = generateShortSummary(tr.toolName, rawPreview);
         // 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");
+                persistArtifact(toolCallId, tr.toolName, rawPreview, "elided-by-compactor", summary);
             }
             catch {
                 /* fail-open */
@@ -312,6 +373,9 @@ function rewriteOlderToolMessage(msg, previewChars, label, keepToolIds, persistA
     // dragging in the full provider-utils type graph at this layer.
     return { ...msg, content: rewritten };
 }
+export function buildSlimContext(msgs) {
+    return msgs.slice(-6); // goal + last 2 turns + refs (YAGNI)
+}
 /**
  * Compact a sub-agent message array in place-like fashion. The input is never
  * mutated. When compaction actually elides something a NEW array is returned.
@@ -326,25 +390,31 @@ function rewriteOlderToolMessage(msg, previewChars, label, keepToolIds, persistA
 export function compactSubAgentMessages(messages, opts = {}) {
     const resolved = resolveOpts(opts);
     const { outputPreviewChars, label, envelopeChars } = resolved;
-    // Step 4: Hard-limit message history sent to the model to prevent token bloating
-    // When input (messages + envelope) exceeds 50K characters and messages array is > 30,
-    // we slice the history to keep at most 30 messages (preserving system and user start).
-    let processedMessages = messages;
     const messagesTotal = cumulativeMessageChars(messages);
     const total = messagesTotal + envelopeChars;
-    if (total > 50_000 && messages.length > 30) {
+    const { effectiveThresholdChars, effectiveKeepLastTurns } = computeDynamicParams(total, resolved);
+    // No-op: return the input BY REFERENCE (contract above) so `compacted === input`.
+    // Identity contract: callers (tool-engine.ts, stream-runner.ts) use
+    // `compacted !== stripped` to decide whether to fire recordCompaction. A false
+    // identity change (new array with zero elision) produces phantom compaction
+    // records — observed as 28 compactions / 0 elisions in session c43cc481a16e.
+    // Fix: check threshold on the ORIGINAL total before slicing.
+    if (total < effectiveThresholdChars)
+        return messages;
+    // Step 4: Hard-limit message history sent to the model to prevent token bloating.
+    // Only slice when compaction is actually warranted (threshold exceeded), so the
+    // slice's identity change pairs with real content reduction, not a phantom no-op.
+    let processedMessages = messages;
+    if (messages.length > 30) {
         processedMessages = sliceMessageHistory(messages, 30);
     }
-    // Calculate effective thresholds and keep last turns using the processed messages
-    const processedMessagesTotal = cumulativeMessageChars(processedMessages);
-    const processedTotal = processedMessagesTotal + envelopeChars;
-    const { effectiveThresholdChars, effectiveKeepLastTurns } = computeDynamicParams(processedTotal, resolved);
-    // No-op: return the input BY REFERENCE (contract above) so `compacted === input`.
-    if (processedTotal < effectiveThresholdChars)
-        return processedMessages;
-    const keepFrom = findKeepFromIndex(processedMessages, effectiveKeepLastTurns);
+    // O2 — after the fill-ratio shrink, further reduce keepLast so the verbatim
+    // tail fits the byte budget (targets read-heavy tails that stay large at low
+    // fill). No-op when tailBudgetChars is unset (sub-agent path).
+    const budgetedKeepLast = shrinkKeepLastToTailBudget(processedMessages, effectiveKeepLastTurns, resolved.tailBudgetChars);
+    const keepFrom = findKeepFromIndex(processedMessages, budgetedKeepLast);
     if (keepFrom <= 0)
-        return processedMessages;
+        return messages;
     // 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
@@ -455,6 +525,47 @@ function stripAssistantToolCallArgs(msg) {
         return msg;
     return { ...msg, content: next };
 }
+export function initCompactionHysteresisState() {
+    return { frozenCompacted: null, frozenStrippedLen: 0, lastCompactTriggerChars: 0 };
+}
+/**
+ * Decide whether to hold the frozen compacted prefix or (re)compact.
+ *
+ * Re-running the compactor on every step slides the keepLast boundary forward
+ * one tool result per step, flipping that result verbatim→stub and breaking the
+ * provider prompt-cache prefix at its position — measured as 63% of a real
+ * session's FRESH input (session 1afb2728e67a). Between compactions we instead
+ * reuse the frozen compacted prefix and append only the messages added since
+ * (history is append-only within a turn), keeping the cached prefix byte-stable
+ * until cumulative size grows past `lastCompactTriggerChars * hysteresis`.
+ *
+ * Pure: returns the next state rather than mutating. `hysteresis <= 1.0`
+ * disables the freeze (legacy per-step compaction). The delta slice uses the
+ * ORIGINAL (pre-compaction) length, so it is correct whether or not the
+ * compactor preserves message count.
+ */
+export function applyCompactionHysteresis(args) {
+    const { stripped, currChars, hysteresis, state, runCompaction } = args;
+    if (hysteresis > 1.0 && state.frozenCompacted !== null && currChars <= state.lastCompactTriggerChars * hysteresis) {
+        const delta = stripped.slice(state.frozenStrippedLen);
+        const compacted = delta.length > 0 ? [...state.frozenCompacted, ...delta] : state.frozenCompacted;
+        return { compacted, didRecompact: false, state };
+    }
+    const compacted = runCompaction();
+    const changed = compacted !== stripped;
+    if (changed && hysteresis > 1.0) {
+        return {
+            compacted,
+            didRecompact: true,
+            state: {
+                frozenCompacted: compacted,
+                frozenStrippedLen: stripped.length,
+                lastCompactTriggerChars: currChars,
+            },
+        };
+    }
+    return { compacted, didRecompact: changed, state };
+}
 /**
  * Injects Anthropic prompt caching (cacheControl) into the last message's content
  * block(s) if the model is Claude (starts with 'claude').

package/dist/src/orchestrator/tool-engine.d.ts

@@ -13,6 +13,27 @@ import type { PendingCallsLog } from "./pending-calls.js";
 import type { ReadPathBudget } from "./read-path-budget.js";
 import type { SafetyOverrideAskInfo, SafetyOverrideVerdict } from "./safety-askcard.js";
 import { type ToolLoopCapAsk } from "./tool-loop-cap.js";
+/**
+ * Resolve the per-turn `maxOutputTokens` budget.
+ *
+ * Normally the budget is derived from the PIL-classified `taskType`
+ * (`taskTypeToMaxTokens`). But a sprint IMPLEMENTATION turn — the /ideal
+ * loop's handoff into the host orchestrator via `processMessageFn`, marked
+ * with `SPRINT_EXECUTION_MARKER` — is a KNOWN code-writing task that must not
+ * be starved by a noisy classify. Observed live (2026-07-10, gsd-core
+ * migration): the impl prompt was classified `analyze`/default → capped at
+ * 4_096 output → the model spent the whole budget narrating its plan, hit
+ * `finishReason:"length"` mid-word, produced ZERO code, and the turn wedged.
+ *
+ * Fix: for a sprint-execution turn, floor the budget at the build/generate
+ * tier (12_288) regardless of the classified type. Scoped to the marker only
+ * (NOT the broad `isImplementationIntent`) so ordinary refactor/debug turns
+ * keep their intentionally tighter L6 budgets.
+ */
+export declare function resolveTurnMaxOutputTokens(pilCtx: {
+    taskType: string | null;
+    raw?: string;
+}): number;
 import type { TurnRunnerDepsBase } from "./turn-runner-deps.js";
 /**
  * Dependency surface the MessageProcessor needs to reach back into Agent
@@ -147,7 +168,12 @@ export declare function rewriteSafetyApprovedToolResults<T extends {
     role: string;
     content?: any;
 }>(messages: T[]): T[];
+export declare class SimpleMutex {
+    private queue;
+    run<T>(fn: () => Promise<T> | T): Promise<T>;
+}
 export interface ToolEngineArgs {
     [key: string]: any;
 }
 export declare function executeToolEngine(args: ToolEngineArgs): AsyncGenerator<StreamChunk, void, unknown>;
+export declare function coalesceReadOnlyMessages(messages: any[]): any[];