minutes-mcp 0.7.3 → 0.8.1

package/dist/index.d.ts

@@ -18,6 +18,8 @@
  *   - research_topic: Cross-meeting topic research
  *   - qmd_collection_status: Check QMD collection registration
  *   - register_qmd_collection: Register Minutes output as QMD collection
+ *   - list_voices: List enrolled voice profiles for speaker identification
+ *   - confirm_speaker: Confirm/correct speaker attribution in a meeting
  *
  * All tools use execFile (not exec) to shell out to the `minutes` CLI binary.
  * No shell interpolation — safe from injection.

package/dist/index.js

@@ -18,22 +18,25 @@
  *   - research_topic: Cross-meeting topic research
  *   - qmd_collection_status: Check QMD collection registration
  *   - register_qmd_collection: Register Minutes output as QMD collection
+ *   - list_voices: List enrolled voice profiles for speaker identification
+ *   - confirm_speaker: Confirm/correct speaker attribution in a meeting
  *
  * All tools use execFile (not exec) to shell out to the `minutes` CLI binary.
  * No shell interpolation — safe from injection.
  */
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, EXTENSION_ID, } from "@modelcontextprotocol/ext-apps/server";
 import { z } from "zod";
 import { execFile, spawn } from "child_process";
 import { promisify } from "util";
-import { existsSync, realpathSync } from "fs";
+import { existsSync } from "fs";
 import { readFile } from "fs/promises";
-import { dirname, extname, join, resolve } from "path";
+import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
 import * as reader from "minutes-sdk";
+import { canonicalizeRoot, expandHomeLikePath, validatePathInDirectories, validatePathInDirectory, } from "./paths.js";
 const UI_RESOURCE_URI = "ui://minutes/dashboard";
 const execFileAsync = promisify(execFile);
 // ── QMD semantic search (optional — falls back to CLI) ──────
@@ -141,7 +144,152 @@ function findMinutesBinary() {
     // Fall back to PATH lookup
     return "minutes";
 }
-const MINUTES_BIN = findMinutesBinary();
+let MINUTES_BIN = findMinutesBinary();
+// ── Expected CLI version (must match this MCP server release) ──
+const EXPECTED_CLI_VERSION = "0.8.1";
+const RELEASE_TAG = "v0.8.1-live-coach";
+// ── CLI auto-install ────────────────────────────────────────
+// When installed via MCPB or `npx minutes-mcp`, the Rust CLI binary
+// may not be present. We attempt to install it automatically so
+// non-technical users don't hit a "binary not found" dead end.
+let installAttempted = false;
+function getReleaseBinaryName() {
+    const platform = process.platform;
+    const arch = process.arch;
+    if (platform === "darwin" && arch === "arm64")
+        return "minutes-macos-arm64";
+    if (platform === "darwin" && arch === "x64")
+        return "minutes-macos-arm64"; // Rosetta handles it
+    if (platform === "linux" && arch === "x64")
+        return "minutes-linux-x64";
+    if (platform === "win32" && arch === "x64")
+        return "minutes-windows-x64.exe";
+    return null;
+}
+function getInstallDir() {
+    const localBin = join(homedir(), ".local", "bin");
+    if (process.platform === "win32") {
+        return join(homedir(), ".cargo", "bin"); // common writable dir on Windows
+    }
+    return localBin;
+}
+async function tryAutoInstall() {
+    if (installAttempted)
+        return false;
+    installAttempted = true;
+    console.error("[Minutes] CLI not found — attempting automatic install...");
+    // Strategy 1: Download pre-built binary from GitHub release (fastest, no deps)
+    const binaryName = getReleaseBinaryName();
+    if (binaryName) {
+        try {
+            const url = `https://github.com/silverstein/minutes/releases/download/${RELEASE_TAG}/${binaryName}`;
+            const installDir = getInstallDir();
+            const isWindows = process.platform === "win32";
+            const targetName = isWindows ? "minutes.exe" : "minutes";
+            const targetPath = join(installDir, targetName);
+            console.error(`[Minutes] Downloading ${binaryName} from ${RELEASE_TAG} release...`);
+            // Ensure install directory exists
+            await execFileAsync("mkdir", ["-p", installDir], { timeout: 5000 }).catch(() => { });
+            // Download with curl (available on macOS, Linux, and modern Windows)
+            await execFileAsync("curl", ["-fSL", "-o", targetPath, url], { timeout: 120000 });
+            // Make executable (not needed on Windows)
+            if (!isWindows) {
+                await execFileAsync("chmod", ["+x", targetPath], { timeout: 5000 });
+            }
+            console.error(`[Minutes] ✓ Installed to ${targetPath}`);
+            MINUTES_BIN = targetPath;
+            return true;
+        }
+        catch (e) {
+            console.error(`[Minutes] Binary download failed: ${e.message || e}`);
+        }
+    }
+    // Strategy 2: Homebrew (macOS only)
+    if (process.platform === "darwin") {
+        try {
+            console.error("[Minutes] Trying: brew tap silverstein/tap && brew install minutes");
+            await execFileAsync("brew", ["tap", "silverstein/tap"], { timeout: 120000 });
+            await execFileAsync("brew", ["install", "minutes"], { timeout: 300000 });
+            console.error("[Minutes] ✓ Installed via Homebrew");
+            MINUTES_BIN = findMinutesBinary();
+            return true;
+        }
+        catch (e) {
+            console.error(`[Minutes] Homebrew install failed: ${e.message || e}`);
+        }
+    }
+    // Strategy 3: Cargo (if Rust is installed)
+    try {
+        console.error("[Minutes] Trying: cargo install minutes-cli");
+        await execFileAsync("cargo", ["install", "minutes-cli"], { timeout: 600000 });
+        console.error("[Minutes] ✓ Installed via cargo");
+        MINUTES_BIN = findMinutesBinary();
+        return true;
+    }
+    catch (e) {
+        console.error(`[Minutes] cargo install failed: ${e.message || e}`);
+    }
+    console.error("[Minutes] Auto-install failed. Install manually:\n" +
+        "  macOS:   brew tap silverstein/tap && brew install minutes\n" +
+        "  Any:     cargo install minutes-cli\n" +
+        "  Source:  https://github.com/silverstein/minutes");
+    return false;
+}
+// ── CLI version check ───────────────────────────────────────
+async function checkCliVersion() {
+    try {
+        const { stdout } = await execFileAsync(MINUTES_BIN, ["--version"], { timeout: 5000 });
+        // Output is like "minutes 0.8.0" or just "0.8.0"
+        const match = stdout.trim().match(/(\d+\.\d+\.\d+)/);
+        if (match) {
+            const installedVersion = match[1];
+            if (installedVersion !== EXPECTED_CLI_VERSION) {
+                console.error(`[Minutes] ⚠ CLI version mismatch: installed ${installedVersion}, server expects ${EXPECTED_CLI_VERSION}. ` +
+                    `Update with: brew upgrade minutes (or cargo install minutes-cli)`);
+            }
+            else {
+                console.error(`[Minutes] CLI v${installedVersion} — up to date`);
+            }
+        }
+    }
+    catch {
+        // 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.
+let modelCheckDone = false;
+async function ensureWhisperModel() {
+    if (modelCheckDone)
+        return;
+    modelCheckDone = true;
+    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 });
+        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");
+            return;
+        }
+    }
+    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 });
+        console.error("[Minutes] ✓ Whisper tiny model downloaded — recording is ready");
+    }
+    catch (e) {
+        console.error(`[Minutes] Model download failed: ${e.message || e}. ` +
+            `Run manually: minutes setup --model tiny`);
+    }
+}
 // ── CLI availability detection ──────────────────────────────
 // When installed via `npx minutes-mcp`, the Rust CLI may not be present.
 // In that case, read-only tools use the pure-TS reader module.
@@ -160,11 +308,32 @@ async function isCliAvailable() {
         cliAvailable = true;
         cliCheckedAt = Date.now();
         console.error("[Minutes] CLI found — full mode (all tools enabled)");
+        // Check version and ensure whisper model in background (non-blocking)
+        checkCliVersion();
+        ensureWhisperModel();
     }
     catch {
+        // CLI not found — try to install it automatically
+        if (!installAttempted) {
+            const installed = await tryAutoInstall();
+            if (installed) {
+                try {
+                    await execFileAsync(MINUTES_BIN, ["--version"], { timeout: 5000 });
+                    cliAvailable = true;
+                    cliCheckedAt = Date.now();
+                    console.error("[Minutes] CLI now available after auto-install — full mode");
+                    checkCliVersion();
+                    ensureWhisperModel();
+                    return true;
+                }
+                catch {
+                    // Install succeeded but binary still not found — path issue
+                }
+            }
+        }
         cliAvailable = false;
         cliCheckedAt = Date.now();
-        console.error("[Minutes] CLI not found — read-only mode. Install for recording: brew install minutes");
+        console.error("[Minutes] CLI not available — read-only mode (search and browse only)");
     }
     return cliAvailable;
 }
@@ -198,52 +367,43 @@ function parseJsonOutput(stdout) {
         return { raw: stdout };
     }
 }
-function canonicalizeFilePath(path) {
-    if (!existsSync(path)) {
-        throw new Error(`Path does not exist: ${path}`);
-    }
-    return realpathSync(path);
-}
-function canonicalizeRoot(root) {
-    // Roots may not exist yet (e.g. ~/.minutes/inbox on first run).
-    // Use realpath if it exists, otherwise lexical resolve.
-    return existsSync(root) ? realpathSync(root) : resolve(root);
-}
-function isWithinDirectory(candidate, root) {
-    // Ensure root ends with separator to prevent prefix attacks (e.g. ~/meetings-evil)
-    const rootWithSep = root.endsWith("/") ? root : root + "/";
-    return candidate === root || candidate.startsWith(rootWithSep);
-}
-function validatePathInDirectory(path, root, allowedExts) {
-    const canonicalPath = canonicalizeFilePath(path);
-    const canonicalRoot = canonicalizeRoot(root);
-    if (!allowedExts.includes(extname(canonicalPath).toLowerCase())) {
-        throw new Error(`Access denied: path must be within ${canonicalRoot} and end with ${allowedExts.join(", ")}`);
-    }
-    if (!isWithinDirectory(canonicalPath, canonicalRoot)) {
-        throw new Error(`Access denied: path must be within ${canonicalRoot}`);
-    }
-    return canonicalPath;
-}
-function validatePathInDirectories(path, roots, allowedExts) {
-    const canonicalPath = canonicalizeFilePath(path);
-    if (!allowedExts.includes(extname(canonicalPath).toLowerCase())) {
-        throw new Error(`Access denied: path must end with one of ${allowedExts.join(", ")}`);
-    }
-    const canonicalRoots = roots.map((root) => canonicalizeRoot(root));
-    if (!canonicalRoots.some((root) => isWithinDirectory(canonicalPath, root))) {
-        throw new Error(`Access denied: file must be inside one of ${canonicalRoots.join(", ")}`);
-    }
-    return canonicalPath;
-}
 // ── MCP Server ──────────────────────────────────────────────
 const server = new McpServer({
     name: "minutes",
-    version: "0.7.3",
+    version: "0.8.1",
+});
+// Declare MCP Apps extension support so hosts classify this server as interactive.
+// The `extensions` field is part of the draft MCP spec (SEP-1724) — not yet in the
+// stable SDK types, so we cast through `any`.
+server.server.registerCapabilities({
+    extensions: { [EXTENSION_ID]: {} },
 });
 // Configurable directories — override via env vars in Claude Desktop extension settings
-const MEETINGS_DIR = process.env.MEETINGS_DIR || join(homedir(), "meetings");
-const MINUTES_HOME = process.env.MINUTES_HOME || join(homedir(), ".minutes");
+const MEETINGS_DIR = canonicalizeRoot(expandHomeLikePath(process.env.MEETINGS_DIR || join(homedir(), "meetings")));
+const MINUTES_HOME = canonicalizeRoot(expandHomeLikePath(process.env.MINUTES_HOME || join(homedir(), ".minutes")));
+let effectiveMeetingsDirPromise = null;
+async function getEffectiveMeetingsDir() {
+    if (effectiveMeetingsDirPromise) {
+        return effectiveMeetingsDirPromise;
+    }
+    effectiveMeetingsDirPromise = (async () => {
+        if (!(await isCliAvailable())) {
+            return MEETINGS_DIR;
+        }
+        try {
+            const { stdout } = await runMinutes(["paths", "--json"]);
+            const parsed = parseJsonOutput(stdout);
+            if (parsed && typeof parsed.output_dir === "string" && parsed.output_dir.length > 0) {
+                return canonicalizeRoot(parsed.output_dir);
+            }
+        }
+        catch {
+            // Fall back to the MCP-configured default when the CLI cannot report paths.
+        }
+        return MEETINGS_DIR;
+    })();
+    return effectiveMeetingsDirPromise;
+}
 // ── UI Resource: MCP App dashboard ──────────────────────────
 registerAppResource(server, "Minutes Dashboard", UI_RESOURCE_URI, { description: "Interactive meeting dashboard and detail viewer" }, async () => {
     const htmlPath = join(__dirname, "..", "dist-ui", "index.html");
@@ -754,7 +914,7 @@ registerAppTool(server, "get_meeting", {
     _meta: { ui: { resourceUri: UI_RESOURCE_URI } },
 }, async ({ path: filePath }) => {
     try {
-        const resolved = validatePathInDirectory(filePath, MEETINGS_DIR, [".md"]);
+        const resolved = validatePathInDirectory(filePath, await getEffectiveMeetingsDir(), [".md"]);
         const content = await readFile(resolved, "utf-8");
         return {
             content: [{ type: "text", text: content }],
@@ -779,7 +939,7 @@ server.tool("process_audio", "Process an audio file through the transcription pi
     }
     const allowedDirs = [
         join(MINUTES_HOME, "inbox"),
-        MEETINGS_DIR,
+        await getEffectiveMeetingsDir(),
         join(homedir(), "Downloads"),
     ];
     const audioExts = [".wav", ".m4a", ".mp3", ".ogg", ".webm"];
@@ -821,7 +981,7 @@ server.tool("add_note", "Add a note to the current recording. Notes are timestam
     try {
         const args = ["note", text];
         if (meeting_path) {
-            const resolved = validatePathInDirectory(meeting_path, MEETINGS_DIR, [".md"]);
+            const resolved = validatePathInDirectory(meeting_path, await getEffectiveMeetingsDir(), [".md"]);
             args.push("--meeting", resolved);
         }
         const { stdout, stderr } = await runMinutes(args);
@@ -933,28 +1093,16 @@ registerAppTool(server, "track_commitments", {
     annotations: { title: "Track Commitments", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: UI_RESOURCE_URI } },
 }, async ({ person }) => {
-    // Use CLI: minutes people --json (rebuild if needed, read from SQLite)
-    const args = ["people", "--json"];
     if (!(await isCliAvailable())) {
         return { content: [{ type: "text", text: "Minutes CLI not available. Install with: cargo install minutes-cli" }] };
     }
-    // Get full people data and extract commitments
+    // Use dedicated commitments command for full text detail
+    const args = ["commitments", "--json"];
+    if (person)
+        args.push("--person", person);
     const { stdout } = await runMinutes(args);
-    const people = parseJsonOutput(stdout);
-    if (!Array.isArray(people)) {
-        return { content: [{ type: "text", text: "No relationship data found. Run: minutes people --rebuild" }] };
-    }
-    // Filter to the requested person if specified
-    let relevantPeople = people;
-    if (person) {
-        const personLower = person.toLowerCase();
-        relevantPeople = people.filter((p) => p.name?.toLowerCase().includes(personLower) ||
-            p.slug?.toLowerCase().includes(personLower));
-    }
-    // Build commitment summary from open_commitments counts
-    const sections = [];
-    const withCommitments = relevantPeople.filter((p) => p.open_commitments > 0);
-    if (withCommitments.length === 0) {
+    const commitments = parseJsonOutput(stdout);
+    if (!Array.isArray(commitments) || commitments.length === 0) {
         const scope = person ? ` for ${person}` : "";
         return {
             content: [{ type: "text", text: `No open commitments found${scope}.` }],
@@ -962,13 +1110,30 @@ registerAppTool(server, "track_commitments", {
             _meta: { ui: { resourceUri: UI_RESOURCE_URI }, view: "commitments" },
         };
     }
-    for (const p of withCommitments) {
-        sections.push(`${p.name}: ${p.open_commitments} open commitment${p.open_commitments !== 1 ? "s" : ""} (last seen: ${p.last_seen?.split("T")[0] || "unknown"})`);
+    // Group by status
+    const stale = commitments.filter((c) => c.status === "stale");
+    const open = commitments.filter((c) => c.status === "open");
+    const lines = [];
+    if (stale.length > 0) {
+        lines.push(`STALE (${stale.length} overdue):`);
+        for (const c of stale) {
+            const who = c.person_name || "unassigned";
+            lines.push(`  ⚠ ${c.text} (${who}; due: ${c.due_date || "no date"}; from: ${c.meeting_title})`);
+        }
     }
-    const text = `Open commitments${person ? ` for ${person}` : ""}:\n\n${sections.join("\n")}`;
+    if (open.length > 0) {
+        if (stale.length > 0)
+            lines.push("");
+        lines.push(`OPEN (${open.length}):`);
+        for (const c of open) {
+            const who = c.person_name || "unassigned";
+            lines.push(`  · ${c.text} (${who}; from: ${c.meeting_title})`);
+        }
+    }
+    const text = `Commitments${person ? ` for ${person}` : ""}:\n\n${lines.join("\n")}`;
     return {
         content: [{ type: "text", text }],
-        structuredContent: { people: withCommitments, person: person || null, view: "commitments" },
+        structuredContent: { commitments, person: person || null, stale_count: stale.length, open_count: open.length, view: "commitments" },
         _meta: { ui: { resourceUri: UI_RESOURCE_URI }, view: "commitments" },
     };
 });
@@ -1070,7 +1235,7 @@ server.resource("meeting", new ResourceTemplate("minutes://meetings/{slug}", { l
     const { stdout } = await runMinutes(["resolve", slug]);
     const parsed = parseJsonOutput(stdout);
     if (parsed.path) {
-        const validated = validatePathInDirectory(parsed.path, MEETINGS_DIR, [".md"]);
+        const validated = validatePathInDirectory(parsed.path, await getEffectiveMeetingsDir(), [".md"]);
         const content = await readFile(validated, "utf-8");
         return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: content }] };
     }
@@ -1078,7 +1243,7 @@ server.resource("meeting", new ResourceTemplate("minutes://meetings/{slug}", { l
 });
 // ── Resource: recent_ideas (voice memos from last N days) ──
 server.resource("recent-ideas", "minutes://ideas/recent", { description: "Recent voice memos and ideas captured from any device (last 14 days)" }, async (uri) => {
-    const meetings = await reader.listMeetings(MEETINGS_DIR, 200);
+    const meetings = await reader.listMeetings(await getEffectiveMeetingsDir(), 200);
     const cutoff = new Date();
     cutoff.setDate(cutoff.getDate() - 14);
     const memos = meetings.filter((m) => {
@@ -1177,6 +1342,132 @@ server.tool("stop_dictation", "Stop the current dictation session.", {}, { title
         ],
     };
 });
+// ── Tool: list_voices ────────────────────────────────────────
+server.tool("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 () => {
+    if (!(await isCliAvailable())) {
+        return { content: [{ type: "text", text: "Minutes CLI not available." }] };
+    }
+    const { stdout, stderr } = await runMinutes(["voices", "--json"]);
+    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" }],
+        };
+    }
+    const lines = profiles.map((p) => `${p.name} — ${p.sample_count} samples, ${p.source} (${p.model_version})`);
+    return {
+        content: [{ type: "text", text: `Voice profiles (${profiles.length}):\n\n${lines.join("\n")}` }],
+        structuredContent: { profiles, view: "voices" },
+    };
+});
+// ── Tool: confirm_speaker ────────────────────────────────────
+server.tool("confirm_speaker", "Confirm or correct a speaker attribution in a meeting. Promotes the attribution to High confidence and rewrites the transcript label. Optionally saves the speaker's voice profile for future meetings.", {
+    meeting: z.string().describe("Path to the meeting markdown file"),
+    speaker_label: z.string().describe("Speaker label to confirm (e.g., SPEAKER_1)"),
+    name: z.string().describe("Real name to assign to this speaker"),
+    save_voice: z.boolean().optional().default(false).describe("Save this speaker's voice profile for future automatic identification"),
+}, { title: "Confirm Speaker", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ meeting, speaker_label, name, save_voice }) => {
+    if (!(await isCliAvailable())) {
+        return { content: [{ type: "text", text: "Minutes CLI not available." }] };
+    }
+    const args = ["confirm", "--meeting", meeting, "--speaker", speaker_label, "--name", name];
+    if (save_voice)
+        args.push("--save-voice");
+    try {
+        const { stdout, stderr } = await runMinutes(args);
+        const output = (stderr || stdout || "").trim();
+        return {
+            content: [{ type: "text", text: output || `Confirmed: ${speaker_label} = ${name}` }],
+            structuredContent: { meeting, speaker_label, name, save_voice, confirmed: true },
+        };
+    }
+    catch (error) {
+        const msg = error?.stderr || error?.message || String(error);
+        return {
+            content: [{ type: "text", text: `Failed to confirm speaker: ${msg}` }],
+            isError: true,
+        };
+    }
+});
+// ── Tool: start_live_transcript ──────────────────────────────
+server.tool("start_live_transcript", "Start a live transcript session. Records audio and transcribes in real-time, writing utterances to a JSONL file. Use read_live_transcript to read the transcript during the session. Runs until stop is called.", {}, { title: "Start Live Transcript", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async () => {
+    if (!(await isCliAvailable())) {
+        return { content: [{ type: "text", text: CLI_INSTALL_MSG }] };
+    }
+    // Pre-flight checks with short timeouts (these are instant file reads)
+    const { stdout: statusOut } = await runMinutes(["status"], 5000);
+    const status = parseJsonOutput(statusOut);
+    if (status.recording) {
+        return {
+            content: [{ type: "text", text: "Recording in progress — stop recording before starting live transcript." }],
+        };
+    }
+    // Check if a live transcript is already running
+    try {
+        const { stdout: ltStatus } = await runMinutes(["transcript", "--status", "--format", "json"], 5000);
+        const ltParsed = parseJsonOutput(ltStatus);
+        if (ltParsed?.active) {
+            return {
+                content: [{ type: "text", text: "Live transcript already running. Use read_live_transcript to read it, or minutes stop to end it." }],
+            };
+        }
+    }
+    catch { /* no active session, proceed */ }
+    // Spawn detached live transcript process
+    const child = spawn(MINUTES_BIN, ["live"], {
+        detached: true,
+        stdio: "ignore",
+        env: { ...process.env, RUST_LOG: "info" },
+    });
+    child.unref();
+    // Verify the session actually started
+    await new Promise((r) => setTimeout(r, 1000));
+    try {
+        const { stdout: verifyOut } = await runMinutes(["transcript", "--status", "--format", "json"], 5000);
+        const verifyStatus = parseJsonOutput(verifyOut);
+        if (verifyStatus?.active) {
+            return {
+                content: [{ type: "text", text: "Live transcript started. Use read_live_transcript to read the transcript. Use minutes stop to end the session." }],
+            };
+        }
+    }
+    catch { /* fall through to error */ }
+    return {
+        content: [{ type: "text", text: "Live transcript may have failed to start. Check minutes health or try again. Common causes: no microphone, whisper model not downloaded, or another session already active." }],
+        isError: true,
+    };
+});
+// ── Tool: read_live_transcript ──────────────────────────────
+server.tool("read_live_transcript", "Read the live transcript. Returns utterances as JSON lines. Use 'since' to get only new lines since a cursor (line number) or time window (e.g., '5m', '30s'). 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"),
+}, { title: "Read Live Transcript", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ since, status_only }) => {
+    if (!(await isCliAvailable())) {
+        return { content: [{ type: "text", text: CLI_INSTALL_MSG }] };
+    }
+    const args = ["transcript", "--format", "json"];
+    if (status_only) {
+        args.push("--status");
+    }
+    else if (since) {
+        args.push("--since", since);
+    }
+    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." : "";
+        return {
+            content: [{ type: "text", text: stdout || fallback }],
+        };
+    }
+    catch (error) {
+        const msg = error?.stderr || error?.message || String(error);
+        return {
+            content: [{ type: "text", text: `Failed to read transcript: ${msg}` }],
+            isError: true,
+        };
+    }
+});
 // ── Start server ────────────────────────────────────────────
 async function main() {
     const transport = new StdioServerTransport();

package/dist/paths.d.ts

@@ -0,0 +1,6 @@
+export declare function expandHomeLikePath(input: string): string;
+export declare function canonicalizeFilePath(path: string): string;
+export declare function canonicalizeRoot(root: string): string;
+export declare function isWithinDirectory(candidate: string, root: string): boolean;
+export declare function validatePathInDirectory(path: string, root: string, allowedExts: string[]): string;
+export declare function validatePathInDirectories(path: string, roots: string[], allowedExts: string[]): string;

package/dist/paths.js

@@ -0,0 +1,58 @@
+import { existsSync, realpathSync } from "fs";
+import { homedir } from "os";
+import { extname, join, resolve } from "path";
+export function expandHomeLikePath(input) {
+    const home = homedir();
+    if (input === "~") {
+        return home;
+    }
+    if (input.startsWith("~/") || input.startsWith("~\\")) {
+        return join(home, input.slice(2));
+    }
+    if (input === "$HOME" || input.startsWith("$HOME/") || input.startsWith("$HOME\\")) {
+        return home + input.slice("$HOME".length);
+    }
+    if (input === "${HOME}" || input.startsWith("${HOME}/") || input.startsWith("${HOME}\\")) {
+        return home + input.slice("${HOME}".length);
+    }
+    return input;
+}
+export function canonicalizeFilePath(path) {
+    if (!existsSync(path)) {
+        throw new Error(`Path does not exist: ${path}`);
+    }
+    return realpathSync(path);
+}
+export function canonicalizeRoot(root) {
+    const expandedRoot = expandHomeLikePath(root);
+    // Roots may not exist yet (e.g. ~/.minutes/inbox on first run).
+    // Use realpath if it exists, otherwise lexical resolve.
+    return existsSync(expandedRoot) ? realpathSync(expandedRoot) : resolve(expandedRoot);
+}
+export function isWithinDirectory(candidate, root) {
+    // Ensure root ends with separator to prevent prefix attacks (e.g. ~/meetings-evil)
+    const rootWithSep = root.endsWith("/") ? root : root + "/";
+    return candidate === root || candidate.startsWith(rootWithSep);
+}
+export function validatePathInDirectory(path, root, allowedExts) {
+    const canonicalPath = canonicalizeFilePath(path);
+    const canonicalRoot = canonicalizeRoot(root);
+    if (!allowedExts.includes(extname(canonicalPath).toLowerCase())) {
+        throw new Error(`Access denied: path must be within ${canonicalRoot} and end with ${allowedExts.join(", ")}`);
+    }
+    if (!isWithinDirectory(canonicalPath, canonicalRoot)) {
+        throw new Error(`Access denied: path must be within ${canonicalRoot}`);
+    }
+    return canonicalPath;
+}
+export function validatePathInDirectories(path, roots, allowedExts) {
+    const canonicalPath = canonicalizeFilePath(path);
+    if (!allowedExts.includes(extname(canonicalPath).toLowerCase())) {
+        throw new Error(`Access denied: path must end with one of ${allowedExts.join(", ")}`);
+    }
+    const canonicalRoots = roots.map((root) => canonicalizeRoot(root));
+    if (!canonicalRoots.some((root) => isWithinDirectory(canonicalPath, root))) {
+        throw new Error(`Access denied: file must be inside one of ${canonicalRoots.join(", ")}`);
+    }
+    return canonicalPath;
+}