@msvesper/vesper-link 0.1.5 → 0.1.6

package/dist/installer.d.ts

@@ -39,6 +39,7 @@ export interface InstallerDependencies {
         requiredCompanion?: ManagedRuntime['companion'];
         bootstrapAuthKey?: string;
         failIfLoginRequired?: boolean;
+        replaceExistingTransport?: boolean;
     }): Promise<RemoteTransport>;
     getHealth: typeof getHealth;
     getCapabilities: typeof getCapabilities;

package/dist/installer.js

@@ -85,6 +85,7 @@ export async function installVesperLink(options) {
             requiredCompanion: runtime.companion,
             bootstrapAuthKey,
             failIfLoginRequired: options.requireExistingIdentity,
+            replaceExistingTransport: options.requireExistingIdentity,
             onNeedsLogin: (url) => {
                 options.onNeedsLogin?.(url);
             },

package/dist/transport.d.ts

@@ -21,8 +21,13 @@ export interface AcquireTransportOptions {
     spawnChild?: (executable: string, args: string[], env: NodeJS.ProcessEnv) => ChildProcessWithoutNullStreams;
     onNeedsLogin?: (url: string) => void;
     failIfLoginRequired?: boolean;
+    replaceExistingTransport?: boolean;
     bootstrapAuthKey?: string;
     startTimeoutMs?: number;
+    handoffTimeoutMs?: number;
+    terminateProcess?: (pid: number) => void;
+    isProcessAlive?: (pid: number) => boolean;
+    restartPriorTransport?: (executable: string, args: string[], env: NodeJS.ProcessEnv) => void;
 }
 export declare function consumeBootstrapAuthKey(explicitAuthKey: string | undefined, environment?: NodeJS.ProcessEnv): string | undefined;
 export declare function acquireRemoteTransport(options: AcquireTransportOptions): Promise<RemoteTransport>;

package/dist/transport.js

@@ -2,6 +2,7 @@ import * as fs from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { isIPv4 } from 'node:net';
 import * as http from 'node:http';
+import * as path from 'node:path';
 import { Readable } from 'node:stream';
 import { assertCompanionProtocol, VESPER_NET_PROTOCOL_VERSION, resolveCompanion } from './companion.js';
 const START_TIMEOUT_MS = 10 * 60_000;
@@ -9,7 +10,9 @@ const ATTACH_TIMEOUT_MS = 2_000;
 const POLL_INTERVAL_MS = 100;
 const MAX_CONTROL_BYTES = 64 * 1024;
 const LOCAL_SECRET_HEADER = 'x-vesper-transport-secret';
+const EXPECTED_OWNER_PID_HEADER = 'x-vesper-expected-owner-pid';
 const KEEPALIVE_MS = 10_000;
+const HANDOFF_TIMEOUT_MS = 10_000;
 const PROXY_ENVIRONMENT_KEYS = new Set([
     'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy',
 ]);
@@ -17,6 +20,8 @@ const AUTH_KEY_ENVIRONMENT_KEYS = new Set([
     'vesper_ts_authkey', 'ts_authkey', 'ts_auth_key',
 ]);
 const AUTH_KEY_PATTERN = /^tskey-auth-[A-Za-z0-9_-]{16,512}$/;
+const TRANSPORT_SECRET_ENVIRONMENT_KEY = 'VESPER_TRANSPORT_SECRET';
+const TRANSPORT_SECRET_PATTERN = /^[0-9a-fA-F]{64}$/;
 function directLoopbackFetch(input, init = {}) {
     const inputRequest = input instanceof Request ? input : undefined;
     const url = new URL(inputRequest?.url ?? input.toString());
@@ -140,7 +145,16 @@ async function readRendezvous(filePath) {
         throw error;
     }
 }
-async function attach(paths, hostUrl, fetchImpl, requiredExecutablePath) {
+function validateLease(candidate, hostUrl) {
+    if (candidate.protocolVersion !== VESPER_NET_PROTOCOL_VERSION || candidate.hostUrl !== hostUrl
+        || typeof candidate.tailnetName !== 'string' || !candidate.tailnetName
+        || typeof candidate.nodeName !== 'string' || !candidate.nodeName
+        || typeof candidate.ipv4 !== 'string' || !isIPv4(candidate.ipv4)
+        || typeof candidate.executablePath !== 'string' || !candidate.executablePath) {
+        throw new Error('Running vesper-net transport targets a different host or protocol');
+    }
+}
+async function inspectTransport(paths, hostUrl, fetchImpl, renewLease) {
     let rendezvous;
     try {
         rendezvous = await readRendezvous(paths.transportRendezvousPath);
@@ -154,54 +168,49 @@ async function attach(paths, hostUrl, fetchImpl, requiredExecutablePath) {
     if (!rendezvous || !isAlive(rendezvous.pid)) {
         return null;
     }
-    const requestLease = async (inspectOnly) => {
-        try {
-            const operation = inspectOnly ? 'identity' : 'lease';
-            return await fetchImpl(`${rendezvous.endpoint}/__vesper_transport/${operation}`, {
-                headers: { [LOCAL_SECRET_HEADER]: rendezvous.secret },
-                signal: AbortSignal.timeout(ATTACH_TIMEOUT_MS),
-            });
-        }
-        catch {
-            return null;
-        }
-    };
-    const readLease = async (inspectOnly) => {
-        const response = await requestLease(inspectOnly);
-        if (!response?.ok) {
-            return null;
-        }
-        return await response.json();
-    };
-    let lease = await readLease(requiredExecutablePath !== undefined);
-    if (!lease) {
+    let response;
+    try {
+        response = await fetchImpl(`${rendezvous.endpoint}/__vesper_transport/${renewLease ? 'lease' : 'identity'}`, {
+            headers: { [LOCAL_SECRET_HEADER]: rendezvous.secret },
+            signal: AbortSignal.timeout(ATTACH_TIMEOUT_MS),
+        });
+    }
+    catch {
         return null;
     }
-    function validateLease(candidate) {
-        if (candidate.protocolVersion !== VESPER_NET_PROTOCOL_VERSION || candidate.hostUrl !== hostUrl
-            || typeof candidate.tailnetName !== 'string' || !candidate.tailnetName
-            || typeof candidate.nodeName !== 'string' || !candidate.nodeName
-            || typeof candidate.ipv4 !== 'string' || !isIPv4(candidate.ipv4)
-            || typeof candidate.executablePath !== 'string' || !candidate.executablePath) {
-            throw new Error('Running vesper-net transport targets a different host or protocol');
-        }
+    if (!response.ok) {
+        return null;
+    }
+    const lease = await response.json();
+    validateLease(lease, hostUrl);
+    return { rendezvous, lease };
+}
+function sameExecutable(left, right) {
+    return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+async function canonicalExecutable(executable) {
+    return fs.realpath(executable).catch(() => path.resolve(executable));
+}
+async function attach(paths, hostUrl, fetchImpl, requiredExecutablePath) {
+    let inspected = await inspectTransport(paths, hostUrl, fetchImpl, requiredExecutablePath === undefined);
+    if (!inspected) {
+        return null;
     }
-    validateLease(lease);
     if (requiredExecutablePath) {
-        const reportedExecutablePath = lease.executablePath;
-        const actualExecutablePath = await fs.realpath(reportedExecutablePath).catch(() => reportedExecutablePath);
-        const sameExecutable = process.platform === 'win32'
-            ? actualExecutablePath.toLowerCase() === requiredExecutablePath.toLowerCase()
-            : actualExecutablePath === requiredExecutablePath;
-        if (!sameExecutable) {
+        const actualExecutablePath = await canonicalExecutable(inspected.lease.executablePath);
+        if (!sameExecutable(actualExecutablePath, requiredExecutablePath)) {
+            return null;
+        }
+        inspected = await inspectTransport(paths, hostUrl, fetchImpl, true);
+        if (!inspected) {
             return null;
         }
-        lease = await readLease(false);
-        if (!lease) {
+        const renewedExecutablePath = await canonicalExecutable(inspected.lease.executablePath);
+        if (!sameExecutable(renewedExecutablePath, requiredExecutablePath)) {
             return null;
         }
-        validateLease(lease);
     }
+    const { rendezvous, lease } = inspected;
     const transportFetch = async (input, init) => {
         const remote = input instanceof Request ? new URL(input.url) : new URL(input.toString());
         if (remote.origin !== new URL(hostUrl).origin) {
@@ -238,6 +247,122 @@ async function attach(paths, hostUrl, fetchImpl, requiredExecutablePath) {
         },
     };
 }
+function isManagedRuntimeExecutable(paths, executable) {
+    const relative = path.relative(path.resolve(paths.runtimeDir), path.resolve(executable));
+    const executableName = path.basename(executable).toLowerCase();
+    return relative !== '' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)
+        && (executableName === 'vesper-net' || executableName === 'vesper-net.exe')
+        && relative.split(path.sep).includes('node_modules');
+}
+async function prepareTransportHandoff(options, fetchImpl, requiredExecutablePath) {
+    const inspected = await inspectTransport(options.paths, options.hostUrl, fetchImpl, false);
+    if (!inspected) {
+        return undefined;
+    }
+    const oldExecutablePath = await canonicalExecutable(inspected.lease.executablePath);
+    if (sameExecutable(oldExecutablePath, requiredExecutablePath)) {
+        return undefined;
+    }
+    if (!isManagedRuntimeExecutable(options.paths, oldExecutablePath)) {
+        throw new Error(`Refusing to replace vesper-net transport outside the managed runtime: ${oldExecutablePath}`);
+    }
+    return { inspected, oldExecutablePath };
+}
+async function stopTransportForHandoff(options, fetchImpl, handoff) {
+    const { inspected, oldExecutablePath } = handoff;
+    const oldPid = inspected.rendezvous.pid;
+    const processIsAlive = options.isProcessAlive ?? isAlive;
+    if (inspected.lease.supportsShutdown === true) {
+        let response;
+        try {
+            response = await fetchImpl(`${inspected.rendezvous.endpoint}/__vesper_transport/shutdown`, {
+                method: 'POST', headers: {
+                    [LOCAL_SECRET_HEADER]: inspected.rendezvous.secret,
+                    [EXPECTED_OWNER_PID_HEADER]: String(oldPid),
+                },
+                signal: AbortSignal.timeout(ATTACH_TIMEOUT_MS),
+            });
+        }
+        catch {
+            throw new Error(`Failed to gracefully stop prior vesper-net transport (pid=${oldPid})`);
+        }
+        if (response.status === 409) {
+            // The inspected owner has already yielded the inherited listener.
+            return;
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to gracefully stop prior vesper-net transport (pid=${oldPid})`);
+        }
+        if (await waitForProcessExit(oldPid, options.handoffTimeoutMs ?? HANDOFF_TIMEOUT_MS, processIsAlive)) {
+            return;
+        }
+        throw new Error(`Timed out stopping prior vesper-net transport (pid=${oldPid})`);
+    }
+    const revalidated = await inspectTransport(options.paths, options.hostUrl, fetchImpl, false);
+    if (!revalidated) {
+        throw new Error(`Timed out stopping prior vesper-net transport (pid=${oldPid})`);
+    }
+    const revalidatedExecutablePath = await canonicalExecutable(revalidated.lease.executablePath);
+    if (revalidated.rendezvous.pid !== oldPid
+        || revalidated.rendezvous.endpoint !== inspected.rendezvous.endpoint
+        || revalidated.rendezvous.secret !== inspected.rendezvous.secret
+        || !sameExecutable(revalidatedExecutablePath, oldExecutablePath)
+        || !isManagedRuntimeExecutable(options.paths, revalidatedExecutablePath)) {
+        throw new Error('vesper-net transport changed ownership during upgrade handoff');
+    }
+    (options.terminateProcess ?? ((pid) => process.kill(pid, 'SIGTERM')))(oldPid);
+    if (!await waitForProcessExit(oldPid, options.handoffTimeoutMs ?? HANDOFF_TIMEOUT_MS, processIsAlive)) {
+        throw new Error(`Timed out stopping prior vesper-net transport (pid=${oldPid})`);
+    }
+}
+async function evictUnexpectedTransportOwner(options, fetchImpl, requiredExecutablePath) {
+    const inspected = await inspectTransport(options.paths, options.hostUrl, fetchImpl, false);
+    if (!inspected) {
+        return;
+    }
+    const executablePath = await canonicalExecutable(inspected.lease.executablePath);
+    if (sameExecutable(executablePath, requiredExecutablePath)) {
+        return;
+    }
+    if (!isManagedRuntimeExecutable(options.paths, executablePath)) {
+        throw new Error(`Refusing to replace vesper-net transport outside the managed runtime: ${executablePath}`);
+    }
+    await stopTransportForHandoff(options, fetchImpl, { inspected, oldExecutablePath: executablePath });
+}
+async function waitForProcessExit(pid, timeoutMs, processIsAlive) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!processIsAlive(pid)) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+    return !processIsAlive(pid);
+}
+function defaultRestartPriorTransport(executable, args, env) {
+    const child = spawn(executable, args, { env, detached: true, windowsHide: true, stdio: 'ignore' });
+    child.unref();
+}
+async function restartPriorTransport(options, handoff, args, error) {
+    if (handoff) {
+        try {
+            const oldPid = handoff.inspected.rendezvous.pid;
+            const processIsAlive = options.isProcessAlive ?? isAlive;
+            if (processIsAlive(oldPid) && !await waitForProcessExit(oldPid, options.handoffTimeoutMs ?? HANDOFF_TIMEOUT_MS, processIsAlive)) {
+                throw new Error(`Prior vesper-net transport is still exiting (pid=${oldPid})`);
+            }
+            (options.restartPriorTransport ?? defaultRestartPriorTransport)(handoff.oldExecutablePath, args, companionEnvironment(process.env));
+        }
+        catch (recoveryError) {
+            throw new AggregateError([error, recoveryError], 'vesper-net candidate failed and prior transport restart failed');
+        }
+    }
+    throw error;
+}
+async function failAfterHandoff(options, handoff, baseArgs, child, error) {
+    child.kill('SIGTERM');
+    return restartPriorTransport(options, handoff, baseArgs, error);
+}
 function defaultSpawn(executable, args, env) {
     return spawn(executable, args, {
         env, detached: true, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
@@ -246,7 +371,8 @@ function defaultSpawn(executable, args, env) {
 function companionEnvironment(environment, bootstrapAuthKey) {
     const filtered = Object.fromEntries(Object.entries(environment).filter(([key]) => {
         const normalized = key.toLowerCase();
-        return !PROXY_ENVIRONMENT_KEYS.has(normalized) && !AUTH_KEY_ENVIRONMENT_KEYS.has(normalized);
+        return !PROXY_ENVIRONMENT_KEYS.has(normalized) && !AUTH_KEY_ENVIRONMENT_KEYS.has(normalized)
+            && normalized !== TRANSPORT_SECRET_ENVIRONMENT_KEY.toLowerCase();
     }));
     if (bootstrapAuthKey !== undefined) {
         filtered.VESPER_TS_AUTHKEY = bootstrapAuthKey;
@@ -292,7 +418,7 @@ export async function acquireRemoteTransport(options) {
         await (options.probeCompanion ?? assertCompanionProtocol)(companion, protocolProbeEnvironment(process.env));
     }
     const requiredExecutablePath = companion
-        ? await fs.realpath(companion.executable).catch(() => companion.executable)
+        ? await canonicalExecutable(companion.executable)
         : undefined;
     const existing = await attach(options.paths, options.hostUrl, fetchImpl, requiredExecutablePath);
     if (existing) {
@@ -304,16 +430,30 @@ export async function acquireRemoteTransport(options) {
     if (!options.requiredCompanion) {
         await (options.probeCompanion ?? assertCompanionProtocol)(companion, protocolProbeEnvironment(process.env));
     }
-    const deadline = Date.now() + (options.startTimeoutMs ?? START_TIMEOUT_MS);
-    const args = [
+    const handoff = options.replaceExistingTransport && requiredExecutablePath
+        ? await prepareTransportHandoff(options, fetchImpl, requiredExecutablePath)
+        : undefined;
+    if (handoff && !TRANSPORT_SECRET_PATTERN.test(handoff.inspected.rendezvous.secret)) {
+        throw new Error('Running vesper-net transport has a malformed handoff secret');
+    }
+    const baseArgs = [
         '--mode', 'transport', '--state-dir', options.paths.tsnetDir, '--hostname', 'vesper-link',
         '--host-url', options.hostUrl, '--rendezvous', options.paths.transportRendezvousPath,
         '--lock', options.paths.transportLockPath, '--idle-timeout', '30s',
     ];
-    const child = (options.spawnChild ?? defaultSpawn)(companion.executable, args, companionEnvironment(process.env, bootstrapAuthKey));
+    const candidateArgs = handoff
+        ? [...baseArgs, '--transport-listen', new URL(handoff.inspected.rendezvous.endpoint).host]
+        : baseArgs;
+    const candidateEnvironment = companionEnvironment(process.env, bootstrapAuthKey);
+    if (handoff) {
+        candidateEnvironment[TRANSPORT_SECRET_ENVIRONMENT_KEY] = handoff.inspected.rendezvous.secret;
+    }
+    const child = (options.spawnChild ?? defaultSpawn)(companion.executable, candidateArgs, candidateEnvironment);
     child.stdin.end();
     let controlBuffer = '';
     let fatalMessage;
+    let waitingForOwner = false;
+    let ownerAcquired = false;
     child.once('error', (error) => { fatalMessage = `spawn failed: ${error.message}`; });
     child.once('exit', (code, signal) => {
         fatalMessage ??= `exited before ready (code=${code ?? 'none'}, signal=${signal ?? 'none'})`;
@@ -339,6 +479,12 @@ export async function acquireRemoteTransport(options) {
                     fatalMessage = 'vesper-net protocol mismatch';
                     child.kill('SIGTERM');
                 }
+                else if (event.type === 'waiting_for_owner') {
+                    waitingForOwner = true;
+                }
+                else if (event.type === 'owner_acquired') {
+                    ownerAcquired = true;
+                }
                 else if (event.type === 'needs_login' && typeof event.loginUrl === 'string') {
                     if (bootstrapAuthKey !== undefined) {
                         fatalMessage = 'automatic enrollment key was not accepted; copy a fresh Memory Link command';
@@ -373,14 +519,43 @@ export async function acquireRemoteTransport(options) {
     });
     // Never persist helper stderr. Drain it to prevent a blocked pipe.
     child.stderr.resume();
+    const deadline = Date.now() + (options.startTimeoutMs ?? START_TIMEOUT_MS);
+    let handoffNeedsRecovery = false;
+    if (handoff) {
+        // Wait until the candidate confirms it has contended on the owner lock.
+        // This closes the stop/start gap where an old runtime could otherwise win.
+        while (!waitingForOwner && !ownerAcquired && !fatalMessage && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        }
+        if (fatalMessage) {
+            child.kill('SIGTERM');
+            return restartPriorTransport(options, undefined, baseArgs, new Error(`vesper-net transport failed: ${fatalMessage}`));
+        }
+        if (!waitingForOwner && !ownerAcquired) {
+            child.kill('SIGTERM');
+            return restartPriorTransport(options, undefined, baseArgs, new Error('Timed out waiting for vesper-net candidate to queue for transport ownership'));
+        }
+        if (waitingForOwner) {
+            try {
+                await stopTransportForHandoff(options, fetchImpl, handoff);
+            }
+            catch (error) {
+                child.kill('SIGTERM');
+                throw error;
+            }
+        }
+        handoffNeedsRecovery = true;
+    }
     while (Date.now() < deadline) {
         let attached;
         try {
+            if (handoff && requiredExecutablePath) {
+                await evictUnexpectedTransportOwner(options, fetchImpl, requiredExecutablePath);
+            }
             attached = await attach(options.paths, options.hostUrl, fetchImpl, requiredExecutablePath);
         }
         catch (error) {
-            child.kill('SIGTERM');
-            throw error;
+            return failAfterHandoff(options, handoffNeedsRecovery ? handoff : undefined, baseArgs, child, error);
         }
         if (attached) {
             if (attached.ownerPid === child.pid) {
@@ -394,11 +569,11 @@ export async function acquireRemoteTransport(options) {
             return attached.transport;
         }
         if (fatalMessage) {
-            child.kill('SIGTERM');
-            throw new Error(`vesper-net transport failed: ${fatalMessage}`);
+            const error = new Error(`vesper-net transport failed: ${fatalMessage}`);
+            return failAfterHandoff(options, handoffNeedsRecovery ? handoff : undefined, baseArgs, child, error);
         }
         await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
     }
-    child.kill('SIGTERM');
-    throw new Error('Timed out waiting for vesper-net transport');
+    const error = new Error('Timed out waiting for vesper-net transport');
+    return failAfterHandoff(options, handoffNeedsRecovery ? handoff : undefined, baseArgs, child, error);
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VESPER_LINK_VERSION = "0.1.5";
+export declare const VESPER_LINK_VERSION = "0.1.6";

package/dist/version.js

@@ -1 +1 @@
-export const VESPER_LINK_VERSION = '0.1.5';
+export const VESPER_LINK_VERSION = '0.1.6';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msvesper/vesper-link",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Connect agent sessions and tools to Vesper Memory",
   "type": "module",
   "bin": {
@@ -28,8 +28,8 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@msvesper/vesper-net-linux-x64": "0.1.5",
-    "@msvesper/vesper-net-win32-x64": "0.1.5"
+    "@msvesper/vesper-net-linux-x64": "0.1.6",
+    "@msvesper/vesper-net-win32-x64": "0.1.6"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",