@cortexkit/opencode-magic-context 0.34.1 → 0.35.0

package/src/config/index.test.ts

@@ -934,3 +934,56 @@ describe("transform_mode resolution", () => {
         expect(result.subc?.connection_file).not.toContain("project-controlled.sock");
     });
 });
+
+describe("loadPluginConfigDetailed — prompt-surface registration owner", () => {
+    it("captures the user default before project guidance routing is merged", () => {
+        const xdg = mkdtempSync(join(tmpdir(), "mc-config-prompt-surface-"));
+        const projectDir = mkdtempSync(join(tmpdir(), "mc-project-prompt-surface-"));
+        const fs = require("node:fs") as typeof import("node:fs");
+        const userDir = join(xdg, "cortexkit");
+        const projectConfigDir = join(projectDir, ".cortexkit");
+        fs.mkdirSync(userDir, { recursive: true });
+        fs.mkdirSync(projectConfigDir, { recursive: true });
+        writeFileSync(
+            join(userDir, "magic-context.jsonc"),
+            JSON.stringify({
+                prompt_surface: {
+                    default: "light",
+                    guidance_override_path: "guidance.md",
+                    tool_descriptions: { ctx_search: "user text" },
+                },
+            }),
+        );
+        writeFileSync(
+            join(projectConfigDir, "magic-context.jsonc"),
+            JSON.stringify({
+                prompt_surface: {
+                    default: "full",
+                    models: { "openai/*": "light" },
+                },
+            }),
+        );
+        const originalXdg = process.env.XDG_CONFIG_HOME;
+        process.env.XDG_CONFIG_HOME = xdg;
+
+        try {
+            const result = loadPluginConfigDetailed(projectDir);
+            expect(result.config.prompt_surface).toEqual({
+                default: "full",
+                models: { "openai/*": "light" },
+                guidance_override_path: "guidance.md",
+                tool_descriptions: { ctx_search: "user text" },
+            });
+            expect(result.registrationPromptSurface).toEqual({
+                default: "light",
+                guidance_override_path: "guidance.md",
+                tool_descriptions: { ctx_search: "user text" },
+            });
+        } finally {
+            if (originalXdg === undefined) delete process.env.XDG_CONFIG_HOME;
+            else process.env.XDG_CONFIG_HOME = originalXdg;
+            rmSync(xdg, { recursive: true, force: true });
+            rmSync(projectDir, { recursive: true, force: true });
+        }
+    });
+});

package/src/config/index.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 
 import { detectConfigFile, parseJsonc } from "../shared/jsonc-parser";
 import { setOutputReserveConfig } from "../shared/models-dev-cache";
+import type { PromptSurfaceConfig } from "../shared/prompt-surface";
 import { isCompactionEnabled, migrateLegacyAgentEnabledInMemory } from "./agent-disable";
 import {
     cortexKitProjectConfigBasePath,
@@ -82,6 +83,8 @@ export type LoadOutcome =
 
 export interface LoadResultDetailed {
     config: MagicContextPluginConfig & { configWarnings?: string[] };
+    /** USER-tier default/overrides captured before project routing is merged. */
+    registrationPromptSurface: PromptSurfaceConfig;
     loadOutcome: LoadOutcome;
     sources: {
         userConfig: LoadOutcome;
@@ -593,6 +596,7 @@ export function loadPluginConfigDetailed(directory: string): LoadResultDetailed
 
     return {
         config,
+        registrationPromptSurface: trustedBaseConfig.prompt_surface,
         loadOutcome: combinedOutcome({ sources, substitutionFailures, recoveredTopLevelKeys }),
         sources,
         substitutionFailures,

package/src/config/project-security.test.ts

@@ -48,6 +48,26 @@ describe("stripUnsafeProjectConfigFields", () => {
         expect(warnings.some((w) => w.includes("output_reserve"))).toBe(true);
     });
 
+    it("strips prompt-surface text overrides but keeps project routing", () => {
+        const raw: Record<string, unknown> = {
+            prompt_surface: {
+                default: "light",
+                models: { "openai/*": "full" },
+                guidance_override_path: "/repo/guidance.md",
+                tool_descriptions: { ctx_search: "repo-controlled text" },
+            },
+        };
+
+        const warnings = stripUnsafeProjectConfigFields(raw);
+
+        expect(raw.prompt_surface).toEqual({
+            default: "light",
+            models: { "openai/*": "full" },
+        });
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toContain("prompt_surface.guidance_override_path/tool_descriptions");
+    });
+
     it("strips language from project config", () => {
         const raw: Record<string, unknown> = { language: "tr", dreamer: { model: "x" } };
         const warnings = stripUnsafeProjectConfigFields(raw);

package/src/config/project-security.ts

@@ -16,6 +16,7 @@ import { DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE } from "./schema/magic-context";
 /** Hidden agents that run with elevated/autonomous capability. */
 const HIDDEN_AGENT_KEYS = ["historian", "dreamer", "sidekick"] as const;
 const HISTORIAN_USER_ONLY_FIELDS = ["model", "fallback_models"] as const;
+const PROMPT_SURFACE_USER_ONLY_FIELDS = ["guidance_override_path", "tool_descriptions"] as const;
 
 /**
  * Fields on a hidden-agent block that constitute a privilege-escalation /
@@ -217,6 +218,9 @@ function makeProjectThresholdWarning(field: string, reason: string): string {
  *    a cloned repo cannot choose a model that sends project memory to a provider.
  *  - `pi.subagent_extensions` — a cloned repo must not choose which extensions
  *    the user's Pi child processes load.
+ *  - `prompt_surface.guidance_override_path` / `tool_descriptions` — a repository
+ *    may select a reviewed preset, but must not inject arbitrary guidance or tool
+ *    description text into the user's provider-visible prompt.
  *  - hidden-agent `prompt`/`permission`/`tools` — a repo must not reprogram or
  *    re-permission the historian/dreamer/sidekick.
  */
@@ -290,6 +294,25 @@ export function stripUnsafeProjectConfigFields(projectRaw: Record<string, unknow
         );
     }
 
+    // Repositories may select preset routing, but project settings cannot add
+    // guidance or tool-description text to the provider-visible prompt; those
+    // user-only fields are removed before project settings are merged.
+    const promptSurface = projectRaw.prompt_surface;
+    if (isPlainObject(promptSurface)) {
+        const removed: string[] = [];
+        for (const field of PROMPT_SURFACE_USER_ONLY_FIELDS) {
+            if (field in promptSurface) {
+                delete promptSurface[field];
+                removed.push(field);
+            }
+        }
+        if (removed.length > 0) {
+            warnings.push(
+                `Ignoring prompt_surface.${removed.join("/")} from project config (security: repositories may select prompt presets but only user config may provide guidance or tool-description text).`,
+            );
+        }
+    }
+
     const pi = projectRaw.pi;
     if (isPlainObject(pi) && "subagent_extensions" in pi) {
         delete pi.subagent_extensions;

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

@@ -19,6 +19,7 @@ describe("MagicContextConfigSchema", () => {
                 transform_mode: "ts",
                 storage: { enforce_private_permissions: true },
                 cache_ttl: "5m",
+                prompt_surface: { default: "full" },
                 execute_threshold_percentage: 65,
                 protected_tags: 20,
                 clear_reasoning_age: 50,
@@ -79,6 +80,7 @@ describe("MagicContextConfigSchema", () => {
                 auto_update: false,
                 toast_duration_ms: 5000,
                 cache_ttl: "10m",
+                prompt_surface: { default: "full" },
                 protected_tags: 3,
                 execute_threshold_percentage: 75,
                 clear_reasoning_age: 60,
@@ -257,6 +259,23 @@ describe("MagicContextConfigSchema", () => {
 
             expect(result.cache_ttl).toEqual(input.cache_ttl);
         });
+
+        // Accepts preset routing, a guidance override path, and tool-description overrides.
+        it("parses prompt-surface defaults, routes, and user overrides", () => {
+            const promptSurface = {
+                default: "light" as const,
+                models: {
+                    "anthropic/claude/sonnet": "full" as const,
+                    "openai/*": "light" as const,
+                },
+                guidance_override_path: "./guidance.md",
+                tool_descriptions: { ctx_search: "Search project context" },
+            };
+
+            expect(
+                MagicContextConfigSchema.parse({ prompt_surface: promptSurface }).prompt_surface,
+            ).toEqual(promptSurface);
+        });
     });
 
     describe("validation", () => {
@@ -264,6 +283,45 @@ describe("MagicContextConfigSchema", () => {
             expect(() => MagicContextConfigSchema.parse({ transform_mode: "wasm" })).toThrow();
         });
 
+        it("rejects malformed prompt-surface model keys and empty override text", () => {
+            const malformedKeys = [
+                "",
+                "provider",
+                "/model",
+                "provider/",
+                "provider//model",
+                "provider/model*",
+                "provider/*/nested",
+                "provider//model",
+                "provider/model/",
+                "provider/ model",
+                "*/model",
+            ];
+            for (const key of malformedKeys) {
+                expect(
+                    MagicContextConfigSchema.safeParse({
+                        prompt_surface: { models: { [key]: "light" } },
+                    }).success,
+                ).toBe(false);
+            }
+
+            expect(
+                MagicContextConfigSchema.safeParse({
+                    prompt_surface: { guidance_override_path: "  " },
+                }).success,
+            ).toBe(false);
+            expect(
+                MagicContextConfigSchema.safeParse({
+                    prompt_surface: { tool_descriptions: { ctx_search: "  " } },
+                }).success,
+            ).toBe(false);
+            expect(
+                MagicContextConfigSchema.safeParse({
+                    prompt_surface: { tool_descriptions: { "  ": "description" } },
+                }).success,
+            ).toBe(false);
+        });
+
         it("rejects empty Pi subagent extension entries", () => {
             expect(() =>
                 MagicContextConfigSchema.parse({ pi: { subagent_extensions: ["  "] } }),

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

@@ -7,6 +7,7 @@ import type {
     AGENTIC_DREAM_TASKS,
     DreamTaskName,
 } from "../../features/magic-context/dreamer/task-registry";
+import { isValidPromptSurfaceModelKey } from "../../shared/prompt-surface";
 import { AgentOverrideConfigSchema } from "./agent-overrides";
 
 export const DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE = 65;
@@ -49,6 +50,60 @@ export const PiConfigSchema = z
     .optional();
 export type PiConfig = NonNullable<z.infer<typeof PiConfigSchema>>;
 
+/**
+ * Route the built-in prompt surface without changing guidance or tool registration.
+ * Project config can choose preset routing; only user config can provide override text.
+ */
+export const PromptSurfacePresetSchema = z.enum(["full", "light"]);
+export type { PromptSurfacePreset } from "../../shared/prompt-surface";
+
+const PromptSurfaceModelKeySchema = z.string().refine(isValidPromptSurfaceModelKey, {
+    message:
+        "Use a non-empty provider/model key or the literal provider/* wildcard; model IDs may contain additional slashes and matching is case-sensitive.",
+});
+// Tool-description keys must be non-empty IDs; harness-specific known-tool
+// validation can run when a user override is applied.
+const PromptSurfaceToolKeySchema = z.string().refine((value) => value.trim().length > 0, {
+    message: "tool description keys must not be empty or whitespace-only",
+});
+
+export const PromptSurfaceConfigSchema = z
+    .object({
+        default: PromptSurfacePresetSchema.default("full").describe(
+            'Fallback prompt-surface preset ("full" or "light").',
+        ),
+        models: z
+            .record(PromptSurfaceModelKeySchema, PromptSurfacePresetSchema)
+            .optional()
+            .describe(
+                "Literal per-model routing. Keys are provider/model or provider/*; matching is case-sensitive and preserves additional slashes in model IDs.",
+            ),
+        guidance_override_path: z
+            .string()
+            .refine((value) => value.trim().length > 0, {
+                message: "guidance_override_path must not be empty or whitespace-only",
+            })
+            .optional()
+            .describe(
+                "USER-LEVEL ONLY path to a complete primary guidance section. Relative paths resolve from the user config file.",
+            ),
+        tool_descriptions: z
+            .record(
+                PromptSurfaceToolKeySchema,
+                z.string().refine((value) => value.trim().length > 0, {
+                    message: "tool description values must not be empty or whitespace-only",
+                }),
+            )
+            .optional()
+            .describe(
+                "USER-LEVEL ONLY top-level description overrides keyed by ctx_* tool ID; parameter schemas and descriptions are unchanged.",
+            ),
+    })
+    .describe(
+        "Prompt-surface preset routing. Project config may select default/models, while guidance_override_path and tool_descriptions are user-level only.",
+    );
+export type PromptSurfaceConfig = z.infer<typeof PromptSurfaceConfigSchema>;
+
 /** A 5-field cron expression, or "" to disable the task. */
 const CronScheduleSchema = z
     .string()
@@ -416,6 +471,8 @@ export interface MagicContextConfig {
     historian?: HistorianConfig;
     dreamer?: DreamerConfig;
     cache_ttl: string | { default: string; [modelKey: string]: string };
+    /** Preset routing for guidance and provider-visible prompt surfaces. */
+    prompt_surface: PromptSurfaceConfig;
     /** User-only output-token reservation override. Zero disables reservation. */
     output_reserve?: number | { default: number; [modelKey: string]: number };
     /** TUI toast lifetime in milliseconds for Magic Context notifications. Default: 5000. */
@@ -637,6 +694,9 @@ export const MagicContextConfigSchema = z
             .describe(
                 'Cache TTL: string (e.g. "5m", "1h", "30s") or per-model object ({ default: "5m", "model-id": "10m" }). Set to "never" for lanes kept warm by an external keepwarm proxy — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time.',
             ),
+        prompt_surface: PromptSurfaceConfigSchema.default({ default: "full" }).describe(
+            "Prompt-surface presets: default is full; models use the literal provider/model or provider/* routing grammar. Guidance and tool-description overrides are user-level only. On OpenCode and Pi, per-model routing applies to the guidance block only: tool descriptions are registered once per process, so they follow the default preset (a v1 plugin-surface limitation; per-model tool descriptions are planned for the OpenCode v2 plugin API once the SDK stabilizes).",
+        ),
         output_reserve: z
             .union([
                 z.number().min(0),
@@ -828,7 +888,7 @@ export const MagicContextConfigSchema = z
                     .boolean()
                     .default(true)
                     .describe(
-                        "When false, Magic Context stops managing the context window and keeps its knowledge layer: memory and docs/user-profile/key-files injection through additive m[0]/m[1], raw-message FTS indexing, dreamer, notes, ctx_search, ctx_expand, ctx_memory, and /ctx-embed remain available. MC's historian/compartment preparation, tagging, markers, pruning, folding, drops, strips, splicing, synthetic context-management todos, temporal markers, nudges, and fail-closed blocking stop; ctx_expand remains a knowledge-surface tool. fail_closed_blocking is inert: a transform failure passes the input messages through without blocking or cancelling. This setting does not enable native compaction: OpenCode's compaction.auto / compaction.prune or Pi's equivalent owns the window, or nothing does. MC's compaction.enabled in magic-context.jsonc is distinct from OpenCode's compaction.auto / compaction.prune in opencode.jsonc; they are different files and different owners. On the first turn after disabling, a long session may trigger one native compaction cycle; MC removes only its own marker boundary, leaves native boundaries and stored compartments intact, and does no pre-trimming mitigation. Marker cleanup is lazy per session, so an unresumed session is cleaned when it is next resumed. If compaction is enabled again, run /ctx-wrapup when the historian is runnable to catch up. OpenCode peer verification against v1.18.4 confirms native compaction covers child sessions: subagents receive additive memory/docs injection and no MC reclaim in this mode, so keep subagent tasks small or leave compaction.enabled on for long subagent runs. If transform_mode is rust, compaction-off resolves to the TypeScript transform and emits one frozen boot warning because there is no Rust reduced-mode contract. This is boot-resolved and requires a process restart; project-tier compaction.enabled is stripped so a cloned repository cannot disable the user's setting. The sidebar reports raw usage as Context: <pct>% · native compaction or Context: <pct>% · no active compaction and does not show an MC execute-threshold fill. /ctx-wrapup, /ctx-recomp, /ctx-flush, and /ctx-session-upgrade refuse without context-management side effects; /ctx-embed remains functional. Raw content hidden by a native boundary before Magic Context's first pass is not retroactively indexed.",
+                        "When false, Magic Context stops managing the context window and keeps its knowledge layer: memory and docs/user-profile/key-files injection through additive m[0]/m[1], raw-message FTS indexing, dreamer, notes, ctx_search, ctx_expand, ctx_memory, and /ctx-embed remain available. MC's historian/compartment preparation, tagging, markers, pruning, folding, drops, strips, splicing, synthetic context-management todos, temporal markers, nudges, and fail-closed blocking stop; ctx_expand remains a knowledge-surface tool. fail_closed_blocking is inert: a transform failure passes the input messages through without blocking or cancelling. This setting does not enable native compaction: OpenCode's compaction.auto / compaction.prune or Pi's equivalent owns the window, or nothing does. MC's compaction.enabled in magic-context.jsonc is distinct from OpenCode's compaction.auto / compaction.prune in opencode.jsonc; they are different files and different owners. On the first turn after disabling, a long session may trigger one native compaction cycle; MC removes only its own marker boundary, leaves native boundaries and stored compartments intact, and does no pre-trimming mitigation. Marker cleanup is lazy per session, so an unresumed session is cleaned when it is next resumed. If compaction is enabled again, run /ctx-wrapup when the historian is runnable to catch up. OpenCode peer verification against v1.18.4 confirms native compaction covers child sessions: subagents receive additive memory/docs injection and no MC reclaim in this mode, so keep subagent tasks small or leave compaction.enabled on for long subagent runs. This is boot-resolved and requires a process restart; project-tier compaction.enabled is stripped so a cloned repository cannot disable the user's setting. The sidebar reports raw usage as Context: <pct>% · native compaction or Context: <pct>% · no active compaction and does not show an MC execute-threshold fill. /ctx-wrapup, /ctx-recomp, /ctx-flush, and /ctx-session-upgrade refuse without context-management side effects; /ctx-embed remains functional. Raw content hidden by a native boundary before Magic Context's first pass is not retroactively indexed.",
                     ),
             })
             .default({ enabled: true })

package/src/shared/index.ts

@@ -1,4 +1,6 @@
 export * from "./logger";
 export * from "./model-suggestion-retry";
 export * from "./normalize-sdk-response";
+export * from "./prompt-surface";
+export * from "./prompt-surface-runtime";
 export * from "./resolve-fallbacks";