@cortexkit/opencode-magic-context 0.41.4 → 0.42.1

package/src/shared/user-facing-codes.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { DreamRunFailureClass } from "../features/magic-context/dreamer/storage-dream-runs";
+import type { EmbeddingFailureClass } from "../features/magic-context/memory/embedding-failure";
+import {
+    type CapabilityRefusal,
+    dreamFailureCode,
+    embeddingFailureCode,
+    renderCapabilityRefusal,
+    renderDreamFailure,
+    renderEmbeddingFailure,
+    renderUserFacingFailure,
+    USER_FACING_FAILURES,
+} from "./user-facing-codes";
+
+const DREAM_CLASSES: DreamRunFailureClass[] = [
+    "provider_timeout",
+    "provider_error",
+    "empty_completion",
+    "no_models",
+    "child_aborted",
+    "parse_failed",
+    "unknown",
+];
+
+const EMBEDDING_CLASSES: EmbeddingFailureClass[] = [
+    "substitution_rejected",
+    "http_error",
+    "transport_error",
+    "invalid_envelope",
+    "empty_result",
+    "certification_refusal",
+    "credential_required",
+    "local_binding_missing",
+    "local_fs_unavailable",
+    "local_download_failure",
+    "local_runtime_error",
+];
+
+describe("user-facing failure codes", () => {
+    test("keeps the closed table unique and renders one calm sentence plus one action", () => {
+        const entries = Object.values(USER_FACING_FAILURES);
+        expect(new Set(entries.map((entry) => entry.code)).size).toBe(entries.length);
+        for (const [key, entry] of Object.entries(USER_FACING_FAILURES)) {
+            expect(entry.code).toMatch(/^MC-[CHDERS]\d{2}$/);
+            expect(entry.sentence).toEndWith(".");
+            expect(entry.action).toEndWith(".");
+            expect(renderUserFacingFailure(key as keyof typeof USER_FACING_FAILURES)).toBe(
+                `${entry.sentence} ${entry.action} (${entry.code})`,
+            );
+        }
+    });
+
+    test("uses actionable command and configuration guidance in markdown and plain text", () => {
+        expect(renderEmbeddingFailure("local_binding_missing")).toContain(
+            "Run `npx @cortexkit/magic-context doctor`, then retry. (MC-E08)",
+        );
+        expect(renderEmbeddingFailure("local_runtime_error", "plain")).toContain(
+            "Run npx @cortexkit/magic-context doctor, then retry. (MC-E11)",
+        );
+        expect(renderEmbeddingFailure("local_runtime_error", "plain")).not.toContain("`");
+        expect(renderEmbeddingFailure("certification_refusal")).toContain(
+            "Finish the provider setup, or set a fallback provider in the embedding settings, then run /ctx-embed start again. (MC-E06)",
+        );
+        expect(renderUserFacingFailure("configuration_warning")).toContain(
+            "Fix the configuration warning shown in /ctx-status diagnostics, then restart. (MC-S03)",
+        );
+        expect(renderUserFacingFailure("session_upgrade_unavailable")).toContain(
+            "Run /ctx-recomp instead. (MC-C07)",
+        );
+    });
+
+    test("maps every structured dream and embedding failure class", () => {
+        for (const failureClass of DREAM_CLASSES) {
+            expect(renderDreamFailure(failureClass)).toEndWith(
+                `(${dreamFailureCode(failureClass)})`,
+            );
+        }
+        for (const failureClass of EMBEDDING_CLASSES) {
+            expect(renderEmbeddingFailure(failureClass)).toEndWith(
+                `(${embeddingFailureCode(failureClass)})`,
+            );
+        }
+    });
+
+    test("renders every capability refusal without internal vocabulary", () => {
+        const capabilities: CapabilityRefusal[] = [
+            "memory_write",
+            "memory_access",
+            "note_change",
+            "note_access",
+            "context_cleanup",
+            "partial_history",
+            "session_upgrade",
+            "smart_note_condition",
+            "history_compression",
+            "context_service",
+        ];
+        for (const capability of capabilities) {
+            const rendered = renderCapabilityRefusal(capability);
+            expect(rendered).toMatch(/\(MC-C\d{2}\)$/);
+            for (const forbidden of ["authority", "MODULE", "drain", "facade", "changefeed"]) {
+                expect(rendered).not.toContain(forbidden);
+            }
+        }
+    });
+
+    test("source fence keeps raw exceptions out of user-facing reply builders", () => {
+        const builders = [
+            "hooks/magic-context/command-handler.ts",
+            "hooks/magic-context/compartment-runner-validation.ts",
+            "hooks/magic-context/compartment-runner-recomp.ts",
+            "hooks/magic-context/compartment-runner-partial-recomp.ts",
+            "hooks/magic-context/format-embed-failure.ts",
+            "hooks/magic-context/recomp-orchestrator.ts",
+            "shared/status-detail-text.ts",
+            "../../pi-plugin/src/commands/ctx-dream.ts",
+            "../../pi-plugin/src/commands/ctx-status.ts",
+        ];
+        const allowedLogFragments = ["command notification delivery failed", "/ctx-dream failed"];
+        const violations: string[] = [];
+        for (const relativePath of builders) {
+            const path = resolve(import.meta.dir, "..", relativePath);
+            const lines = readFileSync(path, "utf8").split("\n");
+            lines.forEach((line, index) => {
+                if (
+                    !/(error\.message|String\((?:err|error)\)|describeError\([^)]*\)\.brief)/.test(
+                        line,
+                    )
+                ) {
+                    return;
+                }
+                if (allowedLogFragments.some((fragment) => line.includes(fragment))) return;
+                violations.push(`${relativePath}:${index + 1}: ${line.trim()}`);
+            });
+        }
+        expect(violations).toEqual([]);
+    });
+});

package/src/shared/user-facing-codes.ts

@@ -0,0 +1,276 @@
+import type { EmbeddingFailureClass } from "../features/magic-context/memory/embedding-failure";
+import type { PromptFailureClass } from "./model-suggestion-retry";
+
+export const USER_FACING_FAILURES = {
+    historian_unavailable: {
+        code: "MC-H01",
+        sentence: "History compression could not finish this turn.",
+        action: "It will retry automatically.",
+    },
+    recomp_unavailable: {
+        code: "MC-R01",
+        sentence: "History compression could not be rebuilt.",
+        action: "Run /ctx-recomp again.",
+    },
+    dream_provider_timeout: {
+        code: "MC-D01",
+        sentence: "Memory maintenance took too long to respond.",
+        action: "Run /ctx-dream again.",
+    },
+    dream_provider_error: {
+        code: "MC-D02",
+        sentence: "Memory maintenance could not reach its model.",
+        action: "Check the model connection, then run /ctx-dream again.",
+    },
+    dream_empty_completion: {
+        code: "MC-D03",
+        sentence: "Memory maintenance received no usable response.",
+        action: "Run /ctx-dream again.",
+    },
+    dream_no_models: {
+        code: "MC-D04",
+        sentence: "Memory maintenance has no model available.",
+        action: "Check the model settings, then run /ctx-dream again.",
+    },
+    dream_child_aborted: {
+        code: "MC-D05",
+        sentence: "Memory maintenance was interrupted.",
+        action: "Run /ctx-dream again.",
+    },
+    dream_parse_failed: {
+        code: "MC-D06",
+        sentence: "Memory maintenance could not use the model response.",
+        action: "Run /ctx-dream again.",
+    },
+    dream_unknown: {
+        code: "MC-D07",
+        sentence: "Memory maintenance could not finish.",
+        action: "Run /ctx-dream again.",
+    },
+    embedding_substitution_rejected: {
+        code: "MC-E01",
+        sentence: "Search indexing could not use the selected model.",
+        action: "Check the embedding model setting, then run /ctx-embed start again.",
+    },
+    embedding_http_error: {
+        code: "MC-E02",
+        sentence: "The search indexing provider refused the request.",
+        action: "Check the provider connection and credentials, then run /ctx-embed start again.",
+    },
+    embedding_transport_error: {
+        code: "MC-E03",
+        sentence: "Search indexing could not reach its provider.",
+        action: "Check the connection, then run /ctx-embed start again.",
+    },
+    embedding_invalid_envelope: {
+        code: "MC-E04",
+        sentence: "Search indexing received an unsupported response.",
+        action: "Check the embedding endpoint, then run /ctx-embed start again.",
+    },
+    embedding_empty_result: {
+        code: "MC-E05",
+        sentence: "Search indexing received no usable result.",
+        action: "Run /ctx-embed start again.",
+    },
+    embedding_certification_refusal: {
+        code: "MC-E06",
+        sentence: "Search indexing is not ready for this provider.",
+        action: "Finish the provider setup, or set a fallback provider in the embedding settings, then run /ctx-embed start again.",
+    },
+    embedding_credential_required: {
+        code: "MC-E07",
+        sentence: "Search indexing needs provider credentials.",
+        action: "Sign in to the provider, then run /ctx-embed start again.",
+    },
+    embedding_local_binding_missing: {
+        code: "MC-E08",
+        sentence: "Local search indexing is unavailable on this system.",
+        action: "Run `npx @cortexkit/magic-context doctor`, then retry.",
+    },
+    embedding_local_fs_unavailable: {
+        code: "MC-E09",
+        sentence: "Local search indexing cannot save its model files.",
+        action: "Update or reinstall Magic Context, then retry.",
+    },
+    embedding_local_download_failure: {
+        code: "MC-E10",
+        sentence: "Local search indexing could not download its model.",
+        action: "Check the network connection, then retry.",
+    },
+    embedding_local_runtime_error: {
+        code: "MC-E11",
+        sentence: "Local search indexing could not start.",
+        action: "Run `npx @cortexkit/magic-context doctor`, then retry.",
+    },
+    embedding_unavailable: {
+        code: "MC-E12",
+        sentence: "Search indexing could not finish.",
+        action: "Run /ctx-embed start again.",
+    },
+    status_unavailable: {
+        code: "MC-S01",
+        sentence: "Magic Context status is temporarily unavailable.",
+        action: "Retry /ctx-status in a moment.",
+    },
+    transform_update_failed: {
+        code: "MC-S02",
+        sentence: "The last context update did not finish.",
+        action: "Send another message to retry.",
+    },
+    configuration_warning: {
+        code: "MC-S03",
+        sentence: "Some configuration settings could not be applied.",
+        action: "Fix the configuration warning shown in /ctx-status diagnostics, then restart.",
+    },
+    status_log_unavailable: {
+        code: "MC-S04",
+        sentence: "Some diagnostic details could not be saved.",
+        action: "Retry /ctx-status in a moment.",
+    },
+    memory_writes_paused: {
+        code: "MC-C01",
+        sentence: "Memory writes are paused while the engine syncs.",
+        action: "Retry in a moment.",
+    },
+    memory_access_unavailable: {
+        code: "MC-C02",
+        sentence: "Memory access is temporarily unavailable.",
+        action: "Retry in a moment.",
+    },
+    note_changes_paused: {
+        code: "MC-C03",
+        sentence: "Note changes are paused while the engine syncs.",
+        action: "Retry in a moment.",
+    },
+    note_access_unavailable: {
+        code: "MC-C04",
+        sentence: "Notes are temporarily unavailable.",
+        action: "Retry in a moment.",
+    },
+    context_cleanup_paused: {
+        code: "MC-C05",
+        sentence: "Context cleanup is paused while the engine syncs.",
+        action: "Retry in a moment.",
+    },
+    partial_history_unavailable: {
+        code: "MC-C06",
+        sentence: "Partial history compression is not available in the current mode.",
+        action: "Run /ctx-recomp without a range.",
+    },
+    session_upgrade_unavailable: {
+        code: "MC-C07",
+        sentence: "Session upgrade is not available in the current mode.",
+        action: "Run /ctx-recomp instead.",
+    },
+    smart_note_conditions_unavailable: {
+        code: "MC-C08",
+        sentence: "Conditional notes are not available in the current mode.",
+        action: "Save a regular note without a condition.",
+    },
+    history_compression_paused: {
+        code: "MC-C09",
+        sentence: "History compression is paused while the engine syncs.",
+        action: "Retry in a moment.",
+    },
+    context_service_unavailable: {
+        code: "MC-C10",
+        sentence: "Magic Context is temporarily unavailable.",
+        action: "Retry in a moment.",
+    },
+} as const;
+
+export type UserFacingFailureKey = keyof typeof USER_FACING_FAILURES;
+
+export type UserFacingTextStyle = "markdown" | "plain";
+
+export function renderUserFacingFailure(
+    key: UserFacingFailureKey,
+    style: UserFacingTextStyle = "markdown",
+): string {
+    const failure = USER_FACING_FAILURES[key];
+    const action = style === "plain" ? failure.action.replaceAll("`", "") : failure.action;
+    return `${failure.sentence} ${action} (${failure.code})`;
+}
+
+export function userFacingFailureCode(key: UserFacingFailureKey): string {
+    return USER_FACING_FAILURES[key].code;
+}
+
+export type CapabilityRefusal =
+    | "memory_write"
+    | "memory_access"
+    | "note_change"
+    | "note_access"
+    | "context_cleanup"
+    | "partial_history"
+    | "session_upgrade"
+    | "smart_note_condition"
+    | "history_compression"
+    | "context_service";
+
+const CAPABILITY_FAILURES: Record<CapabilityRefusal, UserFacingFailureKey> = {
+    memory_write: "memory_writes_paused",
+    memory_access: "memory_access_unavailable",
+    note_change: "note_changes_paused",
+    note_access: "note_access_unavailable",
+    context_cleanup: "context_cleanup_paused",
+    partial_history: "partial_history_unavailable",
+    session_upgrade: "session_upgrade_unavailable",
+    smart_note_condition: "smart_note_conditions_unavailable",
+    history_compression: "history_compression_paused",
+    context_service: "context_service_unavailable",
+};
+
+export function renderCapabilityRefusal(capability: CapabilityRefusal): string {
+    return renderUserFacingFailure(CAPABILITY_FAILURES[capability]);
+}
+
+export function capabilityRefusalCode(capability: CapabilityRefusal): string {
+    return userFacingFailureCode(CAPABILITY_FAILURES[capability]);
+}
+
+const DREAM_FAILURE_KEYS = {
+    provider_timeout: "dream_provider_timeout",
+    provider_error: "dream_provider_error",
+    empty_completion: "dream_empty_completion",
+    no_models: "dream_no_models",
+    child_aborted: "dream_child_aborted",
+    parse_failed: "dream_parse_failed",
+    unknown: "dream_unknown",
+} as const satisfies Record<PromptFailureClass, UserFacingFailureKey>;
+
+const EMBEDDING_FAILURE_KEYS = {
+    substitution_rejected: "embedding_substitution_rejected",
+    http_error: "embedding_http_error",
+    transport_error: "embedding_transport_error",
+    invalid_envelope: "embedding_invalid_envelope",
+    empty_result: "embedding_empty_result",
+    certification_refusal: "embedding_certification_refusal",
+    credential_required: "embedding_credential_required",
+    local_binding_missing: "embedding_local_binding_missing",
+    local_fs_unavailable: "embedding_local_fs_unavailable",
+    local_download_failure: "embedding_local_download_failure",
+    local_runtime_error: "embedding_local_runtime_error",
+} as const satisfies Record<EmbeddingFailureClass, UserFacingFailureKey>;
+
+export function renderDreamFailure(
+    failureClass: PromptFailureClass,
+    style: UserFacingTextStyle = "markdown",
+): string {
+    return renderUserFacingFailure(DREAM_FAILURE_KEYS[failureClass], style);
+}
+
+export function dreamFailureCode(failureClass: PromptFailureClass): string {
+    return userFacingFailureCode(DREAM_FAILURE_KEYS[failureClass]);
+}
+
+export function renderEmbeddingFailure(
+    failureClass: EmbeddingFailureClass,
+    style: UserFacingTextStyle = "markdown",
+): string {
+    return renderUserFacingFailure(EMBEDDING_FAILURE_KEYS[failureClass], style);
+}
+
+export function embeddingFailureCode(failureClass: EmbeddingFailureClass): string {
+    return userFacingFailureCode(EMBEDDING_FAILURE_KEYS[failureClass]);
+}

package/src/shared/window-geometry.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { resolveLimit, resolveOutputReserve } from "./models-dev-cache";
 import {
+    applyProvenInputFloor,
     deriveWindowGeometry,
     formatWindowDerivationLine,
     parseWindowOverlay,
@@ -298,6 +299,49 @@ describe("window geometry", () => {
         expect(hooked?.derivation.reserve).toBe(30_000);
     });
 
+    test("keeps shared-upfront emergency headroom below the separate absolute wall", () => {
+        const result = deriveWindowGeometry(
+            "openai-codex",
+            "gpt-5.6-sol",
+            { context: 272_000, output: 128_000 },
+            { providerLimit: { context: 272_000 }, harness: "pi" },
+        );
+
+        expect(result?.usableSoft).toBe(204_000);
+        expect(result?.usableHard).toBe(204_000);
+        expect(result?.usableHard).toBeLessThan(result?.derivation.absoluteWall ?? 0);
+        expect(result?.derivation.absoluteWall).toBe(272_000);
+        expect((result?.derivation.absoluteWall ?? 0) - (result?.usableHard ?? 0)).toBe(
+            result?.derivation.reserve,
+        );
+        expect(result?.derivation.windowSource).toBe("provider");
+    });
+
+    test("bounds proof at trusted absolute walls but retains the static-catalog escape hatch", () => {
+        const trusted = deriveWindowGeometry(
+            "openai-codex",
+            "gpt-5.6-sol",
+            { context: 272_000, output: 128_000 },
+            { providerLimit: { context: 272_000 }, harness: "pi" },
+        );
+        expect(trusted).toBeDefined();
+        const raisedWithinWall = applyProvenInputFloor(trusted!, 255_834);
+        expect(raisedWithinWall.geometry.usableSoft).toBe(255_834);
+        expect(raisedWithinWall.geometry.usableHard).toBe(204_000);
+        const refused = applyProvenInputFloor(trusted!, 593_717);
+        expect(refused.refused).toEqual({ reading: 593_717, absoluteWall: 272_000 });
+        expect(refused.geometry.usableSoft).toBe(204_000);
+        expect(refused.geometry.usableHard).toBe(204_000);
+
+        const staticFallback = deriveWindowGeometry("custom", "model", { context: 30_000 });
+        expect(staticFallback).toBeDefined();
+        const escaped = applyProvenInputFloor(staticFallback!, 90_000);
+        expect(escaped.refused).toBeUndefined();
+        expect(escaped.geometry.usableSoft).toBe(90_000);
+        expect(escaped.geometry.usableHard).toBe(90_000);
+        expect(escaped.geometry.derivation.absoluteWall).toBe(90_000);
+    });
+
     test("clamps an inversion and logs it", () => {
         const logs: string[] = [];
         const result = deriveWindowGeometry(

package/src/shared/window-geometry.ts

@@ -10,7 +10,12 @@ export const PROMPT_WALL_MARGIN = 4_096;
 export const PI_OUTPUT_FLOOR = 4_096;
 export const OPENCODE_OUTPUT_CAP = 32_000;
 
-const MIN_PLAUSIBLE_CONTEXT_LIMIT = 1_024;
+/**
+ * Smallest context window any served model can plausibly have. Reported or
+ * inferred limits below this are placeholders (0, 1) or corrupt state, never a
+ * real window, so every denominator check shares this one floor.
+ */
+export const MIN_PLAUSIBLE_CONTEXT_LIMIT = 1_024;
 const OUTPUT_RESERVE_CAP_RATIO = 0.25;
 
 export type WindowGeometry = "shared_upfront" | "shared_truncating" | "separate";
@@ -70,11 +75,15 @@ export interface ResolvedWindowOverlayFacts {
     facts: Record<string, WindowOverlayFact>;
 }
 
+export type WindowLimitSource = "catalog" | "overlay" | "provider" | "detected";
+
 export interface WindowDerivation {
     window: number;
     reserve: number;
     reserveSource: WindowReserveSource;
     geometry: WindowGeometry;
+    windowSource: WindowLimitSource;
+    absoluteWall: number;
 }
 
 export interface WindowGeometryResult {
@@ -446,20 +455,22 @@ export function deriveWindowGeometry(
     const catalogContext = isFinitePositive(catalogLimit?.context)
         ? catalogLimit.context
         : undefined;
+    const providerContext = isFinitePositive(providerLimit?.context)
+        ? providerLimit.context
+        : undefined;
     const advertised = numericOverlayFact(options.overlay, "window.advertised");
     const enforced = numericOverlayFact(options.overlay, "window.enforced");
-    let softContext = mergePositive(
-        enforced ?? advertised ?? catalogContext,
-        providerLimit?.context,
-    );
-    let hardContext = mergePositive(enforced ?? softContext, providerLimit?.context);
-    if (isFinitePositive(options.contextCap)) {
+    let softContext = mergePositive(enforced ?? advertised ?? catalogContext, providerContext);
+    let hardContext = mergePositive(enforced ?? softContext, providerContext);
+    const contextCap = isFinitePositive(options.contextCap) ? options.contextCap : undefined;
+    const hasContextCap = contextCap !== undefined;
+    if (contextCap !== undefined) {
         softContext = isFinitePositive(softContext)
-            ? Math.min(softContext, options.contextCap)
-            : options.contextCap;
+            ? Math.min(softContext, contextCap)
+            : contextCap;
         hardContext = isFinitePositive(hardContext)
-            ? Math.min(hardContext, options.contextCap)
-            : options.contextCap;
+            ? Math.min(hardContext, contextCap)
+            : contextCap;
     }
     const input = mergePositive(
         isFinitePositive(catalogLimit?.input) ? catalogLimit.input : undefined,
@@ -573,6 +584,13 @@ export function deriveWindowGeometry(
 
     const hardWindow = hardContext ?? softContext ?? input;
     if (!isFinitePositive(hardWindow)) return undefined;
+    const windowSource: WindowLimitSource = hasContextCap
+        ? "detected"
+        : providerContext !== undefined
+          ? "provider"
+          : enforced !== undefined || advertised !== undefined
+            ? "overlay"
+            : "catalog";
     let usableHard: number;
     if (geometry === "separate") {
         usableHard = hardWindow;
@@ -606,6 +624,66 @@ export function deriveWindowGeometry(
             reserve: Math.floor(Math.max(0, resolvedWindow - usableSoft)),
             reserveSource,
             geometry,
+            windowSource,
+            absoluteWall: Math.floor(hardWindow),
+        },
+    };
+}
+
+export interface ProvenInputFloorResult {
+    geometry: WindowGeometryResult;
+    refused?: { reading: number; absoluteWall: number };
+}
+
+export function hasTrustedAbsoluteWall(geometry: WindowGeometryResult): boolean {
+    return geometry.derivation.windowSource !== "catalog";
+}
+
+/**
+ * Successful requests can disprove static catalog metadata, but cannot
+ * disprove a provider, overlay, or observed-overflow wall. A reading beyond
+ * that wall is malformed usage accounting and must not enlarge the geometry.
+ */
+export function applyProvenInputFloor(
+    geometry: WindowGeometryResult,
+    provenInputTokens: number | undefined,
+): ProvenInputFloorResult {
+    if (
+        !isFinitePositive(provenInputTokens) ||
+        provenInputTokens < MIN_PLAUSIBLE_CONTEXT_LIMIT ||
+        provenInputTokens <= geometry.usableSoft
+    ) {
+        return { geometry };
+    }
+    if (hasTrustedAbsoluteWall(geometry) && provenInputTokens > geometry.derivation.absoluteWall) {
+        return {
+            geometry,
+            refused: {
+                reading: provenInputTokens,
+                absoluteWall: geometry.derivation.absoluteWall,
+            },
+        };
+    }
+
+    const trustedAbsoluteWall = hasTrustedAbsoluteWall(geometry);
+    const window = trustedAbsoluteWall
+        ? geometry.derivation.window
+        : Math.max(geometry.derivation.window, provenInputTokens);
+    return {
+        geometry: {
+            ...geometry,
+            usableSoft: provenInputTokens,
+            usableHard: trustedAbsoluteWall
+                ? geometry.usableHard
+                : Math.max(geometry.usableHard, provenInputTokens),
+            derivation: {
+                ...geometry.derivation,
+                window,
+                reserve: Math.max(0, window - provenInputTokens),
+                absoluteWall: trustedAbsoluteWall
+                    ? geometry.derivation.absoluteWall
+                    : Math.max(geometry.derivation.absoluteWall, provenInputTokens),
+            },
         },
     };
 }