@zokizuan/satori-mcp 6.2.0 → 6.3.0

package/dist/index.js

@@ -8,6 +8,9 @@ const bootstrapKeepAlive = setInterval(() => {
     // The server owns steady-state lifetime after startMcpServerFromEnv resolves.
 }, 60 * 60 * 1000);
 function resolveRunMode() {
+    if (process.env.SATORI_RUN_MODE === "host") {
+        return "host";
+    }
     if (process.env.SATORI_RUN_MODE === "cli") {
         return "cli";
     }
@@ -60,6 +63,11 @@ async function handleShutdown(reason) {
 }
 async function main() {
     const runMode = resolveRunMode();
+    if (runMode === "host") {
+        const { startSharedRuntimeHostFromEnv } = await import("./server/shared-runtime-host.js");
+        activeServer = await startSharedRuntimeHostFromEnv();
+        return;
+    }
     const originalStdoutWrite = process.stdout.write.bind(process.stdout);
     const protocolStdout = createProtocolStdout(originalStdoutWrite);
     const { installBootstrapStdioSafety } = await import("./server/bootstrap-stdio.js");
@@ -86,14 +94,33 @@ process.on("SIGINT", () => {
 process.on("SIGTERM", () => {
     void handleShutdown("SIGTERM");
 });
-process.stdin.once("end", () => {
-    void handleShutdown("STDIN_EOF");
-});
+if (resolveRunMode() !== "host") {
+    process.stdin.once("end", () => {
+        void handleShutdown("STDIN_EOF");
+    });
+}
 main().then(() => {
     clearInterval(bootstrapKeepAlive);
-}).catch((error) => {
+}).catch(async (error) => {
     clearInterval(bootstrapKeepAlive);
     const message = error instanceof Error ? error.message : String(error);
+    if (resolveRunMode() === "host" && process.env.SATORI_SHARED_RUNTIME_ERROR_PATH) {
+        try {
+            const fs = await import("node:fs");
+            const boundedMessage = message.slice(0, 4096);
+            const errorPath = process.env.SATORI_SHARED_RUNTIME_ERROR_PATH;
+            const temporaryPath = `${errorPath}.${process.pid}.tmp`;
+            fs.writeFileSync(temporaryPath, `${JSON.stringify({
+                formatVersion: 1,
+                recordedAt: new Date().toISOString(),
+                message: boundedMessage,
+            })}\n`, { encoding: "utf8", mode: 0o600 });
+            fs.renameSync(temporaryPath, errorPath);
+        }
+        catch {
+            // Startup diagnostics are best-effort and must not mask the owner failure.
+        }
+    }
     if (message.includes("E_PROTOCOL_FAILURE")) {
         console.error(`E_PROTOCOL_FAILURE ${message}`);
     }

package/dist/server/provider-runtime.d.ts

@@ -30,6 +30,7 @@ export declare class ProviderRuntime {
     private readonly mutationLeaseCoordinator;
     private readonly now;
     private readonly searchContinuationCoordinator;
+    private readonly onLifecycleActivityChanged?;
     private readonly generationProofCoordinator;
     private embeddingRuntimePromise;
     private vectorRuntimePromise;
@@ -48,6 +49,7 @@ export declare class ProviderRuntime {
         runtimeOwnerGate?: RuntimeOwnerMutationGate | null;
         mutationLeaseCoordinator?: MutationLeaseCoordinator;
         searchContinuationCoordinator?: SearchContinuationCoordinator;
+        onLifecycleActivityChanged?: () => void;
         now?: () => number;
     });
     validate(operation: ProviderBackedOperation): MissingProviderConfigIssue | null;
@@ -58,6 +60,7 @@ export declare class ProviderRuntime {
     private createVectorBackend;
     private createReranker;
     private createSyncCompletionHook;
+    getActiveLifecycleOperationCount(): number;
     shutdown(): Promise<void>;
 }
 //# sourceMappingURL=provider-runtime.d.ts.map

package/dist/server/provider-runtime.js

@@ -1,9 +1,12 @@
 import { Context, createGenerationProofCoordinator, Embedding, MilvusVectorDatabase, VoyageAIReranker, } from "@zokizuan/satori-core";
+import fs from "node:fs";
+import { createRequire } from "node:module";
 import { SearchContinuationCoordinator, ToolHandlers, } from "../core/handlers.js";
 import { MutationLeaseCoordinator } from "../core/mutation-lease.js";
 import { SyncManager } from "../core/sync.js";
 import { resolveConfiguredEmbeddingDimension, } from "../config.js";
 import { createEmbeddingInstance, logEmbeddingProviderInfo } from "../embedding.js";
+const requireFromProviderRuntime = createRequire(import.meta.url);
 export async function startProviderSyncLifecycle(syncManager, options) {
     // Incremental synchronization may embed changed files, so the
     // metadata-only vector runtime must never own periodic or watcher work.
@@ -133,6 +136,7 @@ export class ProviderRuntime {
         this.mutationLeaseCoordinator = args.mutationLeaseCoordinator || new MutationLeaseCoordinator();
         this.searchContinuationCoordinator = args.searchContinuationCoordinator
             ?? new SearchContinuationCoordinator();
+        this.onLifecycleActivityChanged = args.onLifecycleActivityChanged;
         this.now = args.now || (() => Date.now());
     }
     validate(operation) {
@@ -214,6 +218,7 @@ export class ProviderRuntime {
                 watchDebounceMs: this.watchDebounceMs,
                 onSyncCompleted: this.createSyncCompletionHook(context),
                 mutationLeaseCoordinator: this.mutationLeaseCoordinator,
+                onLifecycleActivityChanged: this.onLifecycleActivityChanged,
             });
             const reranker = this.createReranker(bootstrap);
             if (reranker) {
@@ -300,7 +305,20 @@ export class ProviderRuntime {
         switch (bootstrap.vectorBackend.kind) {
             case 'lancedb': {
                 const moduleSpecifier = '@zokizuan/satori-core/lancedb';
-                const { LanceDbVectorDatabase } = await import(moduleSpecifier);
+                // Core deliberately publishes this native boundary as CommonJS.
+                // Requiring it lazily avoids Node's synthetic ESM named-export
+                // snapshot, which can observe getter-backed exports as undefined
+                // in a detached compiled host.
+                let LanceDbVectorDatabase;
+                try {
+                    const resolvedModule = fs.realpathSync(requireFromProviderRuntime.resolve(moduleSpecifier));
+                    const requireFromResolvedModule = createRequire(resolvedModule);
+                    ({ LanceDbVectorDatabase } = requireFromResolvedModule(resolvedModule));
+                }
+                catch (error) {
+                    throw new Error(`${error instanceof Error ? error.message : String(error)} `
+                        + `(resolved through ${moduleSpecifier})`);
+                }
                 return new LanceDbVectorDatabase({
                     databasePath: bootstrap.vectorBackend.databasePath,
                 });
@@ -331,12 +349,14 @@ export class ProviderRuntime {
             }
         };
     }
+    getActiveLifecycleOperationCount() {
+        return this.activeContexts.reduce((count, toolContext) => count + toolContext.syncManager.getActiveLifecycleOperationCount(), 0);
+    }
     async shutdown() {
         await Promise.all([
             Promise.all(this.activeContexts.map(async (toolContext) => {
                 toolContext.toolHandlers.releaseSearchContinuationOwnership();
-                toolContext.syncManager.stopBackgroundSync();
-                await toolContext.syncManager.stopWatcherMode();
+                await toolContext.syncManager.stopAndDrainLifecycle();
                 await toolContext.context.getVectorStore().close?.();
             })),
             Promise.all([...this.activeEmbeddings].map((embedding) => embedding.close())),

package/dist/server/shared-runtime-client.d.ts

@@ -0,0 +1,11 @@
+import type { Readable, Writable } from "node:stream";
+export type SharedRuntimeClientOptions = Readonly<{
+    runtimeEntry: string;
+    env: NodeJS.ProcessEnv;
+    stdin?: Readable;
+    stdout?: Writable;
+    stderr?: Writable;
+    attachTimeoutMs?: number;
+}>;
+export declare function runSharedRuntimeClient(options: SharedRuntimeClientOptions): Promise<void>;
+//# sourceMappingURL=shared-runtime-client.d.ts.map

package/dist/server/shared-runtime-client.js

@@ -0,0 +1,360 @@
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import { SHARED_RUNTIME_ATTACH_TIMEOUT_MS, SHARED_RUNTIME_HANDSHAKE_MAX_BYTES, SHARED_RUNTIME_PROTOCOL_VERSION, buildSharedRuntimeIdentity, isSharedOfflineRuntimeEligible, resolveSharedRuntimePaths, } from "./shared-runtime-identity.js";
+import { acquireLifecycleLock, isLinuxProcessIdentityLive, metadataMatchesIdentity, readHostMetadata, removeOwnedLifecycleState, } from "./shared-runtime-lifecycle.js";
+class SharedRuntimeAttachError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "SharedRuntimeAttachError";
+    }
+}
+function wait(delayMs) {
+    return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+function connectSocket(socketPath, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection({ path: socketPath });
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error(`Timed out connecting to Satori shared runtime at '${socketPath}'.`));
+        }, timeoutMs);
+        socket.once("connect", () => {
+            clearTimeout(timer);
+            resolve(socket);
+        });
+        socket.once("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+async function attach(socketPath, identity, timeoutMs, expectedHost) {
+    const socket = await connectSocket(socketPath, timeoutMs);
+    socket.pause();
+    const launcherNonce = crypto.randomBytes(24).toString("hex");
+    const request = Object.freeze({
+        type: "satori-shared-runtime-attach",
+        protocolVersion: SHARED_RUNTIME_PROTOCOL_VERSION,
+        sharedRuntimeIdentityHash: identity.hash,
+        installedRuntimeRoot: identity.installedRuntimeRoot,
+        mcpVersion: identity.mcpVersion,
+        launcherNonce,
+    });
+    socket.write(`${JSON.stringify(request)}\n`);
+    let response;
+    try {
+        response = await new Promise((resolve, reject) => {
+            let buffered = Buffer.alloc(0);
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error("Timed out waiting for Satori shared runtime handshake."));
+            }, timeoutMs);
+            const cleanup = () => {
+                clearTimeout(timer);
+                socket.off("data", onData);
+                socket.off("error", onError);
+                socket.off("close", onClose);
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            const onClose = () => {
+                cleanup();
+                reject(new Error("Satori shared runtime closed before completing the handshake."));
+            };
+            const onData = (chunk) => {
+                if (buffered.length + chunk.length > SHARED_RUNTIME_HANDSHAKE_MAX_BYTES) {
+                    cleanup();
+                    reject(new Error("Satori shared runtime handshake response exceeded its byte limit."));
+                    return;
+                }
+                buffered = buffered.length === 0
+                    ? Buffer.from(chunk)
+                    : Buffer.concat([buffered, chunk]);
+                const newline = buffered.indexOf(0x0a);
+                if (newline < 0)
+                    return;
+                const trailing = buffered.subarray(newline + 1);
+                try {
+                    const parsed = JSON.parse(buffered.subarray(0, newline).toString("utf8"));
+                    cleanup();
+                    if (trailing.length > 0)
+                        socket.unshift(trailing);
+                    resolve(parsed);
+                }
+                catch (error) {
+                    cleanup();
+                    reject(error);
+                }
+            };
+            socket.on("data", onData);
+            socket.once("error", onError);
+            socket.once("close", onClose);
+            socket.resume();
+        });
+    }
+    catch (error) {
+        socket.destroy();
+        throw error;
+    }
+    if (response.type !== "satori-shared-runtime-attached"
+        || response.protocolVersion !== SHARED_RUNTIME_PROTOCOL_VERSION
+        || response.sharedRuntimeIdentityHash !== identity.hash
+        || response.installedRuntimeRoot !== identity.installedRuntimeRoot
+        || response.mcpVersion !== identity.mcpVersion) {
+        socket.destroy();
+        throw new SharedRuntimeAttachError(response.error || "Satori shared runtime returned an incompatible handshake.", "EHOSTREJECTED");
+    }
+    if (response.accepted !== true) {
+        socket.destroy();
+        const message = response.error || "Satori shared runtime rejected the launcher identity.";
+        throw new SharedRuntimeAttachError(message, message.includes("not accepting sessions")
+            ? "EHOSTUNREADY"
+            : "EHOSTREJECTED");
+    }
+    if (response.launcherNonce !== launcherNonce
+        || (expectedHost !== undefined && (response.hostPid !== expectedHost.hostPid
+            || response.bootId !== expectedHost.bootId
+            || response.processStartTime !== expectedHost.processStartTime))) {
+        socket.destroy();
+        throw new SharedRuntimeAttachError("Satori shared runtime live process identity does not match its metadata.", "EHOSTREJECTED");
+    }
+    socket.pause();
+    return socket;
+}
+async function attachFromMetadata(identity, metadataPath, timeoutMs) {
+    const metadata = readHostMetadata(metadataPath);
+    if (!metadata)
+        return null;
+    if (!metadataMatchesIdentity(metadata, identity)) {
+        throw new Error("Satori shared runtime metadata belongs to an incompatible runtime.");
+    }
+    if (!isLinuxProcessIdentityLive({
+        pid: metadata.hostPid,
+        bootId: metadata.bootId,
+        startTime: metadata.processStartTime,
+    })) {
+        return null;
+    }
+    return attach(metadata.socketPath, identity, timeoutMs, metadata);
+}
+function isTransientAttachError(error) {
+    const code = error.code;
+    return code === "EHOSTUNREADY"
+        || code === "ECONNREFUSED"
+        || code === "ENOENT"
+        || code === "ECONNRESET";
+}
+async function waitForHostTransition(identity, metadataPath, socketPath, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError = null;
+    while (Date.now() < deadline) {
+        const metadata = readHostMetadata(metadataPath);
+        if (!metadata) {
+            if (!fs.existsSync(socketPath))
+                return null;
+            try {
+                const unexpected = await attach(socketPath, identity, Math.min(500, Math.max(1, deadline - Date.now())));
+                unexpected.destroy();
+                throw new Error("Satori shared runtime accepted a session before publishing lifecycle metadata.");
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === "ECONNREFUSED" || code === "ENOENT" || code === "ECONNRESET") {
+                    return null;
+                }
+                if (code !== "EHOSTUNREADY")
+                    throw error;
+                lastError = error;
+            }
+        }
+        else {
+            if (!metadataMatchesIdentity(metadata, identity)) {
+                throw new Error("Satori shared runtime metadata belongs to an incompatible runtime.");
+            }
+            if (!isLinuxProcessIdentityLive({
+                pid: metadata.hostPid,
+                bootId: metadata.bootId,
+                startTime: metadata.processStartTime,
+            })) {
+                return null;
+            }
+            try {
+                return await attach(metadata.socketPath, identity, Math.min(500, Math.max(1, deadline - Date.now())), metadata);
+            }
+            catch (error) {
+                if (!isTransientAttachError(error))
+                    throw error;
+                lastError = error;
+            }
+        }
+        await wait(25);
+    }
+    throw new Error(`Timed out waiting for the existing Satori shared runtime to finish starting or stopping.`
+        + (lastError ? ` ${lastError instanceof Error ? lastError.message : String(lastError)}` : ""));
+}
+function startDetachedHost(runtimeEntry, identity, env) {
+    const child = spawn(process.execPath, [runtimeEntry], {
+        detached: true,
+        stdio: "ignore",
+        env: {
+            ...env,
+            SATORI_RUN_MODE: "host",
+            SATORI_SHARED_RUNTIME_EXPECTED_HASH: identity.hash,
+            SATORI_SHARED_RUNTIME_ENTRY: runtimeEntry,
+            SATORI_SHARED_RUNTIME_ERROR_PATH: resolveSharedRuntimePaths(identity, env).errorPath,
+        },
+    });
+    child.unref();
+}
+async function connectOrStart(options) {
+    const timeoutMs = options.attachTimeoutMs ?? SHARED_RUNTIME_ATTACH_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    const identity = buildSharedRuntimeIdentity(options.runtimeEntry, options.env);
+    const paths = resolveSharedRuntimePaths(identity, options.env);
+    const remainingTime = () => Math.max(1, deadline - Date.now());
+    for (;;) {
+        let existing;
+        try {
+            existing = await attachFromMetadata(identity, paths.metadataPath, Math.min(500, remainingTime()));
+        }
+        catch (error) {
+            if (!isTransientAttachError(error))
+                throw error;
+            existing = await waitForHostTransition(identity, paths.metadataPath, paths.socketPath, remainingTime());
+        }
+        if (existing)
+            return existing;
+        if (Date.now() >= deadline) {
+            throw new Error("Timed out attaching to the Satori shared runtime.");
+        }
+        const lifecycleLock = await acquireLifecycleLock(paths.lockPath, remainingTime());
+        try {
+            let joined;
+            try {
+                joined = await attachFromMetadata(identity, paths.metadataPath, Math.min(500, remainingTime()));
+            }
+            catch (error) {
+                if (!isTransientAttachError(error))
+                    throw error;
+                // The existing host may already be waiting for this same lock
+                // to finish shutdown. Release it before waiting for the
+                // lifecycle transition, then re-enter through the outer
+                // metadata/handshake proof.
+                continue;
+            }
+            if (joined)
+                return joined;
+            const stale = readHostMetadata(paths.metadataPath);
+            if (fs.existsSync(paths.metadataPath) && !stale) {
+                throw new Error(`Satori shared runtime metadata is malformed at '${paths.metadataPath}'. `
+                    + "Run `satori doctor --verbose` before retrying.");
+            }
+            if (stale && !isLinuxProcessIdentityLive({
+                pid: stale.hostPid,
+                bootId: stale.bootId,
+                startTime: stale.processStartTime,
+            })) {
+                removeOwnedLifecycleState(paths, stale);
+            }
+            if (fs.existsSync(paths.socketPath)) {
+                try {
+                    return await attach(paths.socketPath, identity, Math.min(500, remainingTime()));
+                }
+                catch (error) {
+                    const code = error.code;
+                    if (code === "EHOSTUNREADY") {
+                        // As above, never wait for shutdown while holding its
+                        // lifecycle lock.
+                        continue;
+                    }
+                    if (code !== "ECONNREFUSED" && code !== "ENOENT") {
+                        throw error;
+                    }
+                    if (fs.existsSync(paths.socketPath)) {
+                        const socket = fs.lstatSync(paths.socketPath);
+                        if (!socket.isSocket()) {
+                            throw new Error(`Shared runtime path '${paths.socketPath}' is not a Unix-domain socket.`);
+                        }
+                        fs.unlinkSync(paths.socketPath);
+                    }
+                }
+            }
+            try {
+                fs.unlinkSync(paths.errorPath);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            startDetachedHost(options.runtimeEntry, identity, options.env);
+            let lastError = null;
+            while (Date.now() < deadline) {
+                try {
+                    const connected = await attachFromMetadata(identity, paths.metadataPath, Math.min(500, remainingTime()));
+                    if (connected)
+                        return connected;
+                }
+                catch (error) {
+                    lastError = error;
+                }
+                await wait(25);
+            }
+            let startupDetail = "";
+            try {
+                const errorRecord = JSON.parse(fs.readFileSync(paths.errorPath, "utf8"));
+                if (typeof errorRecord.message === "string") {
+                    startupDetail = ` Host startup failed: ${errorRecord.message}`;
+                }
+            }
+            catch {
+                // No bounded host diagnostic was published.
+            }
+            throw new Error(`Satori shared runtime did not become ready within ${timeoutMs}ms.`
+                + startupDetail
+                + (lastError
+                    ? ` ${lastError instanceof Error ? lastError.message : String(lastError)}`
+                    : ""));
+        }
+        finally {
+            lifecycleLock.release();
+        }
+    }
+}
+export async function runSharedRuntimeClient(options) {
+    if (!isSharedOfflineRuntimeEligible(options.env)) {
+        throw new Error("Shared runtime client was invoked for an ineligible configuration.");
+    }
+    const input = options.stdin ?? process.stdin;
+    const output = options.stdout ?? process.stdout;
+    const socket = await connectOrStart(options);
+    await new Promise((resolve, reject) => {
+        let finished = false;
+        const finish = (error) => {
+            if (finished)
+                return;
+            finished = true;
+            input.unpipe(socket);
+            socket.unpipe(output);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        input.pipe(socket);
+        socket.pipe(output);
+        input.once("end", () => socket.end());
+        input.once("error", (error) => {
+            socket.destroy();
+            finish(error);
+        });
+        socket.once("error", finish);
+        socket.once("close", () => finish());
+        socket.resume();
+    });
+}
+//# sourceMappingURL=shared-runtime-client.js.map

package/dist/server/shared-runtime-host.d.ts

@@ -0,0 +1,24 @@
+import { type SharedRuntimeIdentity, type SharedRuntimePaths } from "./shared-runtime-identity.js";
+import { SharedRuntimeHost } from "./shared-runtime.js";
+export declare class SharedRuntimeSocketHost {
+    private readonly runtimeHost;
+    private readonly identity;
+    private readonly paths;
+    private readonly idleMs;
+    private readonly server;
+    private readonly sessions;
+    private readonly ownershipToken;
+    private metadata;
+    private idleTimer;
+    private closing;
+    private readonly unsubscribeActivity;
+    constructor(runtimeHost: SharedRuntimeHost, identity: SharedRuntimeIdentity, paths: SharedRuntimePaths, idleMs?: number);
+    start(): Promise<void>;
+    private acceptHandshake;
+    private attachSession;
+    private cancelIdleShutdown;
+    private scheduleIdleShutdown;
+    shutdown(): Promise<void>;
+}
+export declare function startSharedRuntimeHostFromEnv(): Promise<SharedRuntimeSocketHost>;
+//# sourceMappingURL=shared-runtime-host.d.ts.map