@cortexkit/opencode-magic-context 0.41.4 → 0.42.1

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

@@ -1,7 +1,6 @@
 import { homedir } from "node:os";
 import { z } from "zod";
 import { isValidLanguageCode } from "../../agents/language-directive";
-import { DEFAULT_PROTECTED_TAGS } from "../../features/magic-context/defaults";
 import { isValidCron } from "../../features/magic-context/dreamer/cron";
 import type {
     AGENTIC_DREAM_TASKS,
@@ -446,27 +445,15 @@ const ProfileDreamerSchema = z
         omp: ProfileOmpModelBlockSchema.optional(),
     })
     .strict();
-const ProfileSidekickSchema = AgentOverrideConfigSchema.pick({
-    model: true,
-    fallback_models: true,
-    variant: true,
-})
-    .extend({
-        thinking_level: PiThinkingLevelSchema.describe(
-            "Pi thinking level for the sidekick model selection.",
-        ),
-    })
-    .strict();
 
 export const ConfigProfileSchema = z
     .object({
         historian: ProfileHistorianSchema.optional(),
         dreamer: ProfileDreamerSchema.optional(),
-        sidekick: ProfileSidekickSchema.optional(),
     })
     .strict()
     .describe(
-        "User-owned model-selection overlay. Only historian/dreamer harness model blocks and sidekick model-selection fields are allowed.",
+        "User-owned model-selection overlay. Only historian/dreamer harness model blocks are allowed.",
     );
 export type ConfigProfile = z.infer<typeof ConfigProfileSchema>;
 
@@ -626,15 +613,6 @@ export const DreamerConfigSchema = AgentMetadataSchema.extend({
 });
 export type DreamerConfig = z.infer<typeof DreamerConfigSchema>;
 
-export const SidekickConfigSchema = AgentOverrideConfigSchema.extend({
-    timeout_ms: z.number().default(30000).describe("Timeout for sidekick calls in milliseconds"),
-    system_prompt: z.string().optional().describe("Custom system prompt for sidekick"),
-    thinking_level: PiThinkingLevelSchema.describe(
-        "Pi only: explicit thinking level for sidekick subagent invocations. See historian.pi.thinking_level.",
-    ),
-}).optional();
-export type SidekickConfig = NonNullable<z.infer<typeof SidekickConfigSchema>>;
-
 /**
  * Historian metadata remains harness-independent. Only model resolution moves to
  * the strict opencode, pi, and omp blocks; two_pass and disallowed_tools stay here.
@@ -699,6 +677,18 @@ const BaseEmbeddingConfigSchema = z
             .describe(
                 "Optional input_type for query (search) embeddings on asymmetric models (e.g. NVIDIA NIM 'query'). When unset, query embeddings use embedding.input_type. Passage/stored content always uses embedding.input_type.",
             ),
+        query_instruction: z
+            .union([z.string(), z.literal(false)])
+            .optional()
+            .describe(
+                "OpenAI-compatible query prefix override. A string is prepended verbatim to search queries; false disables the built-in model-family instruction. Qwen3-Embedding, gte-Qwen instruct, e5 instruct, and Nomic families have built-in recipes. Query-only changes do not re-embed stored content. User-level only; project values are ignored.",
+            ),
+        document_prefix: z
+            .string()
+            .optional()
+            .describe(
+                "OpenAI-compatible stored-document prefix override, prepended verbatim. Defaults to the model-family recipe (empty for Qwen3/gte/e5 instruct; 'search_document: ' for Nomic). Changing it changes stored vectors and triggers re-embedding. User-level only; project values are ignored.",
+            ),
         truncate: z
             .string()
             .optional()
@@ -776,6 +766,12 @@ export const EmbeddingConfigSchema = BaseEmbeddingConfigSchema.transform((data)
             ...(apiKey ? { api_key: apiKey } : {}),
             ...(inputType ? { input_type: inputType } : {}),
             ...(queryInputType ? { query_input_type: queryInputType } : {}),
+            ...(data.query_instruction !== undefined
+                ? { query_instruction: data.query_instruction }
+                : {}),
+            ...(data.document_prefix !== undefined
+                ? { document_prefix: data.document_prefix }
+                : {}),
             ...(truncate ? { truncate } : {}),
             ...(data.max_input_tokens ? { max_input_tokens: data.max_input_tokens } : {}),
         };
@@ -809,6 +805,12 @@ export const EmbeddingConfigSchema = BaseEmbeddingConfigSchema.transform((data)
             ...(apiKey ? { api_key: apiKey } : {}),
             ...(inputType ? { input_type: inputType } : {}),
             ...(queryInputType ? { query_input_type: queryInputType } : {}),
+            ...(data.query_instruction !== undefined
+                ? { query_instruction: data.query_instruction }
+                : {}),
+            ...(data.document_prefix !== undefined
+                ? { document_prefix: data.document_prefix }
+                : {}),
             ...(truncate ? { truncate } : {}),
             ...(data.max_input_tokens ? { max_input_tokens: data.max_input_tokens } : {}),
         };
@@ -871,7 +873,8 @@ export interface MagicContextConfig {
      *  this overrides `execute_threshold_percentage` for that model. Useful for hard caps
      *  matching provider input limits. Values above 90% × context_limit are clamped with a warning. */
     execute_threshold_tokens?: { default?: number; [modelKey: string]: number | undefined };
-    protected_tags: number;
+    protected_tokens?: number;
+    protected_tags?: number;
     clear_reasoning_age: number;
     history_budget_percentage: number;
     historian_timeout_ms: number;
@@ -917,10 +920,12 @@ export interface MagicContextConfig {
      *  Graduated from `experimental.temporal_awareness`; default: true. */
     temporal_awareness: boolean;
     /** Debug: when true, keep the child sessions Magic Context spawns for its
-     *  own subagents (historian, dreamer, sidekick, memory-migration) instead
+     *  own subagents (historian, dreamer, memory-migration) instead
      *  of deleting them on success. For short-term inspection/data collection;
      *  kept sessions accumulate until manually cleared. Default false. */
     keep_subagents: boolean;
+    /** Enable loopback-only diagnostic RPCs that expose memory usage and heap snapshots. */
+    debug_rpc?: boolean;
     /**
      * When true (default), deterministic inoperability (schema fence, storage
      * open/migration failure) blocks the primary-session transform with a loud
@@ -1011,7 +1016,6 @@ export interface MagicContextConfig {
             max_commits: number;
         };
     };
-    sidekick?: SidekickConfig;
 }
 
 export const MagicContextConfigSchema = z
@@ -1063,7 +1067,7 @@ export const MagicContextConfigSchema = z
             .describe(
                 "Output language for Magic Context's generated content and guidance, as a " +
                     '2-letter ISO 639-1 code (e.g. "tr", "es", "de", "ja", "pt"). When set, the ' +
-                    "historian, dreamer, sidekick, and the agent-guidance block instruct the model to " +
+                    "historian, dreamer, and the agent-guidance block instruct the model to " +
                     "write its PROSE in this language while keeping all structural tokens (XML tags, " +
                     "the five memory category names, code identifiers, file paths) in English. " +
                     "USER-LEVEL ONLY (ignored in project config for security). Unset = today's " +
@@ -1080,7 +1084,7 @@ export const MagicContextConfigSchema = z
                 "Select a named user-owned model profile. A valid project name overrides this user default; an empty string, null, or other non-string project value is ignored with a warning so the user selection still applies. Unknown names warn and use the base configuration.",
             ),
         profiles: ConfigProfilesSchema.optional().describe(
-            "User-level named model profiles. A profile may contain only historian/dreamer model, fallback_models, OpenCode variant, and Pi/OMP thinking_level fields plus sidekick model-selection fields; task execution policy (including timeout_minutes) is excluded. Project configs may select a name but cannot define profiles.",
+            "User-level named model profiles. A profile may contain only historian/dreamer model, fallback_models, OpenCode variant, and Pi/OMP thinking_level fields; task execution policy (including timeout_minutes) is excluded. Project configs may select a name but cannot define profiles.",
         ),
         historian: HistorianConfigSchema.describe(
             "Historian metadata plus independent strict OpenCode, Pi, and OMP execution blocks. Retained metadata stays at historian; model, fallback_models, variant, and thinking_level belong only in historian.opencode, historian.pi, or historian.omp.",
@@ -1153,14 +1157,22 @@ export const MagicContextConfigSchema = z
             .describe(
                 "Absolute token thresholds per model. When matched, overrides execute_threshold_percentage for that model. Accepts `default` for all models or per-model keys. Values above 90% × context_limit are clamped with a warning log. Min 5_000, max 2_000_000.",
             ),
-        protected_tags: z
+        protected_tokens: z
             .number()
-            .min(1)
-            .max(100)
+            .int()
+            .min(4000)
+            .max(1_000_000)
             .optional()
             .describe(
-                "Number of recent tags to protect from dropping (min: 1, max: 100, default: 20)",
+                "Positive integer token floor to protect from automatic reclaim (min: 4_000, max: 1_000_000). When omitted, the derived default is clamp(round(0.05 × usableSoft), min(16_000, round(0.08 × usableSoft)), 64_000).",
             ),
+        protected_tags: z
+            .unknown()
+            .optional()
+            .describe(
+                "Deprecated: number of recent tags to protect. Ignored for behaviour; use protected_tokens instead.",
+            )
+            .meta({ deprecated: true }),
         clear_reasoning_age: z
             .number()
             .min(10)
@@ -1294,7 +1306,13 @@ export const MagicContextConfigSchema = z
             .boolean()
             .default(false)
             .describe(
-                "Debug: keep the child sessions Magic Context spawns for its own subagents (historian, dreamer, sidekick, memory-migration) instead of deleting them on success. Useful for short-term inspection/data collection — their full transcript (prompt, tool calls, token usage, output) stays in the host session store. Kept sessions accumulate until manually cleared; leave false for normal use. Requires a restart to take effect.",
+                "Debug: keep the child sessions Magic Context spawns for its own subagents (historian, dreamer, memory-migration) instead of deleting them on success. Useful for short-term inspection/data collection — their full transcript (prompt, tool calls, token usage, output) stays in the host session store. Kept sessions accumulate until manually cleared; leave false for normal use. Requires a restart to take effect.",
+            ),
+        debug_rpc: z
+            .boolean()
+            .default(false)
+            .describe(
+                "Developer-only: enable authenticated loopback RPCs for memory counters and heap snapshots. Disabled by default. USER-LEVEL ONLY and requires a restart.",
             ),
         fail_closed_blocking: z
             .boolean()
@@ -1459,13 +1477,28 @@ export const MagicContextConfigSchema = z
                 git_commit_indexing: { enabled: false, since_days: 365, max_commits: 2000 },
             })
             .describe("Cross-session memory configuration"),
-        sidekick: SidekickConfigSchema.describe(
-            "Optional sidekick agent configuration for session-start memory retrieval",
-        ),
     })
     .transform((data): MagicContextConfig => {
         return {
             ...data,
-            protected_tags: data.protected_tags ?? DEFAULT_PROTECTED_TAGS,
+            protected_tags: data.protected_tags as number | undefined,
         };
     });
+
+/**
+ * Derived default protected_tokens formula:
+ * clamp(round(0.05 × usableSoft), min(16000, round(0.08 × usableSoft)), 64000)
+ *
+ * Sizing table:
+ *   100k -> 8,000
+ *   200k -> 16,000
+ *   372k -> 18,600
+ *   872k -> 43,600
+ *   1M   -> 50,000
+ */
+export function deriveDefaultProtectedTokens(usableSoft: number): number {
+    const clampedUsable = Math.max(0, usableSoft);
+    const lowerBound = Math.min(16_000, Math.round(0.08 * clampedUsable));
+    const target = Math.round(0.05 * clampedUsable);
+    return Math.min(64_000, Math.max(lowerBound, target));
+}

package/src/shared/child-session-teardown.test.ts

@@ -0,0 +1,218 @@
+/// <reference types="bun-types" />
+
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import ts from "typescript";
+
+import { sweepOrphanedRetrospectiveChildren } from "../features/magic-context/dreamer/retrospective-orphan-sweep";
+import { teardownChildSession } from "./child-session-teardown";
+import { _resetKeepSubagentsForTesting, setKeepSubagents } from "./keep-subagents";
+import { Database } from "./sqlite";
+import { closeQuietly } from "./sqlite-helpers";
+
+interface TeardownFixture {
+    client: {
+        session: {
+            delete: ReturnType<typeof mock>;
+            update: ReturnType<typeof mock>;
+        };
+    };
+    calls: string[];
+    deleted: string[];
+    archived: string[];
+    messages: string[];
+}
+
+function teardownFixture(): TeardownFixture {
+    const calls: string[] = [];
+    const deleted: string[] = [];
+    const archived: string[] = [];
+    const messages: string[] = [];
+    return {
+        calls,
+        deleted,
+        archived,
+        messages,
+        client: {
+            session: {
+                update: mock(async ({ path }: { path: { id: string } }) => {
+                    calls.push("archive");
+                    archived.push(path.id);
+                    return {};
+                }),
+                delete: mock(async ({ path }: { path: { id: string } }) => {
+                    calls.push("delete");
+                    deleted.push(path.id);
+                    return {};
+                }),
+            },
+        },
+    };
+}
+
+afterEach(() => {
+    _resetKeepSubagentsForTesting();
+    mock.restore();
+});
+
+describe("teardownChildSession", () => {
+    test("deletes an ordinary child only after its prompt settles", async () => {
+        const fixture = teardownFixture();
+        await teardownChildSession({
+            client: fixture.client,
+            sessionId: "settled-ordinary",
+            sessionDirectory: "/repo",
+            promptSettled: true,
+            privacySensitive: false,
+            context: "ordinary",
+            log: (message) => fixture.messages.push(message),
+        });
+
+        expect(fixture.deleted).toEqual(["settled-ordinary"]);
+        expect(fixture.archived).toEqual([]);
+    });
+
+    test("keeps a settled ordinary child but deletes a settled privacy child under keep_subagents", async () => {
+        setKeepSubagents(true);
+        const ordinary = teardownFixture();
+        await teardownChildSession({
+            client: ordinary.client,
+            sessionId: "kept-ordinary",
+            promptSettled: true,
+            privacySensitive: false,
+            context: "ordinary",
+            log: (message) => ordinary.messages.push(message),
+        });
+        expect(ordinary.deleted).toEqual([]);
+
+        const privacy = teardownFixture();
+        await teardownChildSession({
+            client: privacy.client,
+            sessionId: "deleted-private",
+            promptSettled: true,
+            privacySensitive: true,
+            context: "private",
+            log: (message) => privacy.messages.push(message),
+        });
+        expect(privacy.deleted).toEqual(["deleted-private"]);
+    });
+
+    test("archives an unsettled child before logging, leaves it intact, then the age gate reaps it", async () => {
+        const fixture = teardownFixture();
+        const db = new Database(":memory:");
+        db.exec(`
+            CREATE TABLE session (
+                id TEXT PRIMARY KEY,
+                title TEXT,
+                directory TEXT,
+                time_created INTEGER
+            );
+            INSERT INTO session VALUES (
+                'unsettled-private',
+                'magic-context-dream-map-memories',
+                '/repo',
+                1
+            );
+        `);
+        try {
+            await teardownChildSession({
+                client: fixture.client,
+                sessionId: "unsettled-private",
+                sessionDirectory: "/repo",
+                promptSettled: false,
+                privacySensitive: true,
+                context: "[dreamer] map-memories",
+                log: (message) => {
+                    fixture.calls.push("log");
+                    fixture.messages.push(message);
+                },
+            });
+
+            expect(fixture.calls).toEqual(["archive", "log"]);
+            expect(fixture.deleted).toEqual([]);
+            expect(fixture.messages).toEqual([
+                "[dreamer] map-memories: prompt unsettled — session unsettled-private left to the age-gated sweep",
+            ]);
+            expect(
+                db.prepare("SELECT id FROM session WHERE id = ?").get("unsettled-private"),
+            ).toEqual({
+                id: "unsettled-private",
+            });
+
+            const swept = await sweepOrphanedRetrospectiveChildren({
+                opencodeDb: db,
+                client: fixture.client as never,
+                sessionDirectory: "/repo",
+                staleMs: 1_000,
+                now: 1_002,
+            });
+            expect(swept).toBe(1);
+            expect(fixture.deleted).toEqual(["unsettled-private"]);
+        } finally {
+            closeQuietly(db);
+        }
+    });
+});
+
+function productionTypeScriptFiles(directory: string): string[] {
+    const files: string[] = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) files.push(...productionTypeScriptFiles(path));
+        else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts")) files.push(path);
+    }
+    return files;
+}
+
+function clientSessionDeleteOffsets(path: string, source: string): number[] {
+    const sourceFile = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true);
+    const offsets: number[] = [];
+    const visit = (node: ts.Node): void => {
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+            const deleteAccess = node.expression;
+            const sessionAccess = deleteAccess.expression;
+            if (
+                deleteAccess.name.text === "delete" &&
+                ts.isPropertyAccessExpression(sessionAccess) &&
+                sessionAccess.name.text === "session" &&
+                (ts.isIdentifier(sessionAccess.expression)
+                    ? sessionAccess.expression.text === "client"
+                    : ts.isPropertyAccessExpression(sessionAccess.expression) &&
+                      sessionAccess.expression.name.text === "client")
+            ) {
+                offsets.push(node.getStart(sourceFile));
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return offsets;
+}
+
+describe("child-session delete source fence", () => {
+    test("every client.session.delete call is the age-gated sweep or promptSettled-gated teardown", () => {
+        const sourceRoot = join(import.meta.dir, "..");
+        const sites: string[] = [];
+        for (const path of productionTypeScriptFiles(sourceRoot)) {
+            const source = readFileSync(path, "utf8");
+            for (const offset of clientSessionDeleteOffsets(path, source)) {
+                const line = source.slice(0, offset).split("\n").length;
+                sites.push(`${relative(sourceRoot, path)}:${line}`);
+            }
+        }
+
+        // Directory walk order differs between macOS and Linux; the fence is a set.
+        expect(sites.map((site) => site.replace(/:\d+$/, "")).sort()).toEqual([
+            "features/magic-context/dreamer/retrospective-orphan-sweep.ts",
+            "shared/child-session-teardown.ts",
+        ]);
+        const teardownSource = readFileSync(
+            join(sourceRoot, "shared/child-session-teardown.ts"),
+            "utf8",
+        );
+        expect(teardownSource).toMatch(
+            /if\s*\(\s*promptSettled[\s\S]{0,200}client\.session\.delete\s*\(/,
+        );
+    });
+});

package/src/shared/child-session-teardown.ts

@@ -0,0 +1,66 @@
+import { shouldKeepSubagents } from "./keep-subagents";
+
+interface ChildSessionRequest {
+    path: { id: string };
+    query?: { directory: string };
+}
+
+interface ArchiveChildSessionRequest extends ChildSessionRequest {
+    body: { time: { archived: number } };
+}
+
+export interface ChildSessionTeardownClient {
+    session: {
+        delete(request: ChildSessionRequest): Promise<unknown>;
+    };
+}
+
+export interface TeardownChildSessionArgs {
+    client: ChildSessionTeardownClient;
+    sessionId: string | null;
+    sessionDirectory?: string;
+    promptSettled: boolean;
+    privacySensitive: boolean;
+    context: string;
+    log: (message: string) => void;
+}
+
+/**
+ * Retire a child only after its prompt helper resolves. An unresolved client call
+ * can leave OpenCode's server loop writing, so that row is archived for immediate
+ * UI hiding and retained until the age-gated sweep can delete it safely.
+ *
+ * OpenCode's generated v2 SDK models archival as `session.update` with
+ * `time.archived`; the plugin's legacy path/body client reaches the same PATCH
+ * endpoint, although its generated TypeScript body type does not yet expose time.
+ */
+export async function teardownChildSession(args: TeardownChildSessionArgs): Promise<void> {
+    const { client, sessionId, sessionDirectory, promptSettled, privacySensitive, context, log } =
+        args;
+    if (!sessionId) return;
+
+    const request: ChildSessionRequest = {
+        path: { id: sessionId },
+        ...(sessionDirectory ? { query: { directory: sessionDirectory } } : {}),
+    };
+
+    if (promptSettled && (privacySensitive || !shouldKeepSubagents())) {
+        await client.session.delete(request).catch((error: unknown) => {
+            log(`${context}: session cleanup failed: ${String(error)}`);
+        });
+        return;
+    }
+
+    if (!promptSettled) {
+        const archiveSession = client.session as unknown as {
+            update?: (request: ArchiveChildSessionRequest) => Promise<unknown>;
+        };
+        await archiveSession
+            .update?.({
+                ...request,
+                body: { time: { archived: Date.now() } },
+            })
+            .catch(() => {});
+        log(`${context}: prompt unsettled — session ${sessionId} left to the age-gated sweep`);
+    }
+}

package/src/shared/keep-subagents.ts

@@ -1,19 +1,14 @@
 /**
- * Debug / data-collection switch: when enabled, Magic Context does NOT delete
- * the child sessions it spawns for its own subagents (historian, dreamer,
- * sidekick, memory-migration, key-files, user-memory review, recomp).
+ * Debug / data-collection switch for settled ordinary child sessions
+ * (historian and memory migration). Privacy-sensitive Dreamer and
+ * smart-note children are still deleted after their prompts settle.
  *
- * By default these child sessions are deleted on success (only FAILED ones are
- * kept for debugging). With `keep_subagents: true` ALL of them are retained, so
- * their full transcript — prompt, tool calls, token usage, model output — stays
- * inspectable in OpenCode's session store / the dashboard. Intended for
- * short-term data collection (e.g. profiling what the dreamer actually does)
- * before the dreamer v2 overhaul, NOT for steady-state use — kept sessions
- * accumulate in the host's session DB until manually cleared.
+ * Unsettled children are never deleted inline because OpenCode's server loop may
+ * still be writing after a client timeout or abort. They remain for the
+ * age-gated sweep; privacy-sensitive rows are swept even when this switch is on.
  *
- * Process-global, set once at boot from config (mirrors `harness.ts`). A
- * config change requires a restart to take effect. NEVER thread this through
- * per-call args — it's a coarse, boot-time debug toggle.
+ * Process-global, set once at boot from config (mirrors `harness.ts`). A config
+ * change requires a restart to take effect.
  */
 let keepSubagents = false;
 
@@ -22,7 +17,7 @@ export function setKeepSubagents(value: boolean): void {
     keepSubagents = value === true;
 }
 
-/** True when subagent child sessions should be retained (not deleted). */
+/** True when settled ordinary child sessions should be retained. */
 export function shouldKeepSubagents(): boolean {
     return keepSubagents;
 }

package/src/shared/model-suggestion-retry.ts

@@ -71,7 +71,7 @@ export interface PromptRetryOptions {
     fallbackModels?: readonly ModelInput[];
     /**
      * Identifier for structured logging (e.g. "dreamer:consolidate",
-     * "historian", "compressor", "sidekick"). Helps correlate fallback
+     * "historian", "compressor", "dreamer"). Helps correlate fallback
      * attempts to a specific call site in `magic-context.log`. Defaults to
      * "subagent" if not provided.
      */