@qvac/harness 0.1.0 → 0.1.2

package/dist-lib/lib/tools/exec/adapters/python/worker/entry.js

@@ -0,0 +1,105 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import process from 'process';
+import { setHarnessLog, setHarnessLogSink } from "../../../../../log.js";
+import { defaultLoad } from "../loader.js";
+import { performRun } from "../run-session.js";
+import { asHostMessage, toWireResult } from "./protocol.js";
+function narrowThreadData(data) {
+    if (typeof data === 'object' && data !== null && 'sab' in data && 'handle' in data) {
+        const sab = data.sab;
+        const log = 'log' in data && data.log === true;
+        if (sab instanceof SharedArrayBuffer)
+            return { handle: data.handle, sab, log };
+    }
+    throw new Error('python worker started without { handle, sab } thread data');
+}
+async function openBarePort() {
+    const { default: Channel } = await import('bare-channel');
+    const self = Bare.Thread.self;
+    if (!self)
+        throw new Error('python worker entry loaded on the main thread');
+    const { handle, sab, log } = narrowThreadData(self.data);
+    const port = Channel.from(handle).connect();
+    return {
+        port: {
+            read: () => port.read(),
+            write: (message) => void port.write(message),
+            close: () => void port.close()
+        },
+        handle,
+        sab,
+        log
+    };
+}
+async function openNodePort() {
+    const { parentPort, workerData } = await import('worker_threads');
+    if (!parentPort)
+        throw new Error('python worker entry loaded on the main thread');
+    const data = narrowThreadData({ handle: parentPort, ...(workerData ?? {}) });
+    const queued = [];
+    const waiting = [];
+    parentPort.on('message', (value) => {
+        const next = waiting.shift();
+        if (next)
+            next(value);
+        else
+            queued.push(value);
+    });
+    return {
+        port: {
+            read() {
+                if (queued.length > 0)
+                    return Promise.resolve(queued.shift());
+                return new Promise((resolve) => waiting.push(resolve));
+            },
+            write: (message) => parentPort.postMessage(message),
+            close: () => parentPort.close()
+        },
+        ...data
+    };
+}
+async function loadInterpreter() {
+    const testLoader = process.env.QVAC_PYODIDE_TEST_LOADER;
+    if (!testLoader)
+        return defaultLoad;
+    const loaded = await import(__rewriteRelativeImportExtension(testLoader));
+    if (typeof loaded === 'object' &&
+        loaded !== null &&
+        'default' in loaded &&
+        typeof loaded.default === 'function') {
+        return loaded.default;
+    }
+    throw new Error(`QVAC_PYODIDE_TEST_LOADER module has no default export: ${testLoader}`);
+}
+const { port, sab, log } = typeof globalThis.Bare !== 'undefined' ? await openBarePort() : await openNodePort();
+setHarnessLog(log);
+setHarnessLogSink((message) => port.write({ type: 'log', message }));
+try {
+    const load = await loadInterpreter();
+    const py = await load();
+    py.setInterruptBuffer(new Uint8Array(sab));
+    port.write({ type: 'ready' });
+    for (;;) {
+        const message = asHostMessage(await port.read());
+        if (!message || message.type === 'close')
+            break;
+        const { result, evict } = await performRun(py, message.spec);
+        port.write({ type: 'result', id: message.id, result: toWireResult(result), evict });
+        if (evict)
+            break;
+    }
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    port.write({ type: 'boot-error', message });
+}
+finally {
+    port.close();
+}

package/dist-lib/lib/tools/exec/adapters/python/worker/protocol.d.ts

@@ -0,0 +1,38 @@
+import type { PythonRunResult, RunSpec } from '../run-session.ts';
+export type HostMessage = {
+    readonly type: 'run';
+    readonly id: number;
+    readonly spec: RunSpec;
+} | {
+    readonly type: 'close';
+};
+export type WireResult = {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+    readonly files?: ReadonlyArray<readonly [string, Uint8Array]>;
+    readonly missing?: readonly string[];
+    readonly rejected?: readonly {
+        readonly name: string;
+        readonly reason: string;
+    }[];
+    readonly undeclared?: readonly string[];
+};
+export type WorkerMessage = {
+    readonly type: 'log';
+    readonly message: string;
+} | {
+    readonly type: 'ready';
+} | {
+    readonly type: 'boot-error';
+    readonly message: string;
+} | {
+    readonly type: 'result';
+    readonly id: number;
+    readonly result: WireResult;
+    readonly evict: boolean;
+};
+export declare function toWireResult(result: PythonRunResult): WireResult;
+export declare function fromWireResult(wire: WireResult): PythonRunResult;
+export declare function asHostMessage(value: unknown): HostMessage | null;
+export declare function asWorkerMessage(value: unknown): WorkerMessage | null;

package/dist-lib/lib/tools/exec/adapters/python/worker/protocol.js

@@ -0,0 +1,41 @@
+export function toWireResult(result) {
+    return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+        files: result.files ? [...result.files.entries()] : undefined,
+        missing: result.missing,
+        rejected: result.rejected,
+        undeclared: result.undeclared
+    };
+}
+export function fromWireResult(wire) {
+    return {
+        stdout: wire.stdout,
+        stderr: wire.stderr,
+        exitCode: wire.exitCode,
+        files: wire.files ? new Map(wire.files) : undefined,
+        missing: wire.missing,
+        rejected: wire.rejected,
+        undeclared: wire.undeclared
+    };
+}
+function messageType(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const type = value.type;
+    return typeof type === 'string' ? type : null;
+}
+export function asHostMessage(value) {
+    const type = messageType(value);
+    if (type === 'run' || type === 'close')
+        return value;
+    return null;
+}
+export function asWorkerMessage(value) {
+    const type = messageType(value);
+    if (type === 'log' || type === 'ready' || type === 'boot-error' || type === 'result') {
+        return value;
+    }
+    return null;
+}

package/dist-lib/lib/tools/exec/adapters/python/worker/spawn-bare.d.ts

@@ -0,0 +1,2 @@
+import type { WorkerData, WorkerLink } from './spawn-node.ts';
+export declare function spawnPythonWorker(entry: string, data: WorkerData): WorkerLink;

package/dist-lib/lib/tools/exec/adapters/python/worker/spawn-bare.js

@@ -0,0 +1,30 @@
+import Channel from 'bare-channel';
+import safetyCatch from 'safety-catch';
+export function spawnPythonWorker(entry, data) {
+    const channel = new Channel();
+    const thread = new Bare.Thread(entry, { data: { handle: channel.handle, ...data } });
+    const port = channel.connect();
+    return {
+        read: () => port.read().then((value) => {
+            if (value === null)
+                throw new Error('python worker channel closed');
+            return value;
+        }),
+        write: (message) => port.write(message),
+        kill() {
+            try {
+                thread.terminate();
+            }
+            catch (error) {
+                safetyCatch(error);
+            }
+            port.close().catch(safetyCatch);
+        },
+        reap() {
+            port.close().catch(safetyCatch);
+            thread.join();
+        },
+        ref() { },
+        unref() { }
+    };
+}

package/dist-lib/lib/tools/exec/adapters/python/worker/spawn-node.d.ts

@@ -0,0 +1,13 @@
+export type WorkerLink = {
+    read(): Promise<unknown>;
+    write(message: unknown): Promise<void>;
+    kill(): void;
+    reap(): void;
+    ref(): void;
+    unref(): void;
+};
+export type WorkerData = {
+    readonly sab: SharedArrayBuffer;
+    readonly log: boolean;
+};
+export declare function spawnPythonWorker(entry: string, data: WorkerData): WorkerLink;

package/dist-lib/lib/tools/exec/adapters/python/worker/spawn-node.js

@@ -0,0 +1,45 @@
+import { Worker } from 'worker_threads';
+export function spawnPythonWorker(entry, data) {
+    const worker = new Worker(entry, {
+        workerData: data,
+        resourceLimits: { maxOldGenerationSizeMb: 512, maxYoungGenerationSizeMb: 64, stackSizeMb: 8 }
+    });
+    const queued = [];
+    const waiting = [];
+    let died = null;
+    const push = (value) => {
+        const next = waiting.shift();
+        if (next)
+            next.resolve(value);
+        else
+            queued.push(value);
+    };
+    const fail = (error) => {
+        if (died)
+            return;
+        died = error;
+        for (const pending of waiting.splice(0))
+            pending.reject(error);
+    };
+    worker.on('message', push);
+    worker.on('error', (error) => fail(error instanceof Error ? error : new Error(String(error))));
+    worker.on('exit', (code) => fail(new Error(`python worker exited with code ${code}`)));
+    worker.unref();
+    return {
+        read() {
+            if (queued.length > 0)
+                return Promise.resolve(queued.shift());
+            if (died)
+                return Promise.reject(died);
+            return new Promise((resolve, reject) => waiting.push({ resolve, reject }));
+        },
+        write(message) {
+            worker.postMessage(message);
+            return Promise.resolve();
+        },
+        kill: () => void worker.terminate(),
+        reap: () => void worker.terminate(),
+        ref: () => worker.ref(),
+        unref: () => worker.unref()
+    };
+}

package/dist-lib/lib/tools/exec/adapters/shell/shell-adapter.d.ts

@@ -0,0 +1,12 @@
+import { type KillProcess, type SpawnFn } from '../../runner.ts';
+import type { FallbackExecutionAdapter } from '../adapter.ts';
+export type ShellRuntime = {
+    readonly spawn: SpawnFn;
+    readonly killProcess?: KillProcess;
+};
+export type ShellAdapterOptions = {
+    readonly spawn?: SpawnFn;
+    readonly killProcess?: KillProcess;
+    readonly loadRuntime: () => Promise<ShellRuntime>;
+};
+export declare function createShellAdapter(options: ShellAdapterOptions): FallbackExecutionAdapter;

package/dist-lib/lib/tools/exec/adapters/shell/shell-adapter.js

@@ -0,0 +1,20 @@
+import { runCommand } from "../../runner.js";
+export function createShellAdapter(options) {
+    return {
+        resolve(args) {
+            const command = String(args.command ?? '').trim();
+            return {
+                async run(execution) {
+                    const runtime = options.spawn
+                        ? { spawn: options.spawn, killProcess: options.killProcess }
+                        : await options.loadRuntime();
+                    return runCommand(command, {
+                        ...execution,
+                        spawn: runtime.spawn,
+                        killProcess: runtime.killProcess
+                    });
+                }
+            };
+        }
+    };
+}

package/dist-lib/lib/tools/exec/obsidian/cli-process.d.ts

@@ -0,0 +1,8 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import { type ObsidianPathProbe } from '../../skills/obsidian-readiness.ts';
+import type { KillProcess, SpawnFn } from '../runner.ts';
+export declare function runningCheckCommand(os: string): string;
+export declare function launchCommand(os: string): string;
+export declare function obsidianPathEnv(platform?: NodeJS.Platform, env?: Record<string, string | undefined>, probe?: ObsidianPathProbe): Record<string, string> | undefined;
+export declare function isObsidianRunning(spawn: SpawnFn, killProcess: KillProcess | undefined, signal?: BareAbortSignal, platform?: NodeJS.Platform): Promise<boolean>;
+export declare function launchObsidianApp(spawn: SpawnFn, platform?: NodeJS.Platform): void;

package/dist-lib/lib/tools/exec/obsidian/cli-process.js

@@ -0,0 +1,74 @@
+import fs from 'fs';
+import path from 'path';
+import process from 'process';
+import { execEnv } from "../../../helpers/spawn-path.js";
+import { expandObsidianPath, firstExistingPath, OBSIDIAN_BIN_CANDIDATES } from "../../skills/obsidian-readiness.js";
+const RUNNING_CHECK_MS = 3_000;
+export function runningCheckCommand(os) {
+    if (os === 'win32') {
+        return 'tasklist /FI "IMAGENAME eq Obsidian.exe" /NH | find /I "Obsidian.exe"';
+    }
+    return 'pgrep -x Obsidian || pgrep -i obsidian';
+}
+export function launchCommand(os) {
+    if (os === 'darwin')
+        return 'open -a Obsidian';
+    if (os === 'win32')
+        return 'start "" obsidian';
+    return 'obsidian >/dev/null 2>&1 &';
+}
+export function obsidianPathEnv(platform = process.platform, env = process.env, probe = {}) {
+    const expand = probe.expand ?? ((candidate) => expandObsidianPath(candidate, env));
+    const exists = probe.exists ?? ((candidate) => fs.existsSync(candidate));
+    const bin = firstExistingPath(OBSIDIAN_BIN_CANDIDATES[platform] ?? [], expand, exists);
+    if (!bin)
+        return undefined;
+    const binDir = path.dirname(bin);
+    const scrubbed = execEnv(env, platform);
+    const prev = scrubbed.PATH ?? '';
+    return { ...scrubbed, PATH: prev ? `${binDir}${path.delimiter}${prev}` : binDir };
+}
+export function isObsidianRunning(spawn, killProcess, signal, platform = process.platform) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve(false);
+            return;
+        }
+        const child = spawn(runningCheckCommand(platform), { shell: true });
+        let settled = false;
+        const finish = (running) => {
+            if (settled)
+                return;
+            settled = true;
+            globalThis.clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            try {
+                if (child.pid !== undefined && killProcess)
+                    killProcess(-child.pid, 'SIGKILL');
+                else
+                    child.kill('SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+            resolve(running);
+        };
+        const timer = globalThis.setTimeout(() => finish(false), RUNNING_CHECK_MS);
+        const onAbort = () => finish(false);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        child.on('exit', (code) => finish(code === 0));
+        child.on('error', () => finish(false));
+    });
+}
+export function launchObsidianApp(spawn, platform = process.platform) {
+    try {
+        const env = obsidianPathEnv(platform);
+        const child = spawn(launchCommand(platform), {
+            shell: true,
+            ...(env ? { env } : {})
+        });
+        child.on('error', () => { });
+    }
+    catch {
+    }
+}

package/dist-lib/lib/tools/exec/obsidian/cli.d.ts

@@ -0,0 +1,18 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import { type ExecResult, type KillProcess, type SpawnFn } from '../runner.ts';
+export type RunObsidianCliOptions = {
+    readonly timeoutMs?: number;
+    readonly maxOutputChars?: number;
+    readonly signal?: BareAbortSignal;
+};
+export type RunOutcome = {
+    readonly result: string;
+    readonly stderr: string;
+    readonly exitCode: number | null;
+};
+export type ObsidianCliRuntime = {
+    readonly spawn: SpawnFn;
+    readonly killProcess?: KillProcess;
+};
+export declare function toResult(outcome: RunOutcome): ExecResult;
+export declare function runObsidianCli(command: string, runtime: ObsidianCliRuntime, options?: RunObsidianCliOptions): Promise<ExecResult>;

package/dist-lib/lib/tools/exec/obsidian/cli.js

@@ -0,0 +1,153 @@
+import { appendOutput, capOutput, createCapturedOutput, MAX_OUTPUT_CHARS } from "../runner.js";
+import { isObsidianRunning, launchObsidianApp, obsidianPathEnv } from "./cli-process.js";
+import { OBSIDIAN_CLI_FAILURE_GUIDANCE } from "./guidance.js";
+import { cleanObsidianOutput } from "./output.js";
+const READY_WAIT_MS = 5_000;
+const COMMAND_MS = 15_000;
+const OUTPUT_QUIET_MS = 700;
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            globalThis.clearTimeout(timer);
+            resolve();
+        };
+        const timer = globalThis.setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function failedResult(outcome, exitCode) {
+    const detail = [
+        outcome.result ? `stdout:\n${outcome.result}` : '',
+        outcome.stderr ? `stderr:\n${outcome.stderr}` : ''
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+    const body = detail ? `\n\n${detail}` : '';
+    return {
+        stdout: '',
+        stderr: `Obsidian command failed (exit code ${exitCode}).${body}\n\n${OBSIDIAN_CLI_FAILURE_GUIDANCE}`,
+        exitCode
+    };
+}
+export function toResult(outcome) {
+    if (outcome.exitCode !== null && outcome.exitCode !== 0) {
+        return failedResult(outcome, outcome.exitCode);
+    }
+    if (outcome.exitCode === null && outcome.stderr) {
+        return {
+            stdout: '',
+            stderr: `${outcome.stderr}\n\n${OBSIDIAN_CLI_FAILURE_GUIDANCE}`,
+            exitCode: 1
+        };
+    }
+    if (outcome.result) {
+        return { stdout: outcome.result, stderr: '', exitCode: 0 };
+    }
+    if (outcome.stderr) {
+        return {
+            stdout: '',
+            stderr: `${outcome.stderr}\n\n${OBSIDIAN_CLI_FAILURE_GUIDANCE}`,
+            exitCode: 1
+        };
+    }
+    if (outcome.exitCode === 0) {
+        return { stdout: '(no output)', stderr: '', exitCode: 0 };
+    }
+    return {
+        stdout: '',
+        stderr: 'Obsidian did not respond. Make sure the Obsidian desktop app is open, then try again.\n\n' +
+            OBSIDIAN_CLI_FAILURE_GUIDANCE,
+        exitCode: 1
+    };
+}
+function runOnce(command, runtime, timeoutMs, maxOutputChars, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve({ result: '', stderr: '', exitCode: null });
+            return;
+        }
+        const env = obsidianPathEnv();
+        const child = runtime.spawn(command, {
+            shell: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            ...(env ? { env } : {})
+        });
+        const stdout = createCapturedOutput();
+        const stderr = createCapturedOutput();
+        let settled = false;
+        let quietTimer;
+        const finish = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            globalThis.clearTimeout(hardTimer);
+            globalThis.clearTimeout(quietTimer);
+            signal?.removeEventListener('abort', onAbort);
+            try {
+                if (child.pid !== undefined && runtime.killProcess) {
+                    runtime.killProcess(-child.pid, 'SIGKILL');
+                }
+                else {
+                    child.kill('SIGKILL');
+                }
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+            resolve({
+                result: capOutput(cleanObsidianOutput(stdout.value), maxOutputChars),
+                stderr: capOutput(cleanObsidianOutput(stderr.value), maxOutputChars),
+                exitCode
+            });
+        };
+        const hardTimer = globalThis.setTimeout(() => finish(null), timeoutMs);
+        const onAbort = () => finish(null);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        const bumpQuiet = () => {
+            globalThis.clearTimeout(quietTimer);
+            quietTimer = globalThis.setTimeout(() => finish(null), OUTPUT_QUIET_MS);
+        };
+        child.stdout?.on('data', (chunk) => {
+            appendOutput(stdout, chunk, maxOutputChars);
+            bumpQuiet();
+        });
+        child.stderr?.on('data', (chunk) => {
+            appendOutput(stderr, chunk, maxOutputChars);
+            bumpQuiet();
+        });
+        child.on('exit', (code) => finish(code));
+        child.on('error', () => finish(null));
+    });
+}
+export async function runObsidianCli(command, runtime, options = {}) {
+    const signal = options.signal;
+    const maxOutputChars = options.maxOutputChars ?? MAX_OUTPUT_CHARS;
+    const timeoutMs = options.timeoutMs ?? COMMAND_MS;
+    if (!(await isObsidianRunning(runtime.spawn, runtime.killProcess, signal))) {
+        if (signal?.aborted) {
+            return { stdout: '', stderr: 'Obsidian command aborted.', exitCode: 1 };
+        }
+        launchObsidianApp(runtime.spawn);
+        await delay(READY_WAIT_MS, signal);
+    }
+    if (signal?.aborted) {
+        return { stdout: '', stderr: 'Obsidian command aborted.', exitCode: 1 };
+    }
+    const outcome = await runOnce(command, runtime, timeoutMs, maxOutputChars, signal);
+    if (signal?.aborted) {
+        return { stdout: '', stderr: 'Obsidian command aborted.', exitCode: 1 };
+    }
+    const result = toResult(outcome);
+    return {
+        stdout: capOutput(result.stdout, maxOutputChars),
+        stderr: capOutput(result.stderr, maxOutputChars),
+        exitCode: result.exitCode
+    };
+}

package/dist-lib/lib/tools/exec/obsidian/command.d.ts

@@ -0,0 +1,5 @@
+export declare function parseObsidianCommand(command: string): {
+    action: string;
+    args: string[];
+} | null;
+export declare function normalizeObsidianCommand(command: string): string;

package/dist-lib/lib/tools/exec/obsidian/command.js

@@ -0,0 +1,18 @@
+import { shellArgv } from "../shell-argv.js";
+const OBSIDIAN_BIN = /^obsidian(?:\.exe|\.com)?$/i;
+const OBSIDIAN_PREFIX = /^obsidian(?:\.exe|\.com)?(?:\s|$)/i;
+export function parseObsidianCommand(command) {
+    const trimmed = command.trim();
+    if (!OBSIDIAN_PREFIX.test(trimmed))
+        return null;
+    const tokens = shellArgv(trimmed);
+    if (tokens.length === 0 || !OBSIDIAN_BIN.test(tokens[0] ?? ''))
+        return null;
+    if (tokens.length === 1)
+        return { action: '', args: [] };
+    const [, action, ...args] = tokens;
+    return { action: action ?? '', args };
+}
+export function normalizeObsidianCommand(command) {
+    return command.replace(/^(obsidian(?:\.exe|\.com)?)(\s+vault)\s+info(?=\s|$)/i, '$1$2');
+}

package/dist-lib/lib/tools/exec/obsidian/guidance.d.ts

@@ -0,0 +1,5 @@
+export declare const OBSIDIAN_NO_SHELL_FALLBACK: string;
+export declare const OBSIDIAN_CLI_FAILURE_GUIDANCE = "Do not use `ls`, `cat`, `find`, `grep`, or filesystem paths to inspect the vault or Obsidian config \u2014 that bypasses Obsidian and is wrong. Correct the obsidian command or ask the user to open Obsidian / register the CLI.";
+export declare const OBSIDIAN_DESKTOP_AGENT_REQUIRED: string;
+export declare const OBSIDIAN_VAULT_SETUP_REQUIRED: string;
+export declare const OBSIDIAN_VAULT_MODE_NOTE: string;

package/dist-lib/lib/tools/exec/obsidian/guidance.js

@@ -0,0 +1,18 @@
+export const OBSIDIAN_NO_SHELL_FALLBACK = 'Do not use `ls`, `cat`, `find`, `grep`, or filesystem paths to inspect the vault ' +
+    'or Obsidian config — that bypasses Obsidian and is wrong.';
+export const OBSIDIAN_CLI_FAILURE_GUIDANCE = `${OBSIDIAN_NO_SHELL_FALLBACK} Correct the obsidian command or ask the user to open Obsidian / register the CLI.`;
+export const OBSIDIAN_DESKTOP_AGENT_REQUIRED = 'Obsidian cannot run on this device. Switch the chat to the desktop agent that ' +
+    'has Obsidian connected (Skills → Obsidian on that desktop), then ask again. ' +
+    `${OBSIDIAN_NO_SHELL_FALLBACK} Do not retry the same command here.`;
+export const OBSIDIAN_VAULT_SETUP_REQUIRED = 'Obsidian vault file mode is not set up. Under Snap/Flatpak the Obsidian CLI ' +
+    'cannot reach the desktop app, so this skill needs a vault folder: ask the user ' +
+    'to open Skills > Obsidian > Select vault folder, then retry the same `obsidian` ' +
+    `command. ${OBSIDIAN_NO_SHELL_FALLBACK} This is a one-time setup step, not a reason ` +
+    'to switch tools.';
+export const OBSIDIAN_VAULT_MODE_NOTE = [
+    'Runtime note — Obsidian vault file mode is active (a vault folder is configured):',
+    '- Run vault commands through the `exec` tool, e.g. `obsidian vault info=path`, `obsidian search query="..."`, `obsidian read path="Folder/Note.md"`.',
+    '- Start with `obsidian vault info=path` to confirm the configured vault.',
+    '- `obsidian vaults` returns only the configured vault folder, not every vault in the Obsidian app.',
+    '- App-only actions (open in app, plugin/sync/theme commands) are unavailable in this mode; they require the official Obsidian CLI connected to the running app.'
+].join('\n');

package/dist-lib/lib/tools/exec/obsidian/note-name.d.ts

@@ -0,0 +1 @@
+export declare function markdownFileName(name: string): string;

package/dist-lib/lib/tools/exec/obsidian/note-name.js

@@ -0,0 +1,6 @@
+export function markdownFileName(name) {
+    if (name.includes('/') || name.includes('\\') || name === '.' || name === '..') {
+        throw new Error('name= must be a note name, not a path.');
+    }
+    return name.endsWith('.md') ? name : `${name}.md`;
+}

package/dist-lib/lib/tools/exec/obsidian/output.d.ts

@@ -0,0 +1 @@
+export declare function cleanObsidianOutput(raw: string): string;