@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/logger.ts

@@ -0,0 +1,248 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getMagicContextLogPath } from "./data-path";
+import { sanitizeConfigValue, sanitizeDiagnosticText } from "./redaction";
+
+const isTestEnv = process.env.NODE_ENV === "test";
+
+let buffer: string[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | null = null;
+const FLUSH_INTERVAL_MS = 500;
+const BUFFER_SIZE_LIMIT = 50;
+const MAX_BUFFERED_BYTES = 1024 * 1024;
+let bufferedBytes = 0;
+let droppedLines = 0;
+
+function boundBuffer(): void {
+    while (bufferedBytes > MAX_BUFFERED_BYTES && buffer.length > 0) {
+        bufferedBytes -= Buffer.byteLength(buffer.shift() ?? "");
+        droppedLines++;
+    }
+}
+const MAX_LOG_FILE_BYTES = 32 * 1024 * 1024;
+const SIZE_CHECK_INTERVAL_FLUSHES = 64;
+
+let activeLogFile: string | null = null;
+let activeLogSize: number | null = null;
+let flushesSinceSizeCheck = 0;
+
+export interface LoggerDiagnostics {
+    swallowedWriteCount: number;
+    lastErrorMessage: string | null;
+    lastErrorTime: string | null;
+}
+
+let swallowedWriteCount = 0;
+let lastErrorMessage: string | null = null;
+let lastErrorTime: string | null = null;
+
+function recordSwallowedWrite(error: unknown): void {
+    try {
+        swallowedWriteCount++;
+        lastErrorMessage = sanitizeDiagnosticText(
+            error instanceof Error ? error.message : String(error),
+        );
+        lastErrorTime = new Date().toISOString();
+    } catch {
+        // Diagnostics must not make the logger throw either.
+    }
+}
+
+function ensureDir(filePath: string): void {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function isMissingFile(error: unknown): boolean {
+    return (
+        typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        (error as { code?: unknown }).code === "ENOENT"
+    );
+}
+
+function getCurrentLogSize(logFile: string): number {
+    if (
+        activeLogFile === logFile &&
+        activeLogSize !== null &&
+        flushesSinceSizeCheck < SIZE_CHECK_INTERVAL_FLUSHES
+    ) {
+        return activeLogSize;
+    }
+
+    try {
+        const stat = fs.statSync(logFile);
+        if (!stat.isFile()) {
+            throw new Error(`Magic Context log path is not a regular file: ${logFile}`);
+        }
+        // Logs can contain diagnostic context, so tighten files created by older
+        // versions before copying or appending any new content.
+        fs.chmodSync(logFile, 0o600);
+        activeLogFile = logFile;
+        activeLogSize = stat.size;
+        flushesSinceSizeCheck = 0;
+        return stat.size;
+    } catch (error) {
+        if (!isMissingFile(error)) throw error;
+        activeLogFile = logFile;
+        activeLogSize = 0;
+        flushesSinceSizeCheck = 0;
+        return 0;
+    }
+}
+
+function capLogData(data: string): string {
+    if (Buffer.byteLength(data) <= MAX_LOG_FILE_BYTES) return data;
+
+    // A single diagnostic payload must not defeat the on-disk bound. Cutting a
+    // Buffer can split UTF-8, so trim any replacement character expansion too.
+    let bounded = Buffer.from(data).subarray(0, MAX_LOG_FILE_BYTES).toString("utf8");
+    while (Buffer.byteLength(bounded) > MAX_LOG_FILE_BYTES) {
+        bounded = bounded.slice(0, -1);
+    }
+    return bounded;
+}
+
+function writeBoundedPredecessor(logFile: string, predecessorPath: string, size: number): void {
+    const predecessorFd = fs.openSync(predecessorPath, "w", 0o600);
+    try {
+        // `openSync(..., "w")` preserves an existing file's mode, so set it
+        // before any copied diagnostic text reaches the predecessor.
+        fs.fchmodSync(predecessorFd, 0o600);
+        const bytesToCopy = Math.min(size, MAX_LOG_FILE_BYTES);
+        const sourceFd = fs.openSync(logFile, "r");
+        try {
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, bytesToCopy));
+            let remaining = bytesToCopy;
+            let position = Math.max(0, size - bytesToCopy);
+            while (remaining > 0) {
+                const bytesRead = fs.readSync(
+                    sourceFd,
+                    chunk,
+                    0,
+                    Math.min(chunk.length, remaining),
+                    position,
+                );
+                if (bytesRead === 0) break;
+                fs.writeSync(predecessorFd, chunk, 0, bytesRead);
+                remaining -= bytesRead;
+                position += bytesRead;
+            }
+        } finally {
+            fs.closeSync(sourceFd);
+        }
+    } finally {
+        fs.closeSync(predecessorFd);
+    }
+}
+
+function rotateLogFile(logFile: string, size: number): void {
+    const predecessorPath = `${logFile}.1`;
+    writeBoundedPredecessor(logFile, predecessorPath, size);
+    // Keep the current inode in place so diagnostic readers can observe a
+    // shorter log during rotation instead of seeing the path disappear.
+    fs.truncateSync(logFile, 0);
+    activeLogSize = 0;
+    flushesSinceSizeCheck = 0;
+}
+
+function flush(): void {
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    if (buffer.length === 0 && droppedLines === 0) return;
+    const notice = droppedLines
+        ? `[${new Date().toISOString()}] [magic-context][global] logger dropped ${droppedLines} ${droppedLines === 1 ? "line" : "lines"}: buffer exceeded ${MAX_BUFFERED_BYTES} bytes while writes were pending\n`
+        : "";
+    try {
+        const data = capLogData(notice + buffer.join(""));
+        const logFile = getMagicContextLogPath();
+        ensureDir(logFile);
+        let currentSize = getCurrentLogSize(logFile);
+        const dataSize = Buffer.byteLength(data);
+        if (currentSize > 0 && currentSize + dataSize > MAX_LOG_FILE_BYTES) {
+            rotateLogFile(logFile, currentSize);
+            currentSize = 0;
+        }
+        fs.appendFileSync(logFile, data, { encoding: "utf8", mode: 0o600 });
+        buffer = [];
+        bufferedBytes = 0;
+        droppedLines = 0;
+        activeLogFile = logFile;
+        activeLogSize = currentSize + dataSize;
+        flushesSinceSizeCheck++;
+    } catch (error) {
+        activeLogFile = null;
+        activeLogSize = null;
+        flushesSinceSizeCheck = 0;
+        recordSwallowedWrite(error);
+        boundBuffer();
+    }
+}
+
+function scheduleFlush(): void {
+    if (flushTimer) return;
+    flushTimer = setTimeout(() => {
+        flushTimer = null;
+        flush();
+    }, FLUSH_INTERVAL_MS);
+}
+
+export function log(message: string, data?: unknown): void {
+    if (isTestEnv) return;
+    try {
+        const timestamp = new Date().toISOString();
+        const serialized =
+            data === undefined
+                ? ""
+                : data instanceof Error
+                  ? ` ${sanitizeDiagnosticText(
+                        `${data.message}${data.stack ? `\n${data.stack}` : ""}`,
+                    )}`
+                  : ` ${JSON.stringify(sanitizeConfigValue(data))}`;
+        const line = `[${timestamp}] ${sanitizeDiagnosticText(message)}${serialized}\n`;
+        buffer.push(line);
+        bufferedBytes += Buffer.byteLength(line);
+        boundBuffer();
+        if (buffer.length >= BUFFER_SIZE_LIMIT) {
+            flush();
+        } else {
+            scheduleFlush();
+        }
+    } catch {
+        // Intentional: logging must never throw
+    }
+}
+
+export function sessionLog(sessionId: string, message: string, data?: unknown): void {
+    log(`[magic-context][${sessionId}] ${message}`, data);
+}
+
+export function getLoggerDiagnostics(): LoggerDiagnostics {
+    return {
+        swallowedWriteCount,
+        lastErrorMessage,
+        lastErrorTime,
+    };
+}
+
+/** Flush buffered log entries immediately. Primarily useful to diagnostic readers and tests. */
+export function flushLogger(): void {
+    flush();
+}
+
+/**
+ * Resolve the current log file path. The path is harness-aware (see
+ * {@link getMagicContextLogPath}) and re-evaluated on every call, so callers
+ * who format diagnostic output with this value always see the path the next
+ * flush will actually use.
+ */
+export function getLogFilePath(): string {
+    return getMagicContextLogPath();
+}
+
+// Flush remaining buffer on process exit
+if (!isTestEnv) {
+    process.on("exit", flush);
+}

package/src/shared/model-cache-ttl.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "bun:test";
+import { MagicContextConfigSchema } from "../config/schema/magic-context";
+import { resolveCacheTtl } from "../hooks/magic-context/event-resolvers";
+
+describe("known model cache TTL", () => {
+    it("matches canonical model versions through provider prefixes", () => {
+        for (const prefix of ["", "openai/", "openai-codex/", "openrouter/openai/", "azure/"]) {
+            for (const model of [
+                "gpt-5.6",
+                "gpt-5.6-sol",
+                "gpt-5.7",
+                "gpt-5.10",
+                "gpt-6",
+                "gpt-6.1",
+                "gpt-6-mini",
+                "gpt-7",
+            ]) {
+                expect(resolveCacheTtl("5m", prefix + model), prefix + model).toBe("30m");
+            }
+            for (const model of ["gpt-5.5", "gpt-5.1", "gpt-5", "gpt-4o", "unknown", "not-gpt-6"]) {
+                expect(resolveCacheTtl("5m", prefix + model), prefix + model).toBe("5m");
+            }
+        }
+    });
+    it("uses built-ins for unset and global 5m, but honors global 10m", () => {
+        expect(resolveCacheTtl(MagicContextConfigSchema.parse({}).cache_ttl, "openai/gpt-6")).toBe(
+            "30m",
+        );
+        expect(resolveCacheTtl("5m", "openai/gpt-6")).toBe("30m");
+        expect(resolveCacheTtl("10m", "openai/gpt-6")).toBe("10m");
+    });
+    it("honors per-model entries before built-ins and built-ins before object defaults", () => {
+        expect(resolveCacheTtl({ default: "10m" }, "openai/gpt-6")).toBe("30m");
+        expect(resolveCacheTtl({ default: "10m", "gpt-6": "5m" }, "openai/gpt-6")).toBe("5m");
+        expect(resolveCacheTtl({ default: "10m", "openai/*": "never" }, "openai/gpt-6")).toBe(
+            "never",
+        );
+        expect(resolveCacheTtl({ default: "10m" }, "other/model")).toBe("10m");
+    });
+});

package/src/shared/model-cache-ttl.ts

@@ -0,0 +1,58 @@
+import { canonicalModelIdentity } from "./harness-provider-map";
+import { resolveModelConfigValue } from "./prompt-surface";
+
+export type CacheTtlConfig = string | Record<string, string>;
+export type CacheTtlSource = "config" | "default" | "OpenAI GPT-5.6+ default";
+export interface ResolvedCacheTtl {
+    value: string;
+    source: CacheTtlSource;
+    modelKey: string | undefined;
+}
+
+// Provider documentation: https://developers.openai.com/api/docs/guides/prompt-caching
+// Cache lifetime / Summary of model differences: at least 30 minutes since write or reuse.
+const MODEL_CACHE_LIFETIMES = [
+    {
+        source: "OpenAI GPT-5.6+ default" as const,
+        value: "30m",
+        matches(model: string): boolean {
+            const version = /^gpt-(\d+)(?:\.(\d+))?(?:$|[^\d.])/.exec(model);
+            if (!version) return false;
+            const major = Number(version[1]);
+            const minor = Number(version[2] ?? 0);
+            return major > 5 || (major === 5 && minor >= 6);
+        },
+    },
+];
+
+export function resolveModelCacheTtl(
+    config: CacheTtlConfig | undefined,
+    modelKey: string | undefined,
+): ResolvedCacheTtl {
+    if (config && typeof config !== "string") {
+        const match =
+            modelKey &&
+            !modelKey.includes("/") &&
+            Object.hasOwn(config, modelKey) &&
+            modelKey !== "default"
+                ? config[modelKey]
+                : resolveModelConfigValue(config, modelKey)?.value;
+        if (match !== undefined) return { value: match, source: "config", modelKey };
+    }
+    // A non-5m global string is an explicit policy. The generic 5m default is
+    // not evidence of provider eviction: documented lifetimes avoid paid rewrites.
+    if (typeof config === "string" && config !== "5m")
+        return { value: config, source: "config", modelKey };
+    const model =
+        canonicalModelIdentity(modelKey ?? "")
+            .toLowerCase()
+            .split("/")
+            .at(-1) ?? "";
+    const known = MODEL_CACHE_LIFETIMES.find((entry) => entry.matches(model));
+    if (known) return { value: known.value, source: known.source, modelKey };
+    return {
+        value: (typeof config === "object" ? config.default : config) ?? "5m",
+        source: "default",
+        modelKey,
+    };
+}

package/src/shared/model-resolution.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+    normalizeModelEntry,
+    resolveFallbackEntries,
+    resolveHistorianAgentOverrides,
+    resolveHistorianModel,
+} from "./model-resolution";
+
+describe("model-resolution", () => {
+    test("keeps historian temperature opt-in while preserving explicit overrides", () => {
+        const fixtures = [
+            { temperature: undefined, expected: undefined },
+            { temperature: 0.1, expected: 0.1 },
+            { temperature: 0, expected: 0 },
+        ] as const;
+        for (const fixture of fixtures) {
+            const resolved = resolveHistorianAgentOverrides({
+                ...(fixture.temperature !== undefined ? { temperature: fixture.temperature } : {}),
+                maxTokens: 16_000,
+                opencode: { model: "google/flash", variant: "low" },
+                pi: { model: "pi/must-not-leak", thinking_level: "high" },
+            });
+            expect(resolved).toEqual({
+                maxTokens: 16_000,
+                ...(fixture.expected !== undefined ? { temperature: fixture.expected } : {}),
+                model: "google/flash",
+                variant: "low",
+            });
+        }
+    });
+
+    test("normalizes string and object entries to the same model identity", () => {
+        expect(normalizeModelEntry("anthropic/sonnet", "opencode")).toEqual({
+            model: "anthropic/sonnet",
+        });
+        expect(
+            normalizeModelEntry({ model: "anthropic/sonnet", variant: "high" }, "opencode"),
+        ).toEqual({ model: "anthropic/sonnet", qualifier: "high" });
+    });
+
+    test("keeps ordered qualifier-distinct fallbacks and removes exact duplicates", () => {
+        expect(
+            resolveFallbackEntries(
+                [
+                    { model: "anthropic/sonnet", variant: "low" },
+                    { model: "anthropic/sonnet", variant: "high" },
+                    { model: "anthropic/sonnet", variant: "low" },
+                    "google/flash",
+                    "google/flash",
+                ],
+                "opencode",
+            ),
+        ).toEqual([
+            { model: "anthropic/sonnet", qualifier: "low" },
+            { model: "anthropic/sonnet", qualifier: "high" },
+            { model: "google/flash" },
+        ]);
+    });
+
+    test("keeps the flash calibration available only as an explicit override", () => {
+        expect(
+            resolveHistorianAgentOverrides({
+                opencode: { model: { model: "google/flash", variant: "fast" } },
+                pi: { model: "pi/ignored" },
+                two_pass: true,
+            }),
+        ).toEqual({
+            maxTokens: 32_000,
+            two_pass: true,
+            model: "google/flash",
+            variant: "fast",
+        });
+        expect(
+            resolveHistorianAgentOverrides({ temperature: 0.1, maxTokens: 12_000 }),
+        ).toMatchObject({ temperature: 0.1, maxTokens: 12_000 });
+    });
+
+    test("does not inherit a block qualifier into unqualified fallbacks", () => {
+        const config = {
+            historian: {
+                opencode: {
+                    model: "open/primary",
+                    fallback_models: ["open/fallback"],
+                    variant: "primary-only",
+                },
+                pi: {
+                    model: "pi/primary",
+                    fallback_models: ["pi/fallback"],
+                    thinking_level: "high",
+                },
+            },
+        };
+
+        // Inheritance is deliberately absent because a fallback model may not support the
+        // qualifier selected for the primary model.
+        expect(resolveHistorianModel(config, "opencode")).toEqual({
+            primary: { model: "open/primary", qualifier: "primary-only" },
+            fallbacks: [{ model: "open/fallback" }],
+        });
+        expect(resolveHistorianModel(config, "pi")).toEqual({
+            primary: { model: "pi/primary", qualifier: "high" },
+            fallbacks: [{ model: "pi/fallback" }],
+        });
+    });
+
+    test("reads historian attempts only from the requested harness", () => {
+        const config = {
+            historian: {
+                model: "flat/ignored",
+                opencode: {
+                    model: { model: "open/code", variant: "oc-primary" },
+                    fallback_models: [{ model: "open/fallback", variant: "oc-fallback" }],
+                },
+                pi: {
+                    model: { model: "pi/model", thinking_level: "high" },
+                    fallback_models: [{ model: "pi/fallback", thinking_level: "max" }],
+                },
+            },
+        };
+
+        expect(resolveHistorianModel(config, "opencode")).toEqual({
+            primary: { model: "open/code", qualifier: "oc-primary" },
+            fallbacks: [{ model: "open/fallback", qualifier: "oc-fallback" }],
+        });
+        expect(resolveHistorianModel(config, "pi")).toEqual({
+            primary: { model: "pi/model", qualifier: "high" },
+            fallbacks: [{ model: "pi/fallback", qualifier: "max" }],
+        });
+        expect(resolveHistorianModel({}, "pi")).toEqual({ fallbacks: [] });
+    });
+});

package/src/shared/model-resolution.ts

@@ -0,0 +1,158 @@
+export type ModelHarness = "opencode" | "pi";
+
+export interface ResolvedModelEntry {
+    /** Canonical provider/model reference used for identity and model selection. */
+    model: string;
+    /** OpenCode variant or Pi thinking level, selected for the active entry only. */
+    qualifier?: string;
+}
+
+export type ModelInput = string | ResolvedModelEntry;
+
+type ConfigRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): ConfigRecord | undefined {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? (value as ConfigRecord)
+        : undefined;
+}
+
+function readString(value: unknown): string | undefined {
+    if (typeof value !== "string") return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function resolveHarnessBlock(
+    container: ConfigRecord | undefined,
+    harness: ModelHarness,
+): ConfigRecord | undefined {
+    return asRecord(container?.[harness]);
+}
+
+/**
+ * Collapses the string and object spellings of a harness model entry into the
+ * same model identity. Qualifiers stay separate because they alter an attempt,
+ * not the configured model identity.
+ */
+export function normalizeModelEntry(
+    entry: unknown,
+    harness: ModelHarness,
+): ResolvedModelEntry | undefined {
+    if (typeof entry === "string") {
+        const model = readString(entry);
+        return model ? { model } : undefined;
+    }
+
+    const objectEntry = asRecord(entry);
+    if (!objectEntry) return undefined;
+    const model = readString(objectEntry.model);
+    if (!model) return undefined;
+
+    const qualifier = readString(
+        objectEntry[harness === "opencode" ? "variant" : "thinking_level"],
+    );
+    return qualifier ? { model, qualifier } : { model };
+}
+
+function isValidModelReference(entry: ResolvedModelEntry): boolean {
+    const slash = entry.model.indexOf("/");
+    return slash > 0 && slash < entry.model.length - 1;
+}
+
+function sameAttempt(a: ResolvedModelEntry, b: ResolvedModelEntry): boolean {
+    return a.model === b.model && a.qualifier === b.qualifier;
+}
+
+/**
+ * Resolves a configured fallback list in declaration order. Attempts are
+ * deduplicated by model plus qualifier: the same model with distinct
+ * qualifiers remains two intentional attempts.
+ */
+export function resolveFallbackEntries(
+    value: unknown,
+    harness: ModelHarness,
+): ResolvedModelEntry[] {
+    const values = Array.isArray(value) ? value : value === undefined ? [] : [value];
+    const resolved: ResolvedModelEntry[] = [];
+    for (const value of values) {
+        const entry = normalizeModelEntry(value, harness);
+        if (!entry || !isValidModelReference(entry)) continue;
+        if (resolved.some((candidate) => sameAttempt(candidate, entry))) continue;
+        resolved.push(entry);
+    }
+    return resolved;
+}
+
+function resolvePrimaryEntry(args: {
+    entry: unknown;
+    defaultQualifier: unknown;
+    harness: ModelHarness;
+}): ResolvedModelEntry | undefined {
+    const entry = normalizeModelEntry(args.entry, args.harness);
+    if (!entry) return undefined;
+    const qualifier = entry.qualifier ?? readString(args.defaultQualifier);
+    return qualifier ? { ...entry, qualifier } : entry;
+}
+
+export interface ResolvedHistorianModel {
+    primary?: ResolvedModelEntry;
+    fallbacks: ResolvedModelEntry[];
+}
+
+/**
+ * Resolve historian model attempts from the selected harness block.
+ */
+export function resolveHistorianModel(
+    config: unknown,
+    harness: ModelHarness,
+): ResolvedHistorianModel {
+    const historian = asRecord(asRecord(config)?.historian);
+    const block = resolveHarnessBlock(historian, harness);
+    if (!block) return { fallbacks: [] };
+
+    return {
+        primary: resolvePrimaryEntry({
+            entry: block.model,
+            defaultQualifier: block[harness === "opencode" ? "variant" : "thinking_level"],
+            harness,
+        }),
+        fallbacks: resolveFallbackEntries(block.fallback_models, harness),
+    };
+}
+
+/**
+ * Keep non-model agent settings at their original level while replacing only
+ * OpenCode's model-resolution fields with the executing harness's primary.
+ */
+export function resolveOpenCodeAgentOverrides(agent: unknown): Record<string, unknown> {
+    const source = asRecord(agent);
+    if (!source) return {};
+    const {
+        model: _model,
+        fallback_models: _fallbackModels,
+        variant: _variant,
+        thinking_level: _thinking,
+        opencode,
+        pi,
+        tasks,
+        ...rest
+    } = source;
+    const primary = resolvePrimaryEntry({
+        entry: asRecord(opencode)?.model,
+        defaultQualifier: asRecord(opencode)?.variant,
+        harness: "opencode",
+    });
+    return {
+        ...rest,
+        ...(primary ? { model: primary.model } : {}),
+        ...(primary?.qualifier ? { variant: primary.qualifier } : {}),
+    };
+}
+
+export function resolveHistorianAgentOverrides(agent: unknown): Record<string, unknown> {
+    return {
+        maxTokens: 32_000,
+        ...resolveOpenCodeAgentOverrides(agent),
+    };
+}