@msvesper/vesper-link 0.1.4

package/dist/http-client.js

@@ -0,0 +1,228 @@
+import * as fs from 'node:fs';
+import { MAX_MANIFEST_BYTES, parseAddFactResponse, parseCapabilitiesResponse, parseHealthResponse, parseMemorySearchResponse, parseTranscriptResponse, validateManifest } from './contracts.js';
+import { VESPER_LINK_VERSION } from './version.js';
+const CLIENT_VERSION = VESPER_LINK_VERSION;
+const REQUEST_TIMEOUT_MS = 30_000;
+const UPLOAD_TIMEOUT_MS = 5 * 60_000;
+const TASK_LOCAL_STATUS_BY_CODE = new Map([
+    ['invalid_json', 400],
+    ['invalid_manifest', 400],
+    ['unsupported_provider', 400],
+    ['length_required', 400],
+    ['length_mismatch', 400],
+    ['digest_mismatch', 400],
+    ['content_encoding_unsupported', 400],
+    ['source_changed', 400],
+    ['transcript_not_found', 404],
+    ['upload_busy', 409],
+    ['manifest_changed', 409],
+    ['file_too_large', 413],
+    ['manifest_too_large', 413],
+]);
+function requestHeaders() {
+    return {
+        'user-agent': `vesper-link/${CLIENT_VERSION}`,
+        'x-vesper-client-version': VESPER_LINK_VERSION,
+    };
+}
+async function readJsonResponse(response) {
+    const text = await response.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new SystemicUploadError('malformed_response', `Server returned malformed JSON (${response.status})`);
+    }
+}
+function parseErrorEnvelope(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const envelope = value;
+    if (typeof envelope.requestId !== 'string' || !envelope.error
+        || typeof envelope.error.code !== 'string' || typeof envelope.error.message !== 'string'
+        || typeof envelope.error.retryable !== 'boolean') {
+        return null;
+    }
+    return envelope;
+}
+function parseRetryAfter(value, nowMs) {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed)) {
+        const seconds = Number(trimmed);
+        const retryAt = nowMs + seconds * 1_000;
+        return Number.isSafeInteger(seconds) && Number.isFinite(retryAt) ? new Date(retryAt).toISOString() : undefined;
+    }
+    const parsed = Date.parse(trimmed);
+    return Number.isNaN(parsed) ? undefined : new Date(parsed).toISOString();
+}
+async function expectSuccess(response) {
+    const value = await readJsonResponse(response);
+    if (response.ok) {
+        return value;
+    }
+    const envelope = parseErrorEnvelope(value);
+    if (!envelope) {
+        throw new SystemicUploadError('malformed_error', `Server returned malformed error (${response.status})`);
+    }
+    if (TASK_LOCAL_STATUS_BY_CODE.get(envelope.error.code) === response.status) {
+        throw new TaskUploadError(envelope.error.code, envelope.error.message, response.status);
+    }
+    const retryAfterUntil = response.status === 429
+        ? parseRetryAfter(response.headers.get('retry-after'), Date.now())
+        : undefined;
+    throw new SystemicUploadError(envelope.error.code, envelope.error.message, response.status, retryAfterUntil);
+}
+function parseSuccess(value, parse) {
+    try {
+        return parse(value);
+    }
+    catch (error) {
+        throw new SystemicUploadError('malformed_response', error instanceof Error ? error.message : String(error));
+    }
+}
+function endpoint(host, pathname) {
+    return `${host.replace(/\/$/, '')}/api/remote-memory/v1${pathname}`;
+}
+export async function getHealth(host, fetchImpl = fetch) {
+    let response;
+    try {
+        response = await fetchImpl(endpoint(host, '/health'), {
+            headers: requestHeaders(),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw new SystemicUploadError('network_error', String(error));
+    }
+    return parseSuccess(await expectSuccess(response), parseHealthResponse);
+}
+export async function getCapabilities(host, fetchImpl = fetch) {
+    let response;
+    try {
+        response = await fetchImpl(endpoint(host, '/capabilities'), {
+            headers: requestHeaders(),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw new SystemicUploadError('network_error', String(error));
+    }
+    return parseSuccess(await expectSuccess(response), parseCapabilitiesResponse);
+}
+async function postJson(host, pathname, bodyValue, fetchImpl) {
+    const body = JSON.stringify(bodyValue);
+    let response;
+    try {
+        response = await fetchImpl(endpoint(host, pathname), {
+            method: 'POST',
+            headers: { ...requestHeaders(), 'content-type': 'application/json', 'content-length': String(Buffer.byteLength(body)) },
+            body,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw new SystemicUploadError('network_error', String(error));
+    }
+    return expectSuccess(response);
+}
+export async function searchMemory(host, query, limit = 5, fetchImpl = fetch) {
+    return parseSuccess(await postJson(host, '/search', { query, limit }, fetchImpl), parseMemorySearchResponse);
+}
+export async function addFact(host, fact, fetchImpl = fetch) {
+    return parseSuccess(await postJson(host, '/facts', { fact, source: 'user_instruction' }, fetchImpl), parseAddFactResponse);
+}
+export async function getTranscriptStatus(host, transcriptId, fetchImpl = fetch) {
+    let response;
+    try {
+        response = await fetchImpl(endpoint(host, `/transcripts/${encodeURIComponent(transcriptId)}/status`), {
+            headers: requestHeaders(),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw new SystemicUploadError('network_error', String(error));
+    }
+    return parseSuccess(await expectSuccess(response), parseTranscriptResponse);
+}
+export async function postManifest(host, manifest, fetchImpl = fetch) {
+    try {
+        validateManifest(manifest);
+    }
+    catch (error) {
+        throw new TaskUploadError('invalid_manifest', error instanceof Error ? error.message : String(error));
+    }
+    const body = JSON.stringify(manifest);
+    if (Buffer.byteLength(body) > MAX_MANIFEST_BYTES) {
+        throw new TaskUploadError('manifest_too_large', 'Manifest exceeds 16 KiB');
+    }
+    let response;
+    try {
+        response = await fetchImpl(endpoint(host, '/transcripts'), {
+            method: 'POST',
+            headers: { ...requestHeaders(), 'content-type': 'application/json', 'content-length': String(Buffer.byteLength(body)) },
+            body,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw new SystemicUploadError('network_error', String(error));
+    }
+    return parseSuccess(await expectSuccess(response), parseTranscriptResponse);
+}
+export async function putContent(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const body = fs.createReadStream(options.filePath);
+    let response;
+    try {
+        response = await fetchImpl(endpoint(options.host, `/transcripts/${encodeURIComponent(options.transcriptId)}/content`), {
+            method: 'PUT',
+            headers: {
+                ...requestHeaders(),
+                'content-type': 'application/octet-stream',
+                'content-length': String(options.byteLength),
+            },
+            body: body,
+            // Node fetch requires duplex for streaming request bodies.
+            duplex: 'half',
+            signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        const cause = error instanceof Error ? error.cause : undefined;
+        const fileCode = error.code ?? cause?.code;
+        if (fileCode === 'ENOENT' || fileCode === 'EACCES' || fileCode === 'EPERM') {
+            throw new TaskUploadError('source_changed', `Source became unreadable while uploading: ${String(error)}`);
+        }
+        throw new SystemicUploadError('network_error', String(error));
+    }
+    finally {
+        body.destroy();
+    }
+    return parseSuccess(await expectSuccess(response), parseTranscriptResponse);
+}
+export class TaskUploadError extends Error {
+    code;
+    httpStatus;
+    constructor(code, message, httpStatus) {
+        super(message);
+        this.code = code;
+        this.httpStatus = httpStatus;
+        this.name = 'TaskUploadError';
+    }
+}
+export class SystemicUploadError extends Error {
+    code;
+    httpStatus;
+    retryAfterUntil;
+    constructor(code, message, httpStatus, retryAfterUntil) {
+        super(message);
+        this.code = code;
+        this.httpStatus = httpStatus;
+        this.retryAfterUntil = retryAfterUntil;
+        this.name = 'SystemicUploadError';
+    }
+}

package/dist/install-args.d.ts

@@ -0,0 +1,7 @@
+import type { ExpectedRole } from './installer.js';
+export interface InstallArguments {
+    host: string;
+    expectedRole?: ExpectedRole;
+    bootstrapAuthKey?: string;
+}
+export declare function parseInstallArguments(args: string[], processArgs?: string[]): InstallArguments;

package/dist/install-args.js

@@ -0,0 +1,35 @@
+const AUTH_KEY_PATTERN = /^tskey-auth-[A-Za-z0-9_-]{16,512}$/;
+export function parseInstallArguments(args, processArgs = process.argv) {
+    const values = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const current = args[index];
+        if (!current.startsWith('--') || index + 1 >= args.length) {
+            throw new Error(`Invalid argument: ${current}`);
+        }
+        const valueIndex = index + 1;
+        const value = args[valueIndex];
+        values.set(current.slice(2), value);
+        if (current === '--auth-key') {
+            args[valueIndex] = '[redacted]';
+            for (let processIndex = 2; processIndex < processArgs.length - 1; processIndex += 1) {
+                if (processArgs[processIndex] === '--auth-key' && processArgs[processIndex + 1] === value) {
+                    processArgs[processIndex + 1] = '[redacted]';
+                }
+            }
+        }
+        index = valueIndex;
+    }
+    const host = values.get('host');
+    const expectedRole = values.get('expect-role');
+    const bootstrapAuthKey = values.get('auth-key');
+    values.delete('auth-key');
+    if (!host || (expectedRole !== undefined && expectedRole !== 'uploader' && expectedRole !== 'trusted')
+        || (bootstrapAuthKey !== undefined && !AUTH_KEY_PATTERN.test(bootstrapAuthKey))) {
+        throw new Error('Usage: vesper-link install --host http://<Tailscale IPv4>:11723 [--expect-role uploader|trusted] [--auth-key <one-use-key>]');
+    }
+    return {
+        host,
+        expectedRole: expectedRole,
+        bootstrapAuthKey,
+    };
+}

package/dist/installation.d.ts

@@ -0,0 +1,59 @@
+import type { CapabilitiesResponse } from './contracts.js';
+import { type CurrentRuntimePointer, type ManagedRuntime } from './managed-runtime.js';
+import type { LinkPaths } from './paths.js';
+import { type ProcessRunner } from './process-runner.js';
+import { type OwnedProviderIntegrations, type ProviderMutation, type SupportedProvider } from './provider-integrations.js';
+import { type SchedulerState } from './scheduler.js';
+export interface InstalledState {
+    schemaVersion: 2;
+    installedAt: string;
+    host: string;
+    sourceTrust: 'trusted' | 'uploader';
+    installationId: string;
+    runtime: CurrentRuntimePointer;
+    nodePath: string;
+    launcherPath: string;
+    minuteOffset: number;
+    scheduler: SchedulerState;
+    integrations: OwnedProviderIntegrations;
+    backups: Record<string, string>;
+    createdProviderFiles: string[];
+    paused?: boolean;
+}
+export interface InstallationStatus {
+    installed: boolean;
+    paused: boolean;
+    providers: SupportedProvider[];
+    claudeHookInstalled: boolean;
+    copilotHookInstalled: boolean;
+    sourceTrust?: 'trusted' | 'uploader';
+    schedulerInstalled: boolean;
+    schedulerKind?: 'windows-task' | 'cron';
+    minuteOffset?: number;
+    runtimeVersion?: string;
+    trustedIntegrationsInstalled: boolean;
+}
+export interface InstallFaults {
+    afterStep?(step: 'current' | 'config' | 'providers' | 'scheduler' | 'state'): Promise<void> | void;
+    afterProviderMutation?(mutation: ProviderMutation): Promise<void> | void;
+}
+export declare function verifyInstalledState(paths: LinkPaths, expected: InstalledState, runner?: ProcessRunner): Promise<void>;
+export declare function readInstalledState(paths: LinkPaths): Promise<InstalledState | null>;
+export declare function installManagedRuntime(options: {
+    paths: LinkPaths;
+    runtime: ManagedRuntime;
+    host: string;
+    capabilities: CapabilitiesResponse;
+    nodePath?: string;
+    platform?: NodeJS.Platform;
+    runner?: ProcessRunner;
+    providers?: SupportedProvider[];
+    now?: Date;
+    postInstallDoctor?: () => Promise<void>;
+    faults?: InstallFaults;
+}): Promise<InstalledState>;
+export declare function uninstallIntegrations(paths: LinkPaths, runner?: ProcessRunner, probeProcess?: (pid: number) => 'alive' | 'absent' | 'unknown'): Promise<boolean>;
+export declare function pauseIntegrations(paths: LinkPaths, runner?: ProcessRunner): Promise<boolean>;
+export declare function resumeIntegrations(paths: LinkPaths, runner?: ProcessRunner): Promise<boolean>;
+export declare function resetRemoteIdentity(paths: LinkPaths, confirmed: boolean): Promise<void>;
+export declare function getInstallationStatus(paths: LinkPaths, runner?: ProcessRunner): Promise<InstallationStatus>;