@cortexkit/opencode-magic-context 0.33.1 → 0.34.0

package/src/config/prune-config-leaf.ts

@@ -0,0 +1,68 @@
+/**
+ * Immutable nested-config-leaf pruning for config recovery.
+ *
+ * When Zod validation flags an invalid nested field, recovery prunes just that
+ * field and keeps valid siblings (so one bad value doesn't reset a whole block
+ * and silently restore disabled behavior via schema defaults). The naive version
+ * deleted the FIRST child under the top-level key (`path[1]`), which is wrong for
+ * paths deeper than two levels: an invalid `memory.git_commit_indexing.since_days`
+ * has `path = ["memory","git_commit_indexing","since_days"]`, and deleting
+ * `path[1]` ("git_commit_indexing") drops the entire sub-block — losing a
+ * user's `enabled: false` so the default `enabled: true` is restored.
+ *
+ * `pruneNestedConfigLeaf` walks the full path and removes only the deepest leaf,
+ * deep-cloning each object along the way so sibling values (and the caller's
+ * original object) are never mutated.
+ */
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Remove a single nested leaf from `block`, given a path RELATIVE to it
+ * (i.e. the Zod issue path with its top-level key sliced off). Returns the new
+ * block plus the dotted label of the removed leaf, or null when the path can't
+ * be fully navigated to an object that contains the leaf.
+ */
+export function pruneNestedConfigLeaf(
+    block: Record<string, unknown>,
+    relativePath: readonly PropertyKey[],
+): { block: Record<string, unknown>; removed: string } | null {
+    if (relativePath.length === 0) return null;
+
+    const result: Record<string, unknown> = { ...block };
+    let cursor = result;
+
+    // Navigate to the parent of the leaf, cloning each intermediate object so
+    // the original (and untouched siblings) are preserved.
+    for (let i = 0; i < relativePath.length - 1; i++) {
+        const seg = String(relativePath[i]);
+        const child = cursor[seg];
+        if (!isPlainObject(child)) {
+            // The path descends into a non-object (e.g. an ARRAY element, like an
+            // invalid `system_prompt_injection.skip_signatures[0]`). We can't reach
+            // the deeper leaf — but we CAN prune the nearest OWNING field (the
+            // array/primitive at `seg`) so it falls back to its schema default,
+            // preserving valid siblings. Without this we'd return null → the whole
+            // config collapses to all-defaults, dropping unrelated user settings.
+            if (!(seg in cursor)) return null;
+            delete cursor[seg];
+            return {
+                block: result,
+                removed: relativePath
+                    .slice(0, i + 1)
+                    .map(String)
+                    .join("."),
+            };
+        }
+        const clonedChild: Record<string, unknown> = { ...child };
+        cursor[seg] = clonedChild;
+        cursor = clonedChild;
+    }
+
+    const leaf = String(relativePath[relativePath.length - 1]);
+    if (!(leaf in cursor)) return null;
+    delete cursor[leaf];
+    return { block: result, removed: relativePath.map(String).join(".") };
+}

package/src/config/removed-config-keys.test.ts

@@ -0,0 +1,116 @@
+/// <reference types="bun-types" />
+
+// Regression guard: the `auto_drop_tool_age` and `drop_tool_structure` config
+// keys (and their camelCase threads `autoDropToolAge` / `dropToolStructure`)
+// were REMOVED in Phase 2 — routine age-based tool drops were replaced by the
+// tiered target-headroom emergency drop, which always full-drops. No production
+// source in the plugin or Pi packages may reference them; a stray reference
+// would either be dead code or a config the schema now rejects with a warning.
+//
+// This is a static source-text scan so it fails at test-time without runtime
+// mocking. Tests, generated files, and the doctor's deletion routine (which
+// must name the dead keys to strip them) are intentionally excluded.
+
+import { describe, expect, it } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const PLUGIN_SRC = join(__dirname, "..");
+const PI_SRC = join(__dirname, "..", "..", "..", "pi-plugin", "src");
+
+const FORBIDDEN = [
+    "auto_drop_tool_age",
+    "drop_tool_structure",
+    "autoDropToolAge",
+    "dropToolStructure",
+    // Nudge redesign removed the rolling/iteration nudge config entirely
+    // (Channel 1/2 replaced them). No schema key, no camelCase thread.
+    "nudge_interval_tokens",
+    "iteration_nudge_threshold",
+    "nudgeIntervalTokens",
+    "iterationNudgeThreshold",
+];
+
+// Files allowed to mention the dead keys: the CLI doctor names them to strip
+// them from existing user configs. (The doctor lives in packages/cli, not
+// scanned here, but keep this list as the documented exception surface.)
+const ALLOWED_BASENAMES = new Set<string>([]);
+
+function walkSourceFiles(dir: string, out: string[] = []): string[] {
+    let entries: string[];
+    try {
+        entries = readdirSync(dir);
+    } catch {
+        return out; // package not present in this checkout
+    }
+    for (const entry of entries) {
+        if (entry === "node_modules" || entry === "dist") continue;
+        const full = join(dir, entry);
+        const s = statSync(full);
+        if (s.isDirectory()) {
+            walkSourceFiles(full, out);
+        } else if (
+            s.isFile() &&
+            entry.endsWith(".ts") &&
+            !entry.endsWith(".test.ts") &&
+            !entry.endsWith(".gen.ts") &&
+            !ALLOWED_BASENAMES.has(entry)
+        ) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+
+function scanForForbidden(files: string[]): string[] {
+    const offenders: string[] = [];
+    for (const file of files) {
+        let text: string;
+        try {
+            text = readFileSync(file, "utf-8");
+        } catch {
+            continue; // file absent in this checkout
+        }
+        for (const key of FORBIDDEN) {
+            if (text.includes(key)) offenders.push(`${file}: ${key}`);
+        }
+    }
+    return offenders;
+}
+
+const REPO_ROOT = join(__dirname, "..", "..", "..", "..");
+
+describe("removed Phase 2 config keys", () => {
+    it("no production source references auto_drop_tool_age / drop_tool_structure", () => {
+        const files = [...walkSourceFiles(PLUGIN_SRC), ...walkSourceFiles(PI_SRC)];
+        expect(scanForForbidden(files)).toEqual([]);
+    });
+
+    // The keys also leaked into docs, the generated schema, and e2e test
+    // configs (where they're silently ignored — the worst kind, since the test
+    // reads as if the knob still works). Guard those surfaces too so doc/config
+    // drift fails CI alongside source drift.
+    it("no docs / generated schema / e2e config references the removed keys", () => {
+        const docFiles = [
+            join(REPO_ROOT, "CONFIGURATION.md"),
+            join(REPO_ROOT, "README.md"),
+            join(REPO_ROOT, "assets", "magic-context.schema.json"),
+        ];
+        const e2eFiles = walkSourceFiles(join(REPO_ROOT, "packages", "e2e-tests", "tests")).filter(
+            // e2e tests are the consumer surface here, not unit tests of the
+            // keys — scan them despite the .test.ts skip in walkSourceFiles.
+            () => true,
+        );
+        // walkSourceFiles skips .test.ts, so collect e2e .test.ts explicitly.
+        const e2eDir = join(REPO_ROOT, "packages", "e2e-tests", "tests");
+        let e2eEntries: string[] = [];
+        try {
+            e2eEntries = readdirSync(e2eDir)
+                .filter((f) => f.endsWith(".ts"))
+                .map((f) => join(e2eDir, f));
+        } catch {
+            e2eEntries = [];
+        }
+        expect(scanForForbidden([...docFiles, ...e2eFiles, ...e2eEntries])).toEqual([]);
+    });
+});

package/src/config/schema/agent-overrides.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+const PermissionValueSchema = z.enum(["ask", "allow", "deny"]);
+
+const PermissionSchema = z
+    .object({
+        edit: PermissionValueSchema.optional(),
+        bash: z
+            .union([PermissionValueSchema, z.record(z.string(), PermissionValueSchema)])
+            .optional(),
+        webfetch: PermissionValueSchema.optional(),
+        doom_loop: PermissionValueSchema.optional(),
+        external_directory: PermissionValueSchema.optional(),
+    })
+    .optional();
+
+export const AgentOverrideConfigSchema = z.object({
+    model: z.string().optional().describe("Primary model ID (e.g. 'claude-sonnet-4-6')"),
+    temperature: z.number().min(0).max(2).optional().describe("Sampling temperature (0-2)"),
+    top_p: z.number().min(0).max(1).optional().describe("Nucleus sampling top_p (0-1)"),
+    prompt: z.string().optional().describe("Additional system prompt text"),
+    tools: z.record(z.string(), z.boolean()).optional().describe("Tool enable/disable overrides"),
+    disable: z.boolean().optional().describe("Disable this agent"),
+    description: z.string().optional().describe("Agent description"),
+    mode: z
+        .enum(["subagent", "primary", "all"])
+        .optional()
+        .describe("Agent mode (subagent, primary, or all)"),
+    color: z
+        .string()
+        .regex(/^#[0-9A-Fa-f]{6}$/)
+        .optional()
+        .describe("Hex color for the agent (e.g. '#a1b2c3')"),
+    maxSteps: z.number().optional().describe("Maximum tool-call steps per invocation"),
+    permission: PermissionSchema.describe("Per-tool permission overrides"),
+    maxTokens: z.number().optional().describe("Maximum output tokens"),
+    variant: z
+        .string()
+        .optional()
+        .describe("OpenCode reasoning variant (e.g. for extended thinking)"),
+    fallback_models: z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .describe("Fallback model IDs if primary is unavailable"),
+});

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

@@ -0,0 +1,358 @@
+import { describe, expect, it } from "bun:test";
+import {
+    DEFAULT_HISTORIAN_TIMEOUT_MS,
+    DEFAULT_HISTORY_BUDGET_PERCENTAGE,
+    DEFAULT_LOCAL_EMBEDDING_MODEL,
+    type MagicContextConfig,
+    MagicContextConfigSchema,
+} from "./magic-context";
+
+describe("MagicContextConfigSchema", () => {
+    describe("defaults", () => {
+        it("applies defaults for an empty config", () => {
+            const result = MagicContextConfigSchema.parse({});
+
+            expect(result).toMatchObject({
+                enabled: true,
+                allow_home_project: false,
+                fail_closed_blocking: true,
+                transform_mode: "ts",
+                storage: { enforce_private_permissions: true },
+                cache_ttl: "5m",
+                execute_threshold_percentage: 65,
+                protected_tags: 20,
+                clear_reasoning_age: 50,
+                history_budget_percentage: DEFAULT_HISTORY_BUDGET_PERCENTAGE,
+                historian_timeout_ms: DEFAULT_HISTORIAN_TIMEOUT_MS,
+                embedding: {
+                    provider: "local",
+                    model: DEFAULT_LOCAL_EMBEDDING_MODEL,
+                },
+                memory: {
+                    enabled: true,
+                    injection_budget_tokens: 4000,
+                    auto_promote: true,
+                    retrieval_count_promotion_threshold: 3,
+                },
+                todowrite: {
+                    enabled: true,
+                    overlay: true,
+                },
+            });
+            expect(result.historian).toBeUndefined();
+            expect(result.dreamer).toBeUndefined();
+            expect(result.sidekick).toBeUndefined();
+            expect(result.pi).toBeUndefined();
+        });
+    });
+
+    describe("budget configuration", () => {
+        it("accepts 90% execute thresholds and rejects 91%", () => {
+            expect(
+                MagicContextConfigSchema.safeParse({ execute_threshold_percentage: 90 }).success,
+            ).toBe(true);
+            expect(
+                MagicContextConfigSchema.safeParse({ execute_threshold_percentage: 91 }).success,
+            ).toBe(false);
+        });
+
+        it("accepts numeric and per-model output reserves including zero", () => {
+            expect(MagicContextConfigSchema.parse({ output_reserve: 0 }).output_reserve).toBe(0);
+            expect(
+                MagicContextConfigSchema.parse({
+                    output_reserve: { default: 16_384, "google/gemini": 0 },
+                }).output_reserve,
+            ).toEqual({ default: 16_384, "google/gemini": 0 });
+            expect(MagicContextConfigSchema.safeParse({ output_reserve: -1 }).success).toBe(false);
+        });
+    });
+
+    describe("valid config", () => {
+        it("parses an enabled config without stale reduction-specific keys", () => {
+            const input = {
+                enabled: true,
+                allow_home_project: false,
+                fail_closed_blocking: true,
+                experimental: { mural: { enabled: false } },
+                transform_mode: "ts",
+                auto_update: false,
+                toast_duration_ms: 5000,
+                cache_ttl: "10m",
+                protected_tags: 3,
+                execute_threshold_percentage: 75,
+                clear_reasoning_age: 60,
+                history_budget_percentage: 0.2,
+                historian_timeout_ms: 360_000,
+                commit_cluster_trigger: {
+                    enabled: true,
+                    min_clusters: 3,
+                },
+                sqlite: {
+                    cache_size_mb: 64,
+                    mmap_size_mb: 0,
+                },
+                storage: {
+                    enforce_private_permissions: false,
+                },
+                system_prompt_injection: {
+                    enabled: true,
+                    skip_signatures: ["<!-- magic-context: skip -->"],
+                },
+                temporal_awareness: false,
+                keep_subagents: false,
+                todowrite: {
+                    enabled: false,
+                    overlay: false,
+                },
+                smart_drops: false,
+                shadow_embedding: {
+                    enabled: false,
+                },
+                caveman_text_compression: {
+                    enabled: false,
+                    min_chars: 500,
+                },
+                embedding: {
+                    provider: "openai-compatible",
+                    endpoint: "http://localhost:1234/v1",
+                    model: "text-embedding-3-small",
+                    api_key: "secret-embedding",
+                },
+                memory: {
+                    enabled: true,
+                    injection_budget_tokens: 4000,
+                    auto_promote: true,
+                    retrieval_count_promotion_threshold: 3,
+                    auto_search: {
+                        enabled: false,
+                        score_threshold: 0.6,
+                        min_prompt_chars: 20,
+                    },
+                    git_commit_indexing: {
+                        enabled: false,
+                        since_days: 365,
+                        max_commits: 2000,
+                    },
+                },
+                pi: {
+                    subagent_extensions: ["@example/provider", "./extensions/local.ts"],
+                },
+                sidekick: {
+                    disable: false,
+                    model: "qwen-test",
+                    fallback_models: ["qwen-fallback"],
+                    temperature: 0.1,
+                    variant: "fast",
+                    timeout_ms: 12_000,
+                    system_prompt: "Custom prompt",
+                },
+                compaction: {
+                    enabled: true,
+                },
+            } satisfies MagicContextConfig;
+
+            const result = MagicContextConfigSchema.parse(input);
+
+            expect(result).toEqual(input);
+        });
+
+        it("accepts a boolean storage permission policy and rejects non-booleans", () => {
+            expect(
+                MagicContextConfigSchema.parse({
+                    storage: { enforce_private_permissions: false },
+                }).storage.enforce_private_permissions,
+            ).toBe(false);
+            expect(
+                MagicContextConfigSchema.safeParse({
+                    storage: { enforce_private_permissions: "false" },
+                }).success,
+            ).toBe(false);
+        });
+
+        it("applies sidekick defaults when the object is present", () => {
+            const result = MagicContextConfigSchema.parse({
+                sidekick: {
+                    model: "github-copilot/gpt-5.4",
+                },
+            });
+
+            expect(result.sidekick).toEqual({
+                model: "github-copilot/gpt-5.4",
+                timeout_ms: 30000,
+            });
+        });
+
+        it("accepts disable on hidden agents and strips deprecated top-level enabled", () => {
+            const result = MagicContextConfigSchema.parse({
+                historian: { disable: true },
+                dreamer: {
+                    disable: true,
+                    enabled: true,
+                    // Dreamer v2: per-task config. review-user-memories disabled,
+                    // maintain-docs scheduled.
+                    tasks: {
+                        "review-user-memories": { schedule: "" },
+                        "maintain-docs": { schedule: "0 * * * *" },
+                    },
+                },
+                sidekick: { disable: true, enabled: true },
+            });
+
+            expect(result.historian?.disable).toBe(true);
+            expect(result.dreamer?.disable).toBe(true);
+            expect(result.sidekick?.disable).toBe(true);
+            expect("enabled" in (result.dreamer as Record<string, unknown>)).toBe(false);
+            expect("enabled" in (result.sidekick as Record<string, unknown>)).toBe(false);
+            expect(result.dreamer?.tasks["review-user-memories"].schedule).toBe("");
+            expect(result.dreamer?.tasks["maintain-docs"].schedule).toBe("0 * * * *");
+            expect(result.dreamer?.tasks["classify-memories"].schedule).toBe("0 6 * * *");
+            expect(result.dreamer?.tasks.retrospective.schedule).toBe("0 5 * * *");
+        });
+
+        it("defaults classify-memories and retrospective on daily in dreamer task schema", () => {
+            const result = MagicContextConfigSchema.parse({ dreamer: { model: "x/y" } });
+            expect(result.dreamer?.tasks["classify-memories"].schedule).toBe("0 6 * * *");
+            expect(result.dreamer?.tasks.retrospective.schedule).toBe("0 5 * * *");
+        });
+
+        it("parses both transform modes", () => {
+            expect(MagicContextConfigSchema.parse({ transform_mode: "ts" }).transform_mode).toBe(
+                "ts",
+            );
+            expect(MagicContextConfigSchema.parse({ transform_mode: "rust" }).transform_mode).toBe(
+                "rust",
+            );
+        });
+
+        it("accepts optional auto_update user preference", () => {
+            expect(MagicContextConfigSchema.parse({ auto_update: false }).auto_update).toBe(false);
+            expect(MagicContextConfigSchema.parse({ auto_update: true }).auto_update).toBe(true);
+        });
+
+        it("accepts an explicitly configured Pi subagent extension allowlist", () => {
+            expect(
+                MagicContextConfigSchema.parse({
+                    pi: { subagent_extensions: ["provider-package", "./local.ts"] },
+                }).pi,
+            ).toEqual({ subagent_extensions: ["provider-package", "./local.ts"] });
+        });
+
+        it("accepts and normalizes 2-letter ISO 639-1 language codes", () => {
+            expect(MagicContextConfigSchema.parse({ language: "tr" }).language).toBe("tr");
+            expect(MagicContextConfigSchema.parse({ language: "  ES " }).language).toBe("es");
+            expect(MagicContextConfigSchema.parse({ language: "ja" }).language).toBe("ja");
+        });
+
+        it("parses per-model cache_ttl objects", () => {
+            const input = {
+                cache_ttl: {
+                    default: "5m",
+                    "claude-3-haiku": "10m",
+                    "gpt-4": "2m",
+                },
+            };
+
+            const result = MagicContextConfigSchema.parse(input);
+
+            expect(result.cache_ttl).toEqual(input.cache_ttl);
+        });
+    });
+
+    describe("validation", () => {
+        it("rejects an unknown transform mode", () => {
+            expect(() => MagicContextConfigSchema.parse({ transform_mode: "wasm" })).toThrow();
+        });
+
+        it("rejects empty Pi subagent extension entries", () => {
+            expect(() =>
+                MagicContextConfigSchema.parse({ pi: { subagent_extensions: ["  "] } }),
+            ).toThrow();
+        });
+
+        it("rejects protected_tags greater than 100", () => {
+            expect(() => MagicContextConfigSchema.parse({ protected_tags: 101 })).toThrow();
+        });
+
+        it("rejects protected_tags less than 1", () => {
+            expect(() => MagicContextConfigSchema.parse({ protected_tags: 0 })).toThrow();
+        });
+
+        it("accepts protected_tags boundary values", () => {
+            expect(MagicContextConfigSchema.parse({ protected_tags: 1 }).protected_tags).toBe(1);
+            expect(MagicContextConfigSchema.parse({ protected_tags: 20 }).protected_tags).toBe(20);
+        });
+
+        it("rejects clear_reasoning_age below minimum", () => {
+            expect(() => MagicContextConfigSchema.parse({ clear_reasoning_age: 9 })).toThrow();
+        });
+
+        it("rejects historian_timeout_ms below minimum", () => {
+            expect(() =>
+                MagicContextConfigSchema.parse({ historian_timeout_ms: 59_999 }),
+            ).toThrow();
+        });
+
+        it("rejects non-code output language values", () => {
+            expect(() => MagicContextConfigSchema.parse({ language: "Turkish" })).toThrow(); // full name
+            expect(() => MagicContextConfigSchema.parse({ language: "tur" })).toThrow(); // 3-letter
+            expect(() => MagicContextConfigSchema.parse({ language: "zz" })).toThrow(); // unknown code
+            expect(() => MagicContextConfigSchema.parse({ language: "<x>" })).toThrow();
+        });
+
+        it("rejects openai-compatible embedding config without endpoint", () => {
+            expect(() =>
+                MagicContextConfigSchema.parse({
+                    embedding: {
+                        provider: "openai-compatible",
+                        model: "text-embedding-3-small",
+                    },
+                }),
+            ).toThrow();
+        });
+
+        it("rejects openai-compatible embedding config without model", () => {
+            expect(() =>
+                MagicContextConfigSchema.parse({
+                    embedding: {
+                        provider: "openai-compatible",
+                        endpoint: "http://localhost:1234/v1",
+                    },
+                }),
+            ).toThrow();
+        });
+
+        it("accepts a configured local embedding dtype", () => {
+            const result = MagicContextConfigSchema.parse({
+                embedding: {
+                    provider: "local",
+                    model: "Xenova/paraphrase-multilingual-MiniLM-L12-v2",
+                    local_dtype: "q8",
+                },
+            });
+            expect(result.embedding).toEqual({
+                provider: "local",
+                model: "Xenova/paraphrase-multilingual-MiniLM-L12-v2",
+                local_dtype: "q8",
+            });
+        });
+
+        it("omits local_dtype from the resolved config when unset (preserves default identity)", () => {
+            const result = MagicContextConfigSchema.parse({
+                embedding: { provider: "local" },
+            });
+            expect(result.embedding).toEqual({
+                provider: "local",
+                model: DEFAULT_LOCAL_EMBEDDING_MODEL,
+            });
+            expect("local_dtype" in result.embedding).toBe(false);
+        });
+
+        it("rejects an unsupported local embedding dtype", () => {
+            expect(() =>
+                MagicContextConfigSchema.parse({
+                    embedding: { provider: "local", local_dtype: "fp64" },
+                }),
+            ).toThrow();
+        });
+    });
+});