@cavelang/cli 0.29.1 → 0.31.0

package/dist/internal/loop/llm.js

@@ -29,11 +29,11 @@
  * `cave ingest` and `cave eval` use — into a `Complete`, so no LLM SDK
  * ever becomes a dependency of this package.
  */
-import { spawn } from 'node:child_process';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { emitClaim } from '@cavelang/canonical';
+import { runProcess, shellCommand } from "./process.js";
 /** The reply that ends the reconstruction. */
 export const stopToken = 'STOP';
 const defaultMaxCues = 16;
@@ -172,60 +172,33 @@ export const llmPolicy = (complete, options = {}) => {
  */
 export const shellComplete = (template, options = {}) => {
     const timeoutSeconds = options.timeoutSeconds ?? 120;
-    return prompt => new Promise((resolvePromise, rejectPromise) => {
+    return async (prompt) => {
         let dir;
-        let command = template;
+        const substitutions = {};
         if (template.includes('{prompt-file}')) {
             dir = mkdtempSync(join(tmpdir(), 'cave-loop-'));
             const file = join(dir, 'prompt.md');
             writeFileSync(file, prompt);
-            // Quoted like ingest's substitutions — one argument, never re-parsed.
-            command = template.replaceAll('{prompt-file}', `'${file.replaceAll("'", `'\\''`)}'`);
+            substitutions['prompt-file'] = file;
         }
-        let settled = false;
-        const settle = (finish) => {
-            if (!settled) {
-                settled = true;
-                if (dir !== undefined) {
-                    rmSync(dir, { recursive: true, force: true });
-                }
-                // Grandchildren of a killed shell can inherit the stdio pipes;
-                // dropping our end releases the event loop from waiting on them.
-                child.stdout.destroy();
-                child.stdin.destroy();
-                finish();
+        try {
+            const result = await runProcess(shellCommand(template, substitutions), {
+                input: prompt,
+                timeoutMs: timeoutSeconds * 1000,
+                ...options.cwd === undefined ? {} : { cwd: options.cwd },
+                ...options.signal === undefined ? {} : { signal: options.signal },
+                ...options.maxStdoutBytes === undefined ? {} : { maxStdoutBytes: options.maxStdoutBytes },
+                ...options.maxStderrBytes === undefined ? {} : { maxStderrBytes: options.maxStderrBytes }
+            });
+            if (result.code !== 0) {
+                throw new Error(`agent exited with ${result.code ?? `signal ${result.signal}`}`);
             }
-        };
-        const child = spawn(command, {
-            shell: true,
-            timeout: timeoutSeconds * 1000,
-            stdio: ['pipe', 'pipe', 'inherit'],
-            ...options.cwd === undefined ? {} : { cwd: options.cwd }
-        });
-        let stdout = '';
-        child.stdout.on('data', chunk => {
-            stdout += String(chunk);
-        });
-        child.on('error', error => settle(() => rejectPromise(new Error(`agent failed: ${error.message}`))));
-        // A killed shell can leave grandchildren holding the stdio pipes open,
-        // so the signal path settles on `exit` — waiting for `close` would wait
-        // for processes the timeout was meant to cut loose.
-        child.on('exit', (_code, signal) => {
-            if (signal !== null) {
-                settle(() => rejectPromise(new Error(`agent killed by ${signal} after ${timeoutSeconds}s`)));
-            }
-        });
-        child.on('close', code => settle(() => {
-            if (code === 0) {
-                resolvePromise(stdout);
-            }
-            else {
-                rejectPromise(new Error(`agent exited with ${code}`));
-            }
-        }));
-        child.stdin.on('error', () => { });
-        child.stdin.write(prompt);
-        child.stdin.end();
-    });
+            return result.stdout;
+        }
+        finally {
+            if (dir !== undefined)
+                rmSync(dir, { recursive: true, force: true });
+        }
+    };
 };
 //# sourceMappingURL=llm.js.map

package/dist/internal/loop/llm.js.map

@@ -1 +1 @@
-{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../src/llm.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../src/llm.ts"],"names":[],"mappings":"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"}

package/dist/internal/loop/process-worker.d.ts

@@ -0,0 +1,3 @@
+/** Internal synchronous-bridge worker for process.ts. */
+export {};
+//# sourceMappingURL=process-worker.d.ts.map

package/dist/internal/loop/process-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-worker.d.ts","sourceRoot":"","sources":["../../src/process-worker.ts"],"names":[],"mappings":"AAAA,yDAAyD"}

package/dist/internal/loop/process-worker.js

@@ -0,0 +1,32 @@
+/** Internal synchronous-bridge worker for process.ts. */
+import { readFileSync } from 'node:fs';
+import { ProcessFailure, runProcess } from "./process.js";
+const request = JSON.parse(readFileSync(0, 'utf8'));
+const controller = new AbortController();
+const abort = () => controller.abort();
+process.once('SIGINT', abort);
+process.once('SIGTERM', abort);
+try {
+    const result = await runProcess(request.command, { ...request.options, signal: controller.signal });
+    process.stdout.write(JSON.stringify({ ok: true, result }));
+}
+catch (error) {
+    if (error instanceof ProcessFailure) {
+        process.stdout.write(JSON.stringify({ ok: false, failure: error.toJSON() }));
+    }
+    else {
+        process.stdout.write(JSON.stringify({
+            ok: false,
+            failure: {
+                kind: 'spawn',
+                message: 'process failed to start',
+                result: { code: null, signal: null, stdout: '', stderr: '' }
+            }
+        }));
+    }
+}
+finally {
+    process.removeListener('SIGINT', abort);
+    process.removeListener('SIGTERM', abort);
+}
+//# sourceMappingURL=process-worker.js.map

package/dist/internal/loop/process-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-worker.js","sourceRoot":"","sources":["../../src/process-worker.ts"],"names":[],"mappings":"AAAA,yDAAyD;AAEzD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EACL,cAAc,EACd,UAAU,EAGX,MAAM,cAAc,CAAA;AAOrB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAY,CAAA;AAC9D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;AACxC,MAAM,KAAK,GAAG,GAAS,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,CAAA;AAC5C,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;AAC7B,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;AAC9B,IAAI,CAAC;IACH,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAA;IACnG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;AAC5D,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IACf,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;QACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAA;IAC9E,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;YAClC,EAAE,EAAE,KAAK;YACT,OAAO,EAAE;gBACP,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,yBAAyB;gBAClC,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;aAC7D;SACF,CAAC,CAAC,CAAA;IACL,CAAC;AACH,CAAC;QAAS,CAAC;IACT,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;IACvC,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;AAC1C,CAAC"}

package/dist/internal/loop/process.d.ts

@@ -0,0 +1,61 @@
+/** Portable, bounded external-process execution for CAVE integrations. */
+export type ProcessCommand = {
+    readonly executable: string;
+    readonly args: readonly string[];
+};
+export type ShellSyntax = 'posix' | 'powershell';
+export type ProcessResult = {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stdout: string;
+    readonly stderr: string;
+};
+export type ProcessFailureKind = 'spawn' | 'timeout' | 'aborted' | 'stdout-limit' | 'stderr-limit';
+export type ProcessFailureRecord = {
+    readonly kind: ProcessFailureKind;
+    readonly message: string;
+    readonly result: ProcessResult;
+    readonly limit?: number;
+    readonly errorCode?: string;
+};
+/** Typed, command-redacted failure for resource and lifecycle errors. */
+export declare class ProcessFailure extends Error {
+    readonly name = "ProcessFailure";
+    readonly kind: ProcessFailureKind;
+    readonly result: ProcessResult;
+    readonly limit?: number;
+    readonly errorCode?: string;
+    constructor(record: ProcessFailureRecord);
+    toJSON(): ProcessFailureRecord;
+}
+export type ProcessOptions = {
+    readonly cwd?: string;
+    readonly input?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly maxStdoutBytes?: number;
+    readonly maxStderrBytes?: number;
+};
+export type SyncProcessOptions = Omit<ProcessOptions, 'signal'>;
+export declare const defaultMaxStdoutBytes: number;
+export declare const defaultMaxStderrBytes: number;
+export declare const directCommand: (executable: string, args?: readonly string[]) => ProcessCommand;
+export declare const shellSyntaxFor: (platform?: NodeJS.Platform) => ShellSyntax;
+/** Quote one value as one argument for the selected intentional shell. */
+export declare const quoteShellArgument: (value: string, syntax?: ShellSyntax) => string;
+/** Substitute known placeholders once; unknown placeholders remain literal. */
+export declare const substituteShell: (template: string, substitutions: Readonly<Record<string, string>>, syntax?: ShellSyntax) => string;
+/**
+ * Make an intentional shell command explicit. POSIX uses `/bin/sh`; Windows
+ * uses PowerShell 7. The shell itself is still spawned with `shell:false`.
+ */
+export declare const shellCommand: (template: string, substitutions?: Readonly<Record<string, string>>, platform?: NodeJS.Platform) => ProcessCommand;
+/** Run an executable plus argument array with bounded output and tree cleanup. */
+export declare const runProcess: (command: ProcessCommand, options?: ProcessOptions) => Promise<ProcessResult>;
+/**
+ * Synchronous bridge for compatibility-sensitive APIs. A short-lived Node
+ * worker owns the asynchronous tree cleanup, then returns one bounded result.
+ */
+export declare const runProcessSync: (command: ProcessCommand, options?: SyncProcessOptions) => ProcessResult;
+//# sourceMappingURL=process.d.ts.map

package/dist/internal/loop/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/process.ts"],"names":[],"mappings":"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"}

package/dist/internal/loop/process.js

@@ -0,0 +1,268 @@
+/** Portable, bounded external-process execution for CAVE integrations. */
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+/** Typed, command-redacted failure for resource and lifecycle errors. */
+export class ProcessFailure extends Error {
+    name = 'ProcessFailure';
+    kind;
+    result;
+    limit;
+    errorCode;
+    constructor(record) {
+        super(record.message);
+        this.kind = record.kind;
+        this.result = record.result;
+        this.limit = record.limit;
+        this.errorCode = record.errorCode;
+    }
+    toJSON() {
+        return {
+            kind: this.kind,
+            message: this.message,
+            result: this.result,
+            ...this.limit === undefined ? {} : { limit: this.limit },
+            ...this.errorCode === undefined ? {} : { errorCode: this.errorCode }
+        };
+    }
+}
+export const defaultMaxStdoutBytes = 8 * 1024 * 1024;
+export const defaultMaxStderrBytes = 1024 * 1024;
+export const directCommand = (executable, args = []) => ({ executable, args });
+export const shellSyntaxFor = (platform = process.platform) => platform === 'win32' ? 'powershell' : 'posix';
+/** Quote one value as one argument for the selected intentional shell. */
+export const quoteShellArgument = (value, syntax = shellSyntaxFor()) => syntax === 'powershell' ? `'${value.replaceAll("'", "''")}'` : `'${value.replaceAll("'", `'\\''`)}'`;
+/** Substitute known placeholders once; unknown placeholders remain literal. */
+export const substituteShell = (template, substitutions, syntax = shellSyntaxFor()) => template.replace(/\{([A-Za-z][A-Za-z0-9_-]*)\}/g, (whole, name) => Object.hasOwn(substitutions, name) ? quoteShellArgument(substitutions[name], syntax) : whole);
+const powershellScript = (command) => [
+    '$global:LASTEXITCODE = $null',
+    command,
+    '$caveSucceeded = $?',
+    '$caveExitCode = $global:LASTEXITCODE',
+    'if ($caveSucceeded) { exit 0 }',
+    'if ($null -ne $caveExitCode) { exit $caveExitCode }',
+    'exit 1'
+].join('\n');
+/**
+ * Make an intentional shell command explicit. POSIX uses `/bin/sh`; Windows
+ * uses PowerShell 7. The shell itself is still spawned with `shell:false`.
+ */
+export const shellCommand = (template, substitutions = {}, platform = process.platform) => {
+    const syntax = shellSyntaxFor(platform);
+    const command = substituteShell(template, substitutions, syntax);
+    // EncodedCommand transports the exact UTF-16LE script without a native argv
+    // reparse. PowerShell 7 is required for standard native argument passing;
+    // Windows PowerShell 5.1 corrupts embedded quotes passed to executables. The
+    // wrapper preserves the last native command's exact non-zero exit code.
+    return platform === 'win32' ?
+        directCommand('pwsh.exe', [
+            '-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+            '-EncodedCommand', Buffer.from(powershellScript(command), 'utf16le').toString('base64')
+        ]) :
+        directCommand('/bin/sh', ['-c', command]);
+};
+const emptyResult = () => ({ code: null, signal: null, stdout: '', stderr: '' });
+const positiveLimit = (value, fallback, name) => {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < 0) {
+        throw new TypeError(`${name} must be a non-negative safe integer`);
+    }
+    return result;
+};
+const killTree = (child) => {
+    const pid = child.pid;
+    if (pid === undefined)
+        return Promise.resolve();
+    if (process.platform !== 'win32') {
+        try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+        }
+        return Promise.resolve();
+    }
+    return new Promise(resolve => {
+        const killer = spawn('taskkill.exe', ['/pid', String(pid), '/t', '/f'], {
+            shell: false,
+            stdio: 'ignore',
+            windowsHide: true
+        });
+        killer.once('error', () => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+            resolve();
+        });
+        killer.once('close', () => resolve());
+    });
+};
+const failureMessage = (kind, timeoutMs, limit) => {
+    switch (kind) {
+        case 'spawn': return 'process failed to start';
+        case 'timeout': return `process timed out after ${timeoutMs}ms`;
+        case 'aborted': return 'process was cancelled';
+        case 'stdout-limit': return `process stdout exceeded ${limit} bytes`;
+        case 'stderr-limit': return `process stderr exceeded ${limit} bytes`;
+    }
+};
+/** Run an executable plus argument array with bounded output and tree cleanup. */
+export const runProcess = (command, options = {}) => {
+    const stdoutLimit = positiveLimit(options.maxStdoutBytes, defaultMaxStdoutBytes, 'maxStdoutBytes');
+    const stderrLimit = positiveLimit(options.maxStderrBytes, defaultMaxStderrBytes, 'maxStderrBytes');
+    const timeoutMs = positiveLimit(options.timeoutMs, 0, 'timeoutMs');
+    if (options.signal?.aborted === true) {
+        return Promise.reject(new ProcessFailure({
+            kind: 'aborted', message: failureMessage('aborted', timeoutMs), result: emptyResult()
+        }));
+    }
+    return new Promise((resolve, reject) => {
+        const stdout = [];
+        const stderr = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let code = null;
+        let exitSignal = null;
+        let settled = false;
+        let terminating = false;
+        let timer;
+        let spawnErrorCode;
+        const child = spawn(command.executable, [...command.args], {
+            shell: false,
+            detached: process.platform !== 'win32',
+            windowsHide: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            ...options.cwd === undefined ? {} : { cwd: options.cwd },
+            ...options.env === undefined ? {} : { env: options.env }
+        });
+        const result = () => ({
+            code,
+            signal: exitSignal,
+            stdout: Buffer.concat(stdout).toString('utf8'),
+            stderr: Buffer.concat(stderr).toString('utf8')
+        });
+        const cleanup = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+        };
+        const finish = (failure) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            child.stdin?.destroy();
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            if (failure === undefined)
+                resolve(result());
+            else
+                reject(failure);
+        };
+        const terminate = (kind, limit) => {
+            if (settled || terminating)
+                return;
+            terminating = true;
+            void killTree(child).finally(() => finish(new ProcessFailure({
+                kind,
+                message: failureMessage(kind, timeoutMs, limit),
+                result: result(),
+                ...limit === undefined ? {} : { limit }
+            })));
+        };
+        const abort = () => terminate('aborted');
+        const collect = (stream, chunk) => {
+            if (terminating || settled)
+                return;
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const limit = stream === 'stdout' ? stdoutLimit : stderrLimit;
+            const used = stream === 'stdout' ? stdoutBytes : stderrBytes;
+            const remaining = Math.max(0, limit - used);
+            if (remaining > 0)
+                (stream === 'stdout' ? stdout : stderr).push(bytes.subarray(0, remaining));
+            if (stream === 'stdout')
+                stdoutBytes += Math.min(bytes.length, remaining);
+            else
+                stderrBytes += Math.min(bytes.length, remaining);
+            if (bytes.length > remaining)
+                terminate(stream === 'stdout' ? 'stdout-limit' : 'stderr-limit', limit);
+        };
+        child.stdout?.on('data', chunk => collect('stdout', chunk));
+        child.stderr?.on('data', chunk => collect('stderr', chunk));
+        child.on('error', (error) => {
+            if (terminating)
+                return;
+            spawnErrorCode = error.code;
+            finish(new ProcessFailure({
+                kind: 'spawn',
+                message: failureMessage('spawn', timeoutMs),
+                result: result(),
+                ...spawnErrorCode === undefined ? {} : { errorCode: spawnErrorCode }
+            }));
+        });
+        child.on('exit', (observedCode, observedSignal) => {
+            code = observedCode;
+            exitSignal = observedSignal;
+        });
+        child.on('close', (observedCode, observedSignal) => {
+            code = observedCode;
+            exitSignal = observedSignal;
+            if (!terminating)
+                finish();
+        });
+        child.stdin?.on('error', () => { });
+        if (options.input !== undefined)
+            child.stdin?.end(options.input);
+        else
+            child.stdin?.end();
+        if (timeoutMs > 0)
+            timer = setTimeout(() => terminate('timeout'), timeoutMs);
+        options.signal?.addEventListener('abort', abort, { once: true });
+        // Close the check/listener race if cancellation landed during spawn setup.
+        if (options.signal?.aborted === true)
+            abort();
+    });
+};
+/**
+ * Synchronous bridge for compatibility-sensitive APIs. A short-lived Node
+ * worker owns the asynchronous tree cleanup, then returns one bounded result.
+ */
+export const runProcessSync = (command, options = {}) => {
+    const stdoutLimit = positiveLimit(options.maxStdoutBytes, defaultMaxStdoutBytes, 'maxStdoutBytes');
+    const stderrLimit = positiveLimit(options.maxStderrBytes, defaultMaxStderrBytes, 'maxStderrBytes');
+    const timeoutMs = positiveLimit(options.timeoutMs, 0, 'timeoutMs');
+    const extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+    const worker = fileURLToPath(new URL(`./process-worker.${extension}`, import.meta.url));
+    const result = spawnSync(process.execPath, ['--disable-warning=ExperimentalWarning', worker], {
+        shell: false,
+        windowsHide: true,
+        encoding: 'utf8',
+        input: JSON.stringify({ command, options: { ...options, maxStdoutBytes: stdoutLimit, maxStderrBytes: stderrLimit } }),
+        // JSON can expand a captured control byte to a six-byte `\\u00xx` escape.
+        maxBuffer: Math.max(1024 * 1024, (stdoutLimit + stderrLimit) * 7 + 1024 * 1024),
+        timeout: timeoutMs > 0 ? timeoutMs + 5_000 : undefined
+    });
+    if (result.status !== 0 || result.error !== undefined) {
+        const errorCode = result.error?.code;
+        throw new ProcessFailure({
+            kind: errorCode === 'ETIMEDOUT' ? 'timeout' : 'spawn',
+            message: failureMessage(errorCode === 'ETIMEDOUT' ? 'timeout' : 'spawn', timeoutMs),
+            result: emptyResult(),
+            ...errorCode === undefined ? {} : { errorCode }
+        });
+    }
+    let response;
+    try {
+        response = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new ProcessFailure({ kind: 'spawn', message: failureMessage('spawn', timeoutMs), result: emptyResult() });
+    }
+    if (!response.ok)
+        throw new ProcessFailure(response.failure);
+    return response.result;
+};
+//# sourceMappingURL=process.js.map

package/dist/internal/loop/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../src/process.ts"],"names":[],"mappings":"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"}

package/dist/internal/mcp/guide.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compact, version-matched operating guidance for agents using CAVE.
+ *
+ * Keep this task-oriented. The normative language specification lives in
+ * `.claude/skills/cave-*`; this guide answers the smaller question an MCP
+ * client has at the point of use: which tool should I call, and what must I
+ * preserve when I write or revise knowledge?
+ */
+export declare const guideTopics: readonly ["overview", "write", "find", "revise", "safety"];
+export type GuideTopic = typeof guideTopics[number];
+export declare const guideFor: (topic?: GuideTopic) => string;
+//# sourceMappingURL=guide.d.ts.map

package/dist/internal/mcp/guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../../src/guide.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,WAAW,4DAA6D,CAAA;AACrF,MAAM,MAAM,UAAU,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC,CAAA;AAoDnD,eAAO,MAAM,QAAQ,GAAI,QAAO,UAAuB,KAAG,MAAuB,CAAA"}

package/dist/internal/mcp/guide.js

@@ -0,0 +1,56 @@
+/**
+ * Compact, version-matched operating guidance for agents using CAVE.
+ *
+ * Keep this task-oriented. The normative language specification lives in
+ * `.claude/skills/cave-*`; this guide answers the smaller question an MCP
+ * client has at the point of use: which tool should I call, and what must I
+ * preserve when I write or revise knowledge?
+ */
+export const guideTopics = ['overview', 'write', 'find', 'revise', 'safety'];
+const guides = {
+    overview: `CAVE is durable, local agent memory: atomic claims in an append-only SQLite database.
+
+Typical workflow:
+1. Recall before reasoning: use cave_about for one entity, cave_query for a known relation, cave_search for unknown wording, or cave_reconstruct for multi-hop context.
+2. Record durable facts, decisions, constraints and outcomes as one CAVE claim per line. Use cave_lint before cave_add when composing unfamiliar syntax.
+3. Preserve uncertainty and provenance. Prefer a qualified claim over prose that hides who said it or how certain it is.
+4. Revise by appending the same claim identity with a new confidence. Do not expect edits or current-only views to erase history.
+
+Ask cave_help for one of these topics: write, find, revise, safety.`,
+    write: `Write one fact per line:
+  subject VERB [NOT] object [@context...] [#tag[:value]...] [@ N%] [!] [; comment]
+  subject HAS attribute: value [+/- delta] [@context...] [#tag[:value]...] [@ N%] [!] [; comment]
+
+Examples:
+  auth/middleware USES jwt @ 90%
+  deploy/2026-07-25 YIELDS api/v2 @src:release-notes
+  checkout/errors CAUSE retry-storm @production @ 70% #topic:reliability
+  OpenAI HAS revenue: ~20B USD/yr +/- 2B USD/yr @2026-Q1 @ 90%
+
+Use kebab-case entities with / for scope, UPPERCASE verbs, @ctx without a space for context, and @ 90% with a space for confidence. Keep source citations in @src: contexts. The MCP server stamps an agent source when cave_add receives no @src:. Use cave_lint, then cave_add.`,
+    find: `Choose the narrowest retrieval tool that fits:
+- cave_about: all current claims mentioning a known entity, in either direction.
+- cave_query: a known CAVE-Q shape, such as ?service USES redis or ?ancestor PARENT-OF+ me. Add WHERE conf >= 0.7 when confidence matters.
+- cave_search: literal full-text discovery when entity or verb spelling is unknown.
+- cave_neighbors: inspect named forward and inverse graph edges while walking manually.
+- cave_reconstruct: collect bounded multi-hop context around one or more seed entities before broader reasoning.
+- cave_export: portable canonical text; current=true omits superseded beliefs but does not erase history.
+
+Set aliases=true only when equivalent names should match. Set resolve=true when the task needs the policy-selected winner rather than all coexisting sources. Use asOf for past belief time and at for valid time in the world.`,
+    revise: `CAVE is append-only. A claim's identity includes its subject, verb, object/value and non-source contexts; @src: distinguishes voices.
+
+To update confidence, append the same claim and the same @src: with a new confidence:
+  api/gateway USES redis @src:architecture-review @ 90%
+
+To retract that belief, append the same identity at zero confidence:
+  api/gateway USES redis @src:architecture-review @ 0% ; superseded by current design
+
+Do not silently replace one source with another. Conflicting claims may coexist. Query with resolve=true only when a single policy-ranked answer is required. Run cave_derive after adding or changing premises when stored rules should materialize conclusions. Prefer generated act_<name> tools over free-form cave_add when a declared governed action fits.`,
+    safety: `CAVE preserves history. Retraction, current-only queries, resolution and sensitivity filters change what is shown or believed; they do not guarantee erasure from SQLite remnants, exports, sync peers or backups.
+
+Never store credentials, private keys, tokens, or information whose retention policy requires selective deletion. If a secret is ingested, rotate it, stop propagation, inventory every database/export/backup, rebuild from reviewed safe input, and destroy or expire affected copies.
+
+Use #sensitivity:public, internal, confidential or restricted where disclosure scope matters. Unlabelled claims default to internal on publication surfaces. Use maxSensitivity deliberately when exporting. Treat act_<name> tools as effect-capable even though their knowledge effects are governed and atomic.`
+};
+export const guideFor = (topic = 'overview') => guides[topic];
+//# sourceMappingURL=guide.js.map

package/dist/internal/mcp/guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.js","sourceRoot":"","sources":["../../src/guide.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAA;AAGrF,MAAM,MAAM,GAAyC;IACnD,QAAQ,EAAE;;;;;;;;oEAQwD;IAElE,KAAK,EAAE;;;;;;;;;;kRAUyQ;IAEhR,IAAI,EAAE;;;;;;;;gOAQwN;IAE9N,MAAM,EAAE;;;;;;;;kWAQwV;IAEhW,MAAM,EAAE;;;;mTAIyS;CAClT,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAoB,UAAU,EAAU,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA"}

package/dist/internal/mcp/index.d.ts

@@ -6,7 +6,7 @@
  * { "command": "cave", "args": ["mcp", "--db", "knowledge.db"] }
  * ```
  *
- * Tools: cave_add, cave_query, cave_fuse, cave_search, cave_about,
+ * Tools: cave_help, cave_add, cave_query, cave_fuse, cave_search, cave_about,
  * cave_neighbors, cave_reconstruct, cave_derive, cave_export, cave_lint —
  * plus one generated `act_<name>` tool per action declared in the store
  * (spec §25.5), the governed write vocabulary. `cave_fuse` and
@@ -17,7 +17,7 @@
  * `--tools <list>` narrow the served surface — the minimum viable agent
  * permission boundary.
  */
-export { agentSource, createServer, serve, instructions, instructionsFor, protocolVersion, serverInfo, specCard } from './server.ts';
+export { agentSource, createServer, serve, instructions, instructionsFor, protocolVersion, protocolVersions, serverInfo, specCard } from './server.ts';
 export type { ServerOptions } from './server.ts';
 export { runMcp } from './main.ts';
 export { actionTools, actToolName, actToolPrefix, allowsActions, permissions, scopedActionTools, scopedTools, tools } from './tools.ts';