@cortexkit/opencode-magic-context 0.34.1 → 0.35.0

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

@@ -0,0 +1,250 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+import {
+    type ConfigHarness,
+    cortexKitUserConfigBasePath,
+    resolveLegacyConfigSourcesForHarness,
+} from "../config/migrate-config-location";
+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 { detectConfigFile } from "./jsonc-parser";
+import {
+    type PromptSurfaceConfig,
+    type PromptSurfacePreset,
+    resolvePromptSurface,
+} from "./prompt-surface";
+
+const GUIDANCE_MARKER = "## Magic Context";
+const GUIDANCE_MARKER_LINE = /^## Magic Context[\t ]*\r?$/gm;
+
+export const PROMPT_SURFACE_TOOL_IDS = [
+    "ctx_reduce",
+    "ctx_expand",
+    "ctx_note",
+    "ctx_memory",
+    "ctx_search",
+] as const;
+
+export type PromptSurfaceToolId = (typeof PROMPT_SURFACE_TOOL_IDS)[number];
+
+export const LIGHT_TOOL_DESCRIPTIONS: Readonly<Record<PromptSurfaceToolId, string>> = {
+    ctx_reduce: CTX_REDUCE_LIGHT_DESCRIPTION,
+    ctx_expand: CTX_EXPAND_LIGHT_DESCRIPTION,
+    ctx_note: CTX_NOTE_LIGHT_DESCRIPTION,
+    ctx_memory: CTX_MEMORY_LIGHT_DESCRIPTION,
+    ctx_search: CTX_SEARCH_LIGHT_DESCRIPTION,
+};
+
+/**
+ * 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>(PROMPT_SURFACE_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,
+    ) => PromptSurfaceRegistrationSelection;
+    resolveGuidance: (
+        config: PromptSurfaceConfig | undefined,
+        modelKey: string | undefined,
+    ) => PromptSurfaceGuidanceSelection;
+}
+
+export interface CreatePromptSurfaceRuntimeOptions {
+    harness?: ConfigHarness;
+    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);
+
+    const sharedBase = cortexKitUserConfigBasePath();
+    const shared = detectConfigFile(sharedBase);
+    if (shared.format !== "none") return dirname(shared.path);
+
+    if (options.harness) {
+        const legacy = resolveLegacyConfigSourcesForHarness(
+            options.directory ?? process.cwd(),
+            options.harness,
+        ).user.find((source) => existsSync(source.path));
+        if (legacy) return dirname(legacy.path);
+    }
+
+    return dirname(sharedBase);
+}
+
+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) {
+            // OpenCode and Pi expose one immutable provider tool map per host
+            // registration. Model routes are intentionally ignored here: only the
+            // registration owner's default and user-tier overrides can choose text.
+            const { preset } = resolvePromptSurface(config, undefined);
+
+            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 ctx_* 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;
+}
+
+/** Freeze preset selection and materialized override bytes for one model-key epoch. */
+export function createPromptSurfaceGuidanceEpochCache(runtime: PromptSurfaceRuntime): {
+    resolve: (
+        sessionId: string,
+        config: PromptSurfaceConfig | undefined,
+        modelKey: string | undefined,
+    ) => PromptSurfaceGuidanceSelection;
+    clear: (sessionId: string) => void;
+} {
+    const epochs = new Map<string, GuidanceEpoch>();
+
+    return {
+        resolve(sessionId, config, modelKey) {
+            const cached = epochs.get(sessionId);
+            if (cached && cached.config === config && cached.modelKey === modelKey) {
+                return cached.selection;
+            }
+
+            const selection = runtime.resolveGuidance(config, modelKey);
+            epochs.set(sessionId, { config, modelKey, selection });
+            return selection;
+        },
+        clear(sessionId) {
+            epochs.delete(sessionId);
+        },
+    };
+}

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

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "bun:test";
+
+import { resolveCacheTtl } from "../hooks/magic-context/event-resolvers";
+import { modelKeyLookupOrder, 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,
+        };
+        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"],
+            ["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("applies exact, wildcard, then default precedence", () => {
+        const config = {
+            default: "full" as const,
+            models: {
+                "provider/model": "light" as const,
+                "provider/*": "full" as const,
+            },
+        };
+
+        expect(resolvePromptSurface(config, "provider/model")).toEqual({
+            preset: "light",
+            source: "exact",
+        });
+        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",
+        });
+    });
+});

package/src/shared/prompt-surface.ts

@@ -0,0 +1,138 @@
+/** The built-in prompt-surface variants. */
+export type PromptSurfacePreset = "full" | "light";
+
+/**
+ * The configuration consumed by prompt-surface resolution. The schema adds
+ * validation and defaults; this structural type keeps the resolver usable by
+ * every host without importing a config loader.
+ */
+export interface PromptSurfaceConfig {
+    default?: PromptSurfacePreset;
+    models?: Readonly<Record<string, PromptSurfacePreset>>;
+    guidance_override_path?: string;
+    tool_descriptions?: Readonly<Record<string, string>>;
+}
+
+export type PromptSurfaceResolutionSource = "exact" | "wildcard" | "default";
+
+/** Validate the literal provider/model and provider/* key grammar. */
+export function isValidPromptSurfaceModelKey(key: string): boolean {
+    if (key.length === 0 || key.trim() !== key) return false;
+
+    const slash = key.indexOf("/");
+    if (slash <= 0 || slash === key.length - 1) return false;
+
+    const provider = key.slice(0, slash);
+    const modelID = key.slice(slash + 1);
+    if (
+        provider.trim() !== provider ||
+        modelID.trim() !== modelID ||
+        provider.includes("*") ||
+        (modelID.includes("*") && modelID !== "*")
+    ) {
+        return false;
+    }
+    if (modelID === "*") return true;
+
+    return (
+        modelID.length > 0 &&
+        !modelID.startsWith("/") &&
+        !modelID.endsWith("/") &&
+        !modelID.includes("//")
+    );
+}
+
+export type ModelKeyLookupSource = PromptSurfaceResolutionSource | "bare";
+
+export interface ModelKeyCandidate {
+    key: string;
+    source: ModelKeyLookupSource;
+}
+
+/**
+ * Return the same progressive model-key candidates used by cache_ttl. The
+ * provider/model boundary is the first slash; the rest of the string remains
+ * the model ID, including additional slashes. Candidates are case-sensitive.
+ *
+ * Provider wildcards are checked after progressively less-specific model keys,
+ * but before the caller's default. That keeps an exact or base-model override
+ * authoritative while still allowing `provider/*` to cover otherwise-unlisted
+ * models.
+ */
+export function modelKeyLookupOrder(modelKey: string | undefined): ModelKeyCandidate[] {
+    if (!modelKey) return [];
+
+    const slash = modelKey.indexOf("/");
+    if (slash <= 0 || slash === modelKey.length - 1) return [];
+
+    const provider = modelKey.slice(0, slash);
+    let modelID = modelKey.slice(slash + 1);
+    const candidates: ModelKeyCandidate[] = [];
+
+    while (modelID.length > 0) {
+        candidates.push({ key: `${provider}/${modelID}`, source: "exact" });
+        candidates.push({ key: modelID, source: "bare" });
+
+        const lastDash = modelID.lastIndexOf("-");
+        if (lastDash <= 0) break;
+        modelID = modelID.slice(0, lastDash);
+    }
+
+    candidates.push({ key: `${provider}/*`, source: "wildcard" });
+
+    const seen = new Set<string>();
+    return candidates.filter((candidate) => {
+        if (seen.has(candidate.key)) return false;
+        seen.add(candidate.key);
+        return true;
+    });
+}
+
+/** Resolve one per-model value using the shared cache_ttl lookup walk. */
+export function resolveModelConfigValue<T>(
+    values: Readonly<Record<string, T>> | undefined,
+    modelKey: string | undefined,
+): { value: T; source: ModelKeyLookupSource } | undefined {
+    if (!values) return undefined;
+
+    for (const candidate of modelKeyLookupOrder(modelKey)) {
+        const value = values[candidate.key];
+        if (value !== undefined) {
+            return { value, source: candidate.source };
+        }
+    }
+
+    return undefined;
+}
+
+/**
+ * Resolve the prompt preset for a model. Invalid or missing model keys use the
+ * configured default and are reported as a default resolution rather than a
+ * partial match.
+ */
+export function resolvePromptSurface(
+    config: PromptSurfaceConfig | undefined,
+    modelKey: string | undefined,
+): { preset: PromptSurfacePreset; source: PromptSurfaceResolutionSource } {
+    const fallback = config?.default ?? "full";
+    const match = resolveModelConfigValue(config?.models, modelKey);
+
+    // Bare model keys are accepted by cache_ttl for compatibility, but the
+    // prompt_surface schema deliberately accepts only provider/model keys and
+    // provider wildcards. Ignore a bare entry if an unvalidated object reaches
+    // this API so prompt routing keeps its documented grammar.
+    if (match && match.source !== "bare") {
+        return { preset: match.value, source: match.source };
+    }
+
+    return { preset: fallback, source: "default" };
+}
+
+/** Resolve a cache_ttl-style value with the shared model-key walk. */
+export function resolveModelConfigOrDefault<T>(
+    values: Readonly<Record<string, T>>,
+    modelKey: string | undefined,
+    fallback: T,
+): T {
+    return resolveModelConfigValue(values, modelKey)?.value ?? fallback;
+}