@retaw106/mmc-oc 2.3.0 → 2.5.0

package/src/config/schema/magic-context.test.ts

@@ -135,6 +135,7 @@ describe("MagicContextConfigSchema", () => {
                 },
                 maintenance: {
                     enabled: true,
+                    fallback_models: [],
                     budgets: {
                         inputTokens: 400_000,
                         outputTokens: 32_000,
@@ -159,6 +160,55 @@ describe("MagicContextConfigSchema", () => {
             expect(result).toEqual(input);
         });
 
+        it("parses both maintenance model spellings and distinguishes absent from empty fallbacks", () => {
+            const stringForm = MagicContextConfigSchema.parse({
+                maintenance: { enabled: true, model: "openai/gpt-6-luna" },
+            }).maintenance;
+            expect(stringForm.model).toBe("openai/gpt-6-luna");
+            expect(stringForm.fallback_models).toBeUndefined();
+            expect(
+                MagicContextConfigSchema.parse({
+                    maintenance: { fallback_models: [] },
+                }).maintenance.fallback_models,
+            ).toEqual([]);
+
+            const objectForm = MagicContextConfigSchema.parse({
+                maintenance: {
+                    enabled: true,
+                    model: { model: "xiaomi/mimo-v2.6-flash", variant: "high" },
+                    fallback_models: ["openai/gpt-6-luna", { model: "p/l", thinking_level: "off" }],
+                },
+            }).maintenance;
+            // Object entries keep both harness qualifiers verbatim — the
+            // active harness reads its own, no cross-harness mapping.
+            expect(objectForm.model).toEqual({
+                model: "xiaomi/mimo-v2.6-flash",
+                variant: "high",
+            });
+            expect(objectForm.fallback_models).toEqual([
+                "openai/gpt-6-luna",
+                { model: "p/l", thinking_level: "off" },
+            ]);
+        });
+
+        it("plan 18: rejects blank maintenance model references at parse time (no silent executor flow)", () => {
+            expect(
+                MagicContextConfigSchema.safeParse({
+                    maintenance: { enabled: true, model: "   " },
+                }).success,
+            ).toBe(false);
+            expect(
+                MagicContextConfigSchema.safeParse({
+                    maintenance: { enabled: true, model: { model: "" } },
+                }).success,
+            ).toBe(false);
+            expect(
+                MagicContextConfigSchema.safeParse({
+                    maintenance: { enabled: true, fallback_models: ["ok/one", "  "] },
+                }).success,
+            ).toBe(false);
+        });
+
         it("accepts a boolean storage permission policy and rejects non-booleans", () => {
             expect(
                 MagicContextConfigSchema.parse({

package/src/config/schema/magic-context.ts

@@ -135,6 +135,23 @@ const HistorianModelEntryObjectSchema = z
 export const HistorianModelEntrySchema = z.union([z.string(), HistorianModelEntryObjectSchema]);
 export type HistorianModelEntry = z.infer<typeof HistorianModelEntrySchema>;
 
+/**
+ * A maintenance model entry (plan 18): the same string/object shape as a
+ * historian model entry, but blank references are REJECTED at parse time —
+ * a blank primary must surface as a config diagnostic, never silently flow
+ * into the hidden executor or get corrected to some other model.
+ */
+const MaintenanceModelEntrySchema = HistorianModelEntrySchema.superRefine((entry, ctx) => {
+    const model = typeof entry === "string" ? entry : entry.model;
+    if (typeof model !== "string" || model.trim().length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            message:
+                "maintenance model entries must be non-empty: a bare provider/model string or { model, variant?, thinking_level? }",
+        });
+    }
+});
+
 /**
  * A profile may select models but must not alter execution policy. It uses the
  * same flat historian model-resolution fields; execution metadata is not
@@ -400,6 +417,13 @@ export interface MagicContextConfig {
      */
     maintenance: {
         enabled: boolean;
+        /**
+         * Primary maintenance model entry. When absent, inherit historian
+         * model configuration; never inherit the main-session model.
+         */
+        model?: HistorianModelEntry;
+        /** Ordered fallbacks; absent inherits historian fallbacks only with an inherited primary. */
+        fallback_models?: HistorianModelEntry[];
         /** Per-run four-dimensional budget (decision 9; provisional, calibrated in P3/P4). */
         budgets: {
             inputTokens: number;
@@ -800,6 +824,15 @@ export const MagicContextConfigSchema = z.object({
                 .describe(
                     "Enable the automatic memory-maintenance task (default: true). USER-LEVEL ONLY — the whole maintenance group is stripped from project-tier config.",
                 ),
+            model: MaintenanceModelEntrySchema.optional().describe(
+                "Primary maintenance model entry: a bare provider/model string or { model, variant? (OpenCode), thinking_level? (Pi) }. USER-LEVEL ONLY. When absent, inherit historian model configuration. If neither has a primary, automatic passes skip and manual runs refuse. The main-session model is never inherited.",
+            ),
+            fallback_models: z
+                .array(MaintenanceModelEntrySchema)
+                .optional()
+                .describe(
+                    "Ordered fallback maintenance model entries, tried after CALL failures only. When absent and the primary is inherited, inherit historian fallbacks; explicit [] disables fallbacks. Illegal manifests, permission refusals, and exhausted budgets never switch models.",
+                ),
             budgets: z
                 .object({
                     inputTokens: z
@@ -922,7 +955,7 @@ export const MagicContextConfigSchema = z.object({
             anomalyThreshold: { absoluteRows: 10, poolFraction: 0.25 },
         })
         .describe(
-            "Automatic memory-maintenance run controls (dreamer replacement). USER-LEVEL ONLY: the whole group is stripped from project-tier config so a cloned repository cannot raise budgets, relax cooldowns, or loosen the anomaly guard.",
+            "Automatic memory-maintenance run controls (dreamer replacement). USER-LEVEL ONLY: project-tier config cannot pick maintenance models or change run controls. An absent model inherits historian model configuration, never the session model.",
         ),
 });
 

package/src/shared/model-suggestion-retry.test.ts

@@ -38,6 +38,58 @@ function createArgs(model?: { providerID: string; modelID: string }) {
 }
 
 describe("promptSyncWithModelSuggestionRetry", () => {
+    for (const validated of [false, true]) {
+        for (const allowModelSuggestions of [undefined, true, false]) {
+            test(`provider suggestions ${String(allowModelSuggestions)}, validated=${validated}`, async () => {
+                const models: string[] = [];
+                const prompt = mock(async (args: PromptCall) => {
+                    const model = args.body.model?.modelID ?? "";
+                    models.push(model);
+                    if (model !== "suggested" && model !== "last") {
+                        throw new Error(
+                            `model not found: provider/${model}. did you mean: suggested?`,
+                        );
+                    }
+                    return {};
+                });
+                const options = {
+                    allowModelSuggestions,
+                    fallbackModels: ["provider/fallback", "provider/last"],
+                };
+                const args = createArgs({ providerID: "provider", modelID: "primary" });
+                if (validated) {
+                    await promptSyncWithValidatedOutputRetry(createClient(prompt), args, {
+                        ...options,
+                        fetchOutput: async () => "output",
+                        validateOutput: (output) => output,
+                    });
+                } else {
+                    await promptSyncWithModelSuggestionRetry(createClient(prompt), args, options);
+                }
+                expect(models).toEqual(
+                    allowModelSuggestions === false
+                        ? ["primary", "fallback", "last"]
+                        : ["primary", "suggested"],
+                );
+            });
+        }
+    }
+
+    test("disabled suggestions preserve the original error without fallbacks", async () => {
+        const error = new Error("model not found: provider/primary. did you mean: suggested?");
+        const prompt = mock(async () => {
+            throw error;
+        });
+        await expect(
+            promptSyncWithModelSuggestionRetry(
+                createClient(prompt),
+                createArgs({ providerID: "provider", modelID: "primary" }),
+                { allowModelSuggestions: false },
+            ),
+        ).rejects.toBe(error);
+        expect(prompt).toHaveBeenCalledTimes(1);
+    });
+
     test("primary succeeds, no fallback iteration", async () => {
         const prompt = mock(async () => ({}));
         const client = createClient(prompt);

package/src/shared/model-suggestion-retry.ts

@@ -71,6 +71,8 @@ export interface PromptAttemptInfo {
 export interface PromptRetryOptions {
     transport?: PromptTransport;
     timeoutMs?: number;
+    /** False for callers whose configured model chain must not accept provider suggestions. Defaults to true. */
+    allowModelSuggestions?: boolean;
     /** External abort signal — cancels the in-flight LLM prompt immediately when aborted */
     signal?: AbortSignal;
     /**
@@ -361,8 +363,12 @@ async function abortChildRun(client: Client, sessionId: string): Promise<void> {
  * Everything else (auth errors, ProviderModelNotFoundError without suggestion,
  * rate limits, transient network failures, etc.) is considered retryable on a
  * different model.
+ * Exported as the shared fallback-switch classifier (plan 18): the
+ * memory-maintenance attempt loop reuses this exact predicate so "which
+ * failures may switch models" has ONE definition across historian and
+ * maintainer call sites.
  */
-function isNonRetryable(error: unknown, externalSignal?: AbortSignal): boolean {
+export function isNonRetryable(error: unknown, externalSignal?: AbortSignal): boolean {
     if (
         externalSignal?.aborted ||
         (error instanceof HiddenCompletionRefusal && error.terminal) ||
@@ -484,6 +490,7 @@ async function attemptOnce(
     callContext: string,
     label: string,
     transport?: PromptTransport,
+    allowModelSuggestions = true,
 ): Promise<void> {
     // Keep this snapshot separate from the object passed to the client. A
     // failed prompt facade may rewrite its request body before rejecting; the
@@ -494,9 +501,8 @@ async function attemptOnce(
         await promptWithTimeout(client, attemptArgs, timeoutMs, signal, transport);
         return;
     } catch (error) {
-        // If non-retryable (abort, overflow, timeout), bubble up immediately.
-        // Don't even try suggestion retry — caller needs the original error.
-        if (isNonRetryable(error, signal)) throw error;
+        // Surface the original error when suggestions are disabled or cannot help.
+        if (isNonRetryable(error, signal) || !allowModelSuggestions) throw error;
 
         const suggestion = parseModelSuggestion(error);
         if (!suggestion || !originalBody.model) {
@@ -572,6 +578,7 @@ export async function promptSyncWithModelSuggestionRetry(
             callContext,
             explicitPrimaryLabel,
             options.transport,
+            options.allowModelSuggestions,
         );
         return;
     } catch (error) {
@@ -616,6 +623,7 @@ export async function promptSyncWithModelSuggestionRetry(
                 callContext,
                 label,
                 options.transport,
+                options.allowModelSuggestions,
             );
             log(
                 `[${callContext}] fallback succeeded with ${label} (attempt ${i + 2}/${fallbacks.length + 1})`,
@@ -661,6 +669,7 @@ async function attemptAndValidate<TOutput, TValidated>(
             callContext,
             attempt.label,
             options.transport,
+            options.allowModelSuggestions,
         );
     } catch (error) {
         throw {

package/src/shared/prompt-surface-runtime.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { readFileSync, statSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
 
@@ -59,6 +60,17 @@ export function promptSurfaceHashMaterial(
         : `${systemContent}\n\0magic-context-prompt-surface:${preset}`;
 }
 
+/**
+ * Hash system text after the caller resolves guidance and freezes host date lines.
+ * Keep the legacy MD5 hex encoding so existing cached heads retain their identity.
+ */
+export function systemPromptFingerprint(
+    systemContent: string,
+    preset: PromptSurfacePreset = "full",
+): string {
+    return createHash("md5").update(promptSurfaceHashMaterial(systemContent, preset)).digest("hex");
+}
+
 const PROMPT_SURFACE_TOOL_ID_SET = new Set<string>(ACTIVE_TOOL_IDS);
 
 export interface PromptSurfaceGuidanceSelection {

package/src/shared/reclaim-distance.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "bun:test";
+import {
+    farBehindToolBookmark,
+    isReclaimUserTurn,
+    type ReclaimDistanceEntry,
+} from "./reclaim-distance";
+
+const output = (tag: number, tokens = 1000): ReclaimDistanceEntry => ({
+    toolOutputTag: tag,
+    tokens,
+});
+const turn = (): ReclaimDistanceEntry => ({ userTurn: true, tokens: 10 });
+
+describe("reclaim distance", () => {
+    it("repeated rebuilds cannot age the current task", () => {
+        const entries = [turn(), ...Array.from({ length: 28 }, (_, i) => output(i + 1))];
+        for (const count of [2, 3, 5]) {
+            let bookmark = 0;
+            for (let pass = 0; pass < count + 1; pass++) {
+                expect(bookmark).toBe(0);
+                bookmark = Math.max(bookmark, farBehindToolBookmark(entries, 200_000));
+            }
+        }
+    });
+
+    it("three newer user turns establish a bookmark, not two", () => {
+        const entries = [turn(), output(1), turn(), output(2), turn()];
+        expect(farBehindToolBookmark(entries, 200_000)).toBe(0);
+        expect(farBehindToolBookmark([...entries, turn()], 200_000)).toBe(1);
+    });
+
+    it("single-turn tool loop ages at exactly a quarter of the usable window", () => {
+        const entries = [turn(), output(1), output(2, 49_999)];
+        expect(farBehindToolBookmark(entries, 200_000)).toBe(0);
+        expect(farBehindToolBookmark([...entries, { tokens: 1 }], 200_000)).toBe(1);
+        expect(farBehindToolBookmark([turn(), output(1, 100_000)], 200_000)).toBe(0);
+    });
+
+    it("multipart outputs never age from their own trailing chunks", () => {
+        expect(farBehindToolBookmark([output(1), output(1, 60_000)], 200_000)).toBe(0);
+    });
+
+    it("unknown windows disable only token distance", () => {
+        expect(farBehindToolBookmark([output(1), output(2, 99_999)], 0)).toBe(0);
+        expect(farBehindToolBookmark([output(1), turn(), turn(), turn()], 0)).toBe(1);
+    });
+
+    it("excludes synthetic host wakes, MC reminders, heads and result carriers", () => {
+        expect(
+            isReclaimUserTurn({
+                role: "user",
+                parts: [
+                    {
+                        kind: "text",
+                        synthetic: true,
+                        text: "<system-reminder>Background task finished.</system-reminder>",
+                    },
+                ],
+            }),
+        ).toBe(false);
+        expect(
+            isReclaimUserTurn({
+                role: "user",
+                parts: [
+                    {
+                        kind: "text",
+                        text: "<system-reminder>Your next step: call ctx_reduce on the outputs you've already used (5).</system-reminder>",
+                    },
+                ],
+            }),
+        ).toBe(false);
+        expect(
+            isReclaimUserTurn({
+                role: "user",
+                syntheticHead: true,
+                parts: [{ kind: "text", text: "history" }],
+            }),
+        ).toBe(false);
+        expect(
+            isReclaimUserTurn({ role: "user", parts: [{ kind: "tool_result", text: "output" }] }),
+        ).toBe(false);
+        expect(
+            isReclaimUserTurn({
+                role: "user",
+                parts: [
+                    { kind: "tool_result", text: "output" },
+                    { kind: "text", text: "continue" },
+                ],
+            }),
+        ).toBe(true);
+    });
+
+    it("counts an authored part even after synthetic or ignored parts", () => {
+        for (const provenance of [{ synthetic: true }, { ignored: true }]) {
+            expect(
+                isReclaimUserTurn({ role: "user", parts: [{ kind: "image", ...provenance }] }),
+            ).toBe(false);
+            expect(
+                isReclaimUserTurn({
+                    role: "user",
+                    parts: [{ kind: "text", text: "notice", ...provenance }, { kind: "image" }],
+                }),
+            ).toBe(true);
+        }
+    });
+
+    it("a young lower-tag result holds back distant higher tags", () => {
+        expect(farBehindToolBookmark([output(2), output(3, 50_000), output(1)], 200_000)).toBe(0);
+        expect(farBehindToolBookmark([output(1), output(3, 50_000), output(2)], 200_000)).toBe(1);
+    });
+});

package/src/shared/reclaim-distance.ts

@@ -0,0 +1,91 @@
+export const RECLAIM_DISTANCE_USER_TURNS = 3;
+export const RECLAIM_DISTANCE_WINDOW_FRACTION = 0.25;
+
+export interface ReclaimDistanceEntry {
+    /** Local content tokens, excluding Magic Context's history and reduction/note reminders. */
+    tokens: number;
+    /** One event per authored user-role message, after any folded tool results. */
+    userTurn?: boolean;
+    /** Durable identifier of the tool invocation whose result ends at this entry. */
+    toolOutputTag?: number;
+}
+
+/** Only authored content starts a user turn; host control notices do not. */
+export function isReclaimUserTurn(args: {
+    role?: string;
+    syntheticHead?: boolean;
+    synthetic?: boolean;
+    ignored?: boolean;
+    parts: readonly { kind: string; text?: string; synthetic?: boolean; ignored?: boolean }[];
+}): boolean {
+    return (
+        args.role === "user" &&
+        !args.syntheticHead &&
+        !args.synthetic &&
+        !args.ignored &&
+        args.parts.some((part) => {
+            if (part.synthetic || part.ignored) return false;
+            if (part.kind !== "text" && part.kind !== "image" && part.kind !== "file") return false;
+            if (part.kind !== "text") return true;
+            return stripReclaimMcText(part.text ?? "").trim().length > 0;
+        })
+    );
+}
+
+/** Remove Magic Context's reduction/note reminders, not generic host wake notices. */
+export function stripReclaimMcText(text: string): string {
+    return text
+        .replace(/^§\d+§\s*/, "")
+        .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, (reminder) =>
+            /^(?:Your next step: call ctx_reduce on the outputs you've already used|Still unstamped:|Housekeeping: .* are reclaimable\. Stamp each output with ctx_reduce|.* are reclaimable\. Make a ctx_reduce pass now|.* are still unstamped\. Call ctx_reduce now)/.test(
+                reminder.slice("<system-reminder>".length).trimStart(),
+            )
+                ? ""
+                : reminder,
+        )
+        .replace(/<instruction name="deferred_notes">[\s\S]*?<\/instruction>/g, "");
+}
+
+/**
+ * A free cache rebuild is not evidence that the model has moved on. An output
+ * is far behind only after three newer user turns or a quarter-window of newer
+ * content. Return a prefix of qualifying tags; callers drop against the PREVIOUS
+ * durable bookmark before advancing it, so distance must survive two rebuilds.
+ */
+export function farBehindToolBookmark(
+    entries: readonly ReclaimDistanceEntry[],
+    usableWindow: number,
+): number {
+    let newerTurns = 0;
+    let newerTokens = 0;
+    const farTags: number[] = [];
+    let firstYoungTag = Infinity;
+    const seenOutputs = new Set<number>();
+    const tokenDistance =
+        usableWindow > 0 && Number.isFinite(usableWindow)
+            ? usableWindow * RECLAIM_DISTANCE_WINDOW_FRACTION
+            : Infinity;
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (!entry) continue;
+        const tag = entry.toolOutputTag;
+        // Multi-part outputs are positioned at their last result, not their call
+        // or first chunk: an output must never count its own remaining payload.
+        if (tag !== undefined && !seenOutputs.has(tag)) {
+            seenOutputs.add(tag);
+            if (newerTurns >= RECLAIM_DISTANCE_USER_TURNS || newerTokens >= tokenDistance) {
+                farTags.push(tag);
+            } else {
+                firstYoungTag = Math.min(firstYoungTag, tag);
+            }
+        }
+        if (entry.userTurn) newerTurns++;
+        if (Number.isFinite(entry.tokens) && entry.tokens > 0) newerTokens += entry.tokens;
+    }
+    // Tags follow call order, not result arrival. A late lower-tag sibling must
+    // hold the prefix even when a higher-tag result is already distant.
+    return farTags.reduce(
+        (bookmark, tag) => (tag < firstYoungTag ? Math.max(bookmark, tag) : bookmark),
+        0,
+    );
+}

package/src/shared/root-async-context.probe.mjs

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { setTimeout as delay, setImmediate as tick } from "node:timers/promises";
+import { Worker } from "node:worker_threads";
+import { inRootAsyncContext } from "./sqlite";
+
+const scope = new AsyncLocalStorage();
+const gc = globalThis.Bun ? () => Bun.gc(true) : globalThis.gc;
+const references = {};
+const resources = [];
+const timerStores = {};
+const ambientTick = () => { timerStores.ambient = scope.getStore() !== undefined; };
+const rootTick = () => { timerStores.root = scope.getStore() !== undefined; };
+function create(name, root, worker) {
+    const payload = { synthetic: name };
+    references[name] = new WeakRef(payload);
+    scope.run(payload, () => {
+        const make = worker
+            ? () => new Worker(new URL("worker.mjs", import.meta.url))
+            : () => setInterval(root ? rootTick : ambientTick, 5);
+        resources.push(root ? inRootAsyncContext(make) : make());
+        assert.equal(scope.getStore(), payload, "Root execution must restore the caller's store");
+    });
+}
+create("ambientWorker", false, true);
+create("rootWorker", true, true);
+create("ambientTimer", false, false);
+create("rootTimer", true, false);
+await delay(30);
+for (let i = 0; i < 12; i++) { await tick(); gc(); await tick(); }
+const retained = Object.fromEntries(Object.entries(references).map(([key, ref]) => [key, Number(ref.deref() !== undefined)]));
+for (const resource of resources) {
+    if (resource instanceof Worker) await resource.terminate();
+    else clearInterval(resource);
+}
+console.log(JSON.stringify({ runtime: globalThis.Bun ? `Bun ${Bun.version}` : process.version, timerStores, retained }));

package/src/shared/root-async-context.test.ts

@@ -0,0 +1,49 @@
+import { expect, test } from "bun:test";
+import { rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTestTempDirFromPath } from "./test-temp-dir";
+
+for (const runtime of ["Node", "Bun"] as const) {
+    test(`root resources do not inherit request stores (${runtime})`, async () => {
+        const directory = createTestTempDirFromPath(join(tmpdir(), "root-context-"));
+        try {
+            const entry = join(directory, "probe.mjs");
+            const build = await Bun.build({
+                entrypoints: [new URL("root-async-context.probe.mjs", import.meta.url).pathname],
+                target: "node",
+                format: "esm",
+                external: ["bun:sqlite", "node:sqlite"],
+            });
+            expect(build.success).toBe(true);
+            await writeFile(entry, await build.outputs[0].text());
+            await writeFile(
+                join(directory, "worker.mjs"),
+                `import { parentPort } from 'node:worker_threads'; parentPort.on('message', () => {});`,
+            );
+            const child = Bun.spawn(
+                [...(runtime === "Node" ? ["node", "--expose-gc"] : [process.execPath]), entry],
+                {
+                    stdout: "pipe",
+                    stderr: "pipe",
+                    windowsHide: true,
+                },
+            );
+            const [stdout, stderr, exit] = await Promise.all([
+                new Response(child.stdout).text(),
+                new Response(child.stderr).text(),
+                child.exited,
+            ]);
+            expect(exit, stderr).toBe(0);
+            const result = JSON.parse(stdout);
+            console.log(`${runtime} ALS propagation: ${stdout.trim()}`);
+            expect(result.timerStores).toEqual({ ambient: true, root: false });
+            expect(result.retained.rootWorker).toBe(0);
+            expect(result.retained.rootTimer).toBe(0);
+            expect(result.retained.ambientTimer).toBe(1);
+            if (runtime === "Node") expect(result.retained.ambientWorker).toBe(1);
+        } finally {
+            await rm(directory, { recursive: true, force: true });
+        }
+    });
+}