@cortexkit/opencode-magic-context 0.33.0 → 0.34.0

package/dist/tui-compiled/compaction-off.d.ts

@@ -0,0 +1,13 @@
+import type { SidebarSnapshot } from "../shared/rpc-types";
+export interface CompactionOffSidebarRow {
+    label: "Memories" | "Notes" | "Archived compartments";
+    value: string;
+}
+/**
+ * Formats context pressure from the current wire input and the model context
+ * limit. It deliberately does not use the stored Magic Context threshold
+ * percentage, because native compaction acts on the model window instead.
+ */
+export declare function nativeCompactionContextLabel(snapshot: SidebarSnapshot): string;
+export declare function compactionOffSidebarRows(snapshot: SidebarSnapshot): CompactionOffSidebarRow[];
+//# sourceMappingURL=compaction-off.d.ts.map

package/dist/tui-compiled/compaction-off.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction-off.d.ts","sourceRoot":"","sources":["../../src/tui-compiled/compaction-off.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACpC,KAAK,EAAE,UAAU,GAAG,OAAO,GAAG,uBAAuB,CAAC;IACtD,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAI9E;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,GAAG,uBAAuB,EAAE,CAU7F"}

package/dist/tui-compiled/data/context-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-db.d.ts","sourceRoot":"","sources":["../../../src/tui-compiled/data/context-db.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEzF,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC;AAc3D,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAOrD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;sCACsC;AACtC,wBAAgB,YAAY,IAAI,qBAAqB,GAAG,IAAI,CAE3D;AAED,+BAA+B;AAC/B,wBAAgB,QAAQ,IAAI,IAAI,CAM/B;AAuFD,sDAAsD;AACtD,wBAAsB,mBAAmB,CACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CA8B1B;AAED,wDAAwD;AACxD,wBAAsB,gBAAgB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CA0CvB;AAYD,gEAAgE;AAChE,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAchG;AAED,MAAM,MAAM,sBAAsB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhG,oFAAoF;AACpF,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAe5F;AAED,6CAA6C;AAC7C,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvE;AAED;mFACmF;AACnF,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQxE;AAED;;iDAEiD;AACjD,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUhF;AAED,gEAAgE;AAChE,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAQ3D;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAkBrE;AAED,wEAAwE;AACxE,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAQtD"}
+{"version":3,"file":"context-db.d.ts","sourceRoot":"","sources":["../../../src/tui-compiled/data/context-db.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEzF,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC;AAc3D,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAOrD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;sCACsC;AACtC,wBAAgB,YAAY,IAAI,qBAAqB,GAAG,IAAI,CAE3D;AAED,+BAA+B;AAC/B,wBAAgB,QAAQ,IAAI,IAAI,CAM/B;AAwFD,sDAAsD;AACtD,wBAAsB,mBAAmB,CACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CA8B1B;AAED,wDAAwD;AACxD,wBAAsB,gBAAgB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CA+CvB;AAYD,gEAAgE;AAChE,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAchG;AAED,MAAM,MAAM,sBAAsB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhG,oFAAoF;AACpF,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAe5F;AAED,6CAA6C;AAC7C,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvE;AAED;mFACmF;AACnF,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQxE;AAED;;iDAEiD;AACjD,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUhF;AAED,gEAAgE;AAChE,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAQ3D;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAkBrE;AAED,wEAAwE;AACxE,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAQtD"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cortexkit/opencode-magic-context",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "type": "module",
-  "description": "OpenCode plugin for Magic Context — cross-session memory and context management",
+  "description": "OpenCode plugin for Magic Context \u2014 cross-session memory and context management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "ualtinok",
@@ -27,10 +27,15 @@
     "src/tui",
     "src/tui-compiled",
     "src/shared",
+    "src/config",
+    "src/agents",
+    "src/features/magic-context/defaults.ts",
+    "src/features/magic-context/dreamer/cron.ts",
+    "src/features/magic-context/dreamer/task-registry.ts",
     "README.md"
   ],
   "scripts": {
-    "build": "bun run build:tui && bun build src/index.ts --outdir dist --target node --format esm --splitting --external @opencode-ai/plugin --external @huggingface/transformers --external onnxruntime-web --external bun:sqlite --external node:sqlite && tsc --emitDeclarationOnly",
+    "build": "bun run build:tui && rm -f dist/index.js dist/*-*.js && bun build src/index.ts --outdir dist --target node --format esm --splitting --external @opencode-ai/plugin --external @huggingface/transformers --external onnxruntime-web --external bun:sqlite --external node:sqlite && tsc --emitDeclarationOnly",
     "build:tui": "bun scripts/build-tui.ts",
     "check:tui-compiled": "bun run build:tui && git diff --exit-code -- src/tui-compiled && test -z \"$(git status --porcelain -- src/tui-compiled)\"",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.scripts.json",

package/src/agents/dreamer.ts

@@ -0,0 +1,68 @@
+export const DREAMER_AGENT = "dreamer";
+export const DREAMER_RETROSPECTIVE_AGENT = "dreamer-retrospective";
+// Read-only code investigator for the refresh-primers task. Locked to
+// navigation/read/search tools only — NO write/edit/bash/ctx_memory/ctx_note —
+// because it runs an unsupervised, scheduled, weak-model agentic loop. A
+// ctx_memory mutation here would bump the project memory epoch and bust m[0],
+// violating the primers cache-neutral contract; write/bash could corrupt the
+// user's source. Mirrors the dreamer-retrospective lockPermissions pattern.
+export const DREAMER_PRIMER_INVESTIGATOR_AGENT = "dreamer-primer-investigator";
+
+// Locked read-only code reader for the memory-maintenance tasks (map-memories,
+// verify, verify-broad). Same source-safety + cache-neutrality lock as the
+// primer investigator (NO write/edit/bash/ctx_memory), but deliberately WITHOUT
+// ctx_search — these tasks check memories against the CURRENT local source, not
+// cross-session recall. The host parses the agent's XML manifest and applies the
+// DB writes itself, so the agent never needs a mutation tool.
+export const DREAMER_MEMORY_MAPPER_AGENT = "dreamer-memory-mapper";
+
+/** Read-only tool profile shared by the memory-maintenance reader agent.
+ *  No ctx_search (local-source checks only), no write/bash/ctx_memory. */
+export const DREAMER_MEMORY_MAPPER_ALLOWED_TOOLS = [
+    "read",
+    "grep",
+    "glob",
+    "aft_outline",
+    "aft_zoom",
+    "aft_search",
+] as const;
+
+// Pure-transform classifier for the classify-memories task: prompt in → ONE XML
+// manifest out, ZERO tools. classify scores metadata from the memory text alone
+// (no code inspection), and the host applies the column writes — so the agent
+// needs no tools at all. Locked so a user override can't grant any.
+export const DREAMER_CLASSIFIER_AGENT = "dreamer-classifier";
+
+// Docs maintainer for the maintain-docs task: explores the codebase and writes
+// ARCHITECTURE.md / STRUCTURE.md. Needs file read + write/edit + bash (git log,
+// find) + aft navigation, but deliberately NO ctx_memory/ctx_search/ctx_note —
+// it touches docs, never the memory store. Locked so a user override can't add
+// the memory surface back.
+export const DREAMER_DOCS_AGENT = "dreamer-docs";
+
+/** Codebase-read + doc-write tool profile for the docs maintainer. No memory
+ *  tools (it edits docs, not the memory store). */
+export const DREAMER_DOCS_ALLOWED_TOOLS = [
+    "read",
+    "grep",
+    "glob",
+    "bash",
+    "write",
+    "edit",
+    "aft_outline",
+    "aft_zoom",
+    "aft_search",
+] as const;
+
+// Pure JSON reviewer for the review-user-memories task: reads the candidate
+// observations the host renders and returns a JSON verdict the host applies. It
+// calls NO tools (zero), so it gets the empty allow-list, locked.
+export const DREAMER_REVIEWER_AGENT = "dreamer-reviewer";
+
+/** Tool profile for the base `dreamer` agent, now CURATE-ONLY (memory-pool
+ *  hygiene). Curate edits the memory store through ctx_memory and never reads
+ *  code (a separate verify task owns memory-vs-code correctness), so it needs
+ *  only ctx_memory — not the former bash/write/edit/read/aft/ctx_search/ctx_note
+ *  kitchen sink. Kept on the `dreamer` id so the ctx_memory dreamer-action gate
+ *  (toolContext.agent === DREAMER_AGENT) still recognizes it. */
+export const DREAMER_CURATE_ALLOWED_TOOLS = ["ctx_memory"] as const;

package/src/agents/hidden-agent-registrations.ts

@@ -0,0 +1,331 @@
+import { applyDisallowedTools, buildAllowOnlyPermission } from "./permissions";
+
+/**
+ * Hidden-agent registration builders.
+ *
+ * # Why this lives in its own module (NOT in the plugin entry `index.ts`)
+ *
+ * OpenCode loads a plugin module and, for the legacy plugin shape (a function
+ * `default` export rather than a `{ server, tui }` object), treats EVERY
+ * exported function in that module as a plugin factory and invokes it with the
+ * plugin input `{ client, directory, ... }` (see opencode
+ * `plugin/index.ts` → `getLegacyPlugins`). magic-context uses that legacy shape.
+ *
+ * If `buildHiddenAgentRegistrations` is exported from the entry module it gets
+ * called by the loader as `buildHiddenAgentRegistrations(pluginInput)` — with
+ * the wrong argument — so `args.historianDisallowed` is `undefined` and
+ * `applyDisallowedTools([...], undefined)` throws
+ * `undefined is not an object (evaluating 'disallowed.includes')`, which fails
+ * the WHOLE plugin load. Keeping these helpers out of the entry module means the
+ * entry module's only export is `default` (the real plugin factory); these
+ * builders are still bundled (inlined) into `dist/index.js`, just never treated
+ * as plugin factories.
+ */
+
+// Clamp a user-provided step override to the hidden-agent's built-in cap (loop
+// insurance — see buildHiddenAgentConfig). Caps live as inline literals in
+// buildHiddenAgentRegistrations (historian/sidekick=40, dreamer=150): a handful
+// of tool calls for the historian/sidekick, a real multi-step maintenance loop
+// for the dreamer.
+function clampHiddenAgentStepLimit(value: unknown, cap: number): number {
+    return typeof value === "number" && Number.isFinite(value) ? Math.min(value, cap) : cap;
+}
+
+/**
+ * Static registration data for one hidden agent. The id / allow-list / step cap
+ * are INLINE LITERALS in {@link buildHiddenAgentRegistrations} rather than
+ * cross-module `const` imports.
+ *
+ * # Why inline
+ *
+ * Belt-and-suspenders, not the load-bearing fix. The load failure was caused by
+ * exporting helpers from the entry module (see the module header) — that is what
+ * the entry-only-`default` rule fixes. Inlining the small id/tool/step values
+ * additionally removes any dependency on cross-module top-level `const` init
+ * timing, so this builder returns a complete, valid registration set the instant
+ * it is called regardless of module-evaluation order. Cheap insurance for a path
+ * that runs once per plugin-instance boot.
+ *
+ * The only value that cannot be inlined is the multi-KB generated system prompt;
+ * it stays a module `var` and is guarded at the call site (skip the agent + log
+ * if undefined, never register a broken/deny-all agent).
+ *
+ * `agent-registration-drift.test.ts` asserts the inline literals here stay
+ * byte-identical to the canonical exported constants so they can't silently
+ * diverge.
+ */
+export interface HiddenAgentRegistration {
+    id: string;
+    prompt: string | undefined;
+    allowedTools: readonly string[];
+    maxSteps: number;
+    overrides?: Record<string, unknown>;
+    /** Drop any user `permission` override (privacy-critical agents only). */
+    lockPermissions?: boolean;
+}
+
+/**
+ * Hoisted function declaration: returns the four hidden-agent registrations with
+ * INLINE id / allow-list / step-cap literals (see {@link HiddenAgentRegistration}
+ * for why these must not come from module-level `var` consts). Prompts and
+ * computed overrides are passed in by the caller; the historian disallow filter
+ * is applied here against an inline default allow-list.
+ */
+export function buildHiddenAgentRegistrations(args: {
+    dreamerPrompt: string | undefined;
+    smartNoteCompilerPrompt?: string | undefined;
+    historianPrompt: string | undefined;
+    historianRecompPrompt?: string | undefined;
+    historianEditorPrompt: string | undefined;
+    sidekickPrompt: string | undefined;
+    dreamerOverrides?: Record<string, unknown>;
+    historianOverrides?: Record<string, unknown>;
+    sidekickOverrides?: Record<string, unknown>;
+    historianDisallowed: readonly string[];
+}): HiddenAgentRegistration[] {
+    const historianAllowedTools = applyDisallowedTools(
+        ["read", "aft_outline", "aft_zoom", "aft_search"],
+        args.historianDisallowed,
+    );
+    return [
+        {
+            id: "dreamer",
+            prompt: args.dreamerPrompt,
+            // CURATE-ONLY now. Curate edits the memory store via ctx_memory and
+            // never reads code (a separate verify task owns memory-vs-code
+            // correctness), so it needs only ctx_memory — not the former
+            // bash/write/edit/read/aft/ctx_search/ctx_note surface. maintain-docs
+            // and review-user-memories moved to their own scoped agents below.
+            // (Inline literal — kept byte-identical to DREAMER_CURATE_ALLOWED_TOOLS
+            // by agent-registration-drift.test.ts; see the module header for why
+            // these are not const imports.)
+            allowedTools: ["ctx_memory"],
+            // Curate is a genuine multi-step whole-pool hygiene loop, so it keeps a
+            // high cap.
+            maxSteps: 150,
+            overrides: args.dreamerOverrides,
+            // Lock the curate tool surface: a user dreamer `tools`/`permission`
+            // override must not re-grant bash/write/edit to this unsupervised
+            // memory-hygiene agent. Model/temperature overrides still apply.
+            lockPermissions: true,
+        },
+        {
+            id: "dreamer-docs",
+            prompt: args.dreamerPrompt,
+            // maintain-docs: explore code + write/edit ARCHITECTURE.md/STRUCTURE.md
+            // + bash (git log, find). NO ctx_memory/ctx_search/ctx_note — it edits
+            // docs, never the memory store. (Inline literal — kept byte-identical to
+            // DREAMER_DOCS_ALLOWED_TOOLS by agent-registration-drift.test.ts.)
+            allowedTools: [
+                "read",
+                "grep",
+                "glob",
+                "bash",
+                "write",
+                "edit",
+                "aft_outline",
+                "aft_zoom",
+                "aft_search",
+            ],
+            // Docs maintenance reads the tree and writes two files — a bounded loop,
+            // not the whole-pool 150.
+            maxSteps: 60,
+            overrides: args.dreamerOverrides,
+            // Lock so a user override can't add the memory surface back.
+            lockPermissions: true,
+        },
+        {
+            id: "dreamer-reviewer",
+            prompt: args.dreamerPrompt,
+            // review-user-memories: a pure JSON reviewer of behavioral observations.
+            // It calls NO tools — the host applies its verdict — so zero tools,
+            // locked (mirrors dreamer-classifier).
+            allowedTools: [],
+            maxSteps: 4,
+            overrides: args.dreamerOverrides,
+            lockPermissions: true,
+        },
+        {
+            id: "dreamer-retrospective",
+            prompt: args.dreamerPrompt,
+            allowedTools: ["ctx_search"],
+            maxSteps: 40,
+            overrides: args.dreamerOverrides,
+            // Privacy-critical: this child reads OTHER sessions' raw user text.
+            // Lock it to ctx_search-only — a user dreamer `permission` override
+            // must never broaden it.
+            lockPermissions: true,
+        },
+        {
+            id: "dreamer-primer-investigator",
+            prompt: args.dreamerPrompt,
+            // Read-only code investigation: read/navigate/search the CURRENT
+            // source to answer a primer. Deliberately NO write/edit/bash (could
+            // corrupt user source) and NO ctx_memory/ctx_note (ctx_memory
+            // update/archive/merge bumps the project memory epoch → busts m[0],
+            // violating the primers cache-neutral contract).
+            allowedTools: [
+                "read",
+                "grep",
+                "glob",
+                "aft_outline",
+                "aft_zoom",
+                "aft_search",
+                "ctx_search",
+            ],
+            // Tight read-only-lookup budget — NOT the dreamer's 150. A single
+            // primer is a targeted investigation, not a whole-pool maintenance
+            // loop; it also bounds the per-primer cost of an unsupervised run.
+            maxSteps: 40,
+            overrides: args.dreamerOverrides,
+            // A user dreamer `permission`/`tools` override must never re-grant the
+            // denied write/bash/ctx_memory surface to this unsupervised agent.
+            lockPermissions: true,
+        },
+        {
+            id: "dreamer-memory-mapper",
+            prompt: args.dreamerPrompt,
+            // Read-only local-source reader for map-memories / verify: open and
+            // check the CURRENT source. NO write/edit/bash (could corrupt user
+            // source), NO ctx_memory (mutations bump the project memory epoch →
+            // bust m[0]; the host applies the manifest's DB writes itself), and NO
+            // ctx_search (these tasks check against local code, not cross-session
+            // recall).
+            allowedTools: ["read", "grep", "glob", "aft_outline", "aft_zoom", "aft_search"],
+            // Bounded read-only-lookup budget (mirrors the primer investigator) —
+            // NOT the dreamer's 150. A map/verify batch is a targeted file-lookup
+            // pass, and this bounds the per-batch cost of an unsupervised run.
+            maxSteps: 60,
+            overrides: args.dreamerOverrides,
+            // A user dreamer `permission`/`tools` override must never re-grant the
+            // denied write/bash/ctx_memory surface to this unsupervised agent.
+            lockPermissions: true,
+        },
+        {
+            id: "dreamer-classifier",
+            prompt: args.dreamerPrompt,
+            // ZERO tools: classify scores importance/scope/shareable from the
+            // memory text alone (no code inspection), emits ONE XML manifest, and
+            // the host applies the column writes. A pure transform — no tool can
+            // help it, and locking prevents a user override from granting one.
+            allowedTools: [],
+            maxSteps: 4,
+            overrides: args.dreamerOverrides,
+            lockPermissions: true,
+        },
+        {
+            id: "smart-note-compiler",
+            prompt: args.smartNoteCompilerPrompt,
+            allowedTools: [],
+            maxSteps: 8,
+            overrides: args.dreamerOverrides,
+            // Security-critical: condition text is untrusted prompt data; never
+            // let user dreamer overrides grant tools to the compiler.
+            lockPermissions: true,
+        },
+        {
+            id: "historian",
+            prompt: args.historianPrompt,
+            allowedTools: historianAllowedTools,
+            maxSteps: 40,
+            overrides: args.historianOverrides,
+        },
+        {
+            id: "historian-recomp",
+            prompt: args.historianRecompPrompt ?? args.historianPrompt,
+            allowedTools: historianAllowedTools,
+            maxSteps: 40,
+            overrides: args.historianOverrides,
+        },
+        {
+            id: "historian-editor",
+            prompt: args.historianEditorPrompt,
+            allowedTools: historianAllowedTools,
+            maxSteps: 40,
+            overrides: args.historianOverrides,
+        },
+        {
+            id: "sidekick",
+            prompt: args.sidekickPrompt,
+            allowedTools: ["ctx_search", "aft_outline", "aft_zoom"],
+            maxSteps: 40,
+            overrides: args.sidekickOverrides,
+        },
+    ];
+}
+
+/**
+ * Build a hidden-agent config with a deny-everything-by-default permission
+ * baseline and a hard tool-iteration ceiling. User overrides may lower
+ * `steps`/`maxSteps`, but cannot raise either above the built-in cap.
+ */
+export function buildHiddenAgentConfig(
+    prompt: string,
+    allowedTools: readonly string[],
+    maxSteps: number,
+    overrides?: Record<string, unknown>,
+    agentLabel?: string,
+    lockPermissions = false,
+) {
+    const {
+        permission: overridePermission,
+        tools: overrideTools,
+        // Pulled out so they can be conditionally re-added: under lockPermissions
+        // a user `prompt`/`system` override must NOT replace the hardened
+        // system prompt (see below). Spreading `...rest` below would otherwise
+        // clobber the positional `prompt` arg, since `...rest` lands after it.
+        prompt: overridePrompt,
+        system: overrideSystem,
+        ...rest
+    } = (overrides ?? {}) as {
+        permission?: Record<string, unknown>;
+        tools?: Record<string, boolean>;
+        prompt?: unknown;
+        system?: unknown;
+        [key: string]: unknown;
+    };
+    // When locked (privacy-critical agents), the user `tools` enable/disable map
+    // AND the `prompt`/`system` text are ALL dropped — each is a
+    // privilege/behavior-escalation surface. A user `dreamer.tools: { bash: true }`
+    // would otherwise re-enable a denied tool; a user `dreamer.prompt`/`system`
+    // would otherwise replace the privacy-hardened prompt that, e.g., keeps the
+    // retrospective agent from transcribing raw user text. Unlocked agents keep
+    // their `tools`/`prompt`/`system` overrides.
+    const promptOverrides: Record<string, unknown> = lockPermissions
+        ? {}
+        : {
+              ...(overridePrompt !== undefined ? { prompt: overridePrompt } : {}),
+              ...(overrideSystem !== undefined ? { system: overrideSystem } : {}),
+          };
+    const restOverrides: Record<string, unknown> = lockPermissions
+        ? { ...rest, ...promptOverrides }
+        : {
+              ...rest,
+              ...promptOverrides,
+              ...(overrideTools !== undefined ? { tools: overrideTools } : {}),
+          };
+    const basePermission = buildAllowOnlyPermission(allowedTools, agentLabel);
+    return {
+        prompt,
+        // No builtin fallback chain: the user's `fallback_models` (if any) flow
+        // through `restOverrides`. A hardcoded chain names providers the user may
+        // not have, producing `Model not found` retry storms.
+        ...restOverrides,
+        steps: clampHiddenAgentStepLimit(restOverrides.steps, maxSteps),
+        maxSteps: clampHiddenAgentStepLimit(restOverrides.maxSteps, maxSteps),
+        // Permission baseline goes after `restOverrides` so that accidental
+        // `permission` keys in user overrides we DIDN'T explicitly destructure
+        // can't bypass the deny. The explicit override (destructured above) is
+        // then layered on top — UNLESS lockPermissions is set, in which case the
+        // user override is dropped entirely. lockPermissions is for
+        // privacy-critical agents (dreamer-retrospective reads other sessions'
+        // raw user text and MUST stay ctx_search-only; a user dreamer `permission`
+        // override must never grant it bash/edit/ctx_memory/etc).
+        permission: {
+            ...basePermission,
+            ...(lockPermissions ? {} : (overridePermission ?? {})),
+        },
+        mode: "subagent" as const,
+        hidden: true,
+    };
+}

package/src/agents/historian.ts

@@ -0,0 +1,3 @@
+export const HISTORIAN_AGENT = "historian";
+export const HISTORIAN_RECOMP_AGENT = "historian-recomp";
+export const HISTORIAN_EDITOR_AGENT = "historian-editor";

package/src/agents/language-directive.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+    buildContentLanguageDirective,
+    buildMigrationLanguageDirective,
+    buildPrimaryLanguageDirective,
+    isValidLanguageCode,
+    resolveLanguageName,
+    withContentLanguageDirective,
+    withMigrationLanguageDirective,
+} from "./language-directive";
+
+const EXHAUSTIVE_STRUCTURAL_TOKENS = [
+    "summary",
+    "symptom",
+    "model_or_provider_involved",
+    "ord_span",
+    "provider_sdk",
+    "model_behavior",
+    "tool_protocol",
+    "host_integration",
+    "historian_pipeline",
+    "edit_pipeline",
+    "environment",
+    "undocumented_internal",
+    "other",
+    "fixed",
+    "workaround",
+    "external_blocker",
+    "contained_failure",
+    "deferred",
+    "unknown_but_bounded",
+    "user",
+    "test_result",
+    "tool_result",
+    "self_review",
+    "unprocessed_from",
+    "verified",
+    "update",
+    "archive",
+    "candidate_ids",
+    "update_existing",
+    "memory_id",
+    "dismiss_existing",
+    "consume_candidate_ids",
+    "migrated",
+    "user_observations",
+    "answer",
+] as const;
+
+describe("resolveLanguageName", () => {
+    it("maps a 2-letter ISO 639-1 code to 'English (Endonym)'", () => {
+        expect(resolveLanguageName("tr")).toBe("Turkish (Türkçe)");
+        expect(resolveLanguageName("es")).toBe("Spanish (Español)");
+        expect(resolveLanguageName("ja")).toBe("Japanese (日本語)");
+    });
+    it("normalizes case and surrounding whitespace", () => {
+        expect(resolveLanguageName("  TR ")).toBe("Turkish (Türkçe)");
+    });
+    it("returns the bare English name when the endonym matches it", () => {
+        expect(resolveLanguageName("en")).toBe("English");
+    });
+    it("returns '' for unset, blank, non-codes, and unknown codes", () => {
+        expect(resolveLanguageName()).toBe("");
+        expect(resolveLanguageName("   ")).toBe("");
+        expect(resolveLanguageName("Turkish")).toBe(""); // full name rejected
+        expect(resolveLanguageName("tur")).toBe(""); // 3-letter rejected
+        expect(resolveLanguageName("zz")).toBe(""); // not a real language
+        expect(resolveLanguageName("e1")).toBe("");
+    });
+    it("isValidLanguageCode mirrors resolveLanguageName", () => {
+        expect(isValidLanguageCode("tr")).toBe(true);
+        expect(isValidLanguageCode("zz")).toBe(false);
+        expect(isValidLanguageCode("Español")).toBe(false);
+    });
+});
+
+describe("language directives", () => {
+    it("emits the content directive with the resolved name and structural rule", () => {
+        const directive = buildContentLanguageDirective("tr");
+        expect(directive).toContain("Write human-readable prose you author in: Turkish (Türkçe).");
+        expect(directive).toContain("Copy required output schemas exactly");
+        expect(directive).toContain("No relevant memories found");
+    });
+
+    it("emits the preserve-user-quotes variant", () => {
+        const directive = buildContentLanguageDirective("es", {
+            preserveUserQuotes: true,
+        });
+        expect(directive).toContain(
+            "Preserve U: lines and directly quoted user text in their original source language; write the surrounding summary prose in Spanish (Español).",
+        );
+    });
+
+    it("emits the retrospective no-quote variant", () => {
+        const directive = buildContentLanguageDirective("tr", { retrospective: true });
+        expect(directive).toContain(
+            "Write the lesson text in Turkish (Türkçe); paraphrase source text and never quote the user.",
+        );
+        expect(directive).not.toContain("directly quoted user text");
+    });
+
+    it("emits the migration preserve-language variant", () => {
+        const directive = buildMigrationLanguageDirective("pt");
+        expect(directive).toContain("Preserve each migrated memory's existing language");
+        expect(directive).toContain(
+            "do NOT translate a memory just because an output language is set",
+        );
+        expect(directive).not.toContain("Write human-readable prose you author");
+    });
+
+    it("emits the primary one-liner with the resolved name", () => {
+        expect(buildPrimaryLanguageDirective("zh")).toBe(
+            "Use Chinese (中文) for your natural-language replies to the user unless the user explicitly asks for another language. Keep code, identifiers, file paths, commands, logs, and quoted text verbatim.",
+        );
+    });
+
+    it("returns empty or unchanged for blank or invalid language", () => {
+        expect(buildContentLanguageDirective()).toBe("");
+        expect(buildContentLanguageDirective("   ")).toBe("");
+        expect(buildContentLanguageDirective("Turkish")).toBe(""); // full name not a code
+        expect(buildMigrationLanguageDirective()).toBe("");
+        expect(buildPrimaryLanguageDirective()).toBe("");
+        expect(withContentLanguageDirective("base", "")).toBe("base");
+        expect(withMigrationLanguageDirective("base", " ")).toBe("base");
+        expect(withContentLanguageDirective("base", "zz")).toBe("base"); // unknown code
+    });
+
+    it("does not inline the exhaustive structural token inventory", () => {
+        const directive = buildContentLanguageDirective("tr");
+        for (const token of EXHAUSTIVE_STRUCTURAL_TOKENS) {
+            const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            expect(directive, token).not.toMatch(
+                new RegExp(`(^|[^A-Za-z0-9_])${escaped}([^A-Za-z0-9_]|$)`),
+            );
+        }
+    });
+});