minutes-mcp 0.25.2 → 0.25.4

package/dist/corpus-lease.js

@@ -5,6 +5,7 @@ import { lstat, mkdir, open, opendir, realpath, stat } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { decodePolicyUtf8, fingerprintTextFileFromBoundParent, readTextFileWithRevisionFromBoundParent, writeOperatorDiagnostic, } from "./secure-read.js";
+import { nodeChildEnvironment } from "./node-child.js";
 const MAX_AUTHORIZATION_ATTEMPTS = 2;
 const DEFAULT_FENCE_TIMEOUT_MS = 5_000;
 const DEFAULT_AUTHORIZATION_TIMEOUT_MS = 15_000;
@@ -1431,7 +1432,7 @@ async function dispatchStableCorpusLease(root, operation, hooks = {}) {
         detached: process.platform !== "win32",
         stdio: ["pipe", "pipe", "pipe"],
         windowsHide: true,
-        env: { ...process.env },
+        env: nodeChildEnvironment(),
     });
     child.stderr?.resume();
     let resolveTermination;

package/dist/index.d.ts

@@ -315,6 +315,30 @@ export declare function liveMeetingSnippet(body: string, query?: string): string
 export declare function shouldRunMainEntry(argv1: string | null | undefined, moduleFilename: string): boolean;
 export declare function parseKnowledgeConfig(configContent: string): KnowledgeConfigStatus | null;
 export declare function createCapabilityRepairCoordinator(repair: () => Promise<boolean>, maximumAttempts?: number): () => Promise<boolean>;
+export type HealthItem = {
+    label?: unknown;
+    state?: unknown;
+    [key: string]: unknown;
+};
+export type HealthOutput = {
+    ok: boolean;
+    items: HealthItem[] | null;
+    engine?: string;
+    effectiveEngine?: string;
+    model?: string;
+};
+export declare function parseHealthOutput(stdout: string): HealthOutput;
+type WhisperModelCheckState = {
+    done: boolean;
+};
+export type EnsureWhisperModelOptions = {
+    checkState?: WhisperModelCheckState;
+    health?: () => Promise<string>;
+    configFileExists?: () => Promise<boolean>;
+    setup?: (model: string) => Promise<void>;
+    log?: (message: string) => void;
+};
+export declare function ensureWhisperModel(options?: EnsureWhisperModelOptions): Promise<void>;
 declare function isCliAvailable(): Promise<boolean>;
 export declare function repairCliCapabilities(required: readonly string[], capabilities: CapabilityProbeResult, repair: () => Promise<boolean>, reprobe: () => CapabilityProbeResult): Promise<CapabilityProbeResult>;
 export declare function mcpCliChildEnv(extra?: Record<string, string>): Record<string, string | undefined>;
@@ -451,7 +475,8 @@ export type AgentTrustReadiness = {
     qmd_retirement: "ready-clean" | "blocked";
     remediation?: string;
 };
-export declare function readAgentTrustReadiness(runner?: MinutesRunner): Promise<AgentTrustReadiness>;
+export declare function cliTooOldGuidance(installedVersion: string, minimumVersion?: string, platform?: NodeJS.Platform): string;
+export declare function readAgentTrustReadiness(runner?: MinutesRunner, platform?: NodeJS.Platform): Promise<AgentTrustReadiness>;
 export declare function requireAgentTrustReadiness(runner?: MinutesRunner): Promise<AgentTrustReadiness>;
 export declare function afterAgentTrustReadiness<T>(operation: () => Promise<T>, runner?: MinutesRunner): Promise<T>;
 export declare function afterRequiredCli<T>(operation: () => Promise<T>, cliProbe?: () => Promise<boolean>): Promise<T>;

package/dist/index.js

@@ -44,14 +44,15 @@ import { execFile, spawn, spawnSync } from "child_process";
 import { createHash } from "crypto";
 import { promisify } from "util";
 import { closeSync, constants, copyFileSync, existsSync, fstatSync, mkdirSync, openSync, readdirSync, realpathSync, statSync, } from "fs";
-import { mkdir, readFile, rm, stat, writeFile } from "fs/promises";
+import { access, mkdir, readFile, rm, stat, writeFile } from "fs/promises";
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
 import { parse as parseYaml } from "yaml";
 import * as reader from "minutes-sdk";
 import { canonicalizeRoot, expandHomeLikePath, readTextFileInDirectory, validatePathInDirectories, validatePathInDirectory, } from "./paths.js";
-import { isCliCompatible } from "./version.js";
+import { isCliCompatible, parseVersion } from "./version.js";
+import { nodeChildEnvironment } from "./node-child.js";
 import { hasFeature, probeCapabilitiesSync, } from "./capabilities.js";
 import { downloadReleaseBinaryWithChecksum, extractZipWithPowerShell, } from "./autoInstall.js";
 import { attachCaptureRelay, } from "./captureRelay.js";
@@ -1569,7 +1570,7 @@ const COPILOT_SUPPORTED = hasFeature(CLI_CAPABILITIES, "copilot_realtime");
 // `./version.ts` (see issue #183). Hosted `.mcpb` bundles will run
 // against CLIs with different minor/patch numbers within the same
 // major; that is explicitly supported.
-const MCP_SERVER_VERSION = "0.25.2";
+const MCP_SERVER_VERSION = "0.25.4";
 export function parseKnowledgeConfig(configContent) {
     const knowledgeMatch = configContent.match(/\[knowledge\][\s\S]*?(?=\n\[|$)/);
     if (!knowledgeMatch) {
@@ -1776,38 +1777,150 @@ async function checkCliVersion() {
         // Version check is best-effort. Don't block on failure.
     }
 }
-// ── Auto-setup: download whisper model if missing ───────────
-// Recording needs a whisper model (~75MB for tiny). If the CLI is
-// available but the model isn't downloaded, trigger setup automatically
-// in the background so the first "start recording" just works.
+// ── Auto-setup: download configured whisper model if missing ───────────
+// Whisper recording needs a model. If Whisper is configured but its model
+// isn't downloaded, trigger setup automatically in the background so the
+// first "start recording" just works without changing the user's choice.
 let modelCheckDone = false;
-async function ensureWhisperModel() {
-    if (modelCheckDone)
+function isHealthItem(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function parseHealthOutput(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return { ok: false, items: null };
+    }
+    if (Array.isArray(parsed)) {
+        return parsed.every(isHealthItem)
+            ? { ok: true, items: parsed }
+            : { ok: false, items: null };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, items: null };
+    }
+    const envelope = parsed;
+    if (envelope.ok !== true) {
+        return { ok: false, items: null };
+    }
+    const data = envelope.data;
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        return { ok: false, items: null };
+    }
+    const dataRecord = data;
+    const items = dataRecord.items;
+    if (!Array.isArray(items) || !items.every(isHealthItem)) {
+        return { ok: false, items: null };
+    }
+    return {
+        ok: true,
+        items,
+        ...(typeof dataRecord.engine === "string" ? { engine: dataRecord.engine } : {}),
+        ...(typeof dataRecord.effective_engine === "string"
+            ? { effectiveEngine: dataRecord.effective_engine }
+            : {}),
+        ...(typeof dataRecord.model === "string" ? { model: dataRecord.model } : {}),
+    };
+}
+async function configFileExists() {
+    const configRoot = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    try {
+        await access(join(configRoot, "minutes", "config.toml"));
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export async function ensureWhisperModel(options = {}) {
+    const checkState = options.checkState;
+    if (checkState ? checkState.done : modelCheckDone)
         return;
-    modelCheckDone = true;
+    if (checkState)
+        checkState.done = true;
+    else
+        modelCheckDone = true;
+    const log = options.log ?? ((message) => console.error(message));
+    const health = options.health ?? (async () => {
+        const { stdout } = await execFileAsync(MINUTES_BIN, ["health", "--json"], {
+            timeout: 10000,
+            env: mcpCliChildEnv(),
+        });
+        return stdout;
+    });
+    const setup = options.setup ?? (async (model) => {
+        await execFileAsync(MINUTES_BIN, ["setup", "--model", model], {
+            timeout: 300000,
+            env: mcpCliChildEnv(),
+        });
+    });
+    const doesConfigFileExist = options.configFileExists ?? configFileExists;
+    let healthOutput;
     try {
-        // health --json returns an array of { label, state, detail, optional } items.
-        // The "Speech model" item has state "ready" when downloaded.
-        const { stdout } = await execFileAsync(MINUTES_BIN, ["health", "--json"], { timeout: 10000, env: mcpCliChildEnv() });
-        const items = JSON.parse(stdout);
-        const modelItem = Array.isArray(items) && items.find((i) => i.label === "Speech model");
-        if (modelItem && modelItem.state === "ready") {
-            console.error("[Minutes] Whisper model ready");
+        healthOutput = parseHealthOutput(await health());
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log(`[Minutes] Unable to check speech model status — skipping Whisper auto-setup: ${message}`);
+        return;
+    }
+    if (!healthOutput.ok || healthOutput.items === null) {
+        log("[Minutes] Unrecognized health --json output — skipping Whisper auto-setup");
+        return;
+    }
+    const modelItem = healthOutput.items.find((item) => item.label === "Speech model");
+    if (!modelItem) {
+        log("[Minutes] unrecognized health items — skipping Whisper auto-setup");
+        return;
+    }
+    if (modelItem.state === "ready") {
+        log("[Minutes] Whisper model ready");
+        return;
+    }
+    if (modelItem.state !== "attention") {
+        log(`[Minutes] Speech model health state is ${String(modelItem.state)} — skipping Whisper auto-setup`);
+        return;
+    }
+    const engineForDecision = healthOutput.effectiveEngine ?? healthOutput.engine;
+    if (engineForDecision !== undefined && engineForDecision.toLowerCase() !== "whisper") {
+        const upgradeGuidance = healthOutput.effectiveEngine === undefined
+            ? "; upgrade the CLI to let auto-setup resolve the effective engine"
+            : "";
+        log(`[Minutes] Transcription engine is ${engineForDecision} — skipping Whisper auto-setup${upgradeGuidance}`);
+        return;
+    }
+    let model = healthOutput.model;
+    if (model !== undefined) {
+        log(`[Minutes] Whisper model ${model} is configured but not ready — downloading it...`);
+    }
+    else {
+        let configExists;
+        try {
+            configExists = await doesConfigFileExist();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log(`[Minutes] Unable to check for an existing config — skipping Whisper auto-setup: ${message}`);
             return;
         }
+        if (configExists) {
+            log("[Minutes] config exists but this CLI does not report the configured model; run `minutes setup --model <your model>` or upgrade the CLI");
+            return;
+        }
+        model = "tiny";
+        log("[Minutes] No Whisper model is configured — downloading tiny model (~75MB)...");
     }
-    catch {
-        // health command may not exist in older CLI versions — fall through to setup
-    }
-    // Model not found — download tiny model in background
-    console.error("[Minutes] Whisper model not found — downloading tiny model (~75MB)...");
     try {
-        await execFileAsync(MINUTES_BIN, ["setup", "--model", "tiny"], { timeout: 300000, env: mcpCliChildEnv() });
-        console.error("[Minutes] ✓ Whisper tiny model downloaded — recording is ready");
+        await setup(model);
+        log(`[Minutes] ✓ Whisper ${model} model downloaded — recording is ready`);
     }
-    catch (e) {
-        console.error(`[Minutes] Model download failed: ${e.message || e}. ` +
-            `Run manually: minutes setup --model tiny`);
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log(`[Minutes] Model download failed: ${message}. Run manually: minutes setup --model ${model}`);
     }
 }
 // ── CLI availability detection ──────────────────────────────
@@ -2483,7 +2596,47 @@ export async function readKnowledgeStatusSnapshot(runner = runMinutes) {
     }
     return result;
 }
-export async function readAgentTrustReadiness(runner = runMinutes) {
+const AGENT_READINESS_MIN_CLI_VERSION = "0.25.0";
+function isOlderVersion(installed, minimum) {
+    const found = parseVersion(installed);
+    const required = parseVersion(minimum);
+    if (!found || !required)
+        return false;
+    if (found.major !== required.major)
+        return found.major < required.major;
+    if (found.minor !== required.minor)
+        return found.minor < required.minor;
+    return found.patch < required.patch;
+}
+function rejectedUnknownSubcommand(error, subcommand) {
+    const diagnostic = [error?.stderr, error?.message]
+        .filter((value) => typeof value === "string")
+        .join("\n")
+        .toLowerCase();
+    return (diagnostic.includes(subcommand.toLowerCase()) &&
+        /(?:unrecognized|unknown|invalid) subcommand/.test(diagnostic));
+}
+export function cliTooOldGuidance(installedVersion, minimumVersion = AGENT_READINESS_MIN_CLI_VERSION, platform = process.platform) {
+    const update = platform === "darwin" || platform === "win32"
+        ? "Install the latest free Minutes desktop app from https://useminutes.app"
+        : "Update the Minutes CLI from https://useminutes.app, or run `cargo install minutes-cli`";
+    return (`The Minutes engine is too old for this extension (found v${installedVersion}; ` +
+        `needs v${minimumVersion} or newer). ${update}, then restart this app.`);
+}
+async function oldCliReadinessGuidance(runner, platform) {
+    try {
+        const { stdout } = await runner(["--version"], 5000);
+        const match = stdout.match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/);
+        if (!match || !isOlderVersion(match[0], AGENT_READINESS_MIN_CLI_VERSION)) {
+            return null;
+        }
+        return cliTooOldGuidance(match[0], AGENT_READINESS_MIN_CLI_VERSION, platform);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readAgentTrustReadiness(runner = runMinutes, platform = process.platform) {
     let stdout;
     try {
         ({ stdout } = await runner(["agent-readiness", "--json"]));
@@ -2496,6 +2649,11 @@ export async function readAgentTrustReadiness(runner = runMinutes) {
         // "could not be verified safely" and nothing to do about it (#774).
         if (error?.cliMissing)
             throw error;
+        if (rejectedUnknownSubcommand(error, "agent-readiness")) {
+            const guidance = await oldCliReadinessGuidance(runner, platform);
+            if (guidance)
+                throw new Error(guidance);
+        }
         throw new Error("Minutes agent readiness could not be verified safely.");
     }
     let result;
@@ -4854,7 +5012,7 @@ export async function runIsolatedMcpProcessAudio(filePath, allowedDirs, audioExt
                 child = spawn(helper.binary, helper.args, {
                     detached: true,
                     stdio: ["pipe", "pipe", "pipe", "pipe"],
-                    env: mcpCliChildEnv(),
+                    env: nodeChildEnvironment(mcpCliChildEnv()),
                 });
             }
             catch {
@@ -5657,7 +5815,7 @@ registerTool("stop_dictation", "Stop the current dictation session.", {}, { titl
     };
 });
 // ── Tool: list_voices ────────────────────────────────────────
-registerTool("list_voices", "List enrolled voice profiles for speaker identification. Shows who has been enrolled, sample count, and model version.", {}, { title: "Voice Profiles", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async () => {
+registerTool("list_voices", "List active voice enrollments for speaker identification. Shows who has been enrolled, sample count, and model version.", {}, { title: "Voice Profiles", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async () => {
     if (!(await isCliAvailable())) {
         return { content: [{ type: "text", text: "Minutes CLI not available." }] };
     }
@@ -5665,7 +5823,7 @@ registerTool("list_voices", "List enrolled voice profiles for speaker identifica
     const profiles = parseJsonOutput(stdout);
     if (!Array.isArray(profiles) || profiles.length === 0) {
         return {
-            content: [{ type: "text", text: "No voice profiles enrolled. The user can enroll with: minutes enroll" }],
+            content: [{ type: "text", text: "No voice profiles enrolled. The user can enroll with: minutes voice enroll" }],
         };
     }
     const lines = profiles.map((p) => `${p.name} — ${p.sample_count} samples, ${p.source} (${p.model_version})`);
@@ -6714,15 +6872,16 @@ registerTool("start_live_transcript", "Start real-time transcription. If a recor
     };
 });
 // ── Tool: read_live_transcript ──────────────────────────────
-registerTool("read_live_transcript", "Read the live transcript — works during both recordings and live transcript sessions. Use 'since' to get new lines after a cursor (line number) or time window (e.g., '5m', '30s'). Use 'status' mode to check if a session is active.", {
+registerTool("read_live_transcript", "Read the live transcript — works during both recordings and live transcript sessions. Use 'since' to get new finalized lines after a cursor (line number) or time window (e.g., '5m', '30s'). Set include_current for one fresh, clearly provisional current-speech draft. Use 'status' mode to check if a session is active.", {
     since: z.string().optional().describe("Line number (e.g., '42') or duration (e.g., '5m', '30s'). Omit to get all lines."),
     status_only: z.boolean().optional().default(false).describe("If true, return session status instead of transcript lines"),
+    include_current: z.boolean().optional().default(false).describe("If true, return finalized lines plus at most one fresh provisional current-speech draft and its replacement identity"),
     relay_cursor: z.object({
         session_id: z.string().optional(),
         transcript_seq: z.number().int().nonnegative(),
         nudge_seq: z.number().int().nonnegative(),
     }).optional().describe("Transient relay cursor returned by a previous read. Reconnects without replaying already-seen transcript or nudge frames."),
-}, { title: "Read Live Transcript", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ since, status_only, relay_cursor }) => {
+}, { title: "Read Live Transcript", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ since, status_only, include_current, relay_cursor }) => {
     if (!(await isCliAvailable())) {
         return { content: [{ type: "text", text: CLI_INSTALL_MSG }] };
     }
@@ -6733,18 +6892,30 @@ registerTool("read_live_transcript", "Read the live transcript — works during
     else if (since) {
         args.push("--since", since);
     }
-    let relay;
-    try {
-        relay = await attachCaptureRelay(relay_cursor);
+    if (include_current && !status_only) {
+        args.push("--include-current");
     }
-    catch {
-        // A durable-only or inactive session is still readable. start_live_transcript
-        // reports attachment failures explicitly when another process owns capture.
+    let relay;
+    if (!include_current) {
+        try {
+            relay = await attachCaptureRelay(relay_cursor);
+        }
+        catch {
+            // A durable-only or inactive session is still readable. start_live_transcript
+            // reports attachment failures explicitly when another process owns capture.
+        }
     }
     try {
         const { stdout } = await runMinutes(args, 10000);
         // For status queries, a message is helpful. For transcript reads, empty = no new lines.
         const fallback = status_only ? "No transcript data available." : "";
+        if (include_current && !status_only) {
+            const snapshot = parseJsonOutput(stdout || fallback);
+            return {
+                content: [{ type: "text", text: JSON.stringify(snapshot, null, 2) }],
+                structuredContent: snapshot,
+            };
+        }
         if (relay) {
             const payload = {
                 durable: parseJsonOutput(stdout || fallback),

package/dist/node-child.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Environment for a helper that must run as Node through process.execPath.
+ *
+ * Electron hosts such as Claude Desktop expose their app executable as
+ * process.execPath. Spawning that executable with a JavaScript file does not
+ * start Node unless ELECTRON_RUN_AS_NODE is set for the child. Keep the switch
+ * scoped to helpers whose argv is a Node program; ordinary Minutes CLI children
+ * must continue to receive their existing policy environment unchanged.
+ */
+export declare function nodeChildEnvironment(base?: NodeJS.ProcessEnv, electronVersion?: string | undefined): NodeJS.ProcessEnv;

package/dist/node-child.js

@@ -0,0 +1,16 @@
+/**
+ * Environment for a helper that must run as Node through process.execPath.
+ *
+ * Electron hosts such as Claude Desktop expose their app executable as
+ * process.execPath. Spawning that executable with a JavaScript file does not
+ * start Node unless ELECTRON_RUN_AS_NODE is set for the child. Keep the switch
+ * scoped to helpers whose argv is a Node program; ordinary Minutes CLI children
+ * must continue to receive their existing policy environment unchanged.
+ */
+export function nodeChildEnvironment(base = process.env, electronVersion = process.versions.electron) {
+    const environment = { ...base };
+    if (electronVersion) {
+        environment.ELECTRON_RUN_AS_NODE = "1";
+    }
+    return environment;
+}

package/dist/secure-read.js

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import { lstatSync, realpathSync, statSync, } from "node:fs";
 import { basename, dirname } from "path";
 import { TextDecoder } from "node:util";
+import { nodeChildEnvironment } from "./node-child.js";
 /**
  * Decode security-policy-bearing text without Unicode replacement.
  *
@@ -353,7 +354,7 @@ class BoundParentReader {
         });
         this.child = spawn(process.execPath, ["-e", BOUND_READER_SOURCE], {
             cwd: parent,
-            env: { ...process.env, MINUTES_BOUND_PARENT: parent },
+            env: nodeChildEnvironment({ ...process.env, MINUTES_BOUND_PARENT: parent }),
             stdio: ["pipe", "pipe", "pipe"],
             windowsHide: true,
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minutes-mcp",
-  "version": "0.25.2",
+  "version": "0.25.4",
   "description": "MCP server for minutes \u2014 conversation memory for AI assistants. Works with Claude Desktop, Mistral Vibe, Cursor, Windsurf, and any MCP client.",
   "main": "dist/index.js",
   "type": "module",
@@ -45,12 +45,12 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.6.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "minutes-sdk": "0.25.2",
+    "minutes-sdk": "0.25.4",
     "yaml": "^2.8.3",
     "zod": "^3.25 || ^4.0"
   },
   "devDependencies": {
-    "@types/node": "^22.19.17",
+    "@types/node": "^26.2.0",
     "tsx": "^4.0.0",
     "typescript": "^5.5.0",
     "vite": "^7.3.2",