muonroi-cli 1.8.4 → 1.9.0

package/dist/src/models/registry.d.ts

@@ -1,22 +1,37 @@
+import type { ProviderId } from "../providers/types.js";
 import type { ModelInfo, ReasoningEffort } from "../types/index.js";
+import type { CatalogCouncilRouting, CatalogProviderPeakHour, CatalogVisionProxyRouting } from "./catalog-client.js";
 export declare let MODELS: ModelInfo[];
 export declare let isLoading: boolean;
+export declare let SWITCH_PROVIDER_ORDER: readonly ProviderId[];
 /**
- * Load models from centralized catalog (CP endpoint with static fallback).
- * Called once at boot. No provider API keys needed.
+ * Load models + routing policies from centralized catalog (API with static fallback).
  */
 export declare function loadCatalog(): Promise<void>;
+export declare function getProviderPeakHourRule(providerId: string): CatalogProviderPeakHour | undefined;
+/** Catalog-defined default council lineup (multi-provider debate slots). */
+export declare function getCatalogCouncilRouting(): CatalogCouncilRouting | undefined;
+export declare function getVisionProxyRouting(): CatalogVisionProxyRouting | undefined;
 export declare function getModelIds(): string[];
 export declare function getModelInfo(idOrAlias: string): ModelInfo | undefined;
 export declare function normalizeModelId(idOrAlias: string): string;
 export declare function getEffectiveReasoningEffort(modelId: string, requestedEffort: ReasoningEffort | undefined): ReasoningEffort | undefined;
+/** Returns true if the resolved model has built-in reasoning / extended thinking. */
+export declare function isReasoningModel(modelId: string): boolean;
 export declare function getSupportedReasoningEfforts(modelId: string): ReasoningEffort[];
-/**
- * Pick the first model matching a tier for a given provider.
- * If no match for provider+tier, returns first model of that tier from any provider.
- * Returns undefined if no models in that tier exist.
- */
 export declare function getModelByTier(tier: "fast" | "balanced" | "premium", preferProvider?: string): ModelInfo | undefined;
 export declare function getModelsForProvider(providerId: string): ModelInfo[];
+/**
+ * Part E — does this model have NATIVE online web research (its own
+ * web_search/browsing/Live-Search)? Missing flag → false (safe default per the
+ * Kill #6 rule: never infer web capability from the provider).
+ */
+export declare function modelHasNativeWebResearch(idOrAlias: string): boolean;
+/**
+ * First catalog model with native web research (optionally constrained to a set
+ * of reachable model ids). Used by the council research phase to route the
+ * Researcher stance to a web-capable model. Returns undefined when none exist.
+ */
+export declare function getWebResearchModel(reachableIds?: ReadonlySet<string>): ModelInfo | undefined;
 export declare function getFirstCatalogModel(): ModelInfo;
 export declare function getFirstCatalogProvider(): string;

package/dist/src/models/registry.js

@@ -1,19 +1,33 @@
-import { catalogModelToModelInfo, fetchCatalog } from "./catalog-client.js";
+import { catalogModelToModelInfo, fetchCatalogDocument } from "./catalog-client.js";
 const ALL_REASONING_EFFORTS = ["low", "medium", "high", "xhigh"];
+const DEFAULT_SWITCH_PROVIDER_ORDER = ["deepseek", "zai", "opencode-go", "xai"];
 // ---------------------------------------------------------------------------
 // Centralized model registry — populated by loadCatalog() at boot
 // ---------------------------------------------------------------------------
 export let MODELS = [];
 export let isLoading = true;
+export let SWITCH_PROVIDER_ORDER = DEFAULT_SWITCH_PROVIDER_ORDER;
+const providerPeakHourRules = new Map();
+let catalogCouncilRouting;
+let catalogVisionProxyRouting;
 /**
- * Load models from centralized catalog (CP endpoint with static fallback).
- * Called once at boot. No provider API keys needed.
+ * Load models + routing policies from centralized catalog (API with static fallback).
  */
 export async function loadCatalog() {
     isLoading = true;
     try {
-        const catalog = await fetchCatalog();
-        MODELS = catalog.map(catalogModelToModelInfo);
+        const doc = await fetchCatalogDocument();
+        MODELS = doc.models.map(catalogModelToModelInfo);
+        SWITCH_PROVIDER_ORDER = doc.routing?.switch_provider_order ?? [
+            ...DEFAULT_SWITCH_PROVIDER_ORDER,
+        ];
+        providerPeakHourRules.clear();
+        for (const [providerId, policy] of Object.entries(doc.provider_policies ?? {})) {
+            if (policy.peak_hour)
+                providerPeakHourRules.set(providerId, policy.peak_hour);
+        }
+        catalogCouncilRouting = doc.routing?.council;
+        catalogVisionProxyRouting = doc.routing?.vision_proxy;
     }
     catch {
         // On total failure, MODELS stays empty — callers must handle
@@ -22,6 +36,16 @@ export async function loadCatalog() {
         isLoading = false;
     }
 }
+export function getProviderPeakHourRule(providerId) {
+    return providerPeakHourRules.get(providerId);
+}
+/** Catalog-defined default council lineup (multi-provider debate slots). */
+export function getCatalogCouncilRouting() {
+    return catalogCouncilRouting;
+}
+export function getVisionProxyRouting() {
+    return catalogVisionProxyRouting;
+}
 // ---------------------------------------------------------------------------
 // Lookup helpers
 // ---------------------------------------------------------------------------
@@ -29,7 +53,22 @@ export function getModelIds() {
     return MODELS.map((m) => m.id);
 }
 export function getModelInfo(idOrAlias) {
-    return MODELS.find((m) => m.id === idOrAlias || m.aliases?.includes(idOrAlias));
+    const direct = MODELS.find((m) => m.id === idOrAlias || m.aliases?.includes(idOrAlias));
+    if (direct)
+        return direct;
+    // Gateway-prefix fallback: some routers/persisted configs prefix the model
+    // id with the gateway they came through (e.g. "opencode/deepseek-v4-flash",
+    // "deepseek-ai/DeepSeek-V4-Flash"). The native provider API rejects the
+    // prefixed form. Retry with the last path segment so the canonical catalog
+    // entry (and its provider) still resolves instead of leaking a dead id to
+    // runtime. Only matches when the stripped segment is a real catalog id/alias,
+    // so a non-catalog id still returns undefined (no false positives).
+    const slash = idOrAlias.lastIndexOf("/");
+    if (slash >= 0 && slash < idOrAlias.length - 1) {
+        const tail = idOrAlias.slice(slash + 1);
+        return MODELS.find((m) => m.id === tail || m.aliases?.includes(tail));
+    }
+    return undefined;
 }
 export function normalizeModelId(idOrAlias) {
     const m = getModelInfo(idOrAlias);
@@ -43,6 +82,10 @@ export function getEffectiveReasoningEffort(modelId, requestedEffort) {
         return undefined;
     return requestedEffort;
 }
+/** Returns true if the resolved model has built-in reasoning / extended thinking. */
+export function isReasoningModel(modelId) {
+    return getModelInfo(modelId)?.reasoning ?? false;
+}
 export function getSupportedReasoningEfforts(modelId) {
     const info = getModelInfo(modelId);
     if (!info?.reasoning)
@@ -54,17 +97,37 @@ export function getSupportedReasoningEfforts(modelId) {
  * If no match for provider+tier, returns first model of that tier from any provider.
  * Returns undefined if no models in that tier exist.
  */
+function isTierRoutable(m) {
+    return m.tierRouting !== false;
+}
+function matchesTier(m, tier) {
+    return m.tier === tier || m.routingTiers?.includes(tier) === true;
+}
 export function getModelByTier(tier, preferProvider) {
     if (preferProvider) {
-        const providerMatch = MODELS.find((m) => m.tier === tier && m.provider === preferProvider);
-        if (providerMatch)
-            return providerMatch;
+        return MODELS.find((m) => matchesTier(m, tier) && m.provider === preferProvider && isTierRoutable(m));
     }
-    return MODELS.find((m) => m.tier === tier);
+    return MODELS.find((m) => matchesTier(m, tier) && isTierRoutable(m));
 }
 export function getModelsForProvider(providerId) {
     return MODELS.filter((m) => m.provider === providerId);
 }
+/**
+ * Part E — does this model have NATIVE online web research (its own
+ * web_search/browsing/Live-Search)? Missing flag → false (safe default per the
+ * Kill #6 rule: never infer web capability from the provider).
+ */
+export function modelHasNativeWebResearch(idOrAlias) {
+    return getModelInfo(idOrAlias)?.nativeWebResearch === true;
+}
+/**
+ * First catalog model with native web research (optionally constrained to a set
+ * of reachable model ids). Used by the council research phase to route the
+ * Researcher stance to a web-capable model. Returns undefined when none exist.
+ */
+export function getWebResearchModel(reachableIds) {
+    return MODELS.find((m) => m.nativeWebResearch === true && isTierRoutable(m) && (!reachableIds || reachableIds.has(m.id)));
+}
 export function getFirstCatalogModel() {
     const m = MODELS.find(() => true);
     if (!m)

package/dist/src/ops/doctor.js

@@ -132,7 +132,7 @@ async function checkEEDetailed() {
         // that contradicts a live ee_query working. See VERIFY F9.
         if (!serverOk) {
             const hint = result.mode === "thin-client"
-                ? "Hint: check VPS 72.61.127.154:8082 is reachable; verify ~/.experience/config.json serverBaseUrl + serverReadAuthToken"
+                ? "Hint: check VPS experience.muonroi.com is reachable; verify ~/.experience/config.json serverBaseUrl + serverReadAuthToken"
                 : "Hint: start EE locally or configure thin-client in ~/.experience/config.json";
             return {
                 name: "ee.health",

package/dist/src/orchestrator/ask-user.d.ts

@@ -0,0 +1,61 @@
+/**
+ * src/orchestrator/ask-user.ts
+ *
+ * Types + pure helpers for the model-callable `ask_user` tool.
+ *
+ * The agent calls `ask_user` from its OWN intent — typically after a
+ * `convene_council` conclusion, when it is in an implementation discussion and
+ * wants the human's go/no-go before building. Per the hard no-hardcode
+ * directive, the CLI does NOT synthesise the option set or decide the branch:
+ * the question, options, and default ALL come from the agent's tool input. The
+ * CLI only renders the card and returns the human's answer AS the tool result
+ * string; the agent decides what to do next.
+ *
+ * This mirrors the blocking safety-override askcard plumbing
+ * (setSafetyOverrideHandler → resolver ref-map → answer/cancel drain) but the
+ * card content is agent-supplied, never CLI-built.
+ */
+import type { CouncilQuestionData } from "../types/index.js";
+/** One agent-supplied choice. `value` defaults to `label` when omitted. */
+export interface AskUserOption {
+    label: string;
+    description?: string;
+    value?: string;
+}
+/** The agent's request payload (validated from the tool input). */
+export interface AskUserAskInfo {
+    /** The question to put to the human. Required. */
+    question: string;
+    /** Optional short context/detail shown under the question. */
+    context?: string;
+    /**
+     * Agent-supplied choices. When empty/omitted the card is a free-text prompt.
+     * The CLI NEVER injects its own options.
+     */
+    options?: AskUserOption[];
+    /**
+     * Agent-supplied default selection index into `options`. Clamped into range;
+     * defaults to a neutral 0 (the agent's FIRST option) — index 0 is NOT a CLI
+     * recommendation, just first-listed.
+     */
+    defaultIndex?: number;
+}
+/** Sentinel returned to the agent when the human dismisses the card (Esc). */
+export declare const ASK_USER_DISMISSED = "(the user dismissed the question without answering)";
+/**
+ * Resolve the agent-facing answer string for a chosen option index (or free
+ * text). Returns the option's `value` (falling back to its `label`), the raw
+ * free-text, or the dismissed sentinel. This is the value the AI-SDK
+ * `execute()` returns — the agent reads it and decides the follow-up.
+ */
+export declare function resolveAskUserAnswer(info: AskUserAskInfo, choice: {
+    index?: number;
+    text?: string;
+    cancelled?: boolean;
+}): string;
+/**
+ * Build the CouncilQuestionData card from the agent's request. Options come
+ * ONLY from `info.options`; with none, the card is a single free-text field.
+ * `defaultIndex` is clamped into range (neutral 0 otherwise).
+ */
+export declare function buildAskUserQuestion(info: AskUserAskInfo, questionId: string): CouncilQuestionData;

package/dist/src/orchestrator/ask-user.js

@@ -0,0 +1,65 @@
+/**
+ * src/orchestrator/ask-user.ts
+ *
+ * Types + pure helpers for the model-callable `ask_user` tool.
+ *
+ * The agent calls `ask_user` from its OWN intent — typically after a
+ * `convene_council` conclusion, when it is in an implementation discussion and
+ * wants the human's go/no-go before building. Per the hard no-hardcode
+ * directive, the CLI does NOT synthesise the option set or decide the branch:
+ * the question, options, and default ALL come from the agent's tool input. The
+ * CLI only renders the card and returns the human's answer AS the tool result
+ * string; the agent decides what to do next.
+ *
+ * This mirrors the blocking safety-override askcard plumbing
+ * (setSafetyOverrideHandler → resolver ref-map → answer/cancel drain) but the
+ * card content is agent-supplied, never CLI-built.
+ */
+/** Sentinel returned to the agent when the human dismisses the card (Esc). */
+export const ASK_USER_DISMISSED = "(the user dismissed the question without answering)";
+/**
+ * Resolve the agent-facing answer string for a chosen option index (or free
+ * text). Returns the option's `value` (falling back to its `label`), the raw
+ * free-text, or the dismissed sentinel. This is the value the AI-SDK
+ * `execute()` returns — the agent reads it and decides the follow-up.
+ */
+export function resolveAskUserAnswer(info, choice) {
+    if (choice.cancelled)
+        return ASK_USER_DISMISSED;
+    if (typeof choice.text === "string" && choice.text.length > 0)
+        return choice.text;
+    const opts = info.options ?? [];
+    if (typeof choice.index === "number" && choice.index >= 0 && choice.index < opts.length) {
+        const opt = opts[choice.index];
+        return opt.value ?? opt.label;
+    }
+    return ASK_USER_DISMISSED;
+}
+/**
+ * Build the CouncilQuestionData card from the agent's request. Options come
+ * ONLY from `info.options`; with none, the card is a single free-text field.
+ * `defaultIndex` is clamped into range (neutral 0 otherwise).
+ */
+export function buildAskUserQuestion(info, questionId) {
+    const rawOptions = info.options ?? [];
+    const options = rawOptions.map((o) => ({
+        label: o.label,
+        value: o.value ?? o.label,
+        kind: "choice",
+        description: o.description,
+    }));
+    const hasOptions = options.length > 0;
+    const clampedDefault = hasOptions ? Math.min(Math.max(0, info.defaultIndex ?? 0), options.length - 1) : 0;
+    return {
+        questionId,
+        question: info.question,
+        context: info.context,
+        isRequired: true,
+        phase: "ask-user",
+        // No options → a free-text prompt (single freetext field); otherwise the
+        // agent-supplied choices, verbatim.
+        options: hasOptions ? options : [{ label: "Your answer", value: "", kind: "freetext" }],
+        defaultIndex: clampedDefault,
+    };
+}
+//# sourceMappingURL=ask-user.js.map

package/dist/src/orchestrator/auto-commit.js

@@ -21,9 +21,9 @@
  * cannot inject shell commands.
  */
 import { execFile } from "node:child_process";
-import { logger } from "../utils/logger.js";
 import { resolve } from "node:path";
 import { promisify } from "node:util";
+import { logger } from "../utils/logger.js";
 const pexecFile = promisify(execFile);
 /** Attribution line every auto-commit message ends with (mirrors the prompt rule). */
 export const AUTO_COMMIT_ATTRIBUTION = "Coding by - Muonroi-CLI";

package/dist/src/orchestrator/batch-turn-runner.js

@@ -133,7 +133,7 @@ export class BatchTurnRunner {
                     const batchRequestId = `turn-${Date.now()}-${stepNumber}`;
                     // Phase O1 — capture providerOptions SHAPE for batch path too.
                     deps.setLastProviderOptionsShape(extractProviderOptionsShape(runtime.providerOptions));
-                    const _messagesForCall = deps.messages.map((m) => (m === args.userModelMessage ? args.userEnrichedMessage : m));
+                    const _messagesForCall = deps.messages.map((m) => m === args.userModelMessage ? args.userEnrichedMessage : m);
                     await addBatchRequests({
                         ...deps.getBatchClientOptions(signal),
                         batchId: batch.batch_id,
@@ -145,7 +145,7 @@ export class BatchTurnRunner {
                                         modelId: runtime.modelId,
                                         system,
                                         messages: [..._messagesForCall, ...turnMessages],
-                                        temperature: 0.7,
+                                        temperature: runtime.modelInfo?.fixedTemperature ?? 0.7,
                                         maxOutputTokens: !batchCaps.acceptsParam("maxOutputTokens", runtime.modelInfo)
                                             ? undefined
                                             : deps.maxTokens,

package/dist/src/orchestrator/cache-prefix.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Non-Claude prompt-cache prefix stability (Task 3).
+ *
+ * On non-Claude providers (DeepSeek / GLM / other OpenAI-compatible backends)
+ * the whole system prompt is sent as a single string. Any per-turn-varying
+ * content that sits AFTER the byte-stable `staticPrefix` but BEFORE the
+ * conversation — the `dynamicSuffix` (plan / resume / cwd), the PIL output
+ * suffix, and the live MCP capability roster — shifts the cached prefix and
+ * forces a full cache miss on PIL-active turns. Measured: `pil_active=1` ⟺
+ * `cache_read=0` on 12/12 calls (session `47a774d272da`).
+ *
+ * Fix (variant b): split the assembled system string at the END of
+ * `staticPrefix`. The front stays as the `system` string; the dynamic tail is
+ * relocated into the trailing user message (see `foldDynamicTailIntoUserMessage`)
+ * rather than emitted as a mid-conversation system-role message, because
+ * OpenAI-compatible providers do not reliably accept a non-leading system role.
+ *
+ * IMPORTANT fast-tier caveat: for fast-tier models the cheap-model workbook /
+ * playbook / shell directive are front-loaded BEFORE `staticPrefix` for primacy,
+ * and the workbook's task addendum covaries with `taskType` (== `pil_active`).
+ * That portion still shifts the prefix and is a deliberate primacy design, so
+ * this split does NOT relocate it — the front is fully byte-stable only for
+ * non-fast-tier non-Claude models (the expensive-model path, which is where the
+ * cache payoff is per the plan). See task-3-report.md for the residual analysis.
+ *
+ * The Claude path keeps its own two-block cache split upstream and MUST NOT be
+ * routed through this helper.
+ */
+export interface FrontTailSplit {
+    /** The byte-stable front to send as the `system` string. */
+    front: string;
+    /** The per-turn-dynamic tail to relocate into the trailing user message. */
+    dynamicTail: string;
+}
+/**
+ * Split an assembled non-Claude system string into a byte-stable front and a
+ * per-turn-dynamic tail, cutting at the end of `staticPrefix`.
+ *
+ * Uses the established provider-family detection (`modelId.startsWith("claude")`)
+ * so the Claude branch is a no-op guard. If `staticPrefix` cannot be located in
+ * `systemWithCaps` (unexpected), returns the whole string as `front` with an
+ * empty tail so no instruction content is ever dropped.
+ */
+export declare function splitFrontAndDynamicTail(params: {
+    modelId: string;
+    systemWithCaps: string;
+    staticPrefix: string;
+}): FrontTailSplit;
+/**
+ * `assembleFrontSystem` — thin convenience wrapper returning only the byte-stable
+ * front (the value sent as the `system` string). Named to match the plan's
+ * invariant-test contract.
+ */
+export declare function assembleFrontSystem(params: {
+    modelId: string;
+    systemWithCaps: string;
+    staticPrefix: string;
+}): string;
+/**
+ * Fold a relocated dynamic tail into a user message's content. Handles both
+ * string content and structured (array-of-parts) content. Returns the message
+ * unchanged when the tail is empty. Never mutates the input.
+ */
+export declare function foldDynamicTailIntoUserMessage<T extends {
+    role: unknown;
+    content: unknown;
+}>(msg: T, dynamicTail: string): T;

package/dist/src/orchestrator/cache-prefix.js

@@ -0,0 +1,83 @@
+/**
+ * Non-Claude prompt-cache prefix stability (Task 3).
+ *
+ * On non-Claude providers (DeepSeek / GLM / other OpenAI-compatible backends)
+ * the whole system prompt is sent as a single string. Any per-turn-varying
+ * content that sits AFTER the byte-stable `staticPrefix` but BEFORE the
+ * conversation — the `dynamicSuffix` (plan / resume / cwd), the PIL output
+ * suffix, and the live MCP capability roster — shifts the cached prefix and
+ * forces a full cache miss on PIL-active turns. Measured: `pil_active=1` ⟺
+ * `cache_read=0` on 12/12 calls (session `47a774d272da`).
+ *
+ * Fix (variant b): split the assembled system string at the END of
+ * `staticPrefix`. The front stays as the `system` string; the dynamic tail is
+ * relocated into the trailing user message (see `foldDynamicTailIntoUserMessage`)
+ * rather than emitted as a mid-conversation system-role message, because
+ * OpenAI-compatible providers do not reliably accept a non-leading system role.
+ *
+ * IMPORTANT fast-tier caveat: for fast-tier models the cheap-model workbook /
+ * playbook / shell directive are front-loaded BEFORE `staticPrefix` for primacy,
+ * and the workbook's task addendum covaries with `taskType` (== `pil_active`).
+ * That portion still shifts the prefix and is a deliberate primacy design, so
+ * this split does NOT relocate it — the front is fully byte-stable only for
+ * non-fast-tier non-Claude models (the expensive-model path, which is where the
+ * cache payoff is per the plan). See task-3-report.md for the residual analysis.
+ *
+ * The Claude path keeps its own two-block cache split upstream and MUST NOT be
+ * routed through this helper.
+ */
+/**
+ * Split an assembled non-Claude system string into a byte-stable front and a
+ * per-turn-dynamic tail, cutting at the end of `staticPrefix`.
+ *
+ * Uses the established provider-family detection (`modelId.startsWith("claude")`)
+ * so the Claude branch is a no-op guard. If `staticPrefix` cannot be located in
+ * `systemWithCaps` (unexpected), returns the whole string as `front` with an
+ * empty tail so no instruction content is ever dropped.
+ */
+export function splitFrontAndDynamicTail(params) {
+    const { modelId, systemWithCaps, staticPrefix } = params;
+    // Claude is handled by its own two-block ephemeral-cache split — never here.
+    if (modelId.startsWith("claude") || staticPrefix.length === 0) {
+        return { front: systemWithCaps, dynamicTail: "" };
+    }
+    const anchor = systemWithCaps.indexOf(staticPrefix);
+    if (anchor < 0) {
+        // staticPrefix not found — do not risk relocating (and possibly dropping)
+        // content we cannot precisely locate. Keep the original single string.
+        return { front: systemWithCaps, dynamicTail: "" };
+    }
+    const splitAt = anchor + staticPrefix.length;
+    return {
+        front: systemWithCaps.slice(0, splitAt),
+        dynamicTail: systemWithCaps.slice(splitAt),
+    };
+}
+/**
+ * `assembleFrontSystem` — thin convenience wrapper returning only the byte-stable
+ * front (the value sent as the `system` string). Named to match the plan's
+ * invariant-test contract.
+ */
+export function assembleFrontSystem(params) {
+    return splitFrontAndDynamicTail(params).front;
+}
+/**
+ * Fold a relocated dynamic tail into a user message's content. Handles both
+ * string content and structured (array-of-parts) content. Returns the message
+ * unchanged when the tail is empty. Never mutates the input.
+ */
+export function foldDynamicTailIntoUserMessage(msg, dynamicTail) {
+    if (dynamicTail.trim().length === 0)
+        return msg;
+    const block = `\n\n---\n[Session context — working directory, task guidance, and available tools]\n${dynamicTail.trim()}`;
+    const content = msg.content;
+    if (typeof content === "string") {
+        return { ...msg, content: `${content}${block}` };
+    }
+    if (Array.isArray(content)) {
+        return { ...msg, content: [...content, { type: "text", text: block }] };
+    }
+    // Unknown content shape — do not risk corrupting it; leave unchanged.
+    return msg;
+}
+//# sourceMappingURL=cache-prefix.js.map

package/dist/src/orchestrator/compact-request.d.ts

@@ -0,0 +1,32 @@
+/**
+ * src/orchestrator/compact-request.ts
+ *
+ * Process-global one-shot channel for an AGENT-initiated proactive compaction.
+ *
+ * The `compact` tool (src/tools/registry.ts) sets a pending request when the
+ * model decides to free context mid-task; the tool-engine `prepareStep`
+ * boundary consumes it exactly once and forces a compaction of the accumulated
+ * tool/conversation history BEFORE the next LLM step, then continues the turn.
+ * This is the proactive counterpart to the reactive tool-limit auto-recover
+ * (tool-limit-auto-recover.ts): the agent no longer has to hit a round cap to
+ * shed context — it can ask for a clean history the moment it judges the turn
+ * has gone read-heavy, avoiding the interruption entirely.
+ *
+ * Single-active-turn assumption: the TUI streams one turn at a time, so a
+ * process-global slot is sufficient and cannot cross-talk between concurrent
+ * user turns. A nested sub-session runs within its parent's turn and consumes
+ * the flag on its own next step — worst case a harmless extra compaction, never
+ * data loss (compaction is snapshot + rehydratable via ee_query).
+ */
+export interface ProactiveCompactRequestState {
+    /** Optional focus note the model wants preserved in mind after compaction. */
+    instructions: string | null;
+}
+/** Queue a proactive compaction to run before the next tool-loop step. */
+export declare function requestProactiveCompact(instructions?: string | null): void;
+/** True when a proactive compaction is queued (non-consuming peek). */
+export declare function hasPendingProactiveCompact(): boolean;
+/** Consume the pending request exactly once (returns null when none queued). */
+export declare function consumeProactiveCompact(): ProactiveCompactRequestState | null;
+/** Test hook — clear any queued request. */
+export declare function __resetProactiveCompactForTests(): void;

package/dist/src/orchestrator/compact-request.js

@@ -0,0 +1,41 @@
+/**
+ * src/orchestrator/compact-request.ts
+ *
+ * Process-global one-shot channel for an AGENT-initiated proactive compaction.
+ *
+ * The `compact` tool (src/tools/registry.ts) sets a pending request when the
+ * model decides to free context mid-task; the tool-engine `prepareStep`
+ * boundary consumes it exactly once and forces a compaction of the accumulated
+ * tool/conversation history BEFORE the next LLM step, then continues the turn.
+ * This is the proactive counterpart to the reactive tool-limit auto-recover
+ * (tool-limit-auto-recover.ts): the agent no longer has to hit a round cap to
+ * shed context — it can ask for a clean history the moment it judges the turn
+ * has gone read-heavy, avoiding the interruption entirely.
+ *
+ * Single-active-turn assumption: the TUI streams one turn at a time, so a
+ * process-global slot is sufficient and cannot cross-talk between concurrent
+ * user turns. A nested sub-session runs within its parent's turn and consumes
+ * the flag on its own next step — worst case a harmless extra compaction, never
+ * data loss (compaction is snapshot + rehydratable via ee_query).
+ */
+let pending = null;
+/** Queue a proactive compaction to run before the next tool-loop step. */
+export function requestProactiveCompact(instructions) {
+    const trimmed = typeof instructions === "string" ? instructions.trim() : "";
+    pending = { instructions: trimmed.length > 0 ? trimmed : null };
+}
+/** True when a proactive compaction is queued (non-consuming peek). */
+export function hasPendingProactiveCompact() {
+    return pending !== null;
+}
+/** Consume the pending request exactly once (returns null when none queued). */
+export function consumeProactiveCompact() {
+    const p = pending;
+    pending = null;
+    return p;
+}
+/** Test hook — clear any queued request. */
+export function __resetProactiveCompactForTests() {
+    pending = null;
+}
+//# sourceMappingURL=compact-request.js.map

package/dist/src/orchestrator/compaction.d.ts

@@ -1,5 +1,4 @@
 import { type ModelMessage } from "ai";
-import type { ProviderFactory as LegacyProvider } from "../providers/runtime.js";
 /**
  * A single action the compaction proposer model wants to take on one message.
  */
@@ -21,7 +20,7 @@ export interface CompactionProposal {
  * The model sees the current messages and decides whether compaction is needed at all.
  * Returns null if the proposer call fails (caller should fall back gracefully).
  */
-export declare function proposeCompaction(provider: LegacyProvider, modelId: string, messages: ModelMessage[], signal?: AbortSignal): Promise<CompactionProposal | null>;
+export declare function proposeCompaction(modelId: string, messages: ModelMessage[], signal?: AbortSignal): Promise<CompactionProposal | null>;
 export interface CompactionSettings {
     reserveTokens: number;
     keepRecentTokens: number;
@@ -56,6 +55,16 @@ export declare function getCompactionSummaryText(message: ModelMessage | undefin
 export declare function estimateMessageTokens(message: ModelMessage): number;
 export declare function estimateConversationTokens(systemPrompt: string, messages: ModelMessage[], inFlightText?: string): number;
 export declare function shouldCompactContext(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+/**
+ * Cross-turn anti-thrash guard: true when a post-turn compaction should be
+ * SKIPPED because too few new tokens have accumulated since the last
+ * compaction's `tokensAfter` — i.e. the cache-reset cost would not be
+ * amortized (observed: session ff932f8568e8 re-compacted after only ~14K
+ * new tokens against a 20K floor).
+ *
+ * `lastAfter === null` means no prior compaction this session — never skip.
+ */
+export declare function isCompactionThrash(tokens: number, lastAfter: number | null, minNew: number): boolean;
 export declare function findCutPoint(messages: ModelMessage[], startIndex: number, keepRecentTokens: number): CutPointResult;
 export declare function prepareCompaction(messages: ModelMessage[], systemPrompt: string, settings: CompactionSettings): PreparedCompaction | null;
 export declare function relaxCompactionSettings(settings: CompactionSettings): CompactionSettings;
@@ -68,4 +77,4 @@ export interface CompactionSummaryResult {
     summary: string;
     usage: CompactionUsage;
 }
-export declare function generateCompactionSummary(provider: LegacyProvider, modelId: string, preparation: PreparedCompaction, customInstructions?: string, signal?: AbortSignal): Promise<CompactionSummaryResult>;
+export declare function generateCompactionSummary(modelId: string, preparation: PreparedCompaction, customInstructions?: string, signal?: AbortSignal): Promise<CompactionSummaryResult>;