pi-vault-mind 0.16.36 → 0.16.37

package/README.md

@@ -18,7 +18,7 @@ Passive Obsidian vault extension for the [pi](https://github.com/mariozechner/pi
 - **JSONL Source-of-Truth + LanceDB Index** — every fact lives in a durable, human-readable, version-control-friendly `collections/*.jsonl` file. The LanceDB index is derived and rebuildable via `/vm reindex --all --reembed`.
 - **Bidirectional Obsidian Sync** — substantial entries (`>200 chars` or tagged `decision`/`insight`/`requirement`) auto-write to `Vault/Agent/Inbox/`. Graph entities render as Obsidian Canvas files.
 - **Vault-Scoped Configuration Surface** — Vault Mind setup/config now lives under `<vault>/.vault-mind/`, with the Obsidian setup wizard and `/vm setup` both writing the vault-local surface instead of a shared global config.
-- **Interactive Setup Wizard** — the Obsidian setup wizard handles first-run runtime/install/provider/folder/preferences/review flow, and `/vm setup` remains available for CLI/repair use.
+- **Audio Transcription Lane** — `vm_transcribe` handles audio/video separately from `vm_ingest`, preferring a vault-configured Modal HTTP endpoint for high-quality jobs when `vaultMind.transcription.remoteUrl` is set, while keeping a safe local `faster-whisper` fallback and `/vm transcribe status|config|use|local` ops surface for switching lanes and managing the local server.
 
 ## Architecture
 
@@ -177,13 +177,7 @@ The Broadcaster agent can generate podcasts, study guides, and slide decks from
   - `ollama` — requires Ollama running locally with `embeddinggemma` (higher quality)
   - `modal` — optional, **bring-your-own deploy**: offload embedding + bulk re-index to a cloud GPU service and sync vectors down for offline search (see [docs/integrations/MODAL_EMBEDDING.md](docs/integrations/MODAL_EMBEDDING.md)). Default behavior is unchanged until you opt in.
 
-> **On the Modal provider:** the local providers above work for everyone with
-> zero infrastructure — that's the default. `modal` is an **optional, self-hosted
-> tier**: you deploy your own copy of the service (`uvx modal deploy modal/app.py`
-> from a clone of this repo) to your own Modal account and point the extension at
-> *your* URL + token. There is no shared/hosted endpoint — a deployment's URL and
-> bearer token are private to whoever owns it. (A standalone PyPI package for the
-> server may come later.)
+> **On the Modal transcription path:** this is **bring-your-own deploy**. You deploy your own Modal HTTP endpoint from the `audio-transcription` repo, store its URL under `vaultMind.transcription.remoteUrl`, and Vault Mind can prefer that remote high-quality path by default. If no remote transcription URL is configured, `vm_transcribe` falls back to the local `faster-whisper` lane.
 
 ### 1. Install and set up the vault-local runtime
 
@@ -555,8 +549,8 @@ belongs in `vaultMind.identities` or an explicit environment override.
 | `vm_stats`      | Dashboard: counts, sizes, LanceDB status                |
 | `vm_export`     | Export to JSON, CSV, or Markdown                        |
 | `vm_ingest`     | Convert URLs and documents to markdown via docling       |
+| `vm_transcribe` | Transcribe audio/video, generate transcript notes + raw artifacts |
 | `vm_script`     | Execute sandboxed JS/TS with vm.*, vault.read, log.*    |
-
 ## Commands
 
 | Command                        | Purpose                                                  |

package/dist/runtime/headless-sync-worker.d.ts

@@ -0,0 +1,84 @@
+import { type HeadlessRebuildAfterReindexDependencies, type HeadlessRebuildDependencies } from "../src/headless-rebuild.js";
+import type { UniversalConfig } from "../src/types.js";
+type WorkerPhase = "credentials" | "auth" | "sync" | "embed" | "graph" | "config";
+export declare class HeadlessSyncWorkerError extends Error {
+    readonly phase: WorkerPhase;
+    constructor(phase: WorkerPhase);
+}
+export interface HeadlessSyncWorkerRequest {
+    operationId: string;
+    graphId: string;
+    collections: string[];
+}
+interface SecretClient {
+    secrets: {
+        resolve(reference: string): Promise<string>;
+    };
+}
+interface VectorRevision {
+    collection: string;
+    model: string;
+    dim: number;
+    watermark: number;
+    revision: string;
+}
+interface GraphRevisionRow {
+    graph_id: string;
+    revision: string;
+    source_fingerprint: string;
+    updated_at: string;
+}
+interface RevisionManifest {
+    vectors: Array<VectorRevision & {
+        updated_at: string;
+    }>;
+    graphs: GraphRevisionRow[];
+}
+export interface HeadlessSyncWorkerDependencies {
+    env: Record<string, string | undefined>;
+    workspaceRoot: string;
+    createClient(options: {
+        auth: string;
+        integrationName: string;
+        integrationVersion: string;
+    }): Promise<SecretClient>;
+    execFile(command: string, args: string[], options: {
+        cwd: string;
+        env: Record<string, string | undefined>;
+    }): Promise<unknown>;
+    runRebuild(request: {
+        graphId: string;
+        clonePath: string;
+        wait: true;
+    }, deps: Partial<HeadlessRebuildDependencies> & Pick<HeadlessRebuildAfterReindexDependencies, "reindex">): Promise<{
+        graphId: string;
+        sourceFingerprint: string;
+        jobId?: string;
+        jobStatus?: string;
+    }>;
+    reindexRemote(cfg: UniversalConfig, collections: string[], vaultPath: string, options: {
+        syncDown: false;
+    }): Promise<Array<{
+        collection: string;
+        job?: {
+            status: string;
+        };
+        error?: string;
+        model?: string;
+        dim?: number | null;
+        remote_collection?: string;
+    }>>;
+    readRevisionsManifest(baseUrl: string, token: string): Promise<{
+        vectors: VectorRevision[];
+        graphs: GraphRevisionRow[];
+    }>;
+    fetchNamespaceWatermark(baseUrl: string, token: string, collection: string, model: string, dim: number): Promise<number>;
+    publishRevisions(baseUrl: string, token: string, manifest: RevisionManifest): Promise<void>;
+    now(): string;
+}
+export declare function runHeadlessSyncWorker(request: HeadlessSyncWorkerRequest, deps: HeadlessSyncWorkerDependencies): Promise<{
+    graphId: string;
+    graphJobId?: string;
+    sourceFingerprint: string;
+}>;
+export {};

package/dist/runtime/headless-sync-worker.js

@@ -0,0 +1,319 @@
+import { execFile as nodeExecFile } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { runHeadlessRebuildAfterReindex, } from "../src/headless-rebuild.js";
+import { reindexRemote } from "../src/sync.js";
+const execFileAsync = promisify(nodeExecFile);
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export class HeadlessSyncWorkerError extends Error {
+    phase;
+    constructor(phase) {
+        super(`${phase} failed`);
+        this.name = "HeadlessSyncWorkerError";
+        this.phase = phase;
+    }
+}
+function required(env, key, phase) {
+    const value = env[key];
+    if (!value)
+        throw new HeadlessSyncWorkerError(phase);
+    return value;
+}
+function assertSafe(value, phase) {
+    if (!IDENTIFIER.test(value))
+        throw new HeadlessSyncWorkerError(phase);
+    return value;
+}
+function reference(env, key) {
+    const value = required(env, key, "config");
+    if (!value.startsWith("op://") || value.length > 512)
+        throw new HeadlessSyncWorkerError("config");
+    return value;
+}
+function optionalReference(env, key) {
+    const value = env[key];
+    if (!value)
+        return undefined;
+    return reference(env, key);
+}
+function selectConfig(raw, collections, token) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new HeadlessSyncWorkerError("config");
+    }
+    if (!parsed || typeof parsed !== "object")
+        throw new HeadlessSyncWorkerError("config");
+    const cfg = parsed;
+    const embeddingUrl = cfg.vaultMind?.embedding?.remoteUrl;
+    if (!cfg.collections ||
+        typeof cfg.collections !== "object" ||
+        !cfg.vaultMind ||
+        typeof embeddingUrl !== "string" ||
+        embeddingUrl.length === 0) {
+        throw new HeadlessSyncWorkerError("config");
+    }
+    const selected = {};
+    for (const collection of collections) {
+        const definition = cfg.collections[collection];
+        if (!definition)
+            throw new HeadlessSyncWorkerError("config");
+        selected[collection] = definition;
+    }
+    cfg.collections = selected;
+    cfg.vaultMind.embedding = {
+        ...cfg.vaultMind.embedding,
+        remoteApiKey: token,
+    };
+    return { config: cfg, embeddingUrl };
+}
+function sanitizeError(error, phase) {
+    if (error instanceof HeadlessSyncWorkerError)
+        throw error;
+    throw new HeadlessSyncWorkerError(phase);
+}
+export async function runHeadlessSyncWorker(request, deps) {
+    assertSafe(request.operationId, "config");
+    assertSafe(request.graphId, "config");
+    if (request.collections.length === 0 ||
+        new Set(request.collections).size !== request.collections.length) {
+        throw new HeadlessSyncWorkerError("config");
+    }
+    for (const collection of request.collections)
+        assertSafe(collection, "config");
+    const workspace = path.resolve(deps.workspaceRoot, request.operationId);
+    const home = path.join(workspace, ".home");
+    const env = { ...deps.env, HOME: home };
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    required(deps.env, "OP_SERVICE_ACCOUNT_TOKEN", "credentials");
+    const embeddingToken = required(deps.env, "PVM_REMOTE_EMBEDDING_API_KEY", "credentials");
+    let email;
+    let password;
+    let mfa;
+    let e2ePassword;
+    let vault;
+    try {
+        const resolve = async (ref) => {
+            const result = (await deps.execFile("op", ["read", "--no-newline", ref], {
+                cwd: workspace,
+                env,
+            }));
+            if (typeof result.stdout !== "string" || result.stdout.length === 0) {
+                throw new HeadlessSyncWorkerError("credentials");
+            }
+            return result.stdout;
+        };
+        const mfaRef = optionalReference(deps.env, "PVM_HEADLESS_OP_MFA_REF");
+        const e2eRef = optionalReference(deps.env, "PVM_HEADLESS_OP_E2E_PASSWORD_REF");
+        [email, password, mfa, e2ePassword, vault] = await Promise.all([
+            resolve(reference(deps.env, "PVM_HEADLESS_OP_EMAIL_REF")),
+            resolve(reference(deps.env, "PVM_HEADLESS_OP_PASSWORD_REF")),
+            mfaRef ? resolve(mfaRef) : Promise.resolve(undefined),
+            e2eRef ? resolve(e2eRef) : Promise.resolve(undefined),
+            resolve(reference(deps.env, "PVM_HEADLESS_OP_VAULT_REF")),
+        ]);
+        let parsedVault;
+        try {
+            parsedVault = JSON.parse(vault);
+        }
+        catch {
+            throw new HeadlessSyncWorkerError("credentials");
+        }
+        if (!parsedVault ||
+            typeof parsedVault !== "object" ||
+            !("vault_id" in parsedVault) ||
+            typeof parsedVault.vault_id !== "string" ||
+            !IDENTIFIER.test(parsedVault.vault_id)) {
+            throw new HeadlessSyncWorkerError("credentials");
+        }
+        vault = parsedVault.vault_id;
+    }
+    catch (error) {
+        return sanitizeError(error, "credentials");
+    }
+    try {
+        const loginArgs = ["login", "--email", email, "--password", password];
+        if (mfa)
+            loginArgs.push("--mfa", mfa);
+        await deps.execFile("ob", loginArgs, { cwd: workspace, env });
+        const setupArgs = [
+            "sync-setup",
+            "--vault",
+            vault,
+            "--path",
+            workspace,
+            "--password",
+            e2ePassword,
+            "--device-name",
+            `pvm-headless-${request.operationId}`,
+        ];
+        if (!e2ePassword)
+            setupArgs.splice(setupArgs.indexOf("--password"), 2);
+        await deps.execFile("ob", setupArgs, { cwd: workspace, env });
+        await deps.execFile("ob", ["sync", "--path", workspace], { cwd: workspace, env });
+    }
+    catch (error) {
+        return sanitizeError(error, "auth");
+    }
+    let cfg;
+    let embeddingUrl;
+    try {
+        const configPath = path.join(workspace, ".vault-mind", "vault-mind.config.json");
+        const rawConfig = fs.readFileSync(configPath, "utf8");
+        ({ config: cfg, embeddingUrl } = selectConfig(rawConfig, request.collections, embeddingToken));
+    }
+    catch (error) {
+        return sanitizeError(error, "config");
+    }
+    let checkpoint;
+    let reindexRevisions;
+    try {
+        checkpoint = await deps.runRebuild({ graphId: request.graphId, clonePath: workspace, wait: true }, {
+            runObSync: async (clonePath) => {
+                await deps.execFile("ob", ["sync", "--path", clonePath], { cwd: clonePath, env });
+            },
+            reindex: async (resolvedConfig, clonePath) => {
+                const selectedConfig = {
+                    ...cfg,
+                    ...resolvedConfig,
+                    collections: cfg.collections,
+                };
+                const results = await deps.reindexRemote(selectedConfig, request.collections, clonePath, {
+                    syncDown: false,
+                });
+                if (results.some((result) => result.error || result.job?.status !== "done")) {
+                    throw new HeadlessSyncWorkerError("embed");
+                }
+                reindexRevisions = results
+                    .filter((result) => result.job?.status === "done" &&
+                    !result.error &&
+                    !!result.model &&
+                    !!result.remote_collection)
+                    .map((result) => ({
+                    collection: result.remote_collection,
+                    model: result.model,
+                    dim: (result.dim ?? 0),
+                    revision: result.job.status,
+                    watermark: 0,
+                }));
+            },
+        });
+    }
+    catch (error) {
+        return sanitizeError(error, error instanceof HeadlessSyncWorkerError ? error.phase : "graph");
+    }
+    if (checkpoint.jobStatus !== "done" || !checkpoint.jobId)
+        throw new HeadlessSyncWorkerError("graph");
+    let vectors;
+    try {
+        vectors = reindexRevisions;
+        const remoteCollections = new Set(vectors.map((vector) => vector.collection));
+        if (vectors.length !== request.collections.length ||
+            vectors.some((vector) => !remoteCollections.has(vector.collection) ||
+                !(typeof vector.dim === "number" && vector.dim > 0) ||
+                !Number.isSafeInteger(vector.watermark) ||
+                vector.watermark < 0)) {
+            throw new HeadlessSyncWorkerError("embed");
+        }
+        const watermarks = await Promise.all(vectors.map(async (vector) => {
+            try {
+                return await deps.fetchNamespaceWatermark(embeddingUrl, embeddingToken, vector.collection, vector.model, vector.dim);
+            }
+            catch (error) {
+                throw new HeadlessSyncWorkerError("embed");
+            }
+        }));
+        vectors = vectors.map((vector, index) => ({
+            ...vector,
+            watermark: watermarks[index],
+        }));
+    }
+    catch (error) {
+        return sanitizeError(error, "embed");
+    }
+    try {
+        const existing = await deps.readRevisionsManifest(embeddingUrl, embeddingToken);
+        const selectedRemote = new Set(vectors.map((vector) => vector.collection));
+        const survivingVectors = existing.vectors
+            .filter((vector) => !selectedRemote.has(vector.collection))
+            .map((vector) => ({ ...vector, updated_at: deps.now() }));
+        await deps.publishRevisions(embeddingUrl, embeddingToken, {
+            vectors: [
+                ...survivingVectors,
+                ...vectors.map((vector) => ({
+                    ...vector,
+                    updated_at: deps.now(),
+                })),
+            ],
+            graphs: [
+                ...existing.graphs,
+                {
+                    graph_id: checkpoint.graphId,
+                    revision: checkpoint.jobId,
+                    source_fingerprint: checkpoint.sourceFingerprint,
+                    updated_at: deps.now(),
+                },
+            ],
+        });
+    }
+    catch (error) {
+        return sanitizeError(error, "graph");
+    }
+    return {
+        graphId: checkpoint.graphId,
+        graphJobId: checkpoint.jobId,
+        sourceFingerprint: checkpoint.sourceFingerprint,
+    };
+}
+const defaultDependencies = {
+    env: process.env,
+    workspaceRoot: process.env.PVM_HEADLESS_WORKSPACE_ROOT || "/pvm-vault/workspaces",
+    execFile: async (command, args, options) => execFileAsync(command, args, options),
+    runRebuild: runHeadlessRebuildAfterReindex,
+    reindexRemote: reindexRemote,
+    readRevisionsManifest: async (baseUrl, token) => {
+        const target = baseUrl.replace(/\/$/, "");
+        const response = await fetch(`${target}/sync/revisions`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok)
+            throw new Error("revision read failed");
+        return (await response.json());
+    },
+    fetchNamespaceWatermark: async (baseUrl, token, collection, model, dim) => {
+        const target = baseUrl.replace(/\/$/, "");
+        const params = new URLSearchParams({ collection, model, dim: String(dim) });
+        const response = await fetch(`${target}/sync/namespace-watermark?${params.toString()}`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok)
+            throw new Error("namespace watermark read failed");
+        const body = (await response.json());
+        return body.watermark;
+    },
+    publishRevisions: async (baseUrl, token, manifest) => {
+        const response = await fetch(`${baseUrl.replace(/\/$/, "")}/sync/revisions`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+            body: JSON.stringify(manifest),
+        });
+        if (!response.ok)
+            throw new Error("revision publish failed");
+    },
+    now: () => new Date().toISOString(),
+};
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const [operationId, graphId, collectionsJson] = process.argv.slice(2);
+    void (async () => {
+        const collections = JSON.parse(collectionsJson || "[]");
+        const result = await runHeadlessSyncWorker({ operationId: operationId || "", graphId: graphId || "", collections }, defaultDependencies);
+        process.stdout.write(JSON.stringify(result));
+    })().catch(() => {
+        process.exitCode = 1;
+    });
+}

package/dist/src/agent-docs.d.ts

@@ -0,0 +1,6 @@
+export declare const BASELINE_START = "<!-- vm:baseline:start -->";
+export declare const BASELINE_END = "<!-- vm:baseline:end -->";
+export declare const PERSONALIZATION_START = "<!-- vm:personalization:start -->";
+export declare const PERSONALIZATION_END = "<!-- vm:personalization:end -->";
+export declare const buildDefaultSystemMd: (vaultPath: string) => string;
+export declare const buildDefaultAgentsMd: () => string;

package/dist/src/agent-docs.js

@@ -17,8 +17,10 @@ You are the unrestricted main interactive agent for this vault. Bundled speciali
 - Prefer \`uv\` for Python tools and CLIs. Use \`pnpm\`/\`npm\` for JavaScript and TypeScript packages such as \`run\`.
 - Use \`docling\` for document conversion in ingest flows.
 - Use \`vm_script\` for reusable sandboxed JS/TS workflows when the task fits the approved host-function surface.
+- Use \`vm_transcribe\` for audio/video transcription (voice notes, podcasts, NotebookLM audio overviews). Defaults come from \`vaultMind.transcription\`: prefer the remote Modal HTTP endpoint when \`remoteUrl\` is configured, otherwise fall back to the local engine. Keep this lane separate from \`vm_ingest\`/docling.
+- Use the \`nlm\` CLI for NotebookLM source inventory lookups. Do not use MCP as the primary path for NotebookLM notebook/source queries.
 - Never auto-publish, never fabricate facts, and keep human approval at external side effects.
-- The watcher recognizes \`@agent:<role>\` and \`@agent-<role>\` anywhere in watchable files. \`@agent:main\` is reserved for the main interactive flow and is not auto-dispatched.
+- The watcher recognizes \`@agent:<role>\` and \`@agent-<role>\` anywhere in watchable files. \`@agent:main\` is reserved for human-authored review and follow-up notes; it is never auto-dispatched. Automated transcript preparation, source linking, and note population use \`@agent:audio-overviews\`.
 ${BASELINE_END}
 
 ${PERSONALIZATION_START}
@@ -36,16 +38,19 @@ ${BASELINE_START}
 - \`broadcaster\` — human-facing artifact generation.
 - \`heavy-lifter\` — large-context implementation and deeper delegated work.
 - \`personalization\` — resolves annotated feedback on generated system/agent docs.
+- \`audio-overviews\` — automated worker for NotebookLM audio overview transcription, source resolution, and note population. Uses deterministic scripts/functions rather than freeform improvisation.
 
 ## Watcher + inline requests
 - Use \`@agent:<role>\` or \`@agent-<role>\` in watchable files to request agent help.
-- \`@agent:main\` is recognized but never auto-dispatched; it is for main-agent or human-led follow-up.
+- \`@agent:main\` is recognized but never auto-dispatched; it is for human-authored review notes and follow-up only — not automated transcript generation.
 - Auto-dispatched watcher jobs preserve the request block in the source note and replace only the running-status line with the result summary.
 - Watcher dispatches should be logged to collections so they can be queried later.
 
 ## Tooling baseline
 - Prefer \`uv\` for Python tools.
 - Prefer reusable \`vm_script\` workflows over ad-hoc one-off scripts when the workflow should be repeatable.
+- Use \`vm_transcribe\` for audio/video transcription; keep this lane separate from \`vm_ingest\`/docling.
+- Use \`nlm\` for NotebookLM source inventory. Do not use MCP as the primary path for NotebookLM lookups.
 - Keep reusable content, test, and update workflows in skills/tools rather than scattered shell snippets.
 ${BASELINE_END}
 

package/dist/src/agent-queue.d.ts

@@ -75,7 +75,7 @@ export declare const markJobFailed: (vaultPath: string, id: string, error: strin
 export declare const markJobRunning: (vaultPath: string, id: string) => AgentJob | undefined;
 /** Mark a pending job as cancelled. */
 export declare const cancelJob: (vaultPath: string, id: string) => AgentJob | undefined;
-/** True if the file still contains the dispatch marker for this job. */
+/** True if the file still contains the pending dispatch status placeholder. */
 export declare const markerStillPresent: (filePath: string, dispatchId: string) => boolean;
 /** Scan a vault's queue and mark any running job whose marker is gone as done. */
 export declare const sweepCompletedJobs: (vaultPath: string) => AgentJob[];

package/dist/src/capabilities.d.ts

@@ -0,0 +1,31 @@
+export type CapabilityClass = "extensions" | "skills" | "agents";
+export interface DesiredCapability {
+    source: string;
+    provider?: string;
+    version: string;
+    enabled: boolean;
+}
+export interface DesiredState {
+    version: number;
+    extensions: Record<string, DesiredCapability>;
+    skills: Record<string, DesiredCapability>;
+    agents: Record<string, DesiredCapability>;
+}
+export interface ObservedCapability {
+    id: string;
+    class: CapabilityClass;
+    version: string;
+    enabled: boolean;
+    provider?: string;
+}
+export type DriftStatus = "Installed / Active" | "Disabled" | "Missing" | "Drifted" | "Unverifiable" | "Orphaned" | "Discoverable";
+export interface DriftReportItem {
+    id: string;
+    class: CapabilityClass;
+    desired?: DesiredCapability;
+    observed?: ObservedCapability;
+    status: DriftStatus;
+}
+export declare const readCapabilities: (vaultPath: string) => DesiredState;
+export declare const scanInventory: (vaultPath: string) => ObservedCapability[];
+export declare const computeDrift: (desired: DesiredState, observed: ObservedCapability[]) => DriftReportItem[];