@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/announcement.ts

@@ -0,0 +1,145 @@
+/**
+ * Release-notes startup announcement shared by OpenCode plugin and Pi plugin.
+ *
+ * Bump `ANNOUNCEMENT_VERSION` and populate `ANNOUNCEMENT_FEATURES` *only* when a
+ * release ships user-facing news worth surfacing once at startup. Patch releases
+ * with no user-visible changes should leave both untouched — that way a user who
+ * already dismissed the dialog for the current `ANNOUNCEMENT_VERSION` won't see
+ * it again on the next bugfix bump.
+ *
+ * The persisted state is a single line of text (`last_announced_version`) under
+ * `getMagicContextStorageDir()`. OpenCode and Pi share the same file because
+ * they share the same storage root — so dismissing in one harness suppresses
+ * the dialog in the other for the same announcement.
+ *
+ * Leave both empty (`""` and `[]`) to skip the dialog entirely.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { compareSemverCore } from "../hooks/auto-update-checker/semver";
+import { getMagicContextStorageDir } from "./data-path";
+import { ensureStorageDirectorySync, writeStorageFileAtomicSync } from "./storage-permissions";
+
+/**
+ * Bump only when there are user-visible changes worth a startup dialog.
+ * Does NOT need to match the published package version.
+ */
+export const ANNOUNCEMENT_VERSION = "0.31.0";
+
+/**
+ * Short, user-facing bullet strings. Keep each line ~80 chars or shorter so the
+ * TUI dialog renders cleanly without horizontal scroll on a typical terminal.
+ */
+export const ANNOUNCEMENT_FEATURES: ReadonlyArray<string> = [
+    "New /mmc-wrapup command: compact older history on demand, keeping the newest N messages raw. Run it before switching to a smaller-context model.",
+    "mmc_search now also searches your session notes and smart notes.",
+    "Project identity now survives transient git failures (slow disks, dubious ownership) without splitting your project memory.",
+    "Removed the mmc_reduce_enabled setting; agent-controlled reduction is always on. Caveman text compression is now independent (caveman_text_compression.enabled).",
+];
+
+/**
+ * Persistent footer rendered below the version-specific bullets in every
+ * announcement. Stays in place across releases so users always see the Discord
+ * invite without us needing to repeat it in `ANNOUNCEMENT_FEATURES` each time.
+ *
+ * Leave empty (`""`) to suppress the footer.
+ */
+export const ANNOUNCEMENT_FOOTER = "Join us on Discord: https://discord.gg/F2uWxjGnU";
+
+const STATE_FILENAME = "last_announced_version";
+
+function getStateFilePath(): string {
+    return path.join(getMagicContextStorageDir(), STATE_FILENAME);
+}
+
+type AnnouncementStateRead =
+    | { status: "missing" }
+    | { status: "valid"; version: string }
+    | { status: "error" };
+
+function readAnnouncementState(): AnnouncementStateRead {
+    try {
+        const file = getStateFilePath();
+        if (!fs.existsSync(file)) return { status: "missing" };
+        const version = fs.readFileSync(file, "utf-8").trim();
+        if (!version) return { status: "error" };
+        return { status: "valid", version };
+    } catch {
+        return { status: "error" };
+    }
+}
+
+/**
+ * Read the most recently dismissed announcement version, or `""` if none can be
+ * returned. Callers that need to distinguish first-run from read/corruption
+ * failures should use the internal tri-state path in `shouldShowAnnouncement`.
+ */
+export function readLastAnnouncedVersion(): string {
+    const state = readAnnouncementState();
+    return state.status === "valid" ? state.version : "";
+}
+
+/**
+ * Persist `version` as the most recently dismissed announcement. Best-effort:
+ * write failures are swallowed so dialog-confirm flows never throw on storage
+ * errors. Worst case the user sees the same dialog once more on next startup.
+ */
+export function markAnnouncementSeen(version: string): void {
+    if (!version) return;
+    try {
+        ensureStorageDirectorySync(getMagicContextStorageDir());
+        writeStorageFileAtomicSync(getStateFilePath(), version);
+    } catch {
+        // best-effort
+    }
+}
+
+/**
+ * True when the configured `ANNOUNCEMENT_VERSION` has not yet been dismissed
+ * AND there is at least one feature to show. Used by both the TUI dialog path
+ * and the Desktop ignored-message fallback.
+ *
+ * First-run / sandbox handling: when NO state file exists yet, we seed it to the
+ * current `ANNOUNCEMENT_VERSION` and return false instead of announcing. This
+ * covers two cases that previously spammed the dialog (issue #99):
+ *   - Fresh installs: a brand-new user shouldn't be shown a changelog of release
+ *     bullets they have no context for — they need onboarding, not patch notes.
+ *   - Ephemeral/sandbox environments (Docker, CI, disposable dev containers)
+ *     where the storage dir is wiped between launches: without the seed, the
+ *     missing file made the announcement re-show on every single startup.
+ * Real upgrades still announce exactly once: an existing user already has a
+ * state file at the prior version, so the version mismatch shows the dialog and
+ * dismissing it advances the file to the current version.
+ *
+ * The seed is a deliberate write side-effect on the "no file" branch — folding
+ * it here (rather than a separate startup call) makes every caller path (plugin
+ * startup, Pi startup, TUI rpc pull) consistent with no ordering dependency.
+ */
+export function shouldShowAnnouncement(): boolean {
+    if (!ANNOUNCEMENT_VERSION || ANNOUNCEMENT_FEATURES.length === 0) return false;
+    const state = readAnnouncementState();
+    if (state.status === "missing") {
+        // No prior state: fresh install or wiped sandbox. Seed to current and
+        // skip the announcement so we never pester first-run / ephemeral envs.
+        markAnnouncementSeen(ANNOUNCEMENT_VERSION);
+        return false;
+    }
+    if (state.status === "error") {
+        // A corrupt or temporarily unreadable existing state file is not first-run.
+        // Do not advance the version; a later successful boot can still show it.
+        return false;
+    }
+    // Show ONLY on a forward version change (current > stored). A bare string
+    // inequality re-announced on a DOWNGRADE (0.27.0 → 0.26.0) or when stored
+    // state held an unexpected value. compareSemverCore returns null for
+    // non-semver input → treat conservatively (don't announce).
+    const ordering = compareSemverCore(ANNOUNCEMENT_VERSION, state.version);
+    if (ordering === null) {
+        // Stored version isn't parseable as semver but differs from current: only
+        // announce when it's genuinely not the current string (avoids re-showing on
+        // every boot for a corrupt-but-present value).
+        return state.version !== ANNOUNCEMENT_VERSION;
+    }
+    return ordering > 0;
+}

package/src/shared/assistant-message-extractor.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import {
+    describeAssistantSettlement,
+    extractLatestAssistantText,
+    hasLengthCappedOutput,
+} from "./assistant-message-extractor";
+
+test("reasoning-only and tool-only turns stay out of manifest text and retain finish diagnostics", () => {
+    for (const [type, finish] of [
+        ["reasoning", "stop"],
+        ["tool", "tool-calls"],
+    ]) {
+        const messages = [
+            {
+                info: { role: "assistant", finish },
+                parts: [{ type, text: "private or tool data" }],
+            },
+        ];
+        expect(extractLatestAssistantText(messages)).toBeNull();
+        expect(describeAssistantSettlement(messages)).toContain(`finish=${finish}`);
+    }
+    expect(
+        describeAssistantSettlement({
+            tokenLog: { finish_reason: "length" },
+            reasoning: "private",
+        }),
+    ).toBe("finish=length, reasoning=true");
+});
+
+describe("hasLengthCappedOutput", () => {
+    test("detects OpenCode assistant info.finish", () => {
+        expect(hasLengthCappedOutput([{ info: { role: "assistant", finish: "length" } }])).toBe(
+            true,
+        );
+    });
+
+    test("detects OpenCode step-finish reason", () => {
+        expect(
+            hasLengthCappedOutput([{ parts: [{ type: "step-finish", reason: "length" }] }]),
+        ).toBe(true);
+        expect(hasLengthCappedOutput({ type: "text", reason: "length" })).toBe(false);
+    });
+
+    test("detects Pi stopReason length", () => {
+        expect(hasLengthCappedOutput({ role: "assistant", stopReason: "length" })).toBe(true);
+    });
+});

package/src/shared/assistant-message-extractor.ts

@@ -0,0 +1,156 @@
+type MessageTime = { created?: number };
+
+type MessageInfo = {
+    role?: string;
+    time?: MessageTime;
+    error?: unknown;
+    finish?: string;
+};
+
+type MessagePart = {
+    type?: string;
+    text?: string;
+};
+
+type SessionMessage = {
+    info?: MessageInfo;
+    parts?: unknown;
+};
+
+export interface AssistantFailure {
+    error: unknown;
+    finish: string | null;
+}
+
+import { isRecord } from "./record-type-guard";
+
+function asSessionMessage(value: unknown): SessionMessage | null {
+    if (!isRecord(value)) return null;
+    const info = value.info;
+    const parts = value.parts;
+    return {
+        info: isRecord(info)
+            ? {
+                  role: typeof info.role === "string" ? info.role : undefined,
+                  time: isRecord(info.time)
+                      ? {
+                            created:
+                                typeof info.time.created === "number"
+                                    ? info.time.created
+                                    : undefined,
+                        }
+                      : undefined,
+                  error: info.error,
+                  finish:
+                      typeof info.finish === "string"
+                          ? info.finish
+                          : typeof info.finish_reason === "string"
+                            ? info.finish_reason
+                            : typeof info.finishReason === "string"
+                              ? info.finishReason
+                              : undefined,
+              }
+            : undefined,
+        parts,
+    };
+}
+
+function getCreatedTime(message: SessionMessage): number {
+    return message.info?.time?.created ?? 0;
+}
+
+function getTextParts(message: SessionMessage): MessagePart[] {
+    if (!Array.isArray(message.parts)) return [];
+    return message.parts
+        .filter((part): part is Record<string, unknown> => isRecord(part))
+        .map((part) => ({
+            type: typeof part.type === "string" ? part.type : undefined,
+            text: typeof part.text === "string" ? part.text : undefined,
+        }))
+        .filter((part) => part.type === "text" && Boolean(part.text));
+}
+
+function getLatestAssistantMessage(messages: unknown): SessionMessage | null {
+    if (!Array.isArray(messages) || messages.length === 0) return null;
+
+    return (
+        messages
+            .map(asSessionMessage)
+            .filter((message): message is SessionMessage => message !== null)
+            .filter((message) => message.info?.role === "assistant")
+            .sort((a, b) => getCreatedTime(b) - getCreatedTime(a))[0] ?? null
+    );
+}
+
+export function extractLatestAssistantText(messages: unknown): string | null {
+    const latest = getLatestAssistantMessage(messages);
+    if (!latest) return null;
+
+    return (
+        getTextParts(latest)
+            .map((part) => part.text)
+            .join("\n") || null
+    );
+}
+
+/** Return an error persisted on the newest assistant row, including its settlement reason. */
+export function extractLatestAssistantFailure(messages: unknown): AssistantFailure | null {
+    const latest = getLatestAssistantMessage(messages);
+    if (!latest || latest.info?.error === undefined || latest.info.error === null) return null;
+    return {
+        error: latest.info.error,
+        finish: latest.info.finish ?? null,
+    };
+}
+
+export function hasLengthCappedOutput(value: unknown): boolean {
+    if (Array.isArray(value)) return value.some((item) => hasLengthCappedOutput(item));
+    if (!isRecord(value)) return false;
+
+    if (value.length_capped === true || value.lengthCapped === true) return true;
+    const finishReason =
+        value.finish_reason ??
+        value.finishReason ??
+        value.finish ??
+        (value.type === "step-finish" ? value.reason : undefined) ??
+        value.stopReason;
+    if (typeof finishReason === "string") {
+        const normalized = finishReason.toLowerCase();
+        if (
+            normalized === "length" ||
+            normalized === "max_tokens" ||
+            normalized === "max_output_tokens"
+        ) {
+            return true;
+        }
+    }
+
+    return Object.values(value).some((item) => hasLengthCappedOutput(item));
+}
+
+/** Settlement metadata for diagnostics, never private reasoning as task output. */
+export function describeAssistantSettlement(output: unknown): string {
+    if (isRecord(output) && isRecord(output.tokenLog)) {
+        return `finish=${String(output.tokenLog.finish_reason ?? "unknown")}, reasoning=${typeof output.reasoning === "string" && output.reasoning.length > 0}`;
+    }
+    const latest = getLatestAssistantMessage(output);
+    const parts = Array.isArray(latest?.parts) ? latest.parts.filter(isRecord) : [];
+    return `finish=${latest?.info?.finish ?? "unknown"}, reasoning=${parts.some((part) => part.type === "reasoning")}, tools=${parts.filter((part) => part.type === "tool").length}`;
+}
+
+/** Describe persisted host/provider errors without losing structured status or message fields. */
+export function describeAssistantError(error: unknown): string {
+    if (error instanceof Error) return error.message;
+    if (!isRecord(error)) return String(error);
+    const data = isRecord(error.data) ? error.data : error;
+    const message = typeof data.message === "string" ? data.message : undefined;
+    const status = data.statusCode ?? data.status;
+    const name =
+        typeof error.name === "string"
+            ? error.name
+            : typeof error.type === "string"
+              ? error.type
+              : undefined;
+    const description = [name, message].filter(Boolean).join(": ") || JSON.stringify(error);
+    return status === undefined ? description : `${description} (status=${String(status)})`;
+}

package/src/shared/auto-update-provenance.ts

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from "node:fs";
+
+export const AUTO_UPDATE_CHECK_STATE_FILENAME = "last-update-check.json";
+
+export interface AutoUpdateCheckState {
+    lastCheckedMs?: number;
+    updaterPinnedSpec?: string;
+    updaterPinnedAt?: number;
+}
+
+export function readAutoUpdateCheckState(path: string): AutoUpdateCheckState | null {
+    if (!existsSync(path)) return null;
+    try {
+        const value = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+        if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+        const raw = value as Record<string, unknown>;
+        const state: AutoUpdateCheckState = {};
+        if (typeof raw.lastCheckedMs === "number" && Number.isFinite(raw.lastCheckedMs)) {
+            state.lastCheckedMs = raw.lastCheckedMs;
+        }
+        if (typeof raw.updaterPinnedSpec === "string" && raw.updaterPinnedSpec.length > 0) {
+            state.updaterPinnedSpec = raw.updaterPinnedSpec;
+        }
+        if (typeof raw.updaterPinnedAt === "number" && Number.isFinite(raw.updaterPinnedAt)) {
+            state.updaterPinnedAt = raw.updaterPinnedAt;
+        }
+        return state;
+    } catch {
+        return null;
+    }
+}
+
+export function isUpdaterPinnedSpec(
+    state: AutoUpdateCheckState | null,
+    configuredSpec: string,
+): boolean {
+    return (
+        state?.updaterPinnedSpec === configuredSpec &&
+        typeof state.updaterPinnedAt === "number" &&
+        Number.isFinite(state.updaterPinnedAt)
+    );
+}

package/src/shared/bounded-session-map.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "bun:test";
+import { BoundedSessionMap } from "./bounded-session-map";
+
+describe("BoundedSessionMap", () => {
+    it("rejects non-positive caps", () => {
+        expect(() => new BoundedSessionMap(0)).toThrow();
+        expect(() => new BoundedSessionMap(-5)).toThrow();
+        expect(() => new BoundedSessionMap(Number.NaN)).toThrow();
+    });
+
+    it("stores and retrieves values", () => {
+        const map = new BoundedSessionMap<number>(3);
+        map.set("a", 1);
+        map.set("b", 2);
+        expect(map.get("a")).toBe(1);
+        expect(map.get("b")).toBe(2);
+        expect(map.get("missing")).toBeUndefined();
+        expect(map.size).toBe(2);
+    });
+
+    it("evicts the oldest entry when cap is exceeded", () => {
+        const map = new BoundedSessionMap<string>(3);
+        map.set("a", "alpha");
+        map.set("b", "bravo");
+        map.set("c", "charlie");
+        map.set("d", "delta"); // evicts "a"
+        expect(map.has("a")).toBe(false);
+        expect(map.has("b")).toBe(true);
+        expect(map.has("c")).toBe(true);
+        expect(map.has("d")).toBe(true);
+        expect(map.size).toBe(3);
+    });
+
+    it("treats get() as a touch for LRU ordering", () => {
+        const map = new BoundedSessionMap<string>(3);
+        map.set("a", "alpha");
+        map.set("b", "bravo");
+        map.set("c", "charlie");
+        // Touch "a" — now "b" is the oldest.
+        expect(map.get("a")).toBe("alpha");
+        map.set("d", "delta");
+        expect(map.has("b")).toBe(false);
+        expect(map.has("a")).toBe(true);
+        expect(map.has("c")).toBe(true);
+        expect(map.has("d")).toBe(true);
+    });
+
+    it("peek() does NOT touch recency", () => {
+        const map = new BoundedSessionMap<number>(3);
+        map.set("a", 1);
+        map.set("b", 2);
+        map.set("c", 3);
+        expect(map.peek("a")).toBe(1);
+        // Adding a fourth entry should still evict "a" since peek didn't touch it.
+        map.set("d", 4);
+        expect(map.has("a")).toBe(false);
+    });
+
+    it("set() on existing key refreshes recency without growing size", () => {
+        const map = new BoundedSessionMap<number>(3);
+        map.set("a", 1);
+        map.set("b", 2);
+        map.set("c", 3);
+        map.set("a", 100); // refresh "a" to most-recent with new value
+        expect(map.size).toBe(3);
+        expect(map.get("a")).toBe(100);
+        map.set("d", 4); // evicts "b" (now oldest)
+        expect(map.has("b")).toBe(false);
+        expect(map.has("a")).toBe(true);
+    });
+
+    it("delete() removes entries and returns true when present", () => {
+        const map = new BoundedSessionMap<number>(3);
+        map.set("a", 1);
+        expect(map.delete("a")).toBe(true);
+        expect(map.delete("a")).toBe(false);
+        expect(map.size).toBe(0);
+    });
+
+    it("clear() drops all entries", () => {
+        const map = new BoundedSessionMap<number>(3);
+        map.set("a", 1);
+        map.set("b", 2);
+        map.clear();
+        expect(map.size).toBe(0);
+        expect(map.get("a")).toBeUndefined();
+    });
+
+    it("tolerates cap=1 edge case (every set evicts previous)", () => {
+        const map = new BoundedSessionMap<number>(1);
+        map.set("a", 1);
+        map.set("b", 2);
+        expect(map.has("a")).toBe(false);
+        expect(map.get("b")).toBe(2);
+        expect(map.size).toBe(1);
+    });
+});

package/src/shared/bounded-session-map.ts

@@ -0,0 +1,84 @@
+/**
+ * Bounded LRU map keyed by session id.
+ *
+ * Rationale: magic-context maintains several module-scope Maps that track
+ * per-session state (prepared injection cache, per-message token cache, etc.).
+ * These are cleared on the `session.deleted` event, but sessions that are
+ * never explicitly deleted — because OpenCode crashed, the user force-quit,
+ * the session was archived rather than deleted, or the session simply outlived
+ * the plugin process's interest in it — leak entries for the lifetime of the
+ * plugin process.
+ *
+ * In long-running OpenCode instances with thousands of sessions over time,
+ * an unbounded `Map<sessionId, LargeObject>` can retain tens of megabytes
+ * indefinitely. A session-scoped LRU with a generous cap (e.g. 100) covers
+ * any realistic working-set of active sessions a user actually cares about,
+ * while evicting cold session ids that will either never return or be
+ * rebuilt from durable SQLite state on their next transform pass.
+ *
+ * Implementation notes:
+ * - Built on `Map` which preserves insertion order. On every `set`/`get`
+ *   touch we delete+reinsert to move the key to the tail (most-recent).
+ * - Eviction drops the oldest entry (first in iteration order).
+ * - The cached value type is generic — callers decide what per-session state
+ *   to store. For injection/token state, all three properties of the cached
+ *   object are safe to throw away: they are either recomputable from the
+ *   messages array on the next pass, or reloadable from SQLite.
+ */
+export class BoundedSessionMap<V> {
+    private readonly maxEntries: number;
+    private readonly store = new Map<string, V>();
+
+    constructor(maxEntries: number) {
+        if (!Number.isFinite(maxEntries) || maxEntries < 1) {
+            throw new Error(`BoundedSessionMap: maxEntries must be >= 1, got ${maxEntries}`);
+        }
+        this.maxEntries = maxEntries;
+    }
+
+    get(sessionId: string): V | undefined {
+        const value = this.store.get(sessionId);
+        if (value === undefined) return undefined;
+        // Touch: move to most-recent position.
+        this.store.delete(sessionId);
+        this.store.set(sessionId, value);
+        return value;
+    }
+
+    /**
+     * Peek without touching recency — useful for `has`-style checks that
+     * should not rearrange LRU order. Use sparingly; `get` is the normal
+     * access path.
+     */
+    peek(sessionId: string): V | undefined {
+        return this.store.get(sessionId);
+    }
+
+    has(sessionId: string): boolean {
+        return this.store.has(sessionId);
+    }
+
+    set(sessionId: string, value: V): void {
+        if (this.store.has(sessionId)) {
+            // Refresh recency.
+            this.store.delete(sessionId);
+        } else if (this.store.size >= this.maxEntries) {
+            // Evict oldest entry. Map iteration is insertion-ordered.
+            const oldest = this.store.keys().next().value;
+            if (oldest !== undefined) this.store.delete(oldest);
+        }
+        this.store.set(sessionId, value);
+    }
+
+    delete(sessionId: string): boolean {
+        return this.store.delete(sessionId);
+    }
+
+    clear(): void {
+        this.store.clear();
+    }
+
+    get size(): number {
+        return this.store.size;
+    }
+}

package/src/shared/builtin-commands.ts

@@ -0,0 +1,46 @@
+import type { Config } from "@opencode-ai/sdk";
+
+// Keep command metadata independent of server features: config validation and
+// the separately shipped TUI need the same reserved command names.
+type BuiltinCommandConfig = NonNullable<Config["command"]>;
+
+const COMPACTION_ENABLED_PATH = `compaction${".enabled"}`;
+
+export function getMagicContextBuiltinCommands(compactionEnabled = true) {
+    const unavailableInCompactionOff = (command: string) =>
+        `Unavailable when ${COMPACTION_ENABLED_PATH} is false: /${command} manages compacted history.`;
+
+    return {
+        "mmc-status": {
+            template: "mmc-status",
+            description: "Show magic context status, pending queue, cache TTL, and debug info",
+        },
+        "mmc-recomp": {
+            template: "mmc-recomp",
+            description: compactionEnabled
+                ? "Rebuild compressed history from raw history (full or <start>-<end> range); memories are not changed"
+                : unavailableInCompactionOff("mmc-recomp"),
+        },
+        "mmc-wrapup": {
+            template: "mmc-wrapup",
+            description: compactionEnabled
+                ? "Compact older live history while keeping the newest messages raw"
+                : unavailableInCompactionOff("mmc-wrapup"),
+        },
+        "mmc-flush": {
+            template: "mmc-flush",
+            description: compactionEnabled
+                ? "Force-process all pending magic context operations immediately"
+                : unavailableInCompactionOff("mmc-flush"),
+        },
+        "mmc-memory-maintain": {
+            template: "mmc-memory-maintain",
+            description:
+                "Memory maintenance: `run` one run now, `status` (default) for schedule/runs/pause, `resume` to clear an anomaly pause",
+        },
+    } satisfies BuiltinCommandConfig;
+}
+
+export type MagicContextBuiltinCommandName = keyof ReturnType<
+    typeof getMagicContextBuiltinCommands
+>;