fix: config recovery, lower threshold min, unbundle transformers, error logging

- Config validation failures now use per-field defaults instead of disabling entire plugin (closes #4)
- execute_threshold_percentage minimum lowered from 35 to 20
- Invalid config fields surface warnings to user via startup notification
- Revert @huggingface/transformers bundling back to external resolution
  (bundling broke sharp/onnxruntime-node native binary resolution)
- Logger now serializes Error objects as message + stack instead of {}

Author: ualtinok

CONFIGURATION.md

@@ -64,7 +64,7 @@ Higher-tier models with longer cache windows benefit from a longer TTL. Setting
 | `cache_ttl` | `string` or `object` | `"5m"` | Time after a response before applying pending ops. String or per-model map. |
 | `protected_tags` | `number` (1–100) | `20` | Last N active tags immune from immediate dropping. |
 | `nudge_interval_tokens` | `number` | `10000` | Minimum token growth between rolling nudges. |
-| `execute_threshold_percentage` | `number` (35–80) or `object` | `65` | Context usage that forces queued ops to execute. Capped at 80% max for cache safety. Supports per-model map. |
+| `execute_threshold_percentage` | `number` (20–80) or `object` | `65` | Context usage that forces queued ops to execute. Capped at 80% max for cache safety. Supports per-model map. |
 | `auto_drop_tool_age` | `number` | `100` | Auto-drop tool outputs older than N tags during execution. |
 | `clear_reasoning_age` | `number` | `50` | Clear thinking/reasoning blocks older than N tags. |
 | `iteration_nudge_threshold` | `number` | `15` | Consecutive assistant turns without user input before an iteration nudge. |

bun.lock

@@ -32,7 +32,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target bun --format esm --external @opencode-ai/plugin && bun build src/cli/index.ts --outfile dist/cli.js --target node --format esm && tsc --emitDeclarationOnly",
+    "build": "bun build src/index.ts --outdir dist --target bun --format esm --external @opencode-ai/plugin --external @huggingface/transformers && bun build src/cli/index.ts --outfile dist/cli.js --target node --format esm && tsc --emitDeclarationOnly",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.scripts.json",
     "test": "bun test",
     "lint": "biome check .",
@@ -44,14 +44,14 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
+    "@huggingface/transformers": "~3.7.6",
     "@opencode-ai/plugin": "^1.2.26",
     "@opencode-ai/sdk": "^1.2.26",
     "ai-tokenizer": "^1.0.6",
     "comment-json": "^4.6.2",
     "zod": "^4.1.8"
   },
   "devDependencies": {
-    "@huggingface/transformers": "~3.7.6",
     "@types/node": "^22.0.0",
     "bun-types": "^1.3.10",
     "typescript": "^5.8.0",

packages/plugin/package.json

@@ -83,7 +83,9 @@ function mergeConfigs(
     return config;
 }
 
-function parsePluginConfig(rawConfig: Record<string, unknown>): MagicContextPluginConfig {
+function parsePluginConfig(
+    rawConfig: Record<string, unknown>,
+): MagicContextPluginConfig & { configWarnings?: string[] } {
     const parsed = MagicContextConfigSchema.safeParse(rawConfig);
     const disabledHooks = Array.isArray(rawConfig.disabled_hooks)
         ? rawConfig.disabled_hooks.filter((value): value is string => typeof value === "string")
@@ -93,23 +95,68 @@ function parsePluginConfig(rawConfig: Record<string, unknown>): MagicContextPlug
             ? (rawConfig.command as MagicContextPluginConfig["command"])
             : undefined;
 
-    if (!parsed.success) {
-        // Return safe defaults with enabled:false so downstream code has all required fields
-        // instead of an incomplete cast that would produce undefined for 18+ properties.
-        const defaults = MagicContextConfigSchema.parse({});
-        return { ...defaults, enabled: false, disabled_hooks: disabledHooks, command };
+    if (parsed.success) {
+        return {
+            ...parsed.data,
+            disabled_hooks: disabledHooks,
+            command,
+        };
     }
 
-    const config: MagicContextPluginConfig = {
-        ...parsed.data,
-        disabled_hooks: disabledHooks,
-        command,
-    };
+    // Full parse failed — recover field-by-field using defaults for invalid fields.
+    // Agent configs (historian, dreamer, sidekick) are dropped on error rather than defaulted
+    // because wrong model config could run expensive models or fail silently.
+    const defaults = MagicContextConfigSchema.parse({});
+    const warnings: string[] = [];
+
+    // Build a patched copy of rawConfig, replacing invalid fields with undefined
+    // so Zod fills in defaults on the second parse.
+    const errorPaths = new Set<string>();
+    for (const issue of parsed.error.issues) {
+        const topKey = issue.path[0];
+        if (topKey !== undefined) {
+            errorPaths.add(String(topKey));
+        }
+    }
 
-    return config;
+    const patched: Record<string, unknown> = { ...rawConfig };
+    for (const key of errorPaths) {
+        const isAgentConfig = key === "historian" || key === "dreamer" || key === "sidekick";
+        if (isAgentConfig) {
+            // Drop agent configs entirely on error — don't default them
+            delete patched[key];
+            warnings.push(
+                `"${key}": invalid agent configuration, ignoring. Check your magic-context.jsonc.`,
+            );
+        } else {
+            // Use Zod default for this field
+            delete patched[key];
+            const defaultVal = (defaults as unknown as Record<string, unknown>)[key];
+            warnings.push(
+                `"${key}": invalid value ${JSON.stringify(rawConfig[key])}, using default ${JSON.stringify(defaultVal)}.`,
+            );
+        }
+    }
+
+    const retryParsed = MagicContextConfigSchema.safeParse(patched);
+    if (retryParsed.success) {
+        return {
+            ...retryParsed.data,
+            disabled_hooks: disabledHooks,
+            command,
+            configWarnings: warnings,
+        };
+    }
+
+    // If even the patched version fails (shouldn't happen), fall back to full defaults
+    // but keep enabled:true — the user intended to use the plugin.
+    warnings.push("Config recovery failed, using all defaults.");
+    return { ...defaults, disabled_hooks: disabledHooks, command, configWarnings: warnings };
 }
 
-export function loadPluginConfig(directory: string): MagicContextPluginConfig {
+export function loadPluginConfig(
+    directory: string,
+): MagicContextPluginConfig & { configWarnings?: string[] } {
     const userDetected = detectConfigFile(getUserConfigBasePath());
     // Check project root first, then .opencode/ — root takes precedence
     const rootDetected = detectConfigFile(join(directory, CONFIG_FILE_BASENAME));
@@ -120,14 +167,27 @@ export function loadPluginConfig(directory: string): MagicContextPluginConfig {
     const projectConfig =
         projectDetected.format === "none" ? null : loadConfigFile(projectDetected.path);
 
-    let config: MagicContextPluginConfig = parsePluginConfig({});
+    let config: MagicContextPluginConfig & { configWarnings?: string[] } = parsePluginConfig({});
+    const allWarnings: string[] = [];
 
     if (userConfig) {
-        config = mergeConfigs(config, parsePluginConfig(userConfig));
+        const parsed = parsePluginConfig(userConfig);
+        if (parsed.configWarnings?.length) {
+            allWarnings.push(...parsed.configWarnings.map((w) => `[user config] ${w}`));
+        }
+        config = mergeConfigs(config, parsed);
     }
 
     if (projectConfig) {
-        config = mergeConfigs(config, parsePluginConfig(projectConfig));
+        const parsed = parsePluginConfig(projectConfig);
+        if (parsed.configWarnings?.length) {
+            allWarnings.push(...parsed.configWarnings.map((w) => `[project config] ${w}`));
+        }
+        config = mergeConfigs(config, parsed);
+    }
+
+    if (allWarnings.length > 0) {
+        config.configWarnings = allWarnings;
     }
 
     return config;

packages/plugin/src/config/index.ts

@@ -170,10 +170,10 @@ export const MagicContextConfigSchema = z
         /** Context percentage that forces queued operations to execute. Number or per-model object ({ default: 65, "provider/model": 45 }). Default: DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE */
         execute_threshold_percentage: z
             .union([
-                z.number().min(35).max(95),
+                z.number().min(20).max(95),
                 z
-                    .object({ default: z.number().min(35).max(95) })
-                    .catchall(z.number().min(35).max(95)),
+                    .object({ default: z.number().min(20).max(95) })
+                    .catchall(z.number().min(20).max(95)),
             ])
             .default(DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE),
         /** Number of recent tags to protect from dropping (min: 1, max: 100, default: 20) */

packages/plugin/src/config/schema/magic-context.ts

@@ -26,6 +26,42 @@ import { MagicContextRpcServer } from "./shared/rpc-server";
 const plugin: Plugin = async (ctx) => {
     const pluginConfig = loadPluginConfig(ctx.directory);
 
+    // Surface config validation warnings to user and log
+    if (pluginConfig.configWarnings?.length) {
+        for (const w of pluginConfig.configWarnings) {
+            log(`[magic-context] config warning: ${w}`);
+        }
+        // Send warning to user via startup notification (after a short delay so session is ready)
+        const warningText = [
+            "## ⚠️ Magic Context Config Warning",
+            "",
+            "Some configuration values are invalid and were replaced with defaults:",
+            "",
+            ...pluginConfig.configWarnings.map((w) => `- ${w}`),
+            "",
+            "Check your `magic-context.jsonc` to fix these values.",
+        ].join("\n");
+
+        setTimeout(async () => {
+            try {
+                const { sendIgnoredMessage } = await import(
+                    "./hooks/magic-context/send-session-notification"
+                );
+                // sendIgnoredMessage already handles TUI (toast) vs Desktop (ignored message)
+                // via isTuiConnected(). We need a session ID — use the first active session.
+                const sessions = await Promise.resolve((ctx.client as any).session?.list?.()).catch(
+                    () => null,
+                );
+                const sessionId = (sessions as any)?.data?.[0]?.id ?? (sessions as any)?.[0]?.id;
+                if (sessionId) {
+                    await sendIgnoredMessage(ctx.client, sessionId, warningText, {});
+                }
+            } catch {
+                // Intentional: config warning delivery must not crash startup
+            }
+        }, 3000);
+    }
+
     // Detect conflicts that prevent magic-context from operating correctly
     let conflictResult: ConflictResult | null = null;
     if (pluginConfig.enabled) {

packages/plugin/src/index.ts

@@ -37,7 +37,12 @@ export function log(message: string, data?: unknown): void {
     if (isTestEnv) return;
     try {
         const timestamp = new Date().toISOString();
-        const serialized = data === undefined ? "" : ` ${JSON.stringify(data)}`;
+        const serialized =
+            data === undefined
+                ? ""
+                : data instanceof Error
+                  ? ` ${data.message}${data.stack ? `\n${data.stack}` : ""}`
+                  : ` ${JSON.stringify(data)}`;
         buffer.push(`[${timestamp}] ${message}${serialized}\n`);
         if (buffer.length >= BUFFER_SIZE_LIMIT) {
             flush();