@retaw106/mmc-oc 0.0.0-stage → 1.2.2

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

@@ -0,0 +1,190 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+    createPromptSurfaceGuidanceEpochCache,
+    createPromptSurfaceRuntime,
+    LIGHT_TOOL_DESCRIPTIONS,
+} from "./prompt-surface-runtime";
+import { createTestTempDirFromPath } from "./test-temp-dir";
+
+const tempDirs: string[] = [];
+
+function tempDir(): string {
+    const directory = createTestTempDirFromPath(join(tmpdir(), "prompt-surface-runtime-"));
+    tempDirs.push(directory);
+    return directory;
+}
+
+afterEach(() => {
+    for (const directory of tempDirs) {
+        rmSync(directory, { recursive: true, force: true });
+    }
+    tempDirs.length = 0;
+});
+
+describe("prompt-surface runtime", () => {
+    it("rejects guidance overrides with zero or two section markers", () => {
+        for (const [name, content, expectedCount] of [
+            ["zero.md", "Custom guidance without a section marker", 0],
+            ["two.md", "## Magic Context\n\nFirst\n\n## Magic Context\n\nSecond", 2],
+        ] as const) {
+            const directory = tempDir();
+            writeFileSync(join(directory, name), content);
+            const warnings: string[] = [];
+            const runtime = createPromptSurfaceRuntime({
+                userConfigDirectory: directory,
+                warn: (warning) => warnings.push(warning),
+            });
+
+            const selection = runtime.resolveGuidance(
+                { default: "full", guidance_override_path: name },
+                "provider/model",
+            );
+
+            expect(selection.primaryOverride).toBeUndefined();
+            expect(warnings).toHaveLength(1);
+            expect(warnings[0]).toContain("must contain exactly one");
+            expect(warnings[0]).toContain(`found ${expectedCount}`);
+        }
+    });
+
+    it("captures a valid relative override once per model-key epoch", () => {
+        const directory = tempDir();
+        const path = join(directory, "guidance.md");
+        const first = "## Magic Context\n\nFirst epoch";
+        const second = "## Magic Context\n\nSecond epoch";
+        writeFileSync(path, first);
+        const runtime = createPromptSurfaceRuntime({
+            userConfigDirectory: directory,
+            warn: () => undefined,
+        });
+        const epochs = createPromptSurfaceGuidanceEpochCache(runtime);
+        const config = {
+            default: "full" as const,
+            models: { "provider/light": "light" as const },
+            guidance_override_path: "guidance.md",
+        };
+
+        const initial = epochs.resolve("session", config, "provider/full");
+        writeFileSync(path, second);
+        const fiveDeferred = Array.from({ length: 5 }, () =>
+            epochs.resolve("session", config, "provider/full"),
+        );
+        const changedModel = epochs.resolve("session", config, "provider/light");
+
+        expect(initial.primaryOverride).toBe(first);
+        expect(fiveDeferred.every((selection) => selection === initial)).toBe(true);
+        expect(changedModel.preset).toBe("light");
+        expect(changedModel.primaryOverride).toBe(second);
+    });
+
+    it("shares one frozen guidance epoch between the system hook and Rust adapter", () => {
+        const directory = tempDir();
+        const path = join(directory, "guidance.md");
+        const first = "## Magic Context\n\nShared first epoch";
+        const second = "## Magic Context\n\nShared second epoch";
+        writeFileSync(path, first);
+        const runtime = createPromptSurfaceRuntime({
+            userConfigDirectory: directory,
+            warn: () => undefined,
+        });
+        const systemEpochs = createPromptSurfaceGuidanceEpochCache(runtime);
+        const adapterEpochs = createPromptSurfaceGuidanceEpochCache(runtime);
+        const config = {
+            default: "full" as const,
+            guidance_override_path: "guidance.md",
+        };
+
+        const systemInitial = systemEpochs.resolve("session", config, "provider/model");
+        writeFileSync(path, second);
+        const adapterDeferred = adapterEpochs.resolve("session", config, "provider/model");
+        expect(adapterDeferred).toBe(systemInitial);
+        expect(adapterDeferred.primaryOverride).toBe(first);
+
+        adapterEpochs.clear("session");
+        const systemNextEpoch = systemEpochs.resolve("session", config, "provider/model");
+        expect(systemNextEpoch.primaryOverride).toBe(second);
+    });
+
+    it("uses registration default, applies known overrides, and reports invalid IDs", () => {
+        const warnings: string[] = [];
+        const runtime = createPromptSurfaceRuntime({
+            userConfigDirectory: tempDir(),
+            warn: (warning) => warnings.push(warning),
+        });
+        const registration = runtime.resolveRegistration({
+            default: "full",
+            models: { "provider/model": "light" },
+            tool_descriptions: {
+                mmc_search: "Custom search description",
+                unknown_tool: "Not allowed",
+            },
+        });
+
+        expect(registration.preset).toBe("full");
+        expect(registration.descriptionFor("mmc_search", "Full search")).toBe(
+            "Custom search description",
+        );
+        expect(registration.descriptionFor("mmc_reduce", "Full reduce")).toBe("Full reduce");
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toContain("unknown_tool");
+    });
+
+    it("lets a user description override the built-in light catalog", () => {
+        const runtime = createPromptSurfaceRuntime({
+            userConfigDirectory: tempDir(),
+            warn: () => undefined,
+        });
+        const registration = runtime.resolveRegistration({
+            default: "light",
+            tool_descriptions: { mmc_search: "User light search" },
+        });
+
+        expect(registration.descriptionFor("mmc_search", "Full search")).toBe("User light search");
+        expect(registration.descriptionFor("mmc_reduce", "Full reduce")).toBe(
+            LIGHT_TOOL_DESCRIPTIONS.mmc_reduce,
+        );
+    });
+
+    it("honors model routes for tool text when a model key is supplied", () => {
+        const runtime = createPromptSurfaceRuntime({
+            userConfigDirectory: tempDir(),
+            warn: () => undefined,
+        });
+        const config = {
+            default: "full" as const,
+            models: { "provider/light": "light" as const },
+        };
+        const processScoped = runtime.resolveRegistration(config);
+        const perModel = runtime.resolveRegistration(config, "provider/light");
+
+        expect(processScoped.preset).toBe("full");
+        expect(processScoped.descriptionFor("mmc_search", "Full search")).toBe("Full search");
+        expect(perModel.preset).toBe("light");
+        expect(perModel.descriptionFor("mmc_search", "Full search")).toBe(
+            LIGHT_TOOL_DESCRIPTIONS.mmc_search,
+        );
+    });
+
+    it("serves built-in light descriptions without a fallback notice", () => {
+        const warnings: string[] = [];
+        const runtime = createPromptSurfaceRuntime({
+            userConfigDirectory: tempDir(),
+            warn: (warning) => warnings.push(warning),
+        });
+        const config = { default: "light" as const };
+
+        const registration = runtime.resolveRegistration(config);
+        const guidance = runtime.resolveGuidance(config, "provider/model");
+        runtime.resolveGuidance(config, "provider/other");
+
+        expect(registration.descriptionFor("mmc_search", "Full search")).toBe(
+            LIGHT_TOOL_DESCRIPTIONS.mmc_search,
+        );
+        expect(guidance.preset).toBe("light");
+        expect(warnings).toEqual([]);
+    });
+});

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

@@ -0,0 +1,263 @@
+import { readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+import { opencodeUserConfigBasePath } from "../config/config-paths";
+import {
+    CTX_EXPAND_LIGHT_DESCRIPTION,
+    CTX_MEMORY_LIGHT_DESCRIPTION,
+    CTX_NOTE_LIGHT_DESCRIPTION,
+    CTX_REDUCE_LIGHT_DESCRIPTION,
+    CTX_SEARCH_LIGHT_DESCRIPTION,
+} from "../tools/light-descriptions";
+import type { HarnessId } from "./harness";
+import { piModelRefToCanonical } from "./harness-provider-map";
+import {
+    type PromptSurfaceConfig,
+    type PromptSurfacePreset,
+    resolvePromptSurface,
+} from "./prompt-surface";
+
+const GUIDANCE_MARKER = "## Magic Context";
+const GUIDANCE_MARKER_LINE = /^## Magic Context[\t ]*\r?$/gm;
+
+/**
+ * The single source of truth for the mmc_* tools exposed by the prompt surface.
+ * Consumers derive their registries and light-description catalogs from this list
+ * so adding a tool cannot silently skip one prompt-surface integration point.
+ */
+export const ACTIVE_TOOL_IDS = [
+    "mmc_reduce",
+    "mmc_expand",
+    "mmc_note",
+    "mmc_memory",
+    "mmc_search",
+] as const;
+
+/** @deprecated Use ACTIVE_TOOL_IDS. Kept as an alias for existing consumers. */
+export const PROMPT_SURFACE_TOOL_IDS = ACTIVE_TOOL_IDS;
+
+export type PromptSurfaceToolId = (typeof ACTIVE_TOOL_IDS)[number];
+
+export const LIGHT_TOOL_DESCRIPTIONS = {
+    mmc_reduce: CTX_REDUCE_LIGHT_DESCRIPTION,
+    mmc_expand: CTX_EXPAND_LIGHT_DESCRIPTION,
+    mmc_note: CTX_NOTE_LIGHT_DESCRIPTION,
+    mmc_memory: CTX_MEMORY_LIGHT_DESCRIPTION,
+    mmc_search: CTX_SEARCH_LIGHT_DESCRIPTION,
+} as const satisfies Readonly<Record<PromptSurfaceToolId, string>>;
+
+/**
+ * Preserve the existing full-preset hash exactly while giving other presets a
+ * distinct semantic cache identity, including during any future asset fallback.
+ */
+export function promptSurfaceHashMaterial(
+    systemContent: string,
+    preset: PromptSurfacePreset = "full",
+): string {
+    return preset === "full"
+        ? systemContent
+        : `${systemContent}\n\0magic-context-prompt-surface:${preset}`;
+}
+
+const PROMPT_SURFACE_TOOL_ID_SET = new Set<string>(ACTIVE_TOOL_IDS);
+
+export interface PromptSurfaceGuidanceSelection {
+    /** The configured built-in preset. */
+    preset: PromptSurfacePreset;
+    /** Complete user-authored primary section captured when a model-key epoch starts. */
+    primaryOverride?: string;
+}
+
+export interface PromptSurfaceRegistrationSelection {
+    preset: PromptSurfacePreset;
+    descriptionFor: (toolId: string, fullDescription: string) => string;
+}
+
+export interface PromptSurfaceRuntime {
+    resolveRegistration: (
+        config: PromptSurfaceConfig | undefined,
+        modelKey?: string,
+    ) => PromptSurfaceRegistrationSelection;
+    resolveGuidance: (
+        config: PromptSurfaceConfig | undefined,
+        modelKey: string | undefined,
+    ) => PromptSurfaceGuidanceSelection;
+}
+
+export interface CreatePromptSurfaceRuntimeOptions {
+    /** Optional harness tag; retained for call-site compatibility and diagnostics. */
+    harness?: HarnessId;
+    directory?: string;
+    /** Explicit test/integration seam; production derives the USER config directory. */
+    userConfigDirectory?: string;
+    warn: (message: string) => void;
+}
+
+function resolveUserConfigDirectory(options: CreatePromptSurfaceRuntimeOptions): string {
+    if (options.userConfigDirectory) return resolve(options.userConfigDirectory);
+    return dirname(opencodeUserConfigBasePath());
+}
+
+function markerCount(content: string): number {
+    return content.match(GUIDANCE_MARKER_LINE)?.length ?? 0;
+}
+
+/**
+ * Create one host-registration runtime. Its warning set is shared by tool
+ * registration and every guidance epoch, so invalid overrides are reported once
+ * instead of on every model call.
+ */
+export function createPromptSurfaceRuntime(
+    options: CreatePromptSurfaceRuntimeOptions,
+): PromptSurfaceRuntime {
+    const userConfigDirectory = resolveUserConfigDirectory(options);
+    const warned = new Set<string>();
+
+    const warnOnce = (key: string, message: string): void => {
+        if (warned.has(key)) return;
+        warned.add(key);
+        options.warn(message);
+    };
+
+    const readGuidanceOverride = (configuredPath: string | undefined): string | undefined => {
+        if (!configuredPath) return undefined;
+        const path = isAbsolute(configuredPath)
+            ? configuredPath
+            : resolve(userConfigDirectory, configuredPath);
+
+        let content: string;
+        try {
+            if (!statSync(path).isFile()) {
+                warnOnce(
+                    `guidance-not-file:${path}`,
+                    `prompt_surface.guidance_override_path (${path}) is not a file; using built-in guidance.`,
+                );
+                return undefined;
+            }
+            content = readFileSync(path, "utf8");
+        } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            warnOnce(
+                `guidance-unreadable:${path}:${reason}`,
+                `prompt_surface.guidance_override_path (${path}) could not be read (${reason}); using built-in guidance.`,
+            );
+            return undefined;
+        }
+
+        if (content.trim().length === 0) {
+            warnOnce(
+                `guidance-empty:${path}`,
+                `prompt_surface.guidance_override_path (${path}) is empty; using built-in guidance.`,
+            );
+            return undefined;
+        }
+
+        const markers = markerCount(content);
+        if (markers !== 1) {
+            warnOnce(
+                `guidance-marker-count:${path}:${markers}`,
+                `prompt_surface.guidance_override_path (${path}) must contain exactly one ${JSON.stringify(GUIDANCE_MARKER)} section marker; found ${markers}. Using built-in guidance.`,
+            );
+            return undefined;
+        }
+
+        return content;
+    };
+
+    return {
+        resolveRegistration(config, modelKey) {
+            // OpenCode 1.x and Pi expose one immutable provider tool map per host
+            // registration, so callers omit modelKey and only the default preset
+            // can choose text. OpenCode 2 rewrites draft.tools per request and
+            // passes the draft model so the same resolver honors model routes.
+            const { preset } = resolvePromptSurface(config, modelKey);
+
+            const overrides = config?.tool_descriptions ?? {};
+            for (const [toolId, description] of Object.entries(overrides)) {
+                if (!PROMPT_SURFACE_TOOL_ID_SET.has(toolId)) {
+                    warnOnce(
+                        `unknown-tool:${toolId}`,
+                        `prompt_surface.tool_descriptions.${toolId} is not a known mmc_* tool ID; the override was ignored.`,
+                    );
+                } else if (description.trim().length === 0) {
+                    warnOnce(
+                        `empty-tool:${toolId}`,
+                        `prompt_surface.tool_descriptions.${toolId} is empty; the override was ignored.`,
+                    );
+                }
+            }
+
+            return {
+                preset,
+                descriptionFor(toolId, fullDescription) {
+                    if (!PROMPT_SURFACE_TOOL_ID_SET.has(toolId)) return fullDescription;
+                    const override = overrides[toolId];
+                    if (override !== undefined && override.trim().length > 0) return override;
+                    return preset === "light"
+                        ? LIGHT_TOOL_DESCRIPTIONS[toolId as PromptSurfaceToolId]
+                        : fullDescription;
+                },
+            };
+        },
+
+        resolveGuidance(config, modelKey) {
+            const { preset } = resolvePromptSurface(config, modelKey);
+            return {
+                preset,
+                primaryOverride: readGuidanceOverride(config?.guidance_override_path),
+            };
+        },
+    };
+}
+
+interface GuidanceEpoch {
+    config: PromptSurfaceConfig | undefined;
+    modelKey: string | undefined;
+    selection: PromptSurfaceGuidanceSelection;
+}
+
+export interface PromptSurfaceGuidanceEpochCache {
+    resolve: (
+        sessionId: string,
+        config: PromptSurfaceConfig | undefined,
+        modelKey: string | undefined,
+    ) => PromptSurfaceGuidanceSelection;
+    clear: (sessionId: string) => void;
+}
+
+const guidanceEpochCacheByRuntime = new WeakMap<
+    PromptSurfaceRuntime,
+    PromptSurfaceGuidanceEpochCache
+>();
+
+/**
+ * Freeze preset selection and materialized override bytes for one model-key epoch.
+ * Every hook using the same runtime also shares this cache, so a file edit cannot
+ * make the system hook and Rust adapter observe different bytes within one epoch.
+ */
+export function createPromptSurfaceGuidanceEpochCache(
+    runtime: PromptSurfaceRuntime,
+): PromptSurfaceGuidanceEpochCache {
+    const shared = guidanceEpochCacheByRuntime.get(runtime);
+    if (shared) return shared;
+
+    const epochs = new Map<string, GuidanceEpoch>();
+    const cache: PromptSurfaceGuidanceEpochCache = {
+        resolve(sessionId, config, modelKey) {
+            const canonicalModelKey = modelKey ? piModelRefToCanonical(modelKey) : undefined;
+            const cached = epochs.get(sessionId);
+            if (cached && cached.config === config && cached.modelKey === canonicalModelKey) {
+                return cached.selection;
+            }
+
+            const selection = runtime.resolveGuidance(config, canonicalModelKey);
+            epochs.set(sessionId, { config, modelKey: canonicalModelKey, selection });
+            return selection;
+        },
+        clear(sessionId) {
+            epochs.delete(sessionId);
+        },
+    };
+    guidanceEpochCacheByRuntime.set(runtime, cache);
+    return cache;
+}

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

@@ -0,0 +1,195 @@
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { resolveCacheTtl } from "../hooks/magic-context/event-resolvers";
+import {
+    modelKeyLookupOrder,
+    promptSurfaceConfigIdentity,
+    resolvePromptSurface,
+} from "./prompt-surface";
+
+describe("prompt-surface resolution", () => {
+    it("keeps cache_ttl and prompt-surface routing on the same lookup walk", () => {
+        const routes = {
+            "anthropic/claude/sonnet": "light" as const,
+            "openai/gpt-4o": "light" as const,
+            "google/*": "light" as const,
+            "CaseSensitive/model": "light" as const,
+            "progressive/base": "light" as const,
+            "bare-model": "light" as const,
+        };
+        const cacheTtl = {
+            default: "full",
+            ...Object.fromEntries(Object.entries(routes).map(([key, preset]) => [key, preset])),
+        };
+
+        const cases = [
+            ["anthropic/claude/sonnet", "light"],
+            ["anthropic/claude/other", "full"],
+            ["openai/gpt-4o", "light"],
+            ["openai/gpt-4o-mini", "light"],
+            ["google/gemini-pro", "light"],
+            ["casesensitive/model", "full"],
+            ["CaseSensitive/model", "light"],
+            ["progressive/base-extra", "light"],
+            ["provider/bare-model", "light"],
+            ["unknown/model", "full"],
+            [undefined, "full"],
+        ] as const;
+
+        for (const [modelKey, expected] of cases) {
+            const ttl = resolveCacheTtl(cacheTtl, modelKey);
+            const prompt = resolvePromptSurface({ default: "full", models: routes }, modelKey);
+
+            expect(ttl).toBe(expected);
+            expect(prompt.preset).toBe(expected);
+        }
+    });
+
+    it("resolves Pi-native and canonical model keys with canonical precedence", () => {
+        const nativeKey = "openai-codex/gpt-5.6-sol";
+        const canonicalKey = "openai/gpt-5.6-sol";
+
+        expect(resolveCacheTtl({ default: "5m", [nativeKey]: "60m" }, canonicalKey)).toBe("60m");
+        expect(
+            resolvePromptSurface(
+                { default: "full", models: { [nativeKey]: "light" } },
+                canonicalKey,
+            ),
+        ).toEqual({ preset: "light", source: "exact" });
+        expect(
+            resolveCacheTtl(
+                { default: "5m", [nativeKey]: "60m", [canonicalKey]: "30m" },
+                nativeKey,
+            ),
+        ).toBe("30m");
+        expect(
+            resolvePromptSurface(
+                { default: "full", models: { [nativeKey]: "light", [canonicalKey]: "full" } },
+                nativeKey,
+            ),
+        ).toEqual({ preset: "full", source: "exact" });
+    });
+
+    it("leaves unknown provider keys unchanged", () => {
+        expect(
+            resolveCacheTtl(
+                { default: "5m", "custom-provider/model": "1m" },
+                "custom-provider/model",
+            ),
+        ).toBe("1m");
+        expect(modelKeyLookupOrder("custom-provider/model")[0]).toEqual({
+            key: "custom-provider/model",
+            source: "exact",
+        });
+    });
+
+    it("derives a stable config identity independent of object key order", () => {
+        const left = promptSurfaceConfigIdentity({
+            default: "full",
+            models: { "provider/b": "light", "provider/a": "full" },
+            tool_descriptions: { mmc_search: "Search", mmc_note: "Note" },
+        });
+        const right = promptSurfaceConfigIdentity({
+            tool_descriptions: { mmc_note: "Note", mmc_search: "Search" },
+            models: { "provider/a": "full", "provider/b": "light" },
+            default: "full",
+        });
+        expect(left).toBe(right);
+        expect(
+            promptSurfaceConfigIdentity({ default: "light", models: { "provider/a": "full" } }),
+        ).not.toBe(right);
+    });
+
+    it("matches the Rust cache_ttl resolver over shared routing vectors", () => {
+        const vectors = JSON.parse(
+            readFileSync(
+                resolve(import.meta.dir, "../../testdata/cache-ttl-routing-vectors.json"),
+                "utf8",
+            ),
+        ) as {
+            default: string;
+            models: Record<string, string>;
+            cases: Array<{ name: string; modelKey: string; expected: string }>;
+        };
+        const config = { default: vectors.default, ...vectors.models };
+
+        for (const vector of vectors.cases) {
+            expect(resolveCacheTtl(config, vector.modelKey), vector.name).toBe(vector.expected);
+        }
+    });
+
+    it("applies exact, bare, wildcard, then default precedence", () => {
+        const config = {
+            default: "full" as const,
+            models: {
+                "provider/model": "light" as const,
+                bare: "light" as const,
+                "provider/*": "full" as const,
+            },
+        };
+
+        expect(resolvePromptSurface(config, "provider/model")).toEqual({
+            preset: "light",
+            source: "exact",
+        });
+        expect(resolvePromptSurface(config, "provider/bare")).toEqual({
+            preset: "light",
+            source: "bare",
+        });
+        expect(resolvePromptSurface(config, "provider/other")).toEqual({
+            preset: "full",
+            source: "wildcard",
+        });
+        expect(resolvePromptSurface(config, "other/model")).toEqual({
+            preset: "full",
+            source: "default",
+        });
+    });
+
+    it("preserves multi-slash model IDs and treats case differences literally", () => {
+        expect(modelKeyLookupOrder("provider/model/with/slashes")[0]).toEqual({
+            key: "provider/model/with/slashes",
+            source: "exact",
+        });
+        expect(
+            resolvePromptSurface(
+                {
+                    default: "full",
+                    models: { "provider/model/with/slashes": "light" },
+                },
+                "provider/model/with/slashes",
+            ),
+        ).toEqual({ preset: "light", source: "exact" });
+        expect(
+            resolvePromptSurface(
+                {
+                    default: "full",
+                    models: { "Provider/*": "light" },
+                },
+                "provider/model/with/slashes",
+            ),
+        ).toEqual({ preset: "full", source: "default" });
+    });
+
+    it("falls back when provider or model components are absent", () => {
+        const config = {
+            default: "light" as const,
+            models: { "provider/*": "full" as const },
+        };
+
+        expect(resolvePromptSurface(config, "provider")).toEqual({
+            preset: "light",
+            source: "default",
+        });
+        expect(resolvePromptSurface(config, "/model")).toEqual({
+            preset: "light",
+            source: "default",
+        });
+        expect(resolvePromptSurface(config, "provider/")).toEqual({
+            preset: "light",
+            source: "default",
+        });
+    });
+});