@north-light/api 0.3.580 → 0.3.587

package/dist/hook-authoring.d.ts

@@ -0,0 +1,130 @@
+export type HookJson = null | boolean | number | string | HookJson[] | {
+    [key: string]: HookJson;
+};
+export type HookPhase = 'before' | 'after' | 'replace';
+export interface HookContext {
+    cwd: string;
+    providedParams: string[];
+}
+export interface LifecycleHookNode {
+    id: string;
+    name: string;
+    kind: string;
+    mode: string;
+    lifecycle: string;
+    cwd: string;
+    nodeDir: string;
+    contextDir: string;
+    jobDir: string;
+}
+export interface LifecycleHookRuntime {
+    isBirth: boolean;
+    canvasHome: string;
+    profile: string | null;
+}
+/** `node:create` runs before every node birth, immediately before a cold row is written or a warm spare is claimed. Return `ok:false` to refuse the birth. There is no node payload because no node exists yet. */
+export interface NodeCreateHookRequest {
+    protocolVersion: 1;
+    op: string;
+    event: 'node:create';
+    phase: 'before';
+    operationId: string;
+    create: {
+        kind: string;
+        mode: string;
+        cwd: string;
+        profile: string | null;
+        root: boolean;
+        parentId: string | null;
+        requestingNodeId: string | null;
+        lifecycle: 'resident' | 'terminal';
+        replaces: string | null;
+    };
+    runtime: {
+        canvasHome: string;
+        profile: string | null;
+    };
+    context: {
+        cwd: string;
+    };
+}
+interface HookRequestBase {
+    protocolVersion: 1;
+    op: string;
+    command: string[];
+    operationId: string;
+    input: {
+        [key: string]: HookJson;
+    };
+    context: HookContext;
+}
+export interface BeforeHookRequest extends HookRequestBase {
+    phase: 'before';
+}
+export interface AfterHookRequest extends HookRequestBase {
+    phase: 'after';
+    result: HookJson;
+}
+export interface ReplaceHookRequest extends HookRequestBase {
+    phase: 'replace';
+}
+/** `node:start` handlers run for birth and every revive, so they must be idempotent. `node:close` runs after close. */
+export interface LifecycleHookRequest {
+    protocolVersion: 1;
+    op: string;
+    event: 'node:start' | 'node:close';
+    phase: 'on';
+    operationId: string;
+    node: LifecycleHookNode;
+    runtime: LifecycleHookRuntime;
+    context: {
+        cwd: string;
+    };
+}
+export type HookRequest = BeforeHookRequest | AfterHookRequest | ReplaceHookRequest | NodeCreateHookRequest | LifecycleHookRequest;
+export interface HookSuccess {
+    protocolVersion: 1;
+    ok: true;
+    result?: HookJson;
+}
+export interface HookError {
+    code: string;
+    message: string;
+    field?: string;
+    next?: string;
+}
+export interface HookFailure {
+    protocolVersion: 1;
+    ok: false;
+    error: HookError;
+}
+export type HookResponse = HookSuccess | HookFailure;
+export type HookHandler = (request: HookRequest) => HookResponse | Promise<HookResponse>;
+export type HookHandlers = Record<string, HookHandler>;
+export interface RunHookExecutableOptions {
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+}
+export interface LocalHookProcessOptions {
+    timeoutMs: number;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    input?: string | Uint8Array;
+}
+export interface LocalHookProcessSuccess {
+    ok: true;
+    stdout: string;
+}
+export type LocalHookProcessResult = LocalHookProcessSuccess | HookFailure;
+export interface ForwardHookOptions {
+    headers?: HeadersInit;
+    bearer?: string;
+    timeoutMs: number;
+    maxResponseBytes: number;
+}
+export declare function hookError(code: string, message: string, details?: Omit<HookError, 'code' | 'message'>): HookFailure;
+export declare function runHookExecutable(handlers: HookHandlers, options?: RunHookExecutableOptions): Promise<void>;
+export declare function runLocalHookProcess(argv: readonly string[], options: LocalHookProcessOptions): Promise<LocalHookProcessResult>;
+export declare function forwardHook(endpoint: string | URL, request: HookRequest, options: ForwardHookOptions): Promise<HookResponse>;
+export {};

package/dist/hook-authoring.js

@@ -0,0 +1,447 @@
+import { spawn } from 'node:child_process';
+import { Console } from 'node:console';
+import { posixProcessGroupSpawnOptions, terminateProcessGroup } from './hook-process.js';
+export function hookError(code, message, details = {}) {
+    return { protocolVersion: 1, ok: false, error: { code, message, ...details } };
+}
+export async function runHookExecutable(handlers, options = {}) {
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    let response;
+    try {
+        const raw = await readStream(stdin);
+        let value;
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            response = hookError('invalid_hook_request', 'stdin must contain one JSON hook request');
+            writeResponse(stdout, response);
+            return;
+        }
+        const request = validateRequest(value);
+        if (!request.valid) {
+            response = hookError('invalid_hook_request', request.message);
+            writeResponse(stdout, response);
+            return;
+        }
+        const handler = handlers[request.value.op];
+        if (handler === undefined) {
+            response = hookError('unsupported_hook_op', `no handler is registered for ${request.value.op}`);
+            writeResponse(stdout, response);
+            return;
+        }
+        try {
+            response = await withConsoleStdoutOnStderr(stderr, () => handler(request.value));
+        }
+        catch (error) {
+            stderr.write(`hook handler ${request.value.op} failed: ${describeError(error)}\n`);
+            response = hookError('hook_handler_failed', `handler failed for ${request.value.op}`);
+        }
+        const validated = validateResponse(response, request.value);
+        if (!validated.valid) {
+            stderr.write(`hook handler ${request.value.op} returned an invalid response: ${validated.message}\n`);
+            response = hookError('invalid_hook_response', validated.message);
+        }
+    }
+    catch (error) {
+        stderr.write(`hook executable failed: ${describeError(error)}\n`);
+        response = hookError('hook_executable_failed', 'hook executable could not read its request');
+    }
+    writeResponse(stdout, response);
+}
+export async function runLocalHookProcess(argv, options) {
+    const executable = argv[0];
+    if (executable === undefined || executable === '') {
+        return hookError('local_process_invalid', 'local process argv[0] must not be empty');
+    }
+    if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+        return hookError('local_process_invalid_options', 'timeoutMs must be greater than zero');
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        let timedOut = false;
+        let closed = false;
+        let cleanupComplete = false;
+        let timeout;
+        const stdout = [];
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            resolve(result);
+        };
+        let child;
+        try {
+            child = spawn(executable, argv.slice(1), {
+                cwd: options.cwd,
+                env: options.env,
+                shell: false,
+                stdio: [options.input === undefined ? 'ignore' : 'pipe', 'pipe', 'inherit'],
+                ...posixProcessGroupSpawnOptions(),
+            });
+        }
+        catch (error) {
+            settle(hookError('local_process_spawn_failed', `could not start ${executable}: ${describeError(error)}`));
+            return;
+        }
+        const settleTimeout = () => {
+            if (timedOut && closed && cleanupComplete) {
+                settle(hookError('local_process_timeout', `${executable} did not finish within ${options.timeoutMs}ms`));
+            }
+        };
+        timeout = setTimeout(() => {
+            timedOut = true;
+            void terminateProcessGroup(child).then(() => {
+                cleanupComplete = true;
+                settleTimeout();
+            }, (error) => {
+                cleanupComplete = true;
+                settle(hookError('local_process_cleanup_failed', `could not stop ${executable}: ${describeError(error)}`));
+            });
+        }, options.timeoutMs);
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.once('error', (error) => {
+            if (child.pid !== undefined)
+                return;
+            settle(hookError('local_process_spawn_failed', `could not start ${executable}: ${describeError(error)}`));
+        });
+        child.once('close', (code, signal) => {
+            closed = true;
+            if (timedOut) {
+                settleTimeout();
+                return;
+            }
+            if (code === 0) {
+                settle({ ok: true, stdout: Buffer.concat(stdout).toString('utf8') });
+                return;
+            }
+            const status = signal === null ? `exit code ${code ?? 'unknown'}` : `signal ${signal}`;
+            settle(hookError('local_process_failed', `${executable} exited with ${status}`));
+        });
+        if (options.input !== undefined && child.stdin !== null) {
+            child.stdin.end(options.input);
+        }
+    });
+}
+export async function forwardHook(endpoint, request, options) {
+    if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+        return hookError('hook_forward_invalid_options', 'timeoutMs must be greater than zero');
+    }
+    if (!Number.isSafeInteger(options.maxResponseBytes) || options.maxResponseBytes <= 0) {
+        return hookError('hook_forward_invalid_options', 'maxResponseBytes must be a positive integer');
+    }
+    const headers = new Headers(options.headers);
+    if (!headers.has('content-type'))
+        headers.set('content-type', 'application/json');
+    if (options.bearer !== undefined)
+        headers.set('authorization', `Bearer ${options.bearer}`);
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, options.timeoutMs);
+    try {
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(request),
+            signal: controller.signal,
+        });
+        const body = await readResponseBody(response, options.maxResponseBytes);
+        let value;
+        try {
+            value = JSON.parse(body);
+        }
+        catch {
+            return hookError('hook_forward_invalid_response', `hook endpoint returned invalid JSON (HTTP ${response.status})`);
+        }
+        // A valid protocol envelope is authoritative regardless of HTTP status.
+        const validated = validateResponse(value, request);
+        if (!validated.valid)
+            return hookError('hook_forward_invalid_response', `${validated.message} (HTTP ${response.status})`);
+        return validated.value;
+    }
+    catch (error) {
+        if (timedOut)
+            return hookError('hook_forward_timeout', `hook endpoint did not respond within ${options.timeoutMs}ms`);
+        if (error instanceof ResponseTooLargeError) {
+            return hookError('hook_forward_response_too_large', `hook endpoint exceeded ${options.maxResponseBytes} response bytes`);
+        }
+        return hookError('hook_forward_failed', `hook endpoint request failed: ${describeError(error)}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+const STDOUT_CONSOLE_METHODS = ['log', 'info', 'debug', 'dir', 'table', 'group', 'groupCollapsed'];
+async function withConsoleStdoutOnStderr(stderr, run) {
+    const redirected = new Console({ stdout: stderr, stderr, colorMode: false });
+    const original = new Map();
+    for (const method of STDOUT_CONSOLE_METHODS) {
+        original.set(method, console[method]);
+        console[method] = redirected[method].bind(redirected);
+    }
+    try {
+        return await run();
+    }
+    finally {
+        for (const method of STDOUT_CONSOLE_METHODS)
+            console[method] = original.get(method);
+    }
+}
+function writeResponse(stdout, response) {
+    stdout.write(`${JSON.stringify(response)}\n`);
+}
+async function readStream(stream) {
+    const chunks = [];
+    for await (const chunk of stream)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+async function readResponseBody(response, maxBytes) {
+    if (response.body === null)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel();
+                throw new ResponseTooLargeError();
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return new TextDecoder().decode(concatBytes(chunks, total));
+}
+function concatBytes(chunks, total) {
+    const result = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result;
+}
+function validateRequest(value) {
+    if (!isRecord(value))
+        return invalid('request must be an object');
+    if (value['protocolVersion'] !== 1)
+        return invalid('unsupported hook protocol version');
+    if (typeof value['op'] !== 'string' || value['op'] === '')
+        return invalid('op must be a non-empty string');
+    if (typeof value['operationId'] !== 'string' || !/^[0-9a-f]{32}$/.test(value['operationId'])) {
+        return invalid('operationId must be a 32-character lowercase hexadecimal string');
+    }
+    if (value['event'] === 'node:create') {
+        if (!hasOnlyKeys(value, ['protocolVersion', 'op', 'event', 'phase', 'operationId', 'create', 'runtime', 'context']))
+            return invalid('node:create request contains unknown fields');
+        if (value['phase'] !== 'before')
+            return invalid('node:create phase must be before');
+        if (!isNodeCreate(value['create']))
+            return invalid('node:create request create contains invalid fields');
+        if (!isCreateRuntime(value['runtime']))
+            return invalid('node:create request runtime contains invalid fields');
+        if (!isLifecycleContext(value['context']))
+            return invalid('node:create request context must contain cwd');
+        return valid({
+            protocolVersion: 1,
+            op: value['op'],
+            event: 'node:create',
+            phase: 'before',
+            operationId: value['operationId'],
+            create: value['create'],
+            runtime: value['runtime'],
+            context: value['context'],
+        });
+    }
+    if (value['phase'] === 'on') {
+        if (!hasOnlyKeys(value, ['protocolVersion', 'op', 'event', 'phase', 'operationId', 'node', 'runtime', 'context']))
+            return invalid('lifecycle request contains unknown fields');
+        if (value['event'] !== 'node:start' && value['event'] !== 'node:close')
+            return invalid('unsupported lifecycle event');
+        if (!isLifecycleNode(value['node']))
+            return invalid('lifecycle request node contains invalid fields');
+        if (!isLifecycleRuntime(value['runtime']))
+            return invalid('lifecycle request runtime contains invalid fields');
+        if (!isLifecycleContext(value['context']))
+            return invalid('lifecycle request context must contain cwd');
+        return valid({
+            protocolVersion: 1,
+            op: value['op'],
+            event: value['event'],
+            phase: 'on',
+            operationId: value['operationId'],
+            node: value['node'],
+            runtime: value['runtime'],
+            context: value['context'],
+        });
+    }
+    if (!hasOnlyKeys(value, ['protocolVersion', 'op', 'phase', 'command', 'operationId', 'input', 'context', 'result'])) {
+        return invalid('request contains unknown fields');
+    }
+    if (!isStringArray(value['command']) || value['command'].length === 0)
+        return invalid('command must be a non-empty string array');
+    if (!isRecord(value['input']) || !isJson(value['input']))
+        return invalid('input must be a JSON object');
+    if (!isContext(value['context']))
+        return invalid('context must contain cwd and providedParams');
+    if (value['phase'] === 'after') {
+        if (!Object.hasOwn(value, 'result') || !isJson(value['result']))
+            return invalid('after requests require a JSON result');
+        return valid({
+            protocolVersion: 1,
+            op: value['op'],
+            phase: 'after',
+            command: value['command'],
+            operationId: value['operationId'],
+            input: value['input'],
+            context: value['context'],
+            result: value['result'],
+        });
+    }
+    if (value['phase'] !== 'before' && value['phase'] !== 'replace')
+        return invalid('phase must be before, after, or replace');
+    if (Object.hasOwn(value, 'result'))
+        return invalid('only after requests may contain result');
+    if (value['phase'] === 'before') {
+        return valid({
+            protocolVersion: 1,
+            op: value['op'],
+            phase: 'before',
+            command: value['command'],
+            operationId: value['operationId'],
+            input: value['input'],
+            context: value['context'],
+        });
+    }
+    return valid({
+        protocolVersion: 1,
+        op: value['op'],
+        phase: 'replace',
+        command: value['command'],
+        operationId: value['operationId'],
+        input: value['input'],
+        context: value['context'],
+    });
+}
+function validateResponse(value, request) {
+    if (!isRecord(value))
+        return invalid('response must be an object');
+    if (value['protocolVersion'] !== 1)
+        return invalid('response has an unsupported hook protocol version');
+    if (value['ok'] === true) {
+        if (!hasOnlyKeys(value, ['protocolVersion', 'ok', 'result']))
+            return invalid('successful response contains unknown fields');
+        const hasResult = Object.hasOwn(value, 'result');
+        if (request.phase === 'replace' && !hasResult)
+            return invalid('replace response requires result');
+        if (request.phase !== 'replace' && hasResult)
+            return invalid('only replace responses may contain result');
+        if (hasResult) {
+            const result = value['result'];
+            if (!isJson(result))
+                return invalid('response result must be JSON');
+            return valid({ protocolVersion: 1, ok: true, result });
+        }
+        return valid({ protocolVersion: 1, ok: true });
+    }
+    if (value['ok'] !== false || !hasOnlyKeys(value, ['protocolVersion', 'ok', 'error'])) {
+        return invalid('response must contain protocolVersion, ok, and error or result');
+    }
+    if (!isHookError(value['error']))
+        return invalid('response error must contain code and message strings');
+    return valid({ protocolVersion: 1, ok: false, error: value['error'] });
+}
+function isContext(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ['cwd', 'providedParams'])
+        && typeof value['cwd'] === 'string'
+        && isStringArray(value['providedParams']);
+}
+function isLifecycleContext(value) {
+    return isRecord(value) && hasOnlyKeys(value, ['cwd']) && typeof value['cwd'] === 'string';
+}
+function isNodeCreate(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ['kind', 'mode', 'cwd', 'profile', 'root', 'parentId', 'requestingNodeId', 'lifecycle', 'replaces'])
+        && typeof value['kind'] === 'string'
+        && typeof value['mode'] === 'string'
+        && typeof value['cwd'] === 'string'
+        && (typeof value['profile'] === 'string' || value['profile'] === null)
+        && typeof value['root'] === 'boolean'
+        && (typeof value['parentId'] === 'string' || value['parentId'] === null)
+        && (typeof value['requestingNodeId'] === 'string' || value['requestingNodeId'] === null)
+        && (value['lifecycle'] === 'resident' || value['lifecycle'] === 'terminal')
+        && (typeof value['replaces'] === 'string' || value['replaces'] === null);
+}
+function isCreateRuntime(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ['canvasHome', 'profile'])
+        && typeof value['canvasHome'] === 'string'
+        && (typeof value['profile'] === 'string' || value['profile'] === null);
+}
+function isLifecycleNode(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ['id', 'name', 'kind', 'mode', 'lifecycle', 'cwd', 'nodeDir', 'contextDir', 'jobDir'])
+        && ['id', 'name', 'kind', 'mode', 'lifecycle', 'cwd', 'nodeDir', 'contextDir', 'jobDir'].every((field) => typeof value[field] === 'string');
+}
+function isLifecycleRuntime(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ['isBirth', 'canvasHome', 'profile'])
+        && typeof value['isBirth'] === 'boolean'
+        && typeof value['canvasHome'] === 'string'
+        && (typeof value['profile'] === 'string' || value['profile'] === null);
+}
+function isHookError(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ['code', 'message', 'field', 'next'])
+        && typeof value['code'] === 'string'
+        && value['code'] !== ''
+        && typeof value['message'] === 'string'
+        && value['message'] !== ''
+        && (value['field'] === undefined || typeof value['field'] === 'string')
+        && (value['next'] === undefined || typeof value['next'] === 'string');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function isJson(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJson);
+    return isRecord(value) && Object.values(value).every(isJson);
+}
+function hasOnlyKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.includes(key));
+}
+function valid(value) {
+    return { valid: true, value };
+}
+function invalid(message) {
+    return { valid: false, message };
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+class ResponseTooLargeError extends Error {
+}

package/dist/hook-process.d.ts

@@ -0,0 +1,7 @@
+import type { ChildProcess } from 'node:child_process';
+export declare const PROCESS_GROUP_KILL_GRACE_MS = 250;
+export declare function posixProcessGroupSpawnOptions(): {
+    detached: true;
+};
+/** Signal the isolated group, then unconditionally reap survivors after grace. */
+export declare function terminateProcessGroup(child: ChildProcess, graceMs?: number): Promise<void>;

package/dist/hook-process.js

@@ -0,0 +1,34 @@
+export const PROCESS_GROUP_KILL_GRACE_MS = 250;
+export function posixProcessGroupSpawnOptions() {
+    if (process.platform === 'win32') {
+        throw new Error('hook process execution requires POSIX process groups');
+    }
+    return { detached: true };
+}
+/** Signal the isolated group, then unconditionally reap survivors after grace. */
+export async function terminateProcessGroup(child, graceMs = PROCESS_GROUP_KILL_GRACE_MS) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    signalProcessGroup(pid, 'SIGTERM');
+    await delay(graceMs);
+    signalProcessGroup(pid, 'SIGKILL');
+}
+function signalProcessGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (error) {
+        if (!isMissingProcess(error))
+            throw error;
+    }
+}
+function isMissingProcess(error) {
+    return typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && error.code === 'ESRCH';
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/launcher/client.d.ts

@@ -0,0 +1,6 @@
+import { type LauncherReply, type LauncherRequest, type LimitEvent } from './spec.js';
+/** The most one launcher packet carries (`send_fds` in src/native/linux/addon.c). */
+export declare const LAUNCHER_PACKET_MAX_BYTES = 65535;
+/** The daemon registers where launcher diagnostics (limit applications, OOM kills, skipped limits) become canonical events. */
+export declare function setLauncherEventSink(sink: ((events: LimitEvent[]) => void) | undefined): void;
+export declare function launcherRequest(request: LauncherRequest, fds?: number[], path?: string): Promise<LauncherReply>;

package/dist/launcher/client.js

@@ -0,0 +1,52 @@
+import { connect } from 'node:net';
+import { loadLinuxNative } from '../native/linux.js';
+import { LAUNCHER_SOCKET, LaunchRefused } from './spec.js';
+const native = loadLinuxNative();
+/** The most one launcher packet carries (`send_fds` in src/native/linux/addon.c). */
+export const LAUNCHER_PACKET_MAX_BYTES = 65_535;
+let eventSink;
+/** The daemon registers where launcher diagnostics (limit applications, OOM kills, skipped limits) become canonical events. */
+export function setLauncherEventSink(sink) { eventSink = sink; }
+// The node-token fd is transferred with SCM_RIGHTS in the launch packet, not
+// serialized or written to a file. Caller keeps ownership of its descriptor.
+export async function launcherRequest(request, fds = [], path = LAUNCHER_SOCKET) {
+    if (!native)
+        throw new Error('Linux launcher client requires the native addon');
+    const socket = connect(path);
+    try {
+        await new Promise((resolve, reject) => { socket.once('connect', resolve); socket.once('error', reject); });
+        const fd = socket._handle?.fd;
+        if (fd === undefined || fd < 0)
+            throw new Error('launcher socket fd unavailable');
+        const packet = JSON.stringify(request);
+        // The launcher reads one packet of at most 65,535 bytes. Name the cause rather than surface the addon's bare range error.
+        if (Buffer.byteLength(packet) > LAUNCHER_PACKET_MAX_BYTES) {
+            throw new LaunchRefused('invalid_spec', `launcher request is ${Buffer.byteLength(packet)} bytes, over the ${LAUNCHER_PACKET_MAX_BYTES}-byte packet limit; large values (such as a run's scope list) must travel in a file, not the launch environment`);
+        }
+        native.sendFds(fd, packet, fds);
+        const reply = await new Promise((resolve, reject) => {
+            let data = '';
+            socket.on('data', chunk => { data += chunk.toString(); if (data.includes('\n'))
+                resolve(data.slice(0, data.indexOf('\n'))); });
+            socket.once('end', () => reject(new Error('launcher disconnected without reply')));
+            socket.once('error', reject);
+        });
+        const parsed = JSON.parse(reply);
+        if ('refusal' in parsed)
+            throw new LaunchRefused(parsed.refusal, `launcher refused ${parsed.refusal}`);
+        if ('events' in parsed && parsed.events !== undefined) {
+            const { events, ...rest } = parsed;
+            if (events.length > 0) {
+                try {
+                    eventSink?.(events);
+                }
+                catch { /* diagnostics never fail a launcher call */ }
+            }
+            return rest;
+        }
+        return parsed;
+    }
+    finally {
+        socket.destroy();
+    }
+}