@wolfx/opencode-magic-context 0.21.8-patch.1

package/dist/hooks/magic-context/format-bytes.d.ts

@@ -0,0 +1,2 @@
+export { formatBytes } from "../../shared/format-bytes";
+//# sourceMappingURL=format-bytes.d.ts.map

package/dist/hooks/magic-context/format-bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-bytes.d.ts","sourceRoot":"","sources":["../../../src/hooks/magic-context/format-bytes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/hooks/magic-context/heuristic-cleanup.d.ts

@@ -0,0 +1,22 @@
+import type { ContextDatabase } from "../../features/magic-context/storage";
+import type { TagEntry } from "../../features/magic-context/types";
+import { type CavemanCleanupConfig } from "./caveman-cleanup";
+import type { MessageLike, TagTarget } from "./tag-messages";
+export declare function applyHeuristicCleanup(sessionId: string, db: ContextDatabase, targets: Map<number, TagTarget>, messageTagNumbers: Map<MessageLike, number>, config: {
+    autoDropToolAge: number;
+    dropToolStructure: boolean;
+    protectedTags: number;
+    dropAllTools?: boolean;
+    /**
+     * Age-tier caveman text compression settings. Only honored when the
+     * session is running with ctx_reduce_enabled=false — caller is
+     * responsible for zeroing this out when ctx_reduce is on.
+     */
+    caveman?: CavemanCleanupConfig;
+}, preloadedTags?: TagEntry[]): {
+    droppedTools: number;
+    deduplicatedTools: number;
+    droppedInjections: number;
+    compressedTextTags: number;
+};
+//# sourceMappingURL=heuristic-cleanup.d.ts.map

package/dist/hooks/magic-context/heuristic-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heuristic-cleanup.d.ts","sourceRoot":"","sources":["../../../src/hooks/magic-context/heuristic-cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAQ5E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AAEnE,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEnF,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAe7D,wBAAgB,qBAAqB,CACjC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,eAAe,EACnB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/B,iBAAiB,EAAE,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,EAC3C,MAAM,EAAE;IACJ,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAClC,EACD,aAAa,CAAC,EAAE,QAAQ,EAAE,GAC3B;IACC,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC9B,CA8KA"}

package/dist/hooks/magic-context/historian-state-file.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Historian state-file offloading.
+ *
+ * When the existing-state XML (prior compartments + facts + project memory)
+ * exceeds {@link HISTORIAN_STATE_INLINE_THRESHOLD} characters, the historian
+ * caller writes it to a temp file under the project-local historian dir
+ * (`<project>/.opencode/magic-context/historian/`) and the prompt instructs
+ * the model to `Read this file first`. This avoids pushing 100K+ chars of
+ * inline reference state through the model's input on long sessions, which
+ * on some provider/model combinations (notably github-copilot/gpt-5.4 via
+ * the openai-responses API) causes the model to stall before emitting any
+ * output tokens.
+ *
+ * The state file lives INSIDE the project directory rather than under
+ * `os.tmpdir()` because OpenCode's `external_directory` permission system
+ * asks the user before letting the historian subagent's Read tool open any
+ * file outside the project. Anchoring under `<project>/.opencode/` keeps
+ * the file inside the project boundary so historian runs never trigger a
+ * permission prompt.
+ *
+ * The caller MUST delete the file in finally{} via
+ * {@link cleanupHistorianStateFile}.
+ *
+ * Shared between OpenCode (`compartment-runner-incremental.ts`,
+ * `compartment-runner-recomp.ts`) and Pi (`pi-historian-runner.ts`). The
+ * directory is resolved from the project directory the caller passes in —
+ * both harnesses already track this on their runner deps.
+ */
+export declare const HISTORIAN_STATE_INLINE_THRESHOLD = 30000;
+/**
+ * When existingState is large, write it to a project-local file and return the
+ * path. Returns undefined when existingState is small enough to inline OR when
+ * writing fails (in which case the caller should fall back to inline).
+ *
+ * `directory` is the project directory; the helper writes under
+ * `<directory>/.opencode/magic-context/historian/`. The dir is created
+ * recursively on first write, so the call is safe on fresh projects that have
+ * never had a `.opencode/` subtree.
+ */
+export declare function maybeWriteHistorianStateFile(sessionId: string, existingState: string, directory: string): string | undefined;
+/** Delete a previously written state file. Safe to call with undefined. */
+export declare function cleanupHistorianStateFile(path: string | undefined): void;
+//# sourceMappingURL=historian-state-file.d.ts.map

package/dist/hooks/magic-context/historian-state-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"historian-state-file.d.ts","sourceRoot":"","sources":["../../../src/hooks/magic-context/historian-state-file.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CACxC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAWpB;AAED,2EAA2E;AAC3E,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAOxE"}

package/dist/hooks/magic-context/hook-handlers.d.ts

@@ -0,0 +1,165 @@
+import { getOrCreateSessionMeta } from "../../features/magic-context/storage-meta";
+import type { PluginContext } from "../../plugin/types";
+export type LiveModelBySession = Map<string, {
+    providerID: string;
+    modelID: string;
+}>;
+export type VariantBySession = Map<string, string | undefined>;
+export type AgentBySession = Map<string, string>;
+export type RecentReduceBySession = Map<string, number>;
+export type ToolUsageSinceUserTurn = Map<string, number>;
+/**
+ * Cache-busting signal sets — replaces the old monolithic `flushedSessions`.
+ *
+ * The old `Set<string>` conflated three independent lifetimes into one flag,
+ * which caused defer passes blocked by an in-progress historian to keep
+ * re-firing the same flush signal across multiple turns (Oracle review,
+ * 2026-04-26). Each set now has exactly one consumer and one lifetime.
+ *
+ * Design rule: every producer that wants to refresh state should `add` to
+ * EVERY set whose consumer needs to react. Consumers are responsible for
+ * draining their own set after they consume the signal.
+ */
+/**
+ * One-shot: signals that `<session-history>` (compartments + facts +
+ * memories block in `message[0]`) needs to be rebuilt on the very next
+ * pass. Consumed by `prepareCompartmentInjection()` in `transform.ts`,
+ * which drains the entry after invocation regardless of whether a rebuild
+ * actually occurred — the next defer pass MUST hit the cache.
+ *
+ * Producers: `/ctx-flush`, real variant change, system-prompt hash change,
+ * explicit user refresh paths (flush/recomp/variant/system-prompt hash).
+ * Background historian/compressor publications use DeferredHistoryRefreshSessions.
+ *
+ * NOT a producer: the background compressor — its output deliberately
+ * lands on the next natural cache-bust pass instead of forcing one.
+ */
+export type HistoryRefreshSessions = Set<string>;
+/** Persistent deferred history refresh from background historian/compressor publication. */
+export type DeferredHistoryRefreshSessions = Set<string>;
+/**
+ * One-shot: signals that the system-prompt adjuncts (project docs, user
+ * profile, key files, sticky date) should be re-read from disk on the
+ * very next system-transform call. Consumed by `system-prompt-hash.ts`,
+ * which drains the entry after refreshing.
+ *
+ * Producers: `/ctx-flush`, real variant change, system-prompt hash change.
+ *
+ * NOT a producer: historian/compressor/recomp — those don't change disk
+ * adjuncts, so refreshing them would burn IO for no reason.
+ */
+export type SystemPromptRefreshSessions = Set<string>;
+/**
+ * Persistent: signals that there are queued user `ctx_reduce` ops or
+ * pending heuristic-cleanup work that MUST run, even if the current pass
+ * can't safely run heuristics yet (e.g. a compartment run is active).
+ * Consumed and drained by `transform-postprocess-phase.ts` only after
+ * `shouldRunHeuristics` actually executes — survives any number of
+ * blocked passes until the materialization succeeds.
+ *
+ * Producers: `/ctx-flush`, real variant change, system-prompt hash change,
+ * explicit user refresh paths (flush/recomp/variant/system-prompt hash).
+ * Background historian publications use DeferredMaterializationSessions.
+ *
+ * Why historian/recomp produce here too: those publish paths queue drop
+ * ops via `queueDropsForCompartmentalizedMessages`. The next safe pass
+ * needs to materialize those queued drops or context will accumulate.
+ */
+export type PendingMaterializationSessions = Set<string>;
+/** Persistent deferred drop-materialization signal from background historian publication. */
+export type DeferredMaterializationSessions = Set<string>;
+/**
+ * @deprecated Use `HistoryRefreshSessions`, `SystemPromptRefreshSessions`,
+ * or `PendingMaterializationSessions` directly. Kept as a type alias only
+ * for any external consumers that may still import it. Will be removed in
+ * a future major.
+ */
+export type FlushedSessions = Set<string>;
+export type LastHeuristicsTurnId = Map<string, string>;
+export declare function getLiveNotificationParams(sessionId: string, liveModelBySession: LiveModelBySession, variantBySession: VariantBySession, agentBySession?: AgentBySession): {
+    agent?: string;
+    variant?: string;
+    providerId?: string;
+    modelId?: string;
+};
+export declare function createChatMessageHook(args: {
+    db: Parameters<typeof getOrCreateSessionMeta>[0];
+    toolUsageSinceUserTurn: ToolUsageSinceUserTurn;
+    recentReduceBySession: RecentReduceBySession;
+    liveModelBySession: LiveModelBySession;
+    variantBySession: VariantBySession;
+    agentBySession: AgentBySession;
+    /** Variant changes invalidate `<session-history>` injection cache and
+     *  may pair with a different model whose pending drops still need to
+     *  materialize — so a real variant flip signals all three sets. */
+    historyRefreshSessions: HistoryRefreshSessions;
+    systemPromptRefreshSessions: SystemPromptRefreshSessions;
+    pendingMaterializationSessions: PendingMaterializationSessions;
+    lastHeuristicsTurnId: LastHeuristicsTurnId;
+    ctxReduceEnabled?: boolean;
+}): (input: {
+    sessionID?: string;
+    variant?: string;
+    agent?: string;
+    model?: {
+        providerID?: string;
+        modelID?: string;
+    };
+}) => Promise<void>;
+export declare function createEventHook(args: {
+    eventHandler: (input: {
+        event: {
+            type: string;
+            properties?: unknown;
+        };
+    }) => Promise<void>;
+    contextUsageMap: Map<string, {
+        usage: {
+            percentage: number;
+            inputTokens: number;
+        };
+        updatedAt: number;
+    }>;
+    db: Parameters<typeof getOrCreateSessionMeta>[0];
+    liveModelBySession: LiveModelBySession;
+    variantBySession: VariantBySession;
+    agentBySession: AgentBySession;
+    /**
+     * Cache of resolved session.directory values from `client.session.get(...)`.
+     * Cleaned on `session.deleted` to prevent leaks. See live-session-state.ts
+     * for the full doc-comment.
+     */
+    sessionDirectoryBySession: Map<string, string>;
+    recentReduceBySession: RecentReduceBySession;
+    toolUsageSinceUserTurn: ToolUsageSinceUserTurn;
+    /** All signal sets are cleaned on `session.deleted` to prevent leaks. */
+    historyRefreshSessions: HistoryRefreshSessions;
+    deferredHistoryRefreshSessions: DeferredHistoryRefreshSessions;
+    systemPromptRefreshSessions: SystemPromptRefreshSessions;
+    pendingMaterializationSessions: PendingMaterializationSessions;
+    deferredMaterializationSessions: DeferredMaterializationSessions;
+    lastHeuristicsTurnId: LastHeuristicsTurnId;
+    commitSeenLastPass?: Map<string, boolean>;
+    client: PluginContext["client"];
+    protectedTags: number;
+    ctxReduceEnabled?: boolean;
+}): (input: {
+    event: {
+        type: string;
+        properties?: unknown;
+    };
+}) => Promise<void>;
+export declare function createCommandExecuteBeforeHook(commandHandler: {
+    "command.execute.before": (input: import("./command-handler").CommandExecuteInput, output: import("./command-handler").CommandExecuteOutput, params: {
+        agent?: string;
+        variant?: string;
+        providerId?: string;
+        modelId?: string;
+    }) => Promise<unknown>;
+}): (input: unknown, output: unknown) => Promise<unknown>;
+export declare function createToolExecuteAfterHook(args: {
+    db: Parameters<typeof getOrCreateSessionMeta>[0];
+    recentReduceBySession: RecentReduceBySession;
+    toolUsageSinceUserTurn: ToolUsageSinceUserTurn;
+}): (input: unknown) => Promise<void>;
+//# sourceMappingURL=hook-handlers.d.ts.map

package/dist/hooks/magic-context/hook-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-handlers.d.ts","sourceRoot":"","sources":["../../../src/hooks/magic-context/hook-handlers.ts"],"names":[],"mappings":"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"}

package/dist/hooks/magic-context/hook.d.ts

@@ -0,0 +1,118 @@
+import { type DreamerConfig, type HistorianConfig, type SidekickConfig } from "../../config/schema/magic-context";
+import type { createCompactionHandler } from "../../features/magic-context/compaction";
+import type { Scheduler } from "../../features/magic-context/scheduler";
+import type { Tagger } from "../../features/magic-context/tagger";
+import type { PluginContext } from "../../plugin/types";
+export type { CommandExecuteInput, CommandExecuteOutput } from "./command-handler";
+import type { LiveSessionState } from "./live-session-state";
+export interface MagicContextDeps {
+    client: PluginContext["client"];
+    directory: string;
+    tagger: Tagger;
+    scheduler: Scheduler;
+    onSessionCacheInvalidated?: (sessionId: string) => void;
+    compactionHandler: ReturnType<typeof createCompactionHandler>;
+    liveSessionState?: LiveSessionState;
+    config: {
+        protected_tags: number;
+        ctx_reduce_enabled?: boolean;
+        nudge_interval_tokens?: number;
+        auto_drop_tool_age?: number;
+        drop_tool_structure?: boolean;
+        clear_reasoning_age?: number;
+        iteration_nudge_threshold?: number;
+        execute_threshold_percentage?: number | {
+            default: number;
+            [modelKey: string]: number;
+        };
+        execute_threshold_tokens?: {
+            default?: number;
+            [modelKey: string]: number | undefined;
+        };
+        cache_ttl: string | Record<string, string>;
+        historian?: HistorianConfig;
+        history_budget_percentage?: number;
+        historian_timeout_ms?: number;
+        memory?: {
+            enabled: boolean;
+            injection_budget_tokens: number;
+            /** When true, historian/recomp auto-promote eligible session facts
+             *  to project memories. When false, promotion is skipped. Issue #44. */
+            auto_promote?: boolean;
+        };
+        embedding?: {
+            provider?: "local" | "openai-compatible" | "off";
+        };
+        sidekick?: SidekickConfig;
+        dreamer?: DreamerConfig;
+        commit_cluster_trigger?: {
+            enabled: boolean;
+            min_clusters: number;
+        };
+        /** Issue #53: per-agent system-prompt injection opt-out. Optional in
+         *  the inline type so legacy tests/callers don't have to construct it;
+         *  Zod's .default() guarantees it's present in real loaded configs. */
+        system_prompt_injection?: {
+            enabled: boolean;
+            skip_signatures: string[];
+        };
+        compressor?: {
+            enabled: boolean;
+            min_compartment_ratio: number;
+            max_merge_depth: number;
+            cooldown_ms: number;
+        };
+        experimental?: {
+            temporal_awareness?: boolean;
+            git_commit_indexing?: {
+                enabled: boolean;
+                since_days: number;
+                max_commits: number;
+            };
+            auto_search?: {
+                enabled: boolean;
+                score_threshold: number;
+                min_prompt_chars: number;
+            };
+            caveman_text_compression?: {
+                enabled: boolean;
+                min_chars: number;
+            };
+        };
+    };
+}
+export declare function createMagicContextHook(deps: MagicContextDeps): {
+    "experimental.chat.messages.transform": (_input: Record<string, never>, output: {
+        messages: unknown[];
+    }) => Promise<void>;
+    "experimental.chat.system.transform": (input: {
+        sessionID?: string;
+    }, output: {
+        system: string[];
+    }) => Promise<void>;
+    "experimental.text.complete": (_input: {
+        sessionID: string;
+        messageID: string;
+        partID: string;
+    }, output: {
+        text: string;
+    }) => Promise<void>;
+    "chat.message": (input: {
+        sessionID?: string;
+        variant?: string;
+        agent?: string;
+        model?: {
+            providerID?: string;
+            modelID?: string;
+        };
+    }) => Promise<void>;
+    event: (input: {
+        event: {
+            type: string;
+            properties?: unknown;
+        };
+    }) => Promise<void>;
+    "command.execute.before": (input: unknown, output: unknown) => Promise<unknown>;
+    "tool.execute.after": (input: unknown) => Promise<void>;
+} | null;
+//# sourceMappingURL=hook.d.ts.map

package/dist/hooks/magic-context/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../src/hooks/magic-context/hook.ts"],"names":[],"mappings":"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"}

package/dist/hooks/magic-context/image-token-estimate.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Estimate token cost of an image from its data URL.
+ * Returns a conservative fallback when parsing fails.
+ */
+export declare function estimateImageTokensFromDataUrl(url: string): number;
+//# sourceMappingURL=image-token-estimate.d.ts.map

package/dist/hooks/magic-context/image-token-estimate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-token-estimate.d.ts","sourceRoot":"","sources":["../../../src/hooks/magic-context/image-token-estimate.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkClE"}

package/dist/hooks/magic-context/index.d.ts

@@ -0,0 +1,3 @@
+export type { CommandExecuteInput, CommandExecuteOutput } from "./command-handler";
+export { createMagicContextHook } from "./hook";
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/magic-context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/magic-context/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,QAAQ,CAAC"}

package/dist/hooks/magic-context/inject-compartments.d.ts

@@ -0,0 +1,52 @@
+import type { Memory } from "../../features/magic-context/memory/types";
+import type { Database } from "../../shared/sqlite";
+import type { MessageLike } from "./tag-messages";
+export interface PreparedCompartmentInjection {
+    block: string;
+    compartmentEndMessage: number;
+    compartmentEndMessageId: string | null;
+    compartmentCount: number;
+    skippedVisibleMessages: number;
+    factCount: number;
+    memoryCount: number;
+    rebuiltFromDb: boolean;
+}
+export declare function clearInjectionCache(sessionId: string): void;
+/**
+ * Return the set of memory ids currently rendered in the cached
+ * <session-history> block for this session, if any. Used by ctx_search
+ * to hard-filter memories the agent already sees in context — retrieving
+ * them from search wastes tokens and pushes high-signal raw-history hits
+ * further down the ranking.
+ *
+ * Returns null when no cache exists or the JSON payload is malformed
+ * (callers should treat null as "don't filter" — the worst case is a
+ * redundant memory result, not a correctness issue).
+ */
+export declare function getVisibleMemoryIds(db: Database, sessionId: string): Set<number> | null;
+export interface CompartmentInjectionResult {
+    injected: boolean;
+    compartmentEndMessage: number;
+    compartmentCount: number;
+    skippedVisibleMessages: number;
+}
+export declare function renderMemoryBlock(memories: Memory[]): string | null;
+/**
+ * Sort memories by priority and trim to budget.
+ *
+ * Priority order:
+ *   1. permanent status first
+ *   2. utility tier (retrieved > constraint > other)
+ *   3. seen count descending
+ *   4. shorter content first (fit more memories in budget)
+ *   5. deterministic id tiebreaker for cache stability
+ *
+ * Uses the real Claude tokenizer (via estimateTokens) so the trim stays
+ * consistent with the rest of the plugin's token math — mismatching units
+ * (chars/4 here vs real tokens elsewhere) caused either under- or
+ * over-injection of memories, depending on memory content shape.
+ */
+export declare function trimMemoriesToBudget(sessionId: string, memories: Memory[], budgetTokens: number): Memory[];
+export declare function prepareCompartmentInjection(db: Database, sessionId: string, messages: MessageLike[], isCacheBusting: boolean, projectPath?: string, injectionBudgetTokens?: number, temporalAwareness?: boolean): PreparedCompartmentInjection | null;
+export declare function renderCompartmentInjection(sessionId: string, messages: MessageLike[], prepared: PreparedCompartmentInjection): CompartmentInjectionResult;
+//# sourceMappingURL=inject-compartments.d.ts.map

package/dist/hooks/magic-context/inject-compartments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-compartments.d.ts","sourceRoot":"","sources":["../../../src/hooks/magic-context/inject-compartments.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,2CAA2C,CAAC;AAGxF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD,MAAM,WAAW,4BAA4B;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB,EAAE,MAAM,CAAC;IAC9B,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;CAC1B;AAuBD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAkBvF;AAED,MAAM,WAAW,0BAA0B;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;CAClC;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CA6BnE;AAmBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAChC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAAE,EAClB,YAAY,EAAE,MAAM,GACrB,MAAM,EAAE,CA4CV;AAED,wBAAgB,2BAA2B,CACvC,EAAE,EAAE,QAAQ,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,WAAW,EAAE,EACvB,cAAc,EAAE,OAAO,EACvB,WAAW,CAAC,EAAE,MAAM,EACpB,qBAAqB,CAAC,EAAE,MAAM,EAC9B,iBAAiB,CAAC,EAAE,OAAO,GAC5B,4BAA4B,GAAG,IAAI,CAuMrC;AAED,wBAAgB,0BAA0B,CACtC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,WAAW,EAAE,EACvB,QAAQ,EAAE,4BAA4B,GACvC,0BAA0B,CAgC5B"}

package/dist/hooks/magic-context/key-files-block.d.ts

@@ -0,0 +1,27 @@
+import { type KeyFileStaleReason } from "../../features/magic-context/key-files/project-key-files";
+import type { SessionMeta } from "../../features/magic-context/types";
+import type { Database } from "../../shared/sqlite";
+export interface KeyFilesConfigForRender {
+    enabled: boolean;
+    tokenBudget: number;
+}
+interface CacheEntry {
+    value: string | null;
+    version: number;
+}
+export declare const cachedKeyFilesBySession: Map<string, CacheEntry>;
+export declare function queueStaleUpdate(projectPath: string, path: string, generatedAtWitness: number, staleReason: KeyFileStaleReason): void;
+export declare function flushStaleUpdates(db: Database): number;
+export declare function pendingStaleUpdateCount(): number;
+export declare function clearKeyFilesCacheForSession(sessionId: string): void;
+export declare function buildKeyFilesBlock(db: Database, projectPath: string, config?: KeyFilesConfigForRender): string | null;
+export declare function readVersionedKeyFiles(args: {
+    db: Database;
+    sessionId: string | undefined;
+    sessionMeta: SessionMeta;
+    directory?: string;
+    isCacheBusting: boolean;
+    config?: KeyFilesConfigForRender;
+}): string | null;
+export {};
+//# sourceMappingURL=key-files-block.d.ts.map

package/dist/hooks/magic-context/key-files-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-files-block.d.ts","sourceRoot":"","sources":["../../../src/hooks/magic-context/key-files-block.ts"],"names":[],"mappings":"AAIA,OAAO,EAEH,KAAK,kBAAkB,EAI1B,MAAM,0DAA0D,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,WAAW,uBAAuB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,UAAU,UAAU;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACnB;AASD,eAAO,MAAM,uBAAuB,yBAAgC,CAAC;AAQrE,wBAAgB,gBAAgB,CAC5B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,kBAAkB,EAAE,MAAM,EAC1B,WAAW,EAAE,kBAAkB,GAChC,IAAI,CAGN;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CA0BtD;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEpE;AAOD,wBAAgB,kBAAkB,CAC9B,EAAE,EAAE,QAAQ,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,uBAAgE,GACzE,MAAM,GAAG,IAAI,CAqDf;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IACxC,EAAE,EAAE,QAAQ,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,uBAAuB,CAAC;CACpC,GAAG,MAAM,GAAG,IAAI,CA2BhB"}

package/dist/hooks/magic-context/live-session-state.d.ts

@@ -0,0 +1,42 @@
+import type { AgentBySession, LiveModelBySession, VariantBySession } from "./hook-handlers";
+/**
+ * Plugin-process-scoped shared state. Lives in `index.ts` and is threaded into
+ * every component that needs to share signals with the others (the magic-
+ * context hook, RPC handlers, command handlers, etc).
+ *
+ * The `*Sessions` sets are the cache-busting signal channels added in
+ * the Oracle 2026-04-26 review (replaces the old single `flushedSessions`).
+ * See `hook-handlers.ts` for the full lifetime/semantics doc-comment on
+ * each set, and `system-prompt-hash.ts` / `transform.ts` /
+ * `transform-postprocess-phase.ts` for the consumer drain points.
+ *
+ * Storing them here lets RPC-driven recomp (TUI command path) signal the
+ * same sets the hook-driven recomp (server `/ctx-recomp` path) signals.
+ * Without this, the TUI recomp publish would silently leave injection cache
+ * stale and the next defer pass would reuse old `<session-history>`.
+ */
+export interface LiveSessionState {
+    liveModelBySession: LiveModelBySession;
+    variantBySession: VariantBySession;
+    agentBySession: AgentBySession;
+    historyRefreshSessions: Set<string>;
+    deferredHistoryRefreshSessions: Set<string>;
+    systemPromptRefreshSessions: Set<string>;
+    pendingMaterializationSessions: Set<string>;
+    deferredMaterializationSessions: Set<string>;
+    /**
+     * Cache of resolved session.directory values from `client.session.get(...)`.
+     *
+     * The session→project binding is set at session create time and never
+     * changes (OpenCode source: `Session.directory` is read once from the
+     * session record, no migration path), so caching for the lifetime of the
+     * plugin process is safe. Without this, transform.ts hits OpenCode's
+     * local API on every transform pass — observed to be 1.5s+ for large
+     * sessions under Electron, accounting for the bulk of transform latency.
+     *
+     * Populated on first successful resolution; cleared on `session.deleted`.
+     */
+    sessionDirectoryBySession: Map<string, string>;
+}
+export declare function createLiveSessionState(): LiveSessionState;
+//# sourceMappingURL=live-session-state.d.ts.map

package/dist/hooks/magic-context/live-session-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-session-state.d.ts","sourceRoot":"","sources":["../../../src/hooks/magic-context/live-session-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE5F;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC7B,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,cAAc,EAAE,cAAc,CAAC;IAC/B,sBAAsB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,8BAA8B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5C,2BAA2B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzC,8BAA8B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5C,+BAA+B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7C;;;;;;;;;;;OAWG;IACH,yBAAyB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClD;AAED,wBAAgB,sBAAsB,IAAI,gBAAgB,CAYzD"}

package/dist/hooks/magic-context/note-nudger.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Note nudge state machine.
+ *
+ * State: idle → (trigger fires + notes exist) → nudged → (any trigger fires again) → nudged → ...
+ * Suppression: after a nudge fires, suppress until the NEXT trigger event (any of 3).
+ *
+ * Triggers:
+ *   1. Post-historian completion — compartments just compressed history
+ *   2. Post-commit detection — agent committed work, natural boundary
+ *   3. Todos complete — agent finished planned work, receptive to deferred items
+ *
+ * The nudge itself is a short reminder folded into the existing nudge anchor.
+ * It does NOT include note content — just a count and "use ctx_note read" hint.
+ */
+import { type NoteNudgeDeliveryOutcome } from "../../features/magic-context/storage-meta-persisted";
+import type { Database } from "../../shared/sqlite";
+export type NoteNudgeTrigger = "historian_complete" | "commit_detected" | "todos_complete";
+export declare function recordNoteNudgeDeliveryTime(sessionId: string): void;
+/**
+ * Signal that a trigger event occurred. Call from hook layer when any of the 3 triggers fire.
+ */
+export declare function onNoteTrigger(db: Database, sessionId: string, trigger: NoteNudgeTrigger): void;
+/**
+ * Peek at whether a note nudge should be injected during this transform pass.
+ * Returns the nudge text if yes, null if no.
+ * Does NOT clear triggerPending — call markNoteNudgeDelivered() after successful placement.
+ *
+ * @param currentUserMessageId - The latest user message ID in this transform pass.
+ *   If it matches the trigger-time message, delivery is deferred to avoid busting
+ *   the Anthropic prompt-cache prefix (the trigger fired during the agent's turn,
+ *   so injecting into the current user message would mutate cached content).
+ * @param projectIdentity - Project identity for resolving ready smart notes.
+ * @param noteReadStillVisible - True if the agent currently has a non-stripped
+ *   `ctx_note(action="read")` tool call in their visible message context. When
+ *   the agent has read the latest note state AND that read is still visible,
+ *   the nudge is suppressed (no value re-surfacing what's already on screen).
+ *   When the read has been dropped (compactified, ctx_reduce'd, age-cleaned),
+ *   the nudge fires again at the next work boundary so the agent regains
+ *   visibility into deferred intentions. Caller computes this via
+ *   `hasVisibleNoteReadCall(messages)` AFTER drops are materialized.
+ */
+export declare function peekNoteNudgeText(db: Database, sessionId: string, currentUserMessageId?: string | null, projectIdentity?: string, noteReadStillVisible?: boolean): string | null;
+/**
+ * Mark the note nudge as delivered after successful placement.
+ * Only call after appendReminderToLatestUserMessage returns an anchor (or null if no user message exists).
+ */
+export declare function markNoteNudgeDelivered(db: Database, sessionId: string, text: string, messageId: string | null): NoteNudgeDeliveryOutcome;
+/**
+ * Get sticky note nudge for replay on subsequent transform passes.
+ * Returns { text, messageId } if a delivered nudge needs re-injection, null otherwise.
+ */
+export declare function getStickyNoteNudge(db: Database, sessionId: string): {
+    text: string;
+    messageId: string;
+} | null;
+/**
+ * Legacy wrapper — peek + mark in one call.
+ * Kept for tests; prefer peekNoteNudgeText + markNoteNudgeDelivered in production.
+ */
+export declare function getNoteNudgeText(db: Database, sessionId: string): string | null;
+/**
+ * Call when session is deleted or notes are read to clear persisted state.
+ */
+export declare function clearNoteNudgeState(db: Database, sessionId: string, options?: {
+    persist?: boolean;
+}): void;
+export declare function clearAllNoteNudgeState(db: Database, sessionId: string): void;
+export declare function clearNoteNudgeTriggerAndCooldown(db: Database, sessionId: string): void;
+export declare function resetNoteNudgeCooldownOnly(sessionId: string): void;
+export declare function clearNoteNudgeTriggerOnly(db: Database, sessionId: string): void;
+//# sourceMappingURL=note-nudger.d.ts.map

package/dist/hooks/magic-context/note-nudger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note-nudger.d.ts","sourceRoot":"","sources":["../../../src/hooks/magic-context/note-nudger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAIH,KAAK,wBAAwB,EAGhC,MAAM,qDAAqD,CAAC;AAO7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAY3F,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEnE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAG9F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC7B,EAAE,EAAE,QAAQ,EACZ,SAAS,EAAE,MAAM,EACjB,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,EACpC,eAAe,CAAC,EAAE,MAAM,EACxB,oBAAoB,CAAC,EAAE,OAAO,GAC/B,MAAM,GAAG,IAAI,CAuGf;AAoBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAClC,EAAE,EAAE,QAAQ,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,GACzB,wBAAwB,CAkB1B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAC9B,EAAE,EAAE,QAAQ,EACZ,SAAS,EAAE,MAAM,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAI5C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM/E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAC/B,EAAE,EAAE,QAAQ,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,IAAI,CAKN;AAED,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAa5E;AAED,wBAAgB,gCAAgC,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAKtF;AAED,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAElE;AAED,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAI/E"}