prism-mcp-server 20.11.1 → 20.12.0

package/README.md

@@ -116,6 +116,44 @@ or by re-enabling after each run.
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.12.0
+
+- **Prism now tells you when it's out of date.** Session startup shows a
+  one-line update notice when a newer release exists — cache-backed, at most
+  one registry check per day, silent offline. `PRISM_NO_UPDATE_CHECK=1`
+  opts out.
+- **Hands-free updates, if you want them.** `prism autoupdate enable` sets up
+  a daily `prism update --if-idle`: it updates only the global npm package,
+  defers while any Prism server is running, and never touches host
+  configuration — that stays behind a visible `prism connect`.
+
+## What's New in v20.11.1
+
+- **Saving memory never gets refused.** The save path used to reject
+  `session_save_ledger`/`save_handoff` calls when its path-to-project
+  heuristic disagreed with the project you declared — and the registry the
+  heuristic trusted could contain junk from earlier auto-registration, so
+  legitimate sessions ended unsaved. Your declaration now always wins; the
+  disagreement is returned as an advisory warning, and auto-registration
+  only accepts real repository roots.
+- **Screenshots are evidence again.** `prism browser` captures on macOS were
+  silently *upscaled* to the size cap, so a screenshot no longer showed what
+  actually rendered. Only genuinely oversized captures are resized now, and
+  the cap no longer clips a standard 1920-wide viewport.
+
+## What's New in v20.10.0 – v20.11.0
+
+- **Skill routing now works mid-session.** New prompts are matched on-device
+  as the conversation moves — not just on turn one — and injected within each
+  host's real context limits (Claude Code caps hook output at 10k chars;
+  Codex truncates by default), with pointer-first delivery when a payload
+  can't fit inline.
+- **`prism connect` is a converge command.** It self-updates first, re-execs,
+  then reconciles MCP registration, skills, and hooks — no more
+  "fresh config, stale code" machines.
+- **Scoped skills route on prompts too**, and startup output survives hosts
+  that discard structured tool content.
+
 ## What's New in v20.9.0 – v20.9.3
 
 - **Your skills follow your account.** `skill_save` stores a skill at the

package/dist/autoUpdate.js

@@ -0,0 +1,233 @@
+/**
+ * `prism update` / `prism autoupdate` — unattended-safe package updates.
+ *
+ * Why this is NOT `prism connect` on a timer (design review 2026-08-14):
+ * connect writes host configuration and expects hosts to be closed — a
+ * condition no scheduler can guarantee. This module's whole authority is
+ * `npm install -g prism-mcp-server@<latest>`:
+ *   - host configuration, hooks, and hook trust are untouchable from here —
+ *     there is no code path to them;
+ *   - running server processes keep the code they booted with; the next
+ *     process start picks up the new release (global registrations resolve
+ *     through the bin symlink);
+ *   - `--if-idle` defers entirely while any Prism MCP server process is
+ *     alive, and an UNVERIFIABLE process list counts as busy — fail safe;
+ *   - a single-instance lock prevents overlapping npm runs (a scheduler
+ *     firing while an operator updates by hand).
+ *
+ * Configuration migrations stay behind a visible `prism connect` run.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, openSync, closeSync, writeFileSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isNewer } from "./selfUpdate.js";
+const PACKAGE = "prism-mcp-server";
+const SEMVER = /^\d+\.\d+\.\d+$/;
+export const AUTOUPDATE_LABEL = "com.synalux.prism.autoupdate";
+function defaultFetchLatest() {
+    return execFileSync("npm", ["view", PACKAGE, "version"], {
+        encoding: "utf8",
+        timeout: 15_000,
+    }).trim();
+}
+function defaultInstall(version) {
+    execFileSync("npm", ["install", "-g", `${PACKAGE}@${version}`], {
+        stdio: "inherit",
+        timeout: 300_000,
+    });
+}
+/** Lines for live Prism MCP server processes. Throws when `ps` is unusable —
+ *  the caller treats that as busy, never as idle. */
+export function defaultListPrismProcesses() {
+    const out = execFileSync("ps", ["-axo", "pid=,command="], {
+        encoding: "utf8",
+        timeout: 10_000,
+    });
+    return out
+        .split("\n")
+        .filter((line) => /server\.js/.test(line) && /prism/i.test(line))
+        .map((line) => line.trim());
+}
+const LOCK_DIR = () => join(homedir(), ".prism-mcp");
+const LOCK_FILE = () => join(LOCK_DIR(), "update.lock");
+/** O_EXCL lockfile with stale-holder recovery (dead pid → reclaim once). */
+export function defaultAcquireLock() {
+    mkdirSync(LOCK_DIR(), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(LOCK_FILE(), "wx");
+            writeFileSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                rmSync(LOCK_FILE(), { force: true });
+            }
+            catch { /* released is released */ } };
+        }
+        catch {
+            try {
+                const holder = parseInt(readFileSync(LOCK_FILE(), "utf8").trim(), 10);
+                if (Number.isInteger(holder)) {
+                    try {
+                        process.kill(holder, 0); // alive → genuinely locked
+                        return null;
+                    }
+                    catch {
+                        rmSync(LOCK_FILE(), { force: true }); // stale → reclaim and retry
+                        continue;
+                    }
+                }
+                rmSync(LOCK_FILE(), { force: true }); // unreadable holder → reclaim
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+export function runPackageUpdate(deps) {
+    const env = deps.env ?? process.env;
+    const log = deps.log ?? (() => { });
+    if (env.PRISM_NO_SELF_UPDATE === "1") {
+        return { action: "skipped", detail: "PRISM_NO_SELF_UPDATE=1" };
+    }
+    if ((env.VITEST || env.NODE_ENV === "test") && !deps.fetchLatest) {
+        return { action: "skipped", detail: "test environment" };
+    }
+    if (deps.currentVersion.includes("-")) {
+        return { action: "skipped", detail: `dev build ${deps.currentVersion} — not touching it` };
+    }
+    if (deps.ifIdle) {
+        let running;
+        try {
+            running = (deps.listPrismProcesses ?? defaultListPrismProcesses)();
+        }
+        catch (error) {
+            return {
+                action: "deferred",
+                detail: `cannot verify idleness (${error instanceof Error ? error.message.split("\n")[0] : String(error)}) — deferring`,
+            };
+        }
+        if (running.length > 0) {
+            return {
+                action: "deferred",
+                detail: `${running.length} Prism MCP process(es) running — deferred until idle`,
+            };
+        }
+    }
+    const release = (deps.acquireLock ?? defaultAcquireLock)();
+    if (!release) {
+        return { action: "locked", detail: "another prism update is already running" };
+    }
+    try {
+        let latest;
+        try {
+            latest = (deps.fetchLatest ?? defaultFetchLatest)();
+        }
+        catch (error) {
+            return { action: "failed", detail: `registry unreachable (${error instanceof Error ? error.message.split("\n")[0] : String(error)})` };
+        }
+        if (!SEMVER.test(latest)) {
+            return { action: "failed", detail: `registry returned unexpected version "${latest}"` };
+        }
+        if (!isNewer(deps.currentVersion, latest)) {
+            return { action: "current", detail: `${deps.currentVersion} is current`, latest };
+        }
+        log(`prism ${deps.currentVersion} → ${latest}: updating the global package …`);
+        try {
+            (deps.install ?? defaultInstall)(latest);
+        }
+        catch (error) {
+            return { action: "failed", detail: `npm install -g failed (${error instanceof Error ? error.message.split("\n")[0] : String(error)})`, latest };
+        }
+        return { action: "updated", detail: `global package now ${latest}; running servers pick it up on their next start`, latest };
+    }
+    finally {
+        release();
+    }
+}
+// ─── LaunchAgent (macOS) scheduling ──────────────────────────────
+export function autoupdatePlistPath() {
+    return join(homedir(), "Library", "LaunchAgents", `${AUTOUPDATE_LABEL}.plist`);
+}
+/** Daily 03:30 local, catch-up on wake (LaunchAgents coalesce missed runs). */
+export function buildAutoupdatePlist(prismBin) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${AUTOUPDATE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${prismBin}</string>
+    <string>update</string>
+    <string>--if-idle</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key><integer>3</integer>
+    <key>Minute</key><integer>30</integer>
+  </dict>
+  <key>StandardOutPath</key><string>/tmp/${AUTOUPDATE_LABEL}.log</string>
+  <key>StandardErrorPath</key><string>/tmp/${AUTOUPDATE_LABEL}.log</string>
+</dict>
+</plist>
+`;
+}
+export function autoupdateStatus() {
+    const plistPath = autoupdatePlistPath();
+    if (process.platform !== "darwin") {
+        return { supported: false, enabled: false, plistPath, detail: "scheduled updates are macOS-only for now (LaunchAgent)" };
+    }
+    const enabled = existsSync(plistPath);
+    return {
+        supported: true,
+        enabled,
+        plistPath,
+        detail: enabled ? `enabled — daily 03:30, log: /tmp/${AUTOUPDATE_LABEL}.log` : "disabled",
+    };
+}
+/** Resolve the `prism` bin the LaunchAgent should run. Warns (does not
+ *  refuse) when it resolves outside node_modules — a checkout CLI still
+ *  updates the global package, but the operator should know which code
+ *  their scheduler runs. */
+export function resolvePrismBin(log) {
+    const bin = execFileSync("which", ["prism"], { encoding: "utf8", timeout: 5_000 }).trim();
+    if (!bin)
+        throw new Error("`prism` not found on PATH — install with: npm install -g prism-mcp-server");
+    try {
+        const real = execFileSync("readlink", ["-f", bin], { encoding: "utf8", timeout: 5_000 }).trim();
+        if (real && !real.includes("node_modules")) {
+            log(`⚠ ${bin} resolves to a source checkout (${real}); the scheduled update will run that CLI (it still updates only the global package)`);
+        }
+    }
+    catch { /* readlink unavailable — proceed with the raw path */ }
+    return bin;
+}
+export function enableAutoupdate(log) {
+    if (process.platform !== "darwin")
+        return autoupdateStatus();
+    const plistPath = autoupdatePlistPath();
+    const bin = resolvePrismBin(log);
+    mkdirSync(join(homedir(), "Library", "LaunchAgents"), { recursive: true });
+    writeFileSync(plistPath, buildAutoupdatePlist(bin));
+    // Reload cleanly whether or not a previous generation was loaded.
+    try {
+        execFileSync("launchctl", ["unload", plistPath], { timeout: 10_000, stdio: "ignore" });
+    }
+    catch { /* not loaded */ }
+    execFileSync("launchctl", ["load", "-w", plistPath], { timeout: 10_000 });
+    return autoupdateStatus();
+}
+export function disableAutoupdate() {
+    if (process.platform !== "darwin")
+        return autoupdateStatus();
+    const plistPath = autoupdatePlistPath();
+    try {
+        execFileSync("launchctl", ["unload", plistPath], { timeout: 10_000, stdio: "ignore" });
+    }
+    catch { /* not loaded */ }
+    rmSync(plistPath, { force: true });
+    return autoupdateStatus();
+}

package/dist/cli.js

@@ -164,6 +164,51 @@ program
 program
     .command('browser')
     .description('Run the packaged local Prism Browser automation CLI');
+// ─── prism update / prism autoupdate ──────────────────────────
+// Unattended-safe package updates. Deliberately NOT connect-on-a-timer:
+// connect writes host configuration and expects hosts to be closed, which
+// a scheduler cannot guarantee. `update` touches only the global npm
+// package; running servers pick the release up on their next start.
+program
+    .command('update')
+    .description('Update the global prism-mcp-server package (never touches host configuration)')
+    .option('--if-idle', 'Only update while no Prism MCP server process is running (scheduler-safe)')
+    .action(async (options) => {
+    const { runPackageUpdate } = await import('./autoUpdate.js');
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    const result = runPackageUpdate({
+        currentVersion: pkg.version,
+        ifIdle: options.ifIdle,
+        log: (l) => console.log(l),
+    });
+    console.log(`${result.action}: ${result.detail}`);
+    process.exit(result.action === 'failed' ? 1 : 0);
+});
+program
+    .command('autoupdate <action>')
+    .description('Scheduled daily `prism update --if-idle` — enable | disable | status (opt-in, macOS)')
+    .action(async (action) => {
+    const { enableAutoupdate, disableAutoupdate, autoupdateStatus } = await import('./autoUpdate.js');
+    const log = (l) => console.log(l);
+    let status;
+    if (action === 'enable')
+        status = enableAutoupdate(log);
+    else if (action === 'disable')
+        status = disableAutoupdate();
+    else if (action === 'status')
+        status = autoupdateStatus();
+    else {
+        console.error(`unknown action "${action}" — use enable, disable, or status`);
+        process.exit(1);
+    }
+    if (!status.supported) {
+        console.log(`− ${status.detail}`);
+        process.exit(action === 'status' ? 0 : 1);
+    }
+    console.log(status.enabled
+        ? `✓ autoupdate ${status.detail}\n  agent: ${status.plistPath}`
+        : `− autoupdate ${status.detail}`);
+});
 // ─── prism connect ────────────────────────────────────────────
 // Registers this installed package with supported MCP hosts. The
 // merge is additive: an existing `prism` or `prism-mcp` entry is

package/dist/server.js

@@ -1293,6 +1293,21 @@ export async function startServer() {
     runSkillManifestSync();
     const skillManifestRefresh = setInterval(runSkillManifestSync, 5 * 60 * 1000);
     skillManifestRefresh.unref();
+    // Update-check refresh: 30s AFTER startup on an unref'd timer, so the
+    // registry ping is never on the prompt-critical path and never interleaves
+    // with first-boot storage initialization (a boot-time kick raced the
+    // first-run demo seed on CI — same-instant sqlite init from two paths).
+    // Short-lived spawns (codex exec) exit before the timer fires and never
+    // ping npm; long-lived hosts refresh 30s in, ample for a 24h TTL.
+    // session_bootstrap renders from the persisted cache only.
+    const updateCheckTimer = setTimeout(() => {
+        void (async () => {
+            const { refreshUpdateCache } = await import("./updateNotice.js");
+            const { getSetting, setSetting } = await import("./storage/configStorage.js");
+            await refreshUpdateCache({ getSetting, setSetting });
+        })().catch(() => { });
+    }, 30_000);
+    updateCheckTimer.unref();
     // Register graceful shutdown handlers (SIGTERM, SIGINT, SIGHUP, stdin close).
     // The stdin close handler is critical — when MCP clients disconnect, they
     // often just close the pipe without sending a signal, leaving zombie processes.

package/dist/tools/ledgerHandlers.js

@@ -34,6 +34,18 @@ import { getSetting, setSetting, getAllSettings, refreshConfigStorageCache } fro
 import { MATERIALIZED_GENERATION_KEY } from "../skillManifestSync.js";
 import { mergeHandoff, dbToHandoffSchema, sanitizeForMerge } from "../utils/crdtMerge.js";
 import { resolveProject } from "../utils/projectResolver.js";
+import { getUpdateNotice } from "../updateNotice.js";
+// The running server's own version, for the update-available notice. A read
+// failure must never affect startup: an empty string fails the notice's
+// semver gate, so no notice renders rather than a bogus "running 0.0.0".
+const SERVER_PACKAGE_VERSION = (() => {
+    try {
+        return JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version ?? "";
+    }
+    catch {
+        return "";
+    }
+})();
 import { isRecoverableStartupStorageError, LOCAL_STARTUP_FALLBACK_NOTICE, } from "../utils/startupRecovery.js";
 import { PRISM_USER_ID, PRISM_AUTO_CAPTURE, PRISM_CAPTURE_PORTS } from "../config.js";
 import { captureLocalEnvironment } from "../utils/autoCapture.js";
@@ -2026,7 +2038,17 @@ export async function sessionBootstrapHandler(args = {}, options = {}) {
         ? `👋 Welcome to Prism — first run detected. Let's get you productive in a few minutes.`
         : `👋 Welcome back, ${greetingName}. Prism is loading ${depth} context.`;
     const identityBlock = `- 🤖 **Agent Identity:** ${escapeNativeMarkdown(compactWithOmissionCount(role, 80))} — ${greetingName}`;
-    const startupHeader = isFirstRun ? greeting : `${greeting}\n\n${identityBlock}`;
+    // Cache-only by contract: server startup refreshes the cache asynchronously;
+    // this call never touches the npm registry. First run skips the notice — a
+    // just-installed machine is current, and that screen is action-first.
+    const updateNotice = isFirstRun ? "" : await getUpdateNotice({
+        currentVersion: SERVER_PACKAGE_VERSION,
+        getSetting,
+        runningFrom: process.argv[1],
+    });
+    const startupHeader = isFirstRun
+        ? greeting
+        : `${greeting}\n\n${identityBlock}${updateNotice ? `\n${updateNotice}` : ""}`;
     if (projects.length === 0) {
         const dashboardUrl = await readDashboardUrl();
         const dashboardLine = dashboardUrl

package/dist/updateNotice.js

@@ -0,0 +1,104 @@
+/**
+ * Update-available notice — the trigger half of self-update.
+ *
+ * `prism connect` can converge a machine to the latest release, but nothing
+ * ever *ran* it: no launch agent, cron, or background updater exists, so
+ * releases only reached machines whose operator happened to re-run connect.
+ * The notice closes that gap at the only place every user reliably looks —
+ * the first turn of a session.
+ *
+ * Split enforced by design review (2026-08-14):
+ *  - `getUpdateNotice` is CACHE-ONLY. It runs on the prompt-critical path
+ *    (session_bootstrap) and must never touch the npm registry.
+ *  - `refreshUpdateCache` is the async half. Server startup kicks it
+ *    fire-and-forget after initialization; it respects a 24-hour TTL so a
+ *    machine pings the registry at most once a day no matter how many
+ *    short-lived server processes spawn (codex exec starts one per run).
+ *  - Offline is silent. A registry answer that is not plain semver is
+ *    discarded, never cached, never rendered — the cached value ends up
+ *    inside model-facing markdown, so it is validated on write AND on read.
+ */
+import { execFile } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { isNewer } from "./selfUpdate.js";
+export const UPDATE_CHECK_KEY = "update_check";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const SEMVER = /^\d+\.\d+\.\d+$/;
+const PACKAGE = "prism-mcp-server";
+async function readCache(getSetting) {
+    try {
+        const parsed = JSON.parse(await getSetting(UPDATE_CHECK_KEY, "{}"));
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function cacheIsFresh(cache, now) {
+    return typeof cache.checked_at === "number" &&
+        now() - cache.checked_at < CACHE_TTL_MS &&
+        now() - cache.checked_at >= 0; // a future timestamp is corruption, not freshness
+}
+/** Cache-only: renders the notice line, or "" — never touches the network. */
+export async function getUpdateNotice(deps) {
+    const env = deps.env ?? process.env;
+    if (env.PRISM_NO_UPDATE_CHECK === "1")
+        return "";
+    // A caller that could not determine its own version renders nothing —
+    // a comparison against "" or "0.0.0" would call every release an update.
+    if (!SEMVER.test(deps.currentVersion))
+        return "";
+    const now = deps.now ?? Date.now;
+    const cache = await readCache(deps.getSetting);
+    if (!cacheIsFresh(cache, now))
+        return "";
+    const latest = typeof cache.latest === "string" && SEMVER.test(cache.latest) ? cache.latest : "";
+    if (!latest || !isNewer(deps.currentVersion, latest))
+        return "";
+    let fromCheckout = false;
+    if (deps.runningFrom) {
+        let resolved = deps.runningFrom;
+        try {
+            resolved = realpathSync(deps.runningFrom);
+        }
+        catch { /* keep raw */ }
+        fromCheckout = !resolved.includes("node_modules");
+    }
+    const command = fromCheckout ? "prism connect --refresh" : "prism connect";
+    return `- ⬆️ **Update available:** Prism ${latest} (running ${deps.currentVersion}) — run \`${command}\``;
+}
+function defaultFetchLatest() {
+    return new Promise((resolve, reject) => {
+        const child = execFile("npm", ["view", PACKAGE, "version"], { encoding: "utf8", timeout: 10_000 }, (error, stdout) => (error ? reject(error) : resolve(stdout.trim())));
+        // A short-lived server process (codex exec) must be able to exit without
+        // waiting on this check.
+        child.unref?.();
+    });
+}
+/** Async half: refresh the persisted cache when the TTL has lapsed.
+ *  Never throws — offline machines boot silently. */
+export async function refreshUpdateCache(deps) {
+    const env = deps.env ?? process.env;
+    if (env.PRISM_NO_UPDATE_CHECK === "1")
+        return;
+    if (env.VITEST || env.NODE_ENV === "test") {
+        // Test runners never reach the network — same rule as self-update —
+        // EXCEPT through an explicitly injected fetcher, which is the test.
+        if (!deps.fetchLatest)
+            return;
+    }
+    const now = deps.now ?? Date.now;
+    try {
+        const cache = await readCache(deps.getSetting);
+        if (cacheIsFresh(cache, now))
+            return;
+        const latest = (await (deps.fetchLatest ?? defaultFetchLatest)()).trim();
+        if (!SEMVER.test(latest))
+            return;
+        await deps.setSetting(UPDATE_CHECK_KEY, JSON.stringify({ checked_at: now(), latest }));
+    }
+    catch {
+        // Offline, registry down, npm missing: silence. The notice simply
+        // does not render until a later successful check.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.11.1",
+  "version": "20.12.0",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Persistent session memory for AI coding agents that never leaves your machine — including the on-device model that reasons over it. Restores your prior decisions, open TODOs, and changed files across sessions; adds associative recall of related past work, semantic drift detection, and local inference. Local-first by default. Works with Claude Code, Cursor, and Codex.",
   "module": "index.ts",