@cortexkit/opencode-magic-context 0.42.0 → 0.42.1

package/src/shared/status-detail-text.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { formatOpenCodeDbMissingStatusLine, resolveOpenCodeDbPath } from "./opencode-db-path";
 import type { StatusDetail } from "./rpc-types";
-import { formatStatusDetailMarkdown } from "./status-detail-text";
+import { formatStatusDetailMarkdown, formatStatusDiagnosticsMarkdown } from "./status-detail-text";
 
 const STATUS_FIXTURE: StatusDetail = {
     sessionId: "ses_status",
@@ -18,9 +17,11 @@ const STATUS_FIXTURE: StatusDetail = {
     compartmentInProgress: true,
     sessionNoteCount: 1,
     readySmartNoteCount: 2,
-    cacheTtl: "5m",
-    cacheTtlSource: "session",
+    cacheTtl: "1h",
+    cacheTtlSource: "config",
+    cacheTtlModelKey: "anthropic/claude-opus-5",
     lastTransformError: null,
+    historianFailureCount: 0,
     lastDreamerRunAt: null,
     projectIdentity: "/repo",
     compartmentTokens: 22_000,
@@ -62,38 +63,106 @@ const STATUS_FIXTURE: StatusDetail = {
         lastErrorMessage: null,
         lastErrorTime: null,
     },
+    tailHygiene: {
+        u: 14_400,
+        t: 48_000,
+        severity: 0.3,
+        evaluable: true,
+        generationInvalidated: false,
+        baselineGeneration: 3,
+        computedAt: 1_730_000_000_000,
+        reclaimableToolOutputCount: 3,
+    },
+    embedding: {
+        state: "running",
+        indexed: 9,
+        total: 12,
+    },
     storage_versions: {
         context_db_schema_version: 79,
         plugin_supported_version: 79,
     },
 };
 
-describe("formatStatusDetailMarkdown", () => {
-    test("renders a missing-store condition before the fixed TUI status payload", () => {
-        expect(formatStatusDetailMarkdown(STATUS_FIXTURE)).toBe(
-            `${formatOpenCodeDbMissingStatusLine(resolveOpenCodeDbPath())}\n\n## Magic Context Status
+describe("status detail text", () => {
+    test("renders the OpenCode summary golden", () => {
+        expect(formatStatusDetailMarkdown(STATUS_FIXTURE)).toBe(`## Magic Context Status
 
-- **Mode:** Magic Context compaction
-- **Active profile:** work
-- **Usage:** 75.0% (96,000 / 128,000 usable tokens)
-- **Cache TTL: 5m (session)**; live (42s remaining); TTL 5m
-- **Historian:** running; boundary present; coverage 12
-- **Memory:** 8 active; 3 injected
-- **Tags:** 4 active, 1 dropped; 2 pending drops
-- **Execute threshold:** 65.0%`,
-        );
+- **Context:** 75.0% of usable context (96,000 / 128,000 tokens)
+- **Cache lifetime:** 1h (config for anthropic/claude-opus-5)
+- **Automatic compression:** at 65.0% of usable context
+- **History compression:** Compressing history · 12 history blocks
+- **Reclaimable:** 3 spent tool outputs (~14k tokens)
+- **Memory:** 8 memories · 3 notes
+- **Search indexing:** Running · 9 / 12 history blocks indexed`);
     });
 
-    test("shows module-routed host paths only in Rust-mode chat fallback", () => {
-        const rustStatus = formatStatusDetailMarkdown({
+    test("renders disabled automatic compression and an empty reclaimable set without a gauge", () => {
+        const rendered = formatStatusDetailMarkdown({
+            ...STATUS_FIXTURE,
+            compaction_enabled: false,
+            tailHygiene: {
+                ...STATUS_FIXTURE.tailHygiene!,
+                u: 0,
+                reclaimableToolOutputCount: 0,
+            },
+        });
+        expect(rendered).toContain("- **Automatic compression:** Off");
+        expect(rendered).toContain("- **Reclaimable:** none");
+        expect(rendered).not.toContain("Reclaimable: 0");
+    });
+
+    test("renders summary and diagnostics from one snapshot with matching status values", () => {
+        const summary = formatStatusDetailMarkdown(STATUS_FIXTURE);
+        const diagnostics = formatStatusDiagnosticsMarkdown(STATUS_FIXTURE);
+        for (const value of ["75.0%", "65.0%", "1h (config for anthropic/claude-opus-5)"]) {
+            expect(summary).toContain(value);
+            expect(diagnostics).toContain(value);
+        }
+    });
+
+    test("keeps the previous OpenCode detail behind diagnostics", () => {
+        const diagnostics = formatStatusDiagnosticsMarkdown(STATUS_FIXTURE);
+        expect(diagnostics).toContain("- **Active profile:** work");
+        expect(diagnostics).toContain("- **Tags:** 4 active, 1 dropped; 2 pending drops");
+        expect(diagnostics).toContain("- **Execute threshold:** 65.0%");
+    });
+
+    test("keeps internal vocabulary and identifiers out of the summary", () => {
+        const summary = formatStatusDetailMarkdown({
             ...STATUS_FIXTURE,
+            sessionId: "session-secret",
+            projectIdentity: "/Users/example/secret-project",
             hostBackendsModuleSide: true,
+            lastTransformError: "facade MODULE drain failed in mc-store /tmp/private",
+            historianFailureCount: 2,
         });
-        const tsStatus = formatStatusDetailMarkdown(STATUS_FIXTURE);
+        for (const forbidden of [
+            "session-secret",
+            "/Users/",
+            "tag counter",
+            "protection",
+            "formula",
+            "MODULE",
+            "mc-store",
+            "harness",
+            "compartment",
+            "facade",
+            "changefeed",
+            "drain",
+        ]) {
+            expect(summary.toLowerCase()).not.toContain(forbidden.toLowerCase());
+        }
+        expect(summary).toContain("(MC-S02)");
+        expect(summary).toContain("(MC-H01)");
+    });
 
-        expect(rustStatus).toContain(
-            "Host backends → MODULE: ctx_memory, ctx_note; historian: module-side",
-        );
-        expect(tsStatus).not.toContain("Host backends → MODULE");
+    test("does not expose module routing in the summary", () => {
+        const rustStatus = formatStatusDetailMarkdown({
+            ...STATUS_FIXTURE,
+            hostBackendsModuleSide: true,
+        });
+        expect(rustStatus).not.toContain("MODULE");
+        expect(rustStatus).not.toContain("mc-store");
     });
 });

package/src/shared/status-detail-text.ts

@@ -9,6 +9,8 @@ import {
 } from "./opencode-db-path";
 import type { StatusDetail } from "./rpc-types";
 import { RUST_MODE_HOST_PATHS_LINE } from "./rust-mode-status";
+import { renderUserStatusSummary, statusSummaryFromDetail } from "./status-summary";
+import { renderUserFacingFailure } from "./user-facing-codes";
 
 function formatCount(value: number): string {
     return Math.round(value).toLocaleString();
@@ -21,8 +23,13 @@ function formatCacheLane(detail: StatusDetail): string {
     return `live (${Math.round(detail.cacheRemainingMs / 1000)}s remaining); TTL ${detail.cacheTtl}`;
 }
 
-/** Render the same StatusDetail payload that powers the TUI dialog for chat-only clients. */
+/** Render the default user summary for chat-only OpenCode clients. */
 export function formatStatusDetailMarkdown(detail: StatusDetail): string {
+    return renderUserStatusSummary(statusSummaryFromDetail(detail), "markdown");
+}
+
+/** Render the opt-in operator detail that the status dialog exposes behind Diagnostics. */
+export function formatStatusDiagnosticsMarkdown(detail: StatusDetail): string {
     const usableLimit =
         detail.contextLimit > 0
             ? `${formatCount(detail.contextLimit)} usable tokens`
@@ -71,7 +78,7 @@ export function formatStatusDetailMarkdown(detail: StatusDetail): string {
         );
     }
     if (detail.lastTransformError) {
-        lines.push(`- **Last transform error:** ${detail.lastTransformError}`);
+        lines.push(`- **Warning:** ${renderUserFacingFailure("transform_update_failed")}`);
     }
 
     return lines.join("\n");

package/src/shared/status-summary.ts

@@ -0,0 +1,167 @@
+import { formatCacheTtlDisplay } from "./cache-ttl-display";
+import type { StatusDetail } from "./rpc-types";
+import { renderUserFacingFailure, type UserFacingFailureKey } from "./user-facing-codes";
+
+export type StatusCompressionState = "off" | "compressing" | "ready" | "waiting";
+export type StatusEmbeddingState = "off" | "running" | "paused" | "stopped" | "ready" | "waiting";
+
+export interface UserStatusSummary {
+    inputTokens: number;
+    usableContextTokens: number;
+    usagePercentage: number;
+    cacheLifetime: string;
+    automaticCompressionThreshold: number | null;
+    compression: {
+        state: StatusCompressionState;
+        historyBlockCount: number;
+    };
+    reclaimable: {
+        toolOutputCount: number;
+        tokens: number;
+    };
+    memoryCount: number;
+    noteCount: number;
+    embedding: {
+        state: StatusEmbeddingState;
+        indexed: number;
+        total: number;
+    };
+    warnings: UserFacingFailureKey[];
+}
+
+export function statusSummaryFromDetail(detail: StatusDetail): UserStatusSummary {
+    const compressionState: StatusCompressionState =
+        detail.compaction_enabled === false
+            ? "off"
+            : detail.historianRunning ||
+                detail.compartmentInProgress ||
+                (detail.recompProgress?.phase === "recomp" &&
+                    detail.recompProgress.kind !== "embed")
+              ? "compressing"
+              : detail.compartmentCount > 0
+                ? "ready"
+                : "waiting";
+    const warnings: UserFacingFailureKey[] = [];
+    if (detail.lastTransformError) warnings.push("transform_update_failed");
+    if ((detail.historianFailureCount ?? 0) > 0) warnings.push("historian_unavailable");
+    if ((detail.configParseFailures?.length ?? 0) > 0) warnings.push("configuration_warning");
+    if (detail.embedding?.state === "stopped") warnings.push("embedding_unavailable");
+    if ((detail.loggerDiagnostics?.swallowedWriteCount ?? 0) > 0) {
+        warnings.push("status_log_unavailable");
+    }
+
+    return {
+        inputTokens: detail.inputTokens,
+        usableContextTokens: detail.contextLimit,
+        usagePercentage: detail.usagePercentage,
+        cacheLifetime: formatCacheTtlDisplay({
+            value: detail.cacheTtl,
+            source: detail.cacheTtlSource ?? "session",
+            modelKey: detail.cacheTtlModelKey,
+        }).replace(/^Cache TTL:\s*/, ""),
+        automaticCompressionThreshold:
+            detail.compaction_enabled === false ? null : detail.executeThreshold,
+        compression: {
+            state: compressionState,
+            historyBlockCount: detail.compartmentCount,
+        },
+        reclaimable: {
+            toolOutputCount: detail.tailHygiene?.reclaimableToolOutputCount ?? 0,
+            tokens: detail.tailHygiene?.u ?? 0,
+        },
+        memoryCount: detail.memoryCount,
+        noteCount: (detail.sessionNoteCount ?? 0) + (detail.readySmartNoteCount ?? 0),
+        embedding: detail.embedding ?? {
+            state: "waiting",
+            indexed: 0,
+            total: 0,
+        },
+        warnings: [...new Set(warnings)],
+    };
+}
+
+function formatCount(value: number): string {
+    return Math.round(value).toLocaleString();
+}
+
+function compressionText(summary: UserStatusSummary): string {
+    const historyBlocks = `${summary.compression.historyBlockCount} history block${
+        summary.compression.historyBlockCount === 1 ? "" : "s"
+    }`;
+    switch (summary.compression.state) {
+        case "off":
+            return "Off";
+        case "compressing":
+            return `Compressing history · ${historyBlocks}`;
+        case "ready":
+            return `Ready · ${historyBlocks}`;
+        case "waiting":
+            return "Waiting for enough conversation history";
+    }
+}
+
+function reclaimableText(summary: UserStatusSummary): string {
+    const count = Math.max(0, Math.floor(summary.reclaimable.toolOutputCount));
+    if (count === 0) return "none";
+    const outputs = `${count} spent tool output${count === 1 ? "" : "s"}`;
+    return `${outputs} (~${Math.round(Math.max(0, summary.reclaimable.tokens) / 1000)}k tokens)`;
+}
+
+function embeddingText(summary: UserStatusSummary): string {
+    if (summary.embedding.state === "off") return "Off";
+    const coverage = `${formatCount(summary.embedding.indexed)} / ${formatCount(summary.embedding.total)} history blocks indexed`;
+    switch (summary.embedding.state) {
+        case "running":
+            return `Running · ${coverage}`;
+        case "paused":
+            return `Paused · ${coverage}`;
+        case "stopped":
+            return `Paused after an issue · ${coverage}`;
+        case "ready":
+            return `Ready · ${coverage}`;
+        case "waiting":
+            return `Waiting · ${coverage}`;
+    }
+}
+
+export function renderUserStatusSummary(
+    summary: UserStatusSummary,
+    style: "markdown" | "plain",
+): string {
+    const context = `${summary.usagePercentage.toFixed(1)}% of usable context (${formatCount(summary.inputTokens)} / ${
+        summary.usableContextTokens > 0 ? formatCount(summary.usableContextTokens) : "?"
+    } tokens)`;
+    const values = [
+        ["Context", context],
+        ["Cache lifetime", summary.cacheLifetime],
+        [
+            "Automatic compression",
+            summary.automaticCompressionThreshold === null
+                ? "Off"
+                : `at ${summary.automaticCompressionThreshold.toFixed(1)}% of usable context`,
+        ],
+        ["History compression", compressionText(summary)],
+        ["Reclaimable", reclaimableText(summary)],
+        [
+            "Memory",
+            `${formatCount(summary.memoryCount)} memories · ${formatCount(summary.noteCount)} notes`,
+        ],
+        ["Search indexing", embeddingText(summary)],
+    ] as const;
+    const lines =
+        style === "markdown"
+            ? [
+                  "## Magic Context Status",
+                  "",
+                  ...values.map(([label, value]) => `- **${label}:** ${value}`),
+              ]
+            : ["Magic Context Status", ...values.map(([label, value]) => `${label}: ${value}`)];
+    for (const warning of summary.warnings) {
+        lines.push(
+            style === "markdown"
+                ? `- **Warning:** ${renderUserFacingFailure(warning)}`
+                : `Warning: ${renderUserFacingFailure(warning)}`,
+        );
+    }
+    return lines.join("\n");
+}

package/src/shared/tail-hygiene-status.ts

@@ -9,6 +9,7 @@ export interface WireTailHygieneBaseline {
     generation_invalidated?: boolean;
     baseline_generation?: number;
     computed_at_ms?: number;
+    reclaimable_tool_output_count?: number;
 }
 
 function finiteNumber(value: unknown, fallback = 0): number {
@@ -34,6 +35,10 @@ export function resolveTailHygieneStatus(
             generationInvalidated: rustBaseline.generation_invalidated === true,
             baselineGeneration: Math.max(0, finiteNumber(rustBaseline.baseline_generation)),
             computedAt: Math.max(0, finiteNumber(rustBaseline.computed_at_ms)),
+            reclaimableToolOutputCount: Math.max(
+                0,
+                Math.floor(finiteNumber(rustBaseline.reclaimable_tool_output_count)),
+            ),
         };
     }
     if (tsBaseline === undefined) return undefined;
@@ -47,6 +52,9 @@ export function resolveTailHygieneStatus(
         generationInvalidated: tsBaseline.generationInvalidated,
         baselineGeneration: Math.max(0, tsBaseline.baselineGeneration),
         computedAt: Math.max(0, tsBaseline.computedAt),
+        reclaimableToolOutputCount: tsBaseline.baselineParts.filter(
+            (part) => part.kind === "toolOutput" && part.uTokens > 0,
+        ).length,
     };
 }
 

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([]);
+    });
+});