@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/stable-json.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { stableStringify } from "./stable-json";
+
+describe("stableStringify", () => {
+    test("primitive values match JSON.stringify", () => {
+        expect(stableStringify("hello")).toBe('"hello"');
+        expect(stableStringify(42)).toBe("42");
+        expect(stableStringify(true)).toBe("true");
+        expect(stableStringify(false)).toBe("false");
+        expect(stableStringify(null)).toBe("null");
+    });
+
+    test("undefined renders as literal string", () => {
+        expect(stableStringify(undefined)).toBe("undefined");
+    });
+
+    test("object keys sort by code-point order, not locale", () => {
+        // 'Z' (0x5a) sorts before 'a' (0x61) by code-point.
+        // localeCompare would sort 'a' before 'Z' in many locales.
+        // We want code-point semantics.
+        const input = { Z: 1, a: 2 };
+        expect(stableStringify(input)).toBe('{"Z":1,"a":2}');
+    });
+
+    test("nested objects sort recursively", () => {
+        const input = { b: { y: 1, x: 2 }, a: { z: 3, w: 4 } };
+        expect(stableStringify(input)).toBe('{"a":{"w":4,"z":3},"b":{"x":2,"y":1}}');
+    });
+
+    test("arrays preserve order", () => {
+        const input = [3, 1, 2];
+        expect(stableStringify(input)).toBe("[3,1,2]");
+    });
+
+    test("arrays of objects sort keys per element", () => {
+        const input = [
+            { b: 1, a: 2 },
+            { d: 3, c: 4 },
+        ];
+        expect(stableStringify(input)).toBe('[{"a":2,"b":1},{"c":4,"d":3}]');
+    });
+
+    test("identical objects with different key insertion order produce same string", () => {
+        const a = { foo: 1, bar: 2 };
+        const b = { bar: 2, foo: 1 };
+        expect(stableStringify(a)).toBe(stableStringify(b));
+    });
+
+    test("circular references render as marker, do not throw", () => {
+        const a: Record<string, unknown> = { x: 1 };
+        a.self = a;
+        expect(stableStringify(a)).toBe('{"self":"[Circular]","x":1}');
+    });
+
+    test("mixed cycle through array does not crash", () => {
+        const arr: unknown[] = [];
+        arr.push(arr);
+        expect(stableStringify(arr)).toBe('["[Circular]"]');
+    });
+
+    test("empty object and array", () => {
+        expect(stableStringify({})).toBe("{}");
+        expect(stableStringify([])).toBe("[]");
+    });
+
+    test("special string characters JSON-escaped in keys", () => {
+        const input = { 'with "quotes"': 1 };
+        expect(stableStringify(input)).toBe('{"with \\"quotes\\"":1}');
+    });
+
+    test("Unicode key sort by code-point, not by collation", () => {
+        // 'ä' (U+00E4) sorts AFTER 'z' (U+007A) by code-point.
+        // localeCompare in many locales would put 'ä' near 'a'.
+        const input = { z: 1, ä: 2 };
+        const result = stableStringify(input);
+        expect(result).toBe('{"z":1,"ä":2}');
+    });
+
+    test("deterministic across multiple calls", () => {
+        const input = { c: 3, a: 1, b: 2 };
+        const first = stableStringify(input);
+        const second = stableStringify(input);
+        const third = stableStringify(input);
+        expect(first).toBe(second);
+        expect(second).toBe(third);
+    });
+});

package/src/shared/stable-json.ts

@@ -0,0 +1,37 @@
+/**
+ * Process-local deterministic JSON serialization for JSON-like plain
+ * objects. Keys are sorted by code-point order (NOT locale-sensitive).
+ *
+ * Contract:
+ * - Stable for plain objects, arrays, primitives, and `null`.
+ * - `undefined` serialized as the string "undefined".
+ * - Circular references serialized as the string `"[Circular]"`.
+ * - **NOT** a canonical cross-runtime / cross-locale JSON serializer.
+ *   Two different runtimes that disagree on `JSON.stringify` of primitives
+ *   (none known today) would produce different output.
+ *
+ * Used for:
+ * - `tool_definition_measurements` fingerprint hashing
+ * - `pending_compaction_marker_state` CAS comparison
+ *
+ * If a future use case needs true canonical JSON (e.g. cross-process
+ * signing), build a separate utility — do NOT widen this contract.
+ */
+export function stableStringify(value: unknown, seen = new WeakSet<object>()): string {
+    if (value === undefined) return "undefined";
+    if (value === null || typeof value !== "object") return JSON.stringify(value) ?? String(value);
+    if (seen.has(value)) return '"[Circular]"';
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item, seen)).join(",")}]`;
+    }
+    // Code-point sort (NOT localeCompare). Stable across runtimes/locales.
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => {
+        if (a < b) return -1;
+        if (a > b) return 1;
+        return 0;
+    });
+    return `{${entries
+        .map(([key, child]) => `${JSON.stringify(key)}:${stableStringify(child, seen)}`)
+        .join(",")}}`;
+}

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

@@ -0,0 +1,194 @@
+import { describe, expect, test } from "bun:test";
+import type { StatusDetail } from "./rpc-types";
+import { formatStatusDetailMarkdown } from "./status-detail-text";
+
+const STATUS_FIXTURE: StatusDetail = {
+    sessionId: "ses_status",
+    activeProfile: "work",
+    usagePercentage: 75,
+    inputTokens: 96_000,
+    contextLimit: 128_000,
+    systemPromptTokens: 4_000,
+    compartmentCount: 12,
+    memoryCount: 8,
+    memoryBlockCount: 3,
+    memoryImportanceHistogram: {
+        total: 7_986,
+        unclassified: 1_181,
+        bands: {
+            "0-19": 101,
+            "20-39": 202,
+            "40-59": 6_303,
+            "60-79": 707,
+            "80-100": 673,
+        },
+    },
+    pendingOpsCount: 2,
+    historianRunning: true,
+    compartmentInProgress: true,
+    sessionNoteCount: 1,
+    cacheTtl: "1h",
+    cacheTtlSource: "config",
+    cacheTtlModelKey: "anthropic/claude-opus-5",
+    lastTransformError: null,
+    historianFailureCount: 0,
+    projectIdentity: "/repo",
+    compartmentTokens: 22_000,
+    factTokens: 0,
+    memoryTokens: 1_200,
+    profileTokens: 100,
+    conversationTokens: 62_000,
+    toolCallTokens: 3_000,
+    toolDefinitionTokens: 3_200,
+    executeThreshold: 65,
+    executeThresholdClamped: false,
+    boundaryPresent: true,
+    coverageOrdinal: 12,
+    newWorkTokens: 1_000,
+    totalInputTokens: 96_000,
+    recompProgress: null,
+    tagCounter: 5,
+    activeTags: 4,
+    droppedTags: 1,
+    totalTags: 5,
+    activeBytes: 2_048,
+    lastResponseTime: 1,
+    lastNudgeTokens: 80_000,
+    pendingOps: [],
+    cacheTtlMs: 300_000,
+    cacheRemainingMs: 42_000,
+    cacheExpired: false,
+    cacheNeverExpires: false,
+    executeThresholdMode: "percentage",
+    protectedTagCount: 20,
+    historyBudgetPercentage: 0.15,
+    historyBlockTokens: 22_000,
+    compressionBudget: 12_480,
+    compressionUsage: "176%",
+    toastDurationMs: 5_000,
+    loggerDiagnostics: {
+        swallowedWriteCount: 0,
+        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,
+    },
+    storage_versions: {
+        context_db_schema_version: 79,
+        plugin_supported_version: 79,
+    },
+};
+
+describe("status detail text", () => {
+    test("renders the OpenCode summary golden", () => {
+        expect(formatStatusDetailMarkdown(STATUS_FIXTURE)).toBe(`## Magic Context Status
+
+- **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 · 1 notes`);
+    });
+
+    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("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,
+        });
+        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)");
+    });
+
+    test("shows stalled mirror and authority mismatch codes in the summary", () => {
+        const detail = {
+            ...STATUS_FIXTURE,
+            hostBackendsModuleSide: true,
+            memoryMirror: {
+                cursor: 3726,
+                cursorUpdatedAt: 1,
+                cursorAgeMs: 40_000,
+                liveRows: 275,
+                feedHead: 4850,
+                pendingRows: 1124,
+                stalled: true,
+                code: "MC-M01" as const,
+            },
+            memoryAuthorityMismatch: true,
+        };
+        const summary = formatStatusDetailMarkdown(detail);
+
+        expect(summary).toContain("(MC-M01)");
+        expect(summary).toContain("(MC-M02)");
+    });
+
+    test("renders historian refusal stage and received runner text", () => {
+        const detail =
+            "historian refusal stage=credential provider=google model=google/model-a received=\"open_failed: no apikey credential for provider 'google'\"";
+        const status = formatStatusDetailMarkdown({
+            ...STATUS_FIXTURE,
+            historianRefusal: {
+                stage: "credential",
+                canonicalCause: "credential_unavailable",
+                detail,
+            },
+        });
+
+        expect(status).toContain("Historian refusal:** credential (credential_unavailable)");
+        expect(status).toContain(
+            "received=\"open_failed: no apikey credential for provider 'google'\"",
+        );
+    });
+
+    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

@@ -0,0 +1,7 @@
+import type { StatusDetail } from "./rpc-types";
+import { renderUserStatusSummary, statusSummaryFromDetail } from "./status-summary";
+
+/** Render the status summary for chat-only OpenCode clients (no TUI dialog). */
+export function formatStatusDetailMarkdown(detail: StatusDetail): string {
+    return renderUserStatusSummary(statusSummaryFromDetail(detail), "markdown");
+}

package/src/shared/status-summary.ts

@@ -0,0 +1,189 @@
+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 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;
+    historianRefusal?: {
+        stage: string;
+        canonicalCause: string;
+        detail: string;
+    };
+    compactionMarker?: StatusDetail["compactionMarker"];
+    warnings: UserFacingFailureKey[];
+    hiddenVariantWarnings?: string[];
+}
+
+/**
+ * The status fields the warning list is derived from. A full `StatusDetail`
+ * satisfies it; the status payload check builds one from an unchecked RPC reply
+ * so both paths derive the same warnings.
+ */
+export interface StatusWarningInput {
+    readonly lastTransformError?: string | null;
+    readonly historianFailureCount?: number;
+    readonly configParseFailures?: readonly unknown[];
+    readonly loggerDiagnostics?: { readonly swallowedWriteCount?: number };
+    readonly memoryMirror?: { readonly stalled?: boolean };
+    readonly compactionMarker?: { readonly code: string | null };
+    readonly memoryAuthorityMismatch?: boolean;
+    readonly hostLimitations?: readonly UserFacingFailureKey[];
+}
+
+/** Failure codes the status surfaces print as warnings, deduplicated, in display order. */
+export function statusWarningsFromDetail(detail: StatusWarningInput): UserFacingFailureKey[] {
+    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.loggerDiagnostics?.swallowedWriteCount ?? 0) > 0) {
+        warnings.push("status_log_unavailable");
+    }
+    if (detail.memoryMirror?.stalled) warnings.push("memory_mirror_stalled");
+    if (detail.compactionMarker?.code) warnings.push("compaction_marker_missing");
+    if (detail.memoryAuthorityMismatch) warnings.push("memory_authority_mismatch");
+    // Host limitations are not failures of this turn, but they belong in the
+    // same list: the user needs to see that something they configured or asked
+    // for is not running here.
+    warnings.push(...(detail.hostLimitations ?? []));
+    return [...new Set(warnings)];
+}
+
+export function statusSummaryFromDetail(detail: StatusDetail): UserStatusSummary {
+    const compressionState: StatusCompressionState =
+        detail.compaction_enabled === false
+            ? "off"
+            : detail.historianRunning ||
+                detail.compartmentInProgress ||
+                detail.recompProgress?.phase === "recomp"
+              ? "compressing"
+              : detail.compartmentCount > 0
+                ? "ready"
+                : "waiting";
+
+    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,
+        historianRefusal: detail.historianRefusal,
+        compactionMarker: detail.compactionMarker,
+        warnings: statusWarningsFromDetail(detail),
+        hiddenVariantWarnings: detail.hiddenVariantWarnings ?? [],
+    };
+}
+
+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)`;
+}
+
+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: Array<readonly [string, string]> = [
+        ["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`,
+        ],
+    ];
+    if (summary.historianRefusal) {
+        values.push([
+            "Historian refusal",
+            `${summary.historianRefusal.stage} (${summary.historianRefusal.canonicalCause}) — ${summary.historianRefusal.detail}`,
+        ]);
+    }
+    if (summary.compactionMarker?.code) {
+        values.push([
+            "History boundary marker",
+            `${summary.compactionMarker.code} · ${summary.compactionMarker.attempts} attempts · last error: ${summary.compactionMarker.lastError ?? "unknown"}`,
+        ]);
+    }
+    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.hiddenVariantWarnings ?? []) {
+        lines.push(style === "markdown" ? `- **Warning:** ${warning}` : `Warning: ${warning}`);
+    }
+    for (const warning of summary.warnings) {
+        lines.push(
+            style === "markdown"
+                ? `- **Warning:** ${renderUserFacingFailure(warning)}`
+                : `Warning: ${renderUserFacingFailure(warning)}`,
+        );
+    }
+    return lines.join("\n");
+}