@msvesper/vesper-link 0.1.4

package/dist/installer.js

@@ -0,0 +1,214 @@
+import * as fs from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { normalizeHost } from './config.js';
+import { getCapabilities, getHealth, SystemicUploadError } from './http-client.js';
+import { installManagedRuntime } from './installation.js';
+import { acquireSyncLock } from './lock.js';
+import { prepareManagedRuntime, validateInstallPrerequisites, validateManagedRuntime, } from './managed-runtime.js';
+import { NodeProcessRunner } from './process-runner.js';
+import { acquireRemoteTransport, consumeBootstrapAuthKey } from './transport.js';
+import { VESPER_LINK_VERSION } from './version.js';
+export class WaitingForTagError extends Error {
+    progress;
+    code = 'waiting_for_tag';
+    constructor(progress) {
+        const tag = progress.expectedRole ? 'tag:vesper-' + progress.expectedRole : 'exactly one Vesper capability tag';
+        super('Remote node ' + (progress.nodeName ?? 'unknown') + ' in ' + (progress.tailnetName ?? 'unknown')
+            + ' is enrolled but not authorized; assign ' + tag + ' and rerun install');
+        this.progress = progress;
+        this.name = 'WaitingForTagError';
+    }
+}
+export class AutomaticEnrollmentConflictError extends Error {
+    code = 'automatic_enrollment_existing_identity';
+    constructor(progress) {
+        const tag = progress.expectedRole ? `tag:vesper-${progress.expectedRole}` : 'the requested Vesper capability tag';
+        super(`This device already has a Tailscale identity that is not authorized for Memory Link. `
+            + `Assign ${tag} to ${progress.nodeName ?? 'the existing device'} in Tailscale, `
+            + `or run npx --yes @msvesper/vesper-link@${VESPER_LINK_VERSION} reset-identity --confirm RESET `
+            + 'and then run a freshly copied connection command.');
+        this.name = 'AutomaticEnrollmentConflictError';
+    }
+}
+const defaultDependencies = {
+    validatePrerequisites: validateInstallPrerequisites,
+    prepareRuntime: prepareManagedRuntime,
+    validateRuntime: validateManagedRuntime,
+    acquireTransport: (options) => acquireRemoteTransport(options),
+    getHealth,
+    getCapabilities,
+    installManaged: installManagedRuntime,
+    triggerFirstSync: defaultTriggerFirstSync,
+};
+async function defaultTriggerFirstSync(paths) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [paths.launcherPath, 'sync-once'], {
+            detached: true, windowsHide: true, stdio: 'ignore',
+        });
+        child.once('error', reject);
+        child.once('spawn', () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+export async function installVesperLink(options) {
+    const dependencies = options.dependencies ?? defaultDependencies;
+    const runner = options.runner ?? new NodeProcessRunner();
+    let bootstrapAuthKey = consumeBootstrapAuthKey(options.bootstrapAuthKey);
+    options.bootstrapAuthKey = undefined;
+    const automaticEnrollment = bootstrapAuthKey !== undefined;
+    const host = normalizeHost(options.host);
+    const companion = await dependencies.validatePrerequisites({ hostUrl: host, runner });
+    const releaseCandidateLock = await acquireSyncLock(options.paths.lockPath);
+    let runtime;
+    try {
+        runtime = await dependencies.prepareRuntime({ paths: options.paths, companion });
+        await dependencies.validateRuntime(runtime);
+    }
+    finally {
+        await releaseCandidateLock();
+    }
+    const progress = {
+        schemaVersion: 1, state: 'enrolling', host, expectedRole: options.expectedRole, updatedAt: new Date().toISOString(),
+    };
+    await writeProgress(options.paths, progress);
+    let transport;
+    try {
+        transport = await dependencies.acquireTransport({
+            paths: options.paths, hostUrl: host,
+            requiredCompanion: runtime.companion,
+            bootstrapAuthKey,
+            onNeedsLogin: (url) => {
+                options.onNeedsLogin?.(url);
+            },
+        });
+    }
+    finally {
+        bootstrapAuthKey = undefined;
+    }
+    let capabilities;
+    let reportedWaiting = false;
+    try {
+        progress.tailnetName = transport.identity.tailnetName;
+        progress.nodeName = transport.identity.nodeName;
+        progress.ipv4 = transport.identity.ipv4;
+        while (capabilities === undefined) {
+            try {
+                capabilities = await dependencies.getCapabilities(transport.hostUrl, transport.fetch);
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof SystemicUploadError) || error.httpStatus !== 403) {
+                    throw error;
+                }
+                if (automaticEnrollment) {
+                    throw new AutomaticEnrollmentConflictError(progress);
+                }
+                progress.state = 'waiting_for_tag';
+                progress.updatedAt = new Date().toISOString();
+                await writeProgress(options.paths, progress);
+                if (!reportedWaiting) {
+                    reportedWaiting = true;
+                    options.onWaitingForTag?.(progress);
+                }
+                if (options.pollAuthorization === false) {
+                    throw new WaitingForTagError(progress);
+                }
+                await waitForPoll(options.pollIntervalMs ?? 5_000, options.signal);
+            }
+        }
+        if (!capabilities.canUploadSessions) {
+            throw new Error('The Vesper host does not allow session upload for this node');
+        }
+        if (options.expectedRole && capabilities.sourceTrust !== options.expectedRole) {
+            throw new Error('Expected role ' + options.expectedRole + ' but live capabilities report ' + capabilities.sourceTrust);
+        }
+        if (capabilities.sourceTrust === 'trusted' && (!capabilities.canSearchMemory || !capabilities.canAddFact)) {
+            throw new Error('Trusted capabilities are incomplete');
+        }
+        if (capabilities.sourceTrust === 'uploader' && (capabilities.canSearchMemory || capabilities.canAddFact)) {
+            throw new Error('Uploader capabilities unexpectedly include Memory access');
+        }
+        const health = await dependencies.getHealth(transport.hostUrl, transport.fetch);
+        if (!health.archiveReady) {
+            throw new Error('Remote Memory archive is not ready');
+        }
+    }
+    finally {
+        await transport.release();
+    }
+    const releaseInstallLock = await acquireSyncLock(options.paths.lockPath);
+    let installed;
+    try {
+        await dependencies.validateRuntime(runtime);
+        const candidateTransport = await dependencies.acquireTransport({
+            paths: options.paths, hostUrl: host, requiredCompanion: runtime.companion,
+        });
+        try {
+            const [candidateHealth, candidateCapabilities] = await Promise.all([
+                dependencies.getHealth(candidateTransport.hostUrl, candidateTransport.fetch),
+                dependencies.getCapabilities(candidateTransport.hostUrl, candidateTransport.fetch),
+            ]);
+            if (!candidateHealth.archiveReady || candidateCapabilities.sourceTrust !== capabilities.sourceTrust
+                || !candidateCapabilities.canUploadSessions) {
+                throw new Error('Candidate doctor detected changed remote capabilities');
+            }
+        }
+        finally {
+            await candidateTransport.release();
+        }
+        installed = await dependencies.installManaged({
+            paths: options.paths, runtime, host, capabilities, runner,
+            postInstallDoctor: async () => {
+                await dependencies.validateRuntime(runtime);
+                const postTransport = await dependencies.acquireTransport({
+                    paths: options.paths, hostUrl: host, requiredCompanion: runtime.companion,
+                });
+                try {
+                    const [health, currentCapabilities] = await Promise.all([
+                        dependencies.getHealth(postTransport.hostUrl, postTransport.fetch),
+                        dependencies.getCapabilities(postTransport.hostUrl, postTransport.fetch),
+                    ]);
+                    if (!health.archiveReady || currentCapabilities.sourceTrust !== capabilities.sourceTrust) {
+                        throw new Error('Post-install doctor detected changed remote capabilities');
+                    }
+                }
+                finally {
+                    await postTransport.release();
+                }
+            },
+        });
+    }
+    finally {
+        await releaseInstallLock();
+    }
+    await fs.rm(options.paths.installProgressPath, { force: true });
+    // The first ordinary scan is itself the backfill queue. It is intentionally
+    // outside the local install transaction and detached so install does not wait
+    // for up to 2,000 uploads to finish.
+    await dependencies.triggerFirstSync(options.paths);
+    return { state: installed, firstSyncStarted: true };
+}
+async function waitForPoll(milliseconds, signal) {
+    if (signal?.aborted) {
+        throw signal.reason ?? new Error('Installation cancelled');
+    }
+    await new Promise((resolve, reject) => {
+        const complete = () => {
+            signal?.removeEventListener('abort', abort);
+            resolve();
+        };
+        const timer = setTimeout(complete, milliseconds);
+        const abort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+            reject(signal?.reason ?? new Error('Installation cancelled'));
+        };
+        signal?.addEventListener('abort', abort, { once: true });
+    });
+}
+async function writeProgress(paths, progress) {
+    const { writeJsonAtomic } = await import('./atomic-json.js');
+    await writeJsonAtomic(paths.installProgressPath, progress);
+}

package/dist/lock.d.ts

@@ -0,0 +1,5 @@
+export declare function acquireSyncLock(lockPath: string): Promise<() => Promise<void>>;
+export declare class SyncAlreadyRunningError extends Error {
+    readonly ownerPid: number;
+    constructor(ownerPid: number);
+}

package/dist/lock.js

@@ -0,0 +1,57 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readLock(lockPath) {
+    try {
+        return JSON.parse(await fs.readFile(lockPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw new Error(`Cannot read sync lock ${lockPath}: ${String(error)}`);
+    }
+}
+export async function acquireSyncLock(lockPath) {
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const handle = await fs.open(lockPath, 'wx');
+            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+            await handle.close();
+            return async () => {
+                const current = await readLock(lockPath);
+                if (current?.pid === process.pid) {
+                    await fs.rm(lockPath, { force: true });
+                }
+            };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                throw error;
+            }
+            const existing = await readLock(lockPath);
+            if (existing && isProcessAlive(existing.pid)) {
+                throw new SyncAlreadyRunningError(existing.pid);
+            }
+            await fs.rm(lockPath, { force: true });
+        }
+    }
+    throw new Error(`Failed to acquire sync lock: ${lockPath}`);
+}
+export class SyncAlreadyRunningError extends Error {
+    ownerPid;
+    constructor(ownerPid) {
+        super(`Another vesper-link sync is already running (pid ${ownerPid})`);
+        this.ownerPid = ownerPid;
+        this.name = 'SyncAlreadyRunningError';
+    }
+}

package/dist/managed-runtime.d.ts

@@ -0,0 +1,33 @@
+import { type CompanionInfo } from './companion.js';
+import type { LinkPaths } from './paths.js';
+import { type ProcessRunner } from './process-runner.js';
+export interface ManagedRuntime {
+    version: string;
+    runtimePath: string;
+    packagePath: string;
+    cliPath: string;
+    companion: CompanionInfo;
+}
+export interface CurrentRuntimePointer {
+    schemaVersion: 1;
+    version: string;
+    runtimePath: string;
+}
+export declare function stableLauncherSource(): string;
+export declare function validateInstallPrerequisites(options: {
+    hostUrl: string;
+    runner?: ProcessRunner;
+    platform?: NodeJS.Platform;
+    architecture?: string;
+    nodeVersion?: string;
+    resolveSourceCompanion?: () => Promise<CompanionInfo>;
+    probeCompanion?: (companion: CompanionInfo, environment: NodeJS.ProcessEnv) => Promise<void>;
+}): Promise<CompanionInfo>;
+export declare function prepareManagedRuntime(options: {
+    paths: LinkPaths;
+    companion: CompanionInfo;
+    sourcePackagePath?: string;
+    platform?: NodeJS.Platform;
+    architecture?: string;
+}): Promise<ManagedRuntime>;
+export declare function validateManagedRuntime(runtime: ManagedRuntime): Promise<void>;

package/dist/managed-runtime.js

@@ -0,0 +1,130 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { assertCompanionProtocol, resolveCompanion } from './companion.js';
+import { NodeProcessRunner } from './process-runner.js';
+async function metadata(filePath) {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+}
+function majorVersion(value) {
+    const match = /^(\d+)\./.exec(value);
+    return match ? Number(match[1]) : 0;
+}
+function protocolProbeEnvironment(environment) {
+    const blocked = new Set([
+        'vesper_ts_authkey', 'ts_authkey', 'ts_auth_key',
+        'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy',
+    ]);
+    return Object.fromEntries(Object.entries(environment).filter(([key]) => !blocked.has(key.toLowerCase())));
+}
+function npmVersionCommand(platform, environment = process.env) {
+    if (platform !== 'win32') {
+        return { command: 'npm', args: ['--version'] };
+    }
+    const commandProcessor = environment.ComSpec ?? environment.COMSPEC;
+    if (!commandProcessor) {
+        throw new Error('Windows command processor is unavailable');
+    }
+    // Node 24 rejects direct spawn of .cmd files with EINVAL. This fixed command
+    // contains no user input, so invoke npm through the Windows command processor.
+    return { command: commandProcessor, args: ['/d', '/s', '/c', 'npm.cmd --version'] };
+}
+async function copyDirectory(source, destination) {
+    await fs.cp(source, destination, { recursive: true, force: false, errorOnExist: true });
+}
+export function stableLauncherSource() {
+    return `#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const stateDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const current = JSON.parse(await fs.readFile(path.join(stateDir, 'current.json'), 'utf8'));
+if (current.schemaVersion !== 1 || typeof current.runtimePath !== 'string') {
+  throw new Error('vesper-link current runtime pointer is malformed');
+}
+const runtimeRoot = path.join(stateDir, 'runtime');
+const relative = path.relative(runtimeRoot, current.runtimePath);
+if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+  throw new Error('vesper-link current runtime escaped the managed runtime root');
+}
+await import(pathToFileURL(path.join(current.runtimePath, 'package', 'dist', 'cli.js')).href);
+`;
+}
+export async function validateInstallPrerequisites(options) {
+    // URL validation is intentionally delegated to the same strict parser used by config.
+    const { normalizeHost } = await import('./config.js');
+    normalizeHost(options.hostUrl);
+    const platform = options.platform ?? process.platform;
+    const architecture = options.architecture ?? process.arch;
+    if (!((platform === 'win32' || platform === 'linux') && architecture === 'x64')) {
+        throw new Error(`Unsupported vesper-link platform: ${platform}-${architecture}`);
+    }
+    const nodeVersion = options.nodeVersion ?? process.versions.node;
+    if (majorVersion(nodeVersion) < 20) {
+        throw new Error(`Node.js 20 or newer is required; found ${nodeVersion}`);
+    }
+    const runner = options.runner ?? new NodeProcessRunner();
+    const npmProbe = npmVersionCommand(platform);
+    const npm = await runner.run(npmProbe.command, npmProbe.args);
+    if (npm.code !== 0 || majorVersion(npm.stdout.trim()) < 9) {
+        throw new Error(`A working npm 9 or newer is required: ${npm.stderr.trim() || npm.stdout.trim()}`);
+    }
+    const companion = await (options.resolveSourceCompanion ?? (() => resolveCompanion(platform, architecture)))();
+    await (options.probeCompanion ?? assertCompanionProtocol)(companion, protocolProbeEnvironment(process.env));
+    return companion;
+}
+export async function prepareManagedRuntime(options) {
+    const sourcePackagePath = options.sourcePackagePath
+        ?? path.dirname(fileURLToPath(new URL('../package.json', import.meta.url)));
+    const packageMetadata = await metadata(path.join(sourcePackagePath, 'package.json'));
+    if (packageMetadata.name !== '@msvesper/vesper-link' || typeof packageMetadata.version !== 'string') {
+        throw new Error('Cannot identify the source vesper-link package');
+    }
+    const version = packageMetadata.version;
+    const runtimePath = path.join(options.paths.runtimeDir, version);
+    const packagePath = path.join(runtimePath, 'package');
+    const cliPath = path.join(packagePath, 'dist', 'cli.js');
+    const existingMetadata = await metadata(path.join(packagePath, 'package.json')).catch((error) => {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    });
+    if (!existingMetadata) {
+        await fs.mkdir(options.paths.runtimeDir, { recursive: true });
+        const temporary = path.join(options.paths.runtimeDir, `.${version}.${process.pid}.${Date.now()}.candidate`);
+        try {
+            await fs.mkdir(path.join(temporary, 'package'), { recursive: true });
+            await Promise.all([
+                copyDirectory(path.join(sourcePackagePath, 'dist'), path.join(temporary, 'package', 'dist')),
+                fs.copyFile(path.join(sourcePackagePath, 'package.json'), path.join(temporary, 'package', 'package.json')),
+            ]);
+            const companionPackagePath = path.dirname(path.dirname(options.companion.executable));
+            const destination = path.join(temporary, 'package', 'node_modules', ...options.companion.packageName.split('/'));
+            await fs.mkdir(path.dirname(destination), { recursive: true });
+            await copyDirectory(companionPackagePath, destination);
+            await fs.rename(temporary, runtimePath);
+        }
+        finally {
+            await fs.rm(temporary, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+    else if (existingMetadata.name !== '@msvesper/vesper-link' || existingMetadata.version !== version) {
+        throw new Error(`Managed runtime ${runtimePath} contains a different package`);
+    }
+    await fs.access(cliPath);
+    const candidatePackageJson = path.join(packagePath, 'package.json');
+    const candidateRequire = createRequire(candidatePackageJson);
+    const companion = await resolveCompanion(options.platform ?? process.platform, options.architecture ?? process.arch, (specifier) => candidateRequire.resolve(specifier), candidatePackageJson);
+    await assertCompanionProtocol(companion, protocolProbeEnvironment(process.env));
+    return { version, runtimePath, packagePath, cliPath, companion };
+}
+export async function validateManagedRuntime(runtime) {
+    const packageMetadata = await metadata(path.join(runtime.packagePath, 'package.json'));
+    if (packageMetadata.name !== '@msvesper/vesper-link' || packageMetadata.version !== runtime.version) {
+        throw new Error('Managed runtime package identity changed after preparation');
+    }
+    await fs.access(runtime.cliPath);
+    await assertCompanionProtocol(runtime.companion, protocolProbeEnvironment(process.env));
+}

package/dist/memory-mcp.d.ts

@@ -0,0 +1,27 @@
+import { addFact, searchMemory } from './http-client.js';
+import type { LinkPaths } from './paths.js';
+import { type RemoteTransport } from './transport.js';
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method: string;
+    params?: unknown;
+}
+interface McpDependencies {
+    acquireTransport(paths: LinkPaths, hostUrl: string): Promise<RemoteTransport>;
+    search(hostUrl: string, query: string, limit: number, fetchImpl: typeof fetch): ReturnType<typeof searchMemory>;
+    add(hostUrl: string, fact: string, fetchImpl: typeof fetch): ReturnType<typeof addFact>;
+}
+export declare class MemoryMcpSession {
+    private readonly paths;
+    private readonly dependencies;
+    private transport;
+    private hostUrl;
+    constructor(paths: LinkPaths, dependencies?: McpDependencies);
+    handle(request: JsonRpcRequest): Promise<unknown>;
+    close(): Promise<void>;
+    private remote;
+    private callTool;
+}
+export declare function runMemoryMcp(paths: LinkPaths): Promise<void>;
+export {};

package/dist/memory-mcp.js

@@ -0,0 +1,155 @@
+import * as readline from 'node:readline';
+import { readConfig } from './config.js';
+import { addFact, searchMemory } from './http-client.js';
+import { readInstalledState } from './installation.js';
+import { acquireRemoteTransport } from './transport.js';
+import { VESPER_LINK_VERSION } from './version.js';
+const MCP_PROTOCOL_VERSION = '2025-03-26';
+const defaultDependencies = {
+    acquireTransport: (paths, hostUrl) => acquireRemoteTransport({ paths, hostUrl }),
+    search: searchMemory,
+    add: addFact,
+};
+function objectValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function tools() {
+    return [
+        {
+            name: 'search_memory',
+            description: 'Search the canonical Vesper Memory for prior preferences, decisions, facts, and context.',
+            inputSchema: {
+                type: 'object', additionalProperties: false, required: ['query'],
+                properties: {
+                    query: { type: 'string', description: 'What to search for.' },
+                    limit: { type: 'integer', minimum: 1, maximum: 10, default: 5 },
+                },
+            },
+        },
+        {
+            name: 'add_fact',
+            description: 'Save one fact to Vesper Memory only when the user explicitly asks to remember it.',
+            inputSchema: {
+                type: 'object', additionalProperties: false, required: ['fact'],
+                properties: { fact: { type: 'string', description: 'The fact the user explicitly asked to remember.' } },
+            },
+        },
+    ];
+}
+export class MemoryMcpSession {
+    paths;
+    dependencies;
+    transport;
+    hostUrl;
+    constructor(paths, dependencies = defaultDependencies) {
+        this.paths = paths;
+        this.dependencies = dependencies;
+    }
+    async handle(request) {
+        if (request.method === 'initialize') {
+            return {
+                protocolVersion: MCP_PROTOCOL_VERSION, capabilities: { tools: { listChanged: false } },
+                serverInfo: { name: 'vesper-memory', version: VESPER_LINK_VERSION },
+            };
+        }
+        if (request.method === 'ping') {
+            return {};
+        }
+        if (request.method === 'tools/list') {
+            return { tools: tools() };
+        }
+        if (request.method === 'tools/call') {
+            return this.callTool(objectValue(request.params));
+        }
+        throw Object.assign(new Error(`Method not found: ${request.method}`), { rpcCode: -32601 });
+    }
+    async close() {
+        const transport = this.transport;
+        this.transport = undefined;
+        if (transport) {
+            await transport.release();
+        }
+    }
+    async remote() {
+        if ((await readInstalledState(this.paths))?.paused) {
+            await this.close();
+            throw new Error('vesper-link is paused; run resume before using Remote Memory');
+        }
+        if (!this.transport) {
+            const config = await readConfig(this.paths.configPath);
+            this.hostUrl = config.host;
+            this.transport = await this.dependencies.acquireTransport(this.paths, config.host);
+        }
+        return this.transport;
+    }
+    async callTool(params) {
+        const name = params.name;
+        const args = objectValue(params.arguments);
+        if (name === 'search_memory') {
+            const query = typeof args.query === 'string' ? args.query.trim() : '';
+            const limit = args.limit === undefined ? 5 : args.limit;
+            if (!query || !Number.isInteger(limit) || limit < 1 || limit > 10) {
+                throw Object.assign(new Error('search_memory requires a non-empty query and limit from 1 to 10'), { rpcCode: -32602 });
+            }
+            const transport = await this.remote();
+            const hostUrl = this.hostUrl;
+            const response = await this.dependencies.search(hostUrl, query, limit, transport.fetch);
+            return { content: [{ type: 'text', text: JSON.stringify(response.results) }] };
+        }
+        if (name === 'add_fact') {
+            const fact = typeof args.fact === 'string' ? args.fact.trim() : '';
+            if (!fact) {
+                throw Object.assign(new Error('add_fact requires a non-empty fact'), { rpcCode: -32602 });
+            }
+            const transport = await this.remote();
+            const hostUrl = this.hostUrl;
+            const response = await this.dependencies.add(hostUrl, fact, transport.fetch);
+            return {
+                content: [{ type: 'text', text: response.status === 'written'
+                            ? `Remembered (${response.schemaType}, ${response.id}).`
+                            : `Already present (${response.schemaType}, ${response.id}).` }],
+            };
+        }
+        throw Object.assign(new Error(`Unknown tool: ${String(name)}`), { rpcCode: -32602 });
+    }
+}
+export async function runMemoryMcp(paths) {
+    const session = new MemoryMcpSession(paths);
+    const input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+    try {
+        for await (const line of input) {
+            if (!line.trim()) {
+                continue;
+            }
+            let request;
+            try {
+                request = JSON.parse(line);
+            }
+            catch {
+                process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } })}\n`);
+                continue;
+            }
+            if (request.jsonrpc !== '2.0' || typeof request.method !== 'string') {
+                process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id ?? null, error: { code: -32600, message: 'Invalid request' } })}\n`);
+                continue;
+            }
+            if (request.id === undefined) {
+                continue;
+            }
+            try {
+                const result = await session.handle(request);
+                process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, result })}\n`);
+            }
+            catch (error) {
+                const code = typeof error.rpcCode === 'number'
+                    ? error.rpcCode : -32000;
+                process.stdout.write(`${JSON.stringify({
+                    jsonrpc: '2.0', id: request.id, error: { code, message: error instanceof Error ? error.message : String(error) },
+                })}\n`);
+            }
+        }
+    }
+    finally {
+        await session.close();
+    }
+}

package/dist/operational-log.d.ts

@@ -0,0 +1,17 @@
+export interface SyncLogRecord {
+    timestamp: string;
+    event: 'sync_completed' | 'sync_failed';
+    discovered?: number;
+    queued?: number;
+    uploaded?: number;
+    unchanged?: number;
+    failed?: number;
+    collectorIssueCount?: number;
+    stoppedBy?: string;
+    errorCode?: string;
+    errorType?: string;
+}
+export declare function appendSyncLog(logsDir: string, record: SyncLogRecord, options?: {
+    maxBytes?: number;
+    fileCount?: number;
+}): Promise<void>;