@blastlauncher/engine 0.0.0-stage → 3.0.0-alpha.1

package/dist/install-dependencies.js

@@ -0,0 +1,203 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { loadSharedDependencies } from "./dependencies.js";
+import { requiredPeerAdditions, supplied } from "./install-peers.js";
+import { defaultDataDir } from "./storage.js";
+export const npmDependencyInstaller = ({ command, args, cwd, onLog }) => new Promise((done, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout.on("data", (chunk) => onLog?.(chunk.toString()));
+    child.stderr.on("data", (chunk) => onLog?.(chunk.toString()));
+    child.once("error", reject);
+    child.once("close", (code, signal) => {
+        if (code === 0)
+            done();
+        else
+            reject(new Error(`npm install failed (${signal ?? code})`));
+    });
+});
+function stripSuppliedDependencies(dependencies) {
+    for (const [name, dependency] of Object.entries(dependencies)) {
+        if (supplied(name))
+            delete dependencies[name];
+        else if (dependency.dependencies)
+            stripSuppliedDependencies(dependency.dependencies);
+    }
+}
+async function optionalFile(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function inputs(options) {
+    const extensionDir = resolve(options.extensionDir);
+    const manifest = JSON.parse(await readFile(join(extensionDir, "package.json"), "utf8"));
+    if (typeof manifest.name !== "string" || !manifest.name)
+        throw new Error("An extension name is required for dependency installation");
+    const lock = await optionalFile(join(extensionDir, "package-lock.json"));
+    // Sort dependency fields so JSON property order does not invalidate an install.
+    const dependencies = Object.fromEntries(Object.entries(manifest.dependencies ?? {}).toSorted(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+    const baseKey = createHash("sha256")
+        // Rebuild installs made before required peers were repaired.
+        .update("lean-install-v2\n")
+        .update(JSON.stringify(dependencies))
+        .update("\n")
+        .update(lock ?? "")
+        .digest("hex");
+    const encoded = encodeURIComponent(manifest.name).replace(/\./g, "%2E");
+    const directory = resolve(options.dataDir ?? defaultDataDir(), "deps", encoded);
+    const additions = JSON.parse((await optionalFile(join(directory, "peer-additions.json"))) ?? "{}");
+    const key = installKey(baseKey, additions);
+    return { manifest, dependencies, extensionDir, lock, key, baseKey, directory };
+}
+function installKey(baseKey, additions) {
+    return createHash("sha256")
+        .update(baseKey)
+        .update(JSON.stringify(Object.entries(additions).toSorted(([a], [b]) => a.localeCompare(b))))
+        .digest("hex");
+}
+/** Cheap disk-only check; a key is published only after a successful install. */
+export async function checkExtensionDependencies(options) {
+    const { directory, key, lock, dependencies } = await inputs(options);
+    const needed = (await optionalFile(join(directory, "key"))) !== key;
+    const shared = await loadSharedDependencies(options.sharedDependencies);
+    const unresolved = [];
+    for (const name of Object.keys(dependencies)) {
+        if (supplied(name))
+            continue;
+        if (!needed &&
+            (await optionalFile(join(directory, "node_modules", name, "package.json"))) !== undefined)
+            continue;
+        if (shared?.resolveShared(name))
+            continue;
+        unresolved.push(name);
+    }
+    const unique = [...new Set(unresolved)].toSorted();
+    return {
+        directory,
+        key,
+        needed,
+        unresolved: unique,
+        pinned: lock !== undefined,
+        installable: unique.every((name) => Object.hasOwn(dependencies, name)),
+    };
+}
+/** Installs only production dependencies; never writes to the extension. */
+export async function installExtensionDependencies(options) {
+    const input = await inputs(options);
+    const status = {
+        directory: input.directory,
+        key: input.key,
+        needed: false,
+        pinned: input.lock !== undefined,
+        unresolved: [],
+        installable: true,
+    };
+    if ((await optionalFile(join(input.directory, "key"))) === input.key) {
+        options.onLog?.("Dependencies are up to date.");
+        return status;
+    }
+    if (!status.pinned)
+        options.onLog?.("Warning: no package-lock.json; dependency versions are unpinned.");
+    const dependencies = Object.fromEntries(Object.entries(input.dependencies)
+        .filter(([name]) => !supplied(name))
+        .map(([name, value]) => {
+        if (typeof value !== "string")
+            throw new Error(`Invalid dependency ${name}`);
+        // Local packages retain their source location after the manifest is copied.
+        return [
+            name,
+            value.startsWith("file:") ? `file:${resolve(input.extensionDir, value.slice(5))}` : value,
+        ];
+    }));
+    await rm(input.directory, { recursive: true, force: true });
+    await mkdir(input.directory, { recursive: true });
+    try {
+        await writeFile(join(input.directory, "package.json"), JSON.stringify({
+            name: input.manifest.name,
+            version: input.manifest.version ?? "0.0.0",
+            private: true,
+            dependencies,
+        }, null, 2));
+        if (input.lock !== undefined) {
+            const lock = JSON.parse(input.lock);
+            // Keep pinned package entries, but align the root with the filtered manifest.
+            if (lock.packages?.[""]) {
+                lock.packages[""] = {
+                    name: input.manifest.name,
+                    version: input.manifest.version ?? "0.0.0",
+                    dependencies,
+                };
+            }
+            if (lock.packages) {
+                for (const path of Object.keys(lock.packages)) {
+                    // Drop supplied packages and their private graphs at any nesting depth.
+                    if (path
+                        .split(/(?:^|\/)node_modules\//)
+                        .slice(1)
+                        .some(supplied))
+                        delete lock.packages[path];
+                }
+            }
+            if (lock.dependencies)
+                stripSuppliedDependencies(lock.dependencies);
+            await writeFile(join(input.directory, "package-lock.json"), JSON.stringify(lock, null, 2));
+        }
+        const install = () => (options.installer ?? npmDependencyInstaller)({
+            command: process.platform === "win32" ? "npm.cmd" : "npm",
+            args: [
+                "install",
+                "--omit=dev",
+                "--omit=peer",
+                "--ignore-scripts",
+                "--no-audit",
+                "--no-fund",
+            ],
+            cwd: input.directory,
+            ...(options.onLog ? { onLog: options.onLog } : {}),
+        });
+        if (Object.keys(dependencies).length)
+            await install();
+        const additions = {};
+        for (let pass = 0; pass < 2; pass++) {
+            const peers = await requiredPeerAdditions(input.directory, input.lock, options.onLog);
+            let changed = false;
+            for (const [name, range] of Object.entries(peers)) {
+                if (name in input.dependencies || additions[name] === range) {
+                    options.onLog?.(`Warning: unresolved required peer ${name} (${range}).`);
+                    continue;
+                }
+                dependencies[name] = additions[name] = range;
+                changed = true;
+            }
+            if (!changed)
+                break;
+            const path = join(input.directory, "package.json");
+            const manifest = JSON.parse(await readFile(path, "utf8"));
+            await writeFile(path, JSON.stringify({ ...manifest, dependencies }, null, 2));
+            try {
+                await install();
+            }
+            catch (error) {
+                options.onLog?.(`Warning: required peer installation failed: ${String(error)}`);
+                break;
+            }
+        }
+        for (const [name, range] of Object.entries(await requiredPeerAdditions(input.directory, input.lock)))
+            options.onLog?.(`Warning: unresolved required peer ${name} (${range}).`);
+        status.key = installKey(input.baseKey, additions);
+        await writeFile(join(input.directory, "peer-additions.json"), JSON.stringify(additions));
+        await writeFile(join(input.directory, "key"), status.key);
+        return status;
+    }
+    catch (error) {
+        await rm(input.directory, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/install-peers.d.ts

@@ -0,0 +1,3 @@
+export declare function supplied(name: string): boolean;
+/** Disk-only peer discovery. npm remains responsible for fetching selected versions. */
+export declare function requiredPeerAdditions(directory: string, lock: string | undefined, onLog?: (message: string) => void): Promise<Record<string, string>>;

package/dist/install-peers.js

@@ -0,0 +1,120 @@
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { Range, minVersion, rcompare, satisfies, valid } from "semver";
+export function supplied(name) {
+    return name === "@raycast/api" || /^react(?:\/|$)/.test(name) || name.startsWith("@types/");
+}
+async function manifest(directory) {
+    try {
+        return JSON.parse(await readFile(join(directory, "package.json"), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function* packages(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    for (const entry of entries.toSorted((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.name.startsWith("."))
+            continue;
+        const path = join(directory, entry.name);
+        if (entry.name.startsWith("@")) {
+            yield* packages(path);
+        }
+        else if (entry.isDirectory() || entry.isSymbolicLink()) {
+            yield path;
+            // Do not follow local-package symlinks into unrelated dependency trees.
+            if (entry.isDirectory())
+                yield* packages(join(path, "node_modules"));
+        }
+    }
+}
+function lockedVersions(lock, name) {
+    if (lock === undefined)
+        return [];
+    const parsed = JSON.parse(lock);
+    const versions = new Set();
+    for (const [path, entry] of Object.entries(parsed.packages ?? {})) {
+        if (path === `node_modules/${name}` || path.endsWith(`/node_modules/${name}`)) {
+            const version = entry.version;
+            if (version && valid(version))
+                versions.add(version);
+        }
+    }
+    const visit = (dependencies) => {
+        for (const [key, entry] of Object.entries(dependencies)) {
+            if (key === name && entry.version && valid(entry.version))
+                versions.add(entry.version);
+            if (entry.dependencies)
+                visit(entry.dependencies);
+        }
+    };
+    visit(parsed.dependencies ?? {});
+    return [...versions].toSorted(rcompare);
+}
+/** Intersect comparator sets, including each branch of union ranges. */
+function intersection(ranges) {
+    let combinations = [""];
+    for (const range of ranges) {
+        const sets = new Range(range).set;
+        combinations = combinations.flatMap((left) => sets.map((set) => `${left} ${set.map((item) => item.value).join(" ")}`.trim()));
+    }
+    const possible = combinations.filter((range) => {
+        const minimum = minVersion(range);
+        return minimum !== null && ranges.every((constraint) => satisfies(minimum, constraint));
+    });
+    return possible.length ? possible.join(" || ") || "*" : undefined;
+}
+/** Disk-only peer discovery. npm remains responsible for fetching selected versions. */
+export async function requiredPeerAdditions(directory, lock, onLog) {
+    const required = new Map();
+    for await (const path of packages(join(directory, "node_modules"))) {
+        const pkg = await manifest(path);
+        for (const [name, range] of Object.entries(pkg?.peerDependencies ?? {})) {
+            if (supplied(name) || pkg.peerDependenciesMeta?.[name]?.optional === true)
+                continue;
+            const peer = required.get(name) ?? { ranges: new Set(), missing: false };
+            peer.ranges.add(String(range));
+            let installed;
+            for (let ancestor = path;; ancestor = dirname(ancestor)) {
+                installed = await manifest(join(ancestor, "node_modules", name));
+                if (installed || ancestor === directory)
+                    break;
+            }
+            try {
+                peer.missing ||= !installed?.version || !satisfies(installed.version, String(range));
+            }
+            catch {
+                peer.missing = true;
+            }
+            required.set(name, peer);
+        }
+    }
+    const additions = {};
+    for (const [name, peer] of [...required].toSorted(([a], [b]) => a.localeCompare(b))) {
+        if (!peer.missing)
+            continue;
+        const ranges = [...peer.ranges].toSorted();
+        try {
+            const range = intersection(ranges);
+            if (range === undefined)
+                throw new Error("conflicting ranges");
+            additions[name] =
+                lockedVersions(lock, name).find((version) => satisfies(version, range)) ?? range;
+        }
+        catch {
+            onLog?.(`Warning: cannot resolve required peer ${name} (${ranges.join("; ")}).`);
+        }
+    }
+    return additions;
+}

package/dist/oauth.d.ts

@@ -0,0 +1,4 @@
+import type { CapabilityHandler } from "./broker.js";
+import { type StorageOptions } from "./storage.js";
+export declare function oauthTokenFile(options: StorageOptions): string;
+export declare function createOAuthHandlers(options: StorageOptions): Record<string, CapabilityHandler>;

package/dist/oauth.js

@@ -0,0 +1,99 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { defaultDataDir, storageFile } from "./storage.js";
+// Shared by sessions in this host process to serialize read/modify/write cycles.
+const queues = new Map();
+export function oauthTokenFile(options) {
+    return storageFile(join(options.dataDir ?? defaultDataDir(), "oauth"), options.extensionName);
+}
+export function createOAuthHandlers(options) {
+    const file = oauthTokenFile(options);
+    const serialize = (operation) => {
+        const next = (queues.get(file) ?? Promise.resolve()).then(operation, operation);
+        queues.set(file, next);
+        void next
+            .finally(() => {
+            if (queues.get(file) === next)
+                queues.delete(file);
+        })
+            .catch(() => undefined);
+        return next;
+    };
+    const read = async () => {
+        try {
+            const value = JSON.parse(await readFile(file, "utf8"));
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                throw new Error("Invalid OAuth token store");
+            return value;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return {};
+            throw new Error("Cannot read OAuth token store", { cause: error });
+        }
+    };
+    const write = async (value) => {
+        await mkdir(dirname(file), { recursive: true });
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify(value), { mode: 0o600 });
+            await rename(temporary, file);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    };
+    const handler = (operation) => (params) => serialize(async () => {
+        if (!params ||
+            typeof params !== "object" ||
+            Array.isArray(params) ||
+            typeof params.providerId !== "string" ||
+            !params.providerId)
+            throw new Error("OAuth providerId must be a non-empty string");
+        const key = params.providerId;
+        const items = await read();
+        if (operation === "get")
+            return Object.hasOwn(items, key) ? items[key] : null;
+        if (operation === "remove")
+            delete items[key];
+        else {
+            const tokens = params.tokens;
+            if (!tokens ||
+                typeof tokens !== "object" ||
+                Array.isArray(tokens) ||
+                typeof tokens.accessToken !== "string")
+                throw new Error("Invalid OAuth token set");
+            for (const field of ["refreshToken", "idToken", "scope"])
+                if (tokens[field] !== undefined && typeof tokens[field] !== "string")
+                    throw new Error("Invalid OAuth token set");
+            if (params.revocationEndpoint !== undefined &&
+                (typeof params.revocationEndpoint !== "string" || params.revocationEndpoint === ""))
+                throw new Error("Invalid OAuth revocation endpoint");
+            if (tokens.expiresIn !== undefined &&
+                (typeof tokens.expiresIn !== "number" || !Number.isFinite(tokens.expiresIn)))
+                throw new Error("Invalid OAuth token expiry");
+            const stored = {
+                accessToken: tokens.accessToken,
+                updatedAt: new Date().toISOString(),
+            };
+            for (const field of ["refreshToken", "idToken", "scope", "expiresIn"])
+                if (tokens[field] !== undefined)
+                    stored[field] = tokens[field];
+            if (params.revocationEndpoint !== undefined)
+                stored.revocationEndpoint = params.revocationEndpoint;
+            Object.defineProperty(items, key, {
+                value: stored,
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+        await write(items);
+    });
+    return {
+        "oauth.tokens.get": handler("get"),
+        "oauth.tokens.set": handler("set"),
+        "oauth.tokens.remove": handler("remove"),
+    };
+}

package/dist/preferences.d.ts

@@ -0,0 +1,15 @@
+import { type StorageItems, type StorageOptions } from "./storage.js";
+type Preferences = {
+    extension: StorageItems;
+    commands: Record<string, StorageItems>;
+};
+export declare function preferenceFile(dataDir: string, extensionName: string): string;
+/** Plaintext preferences, isolated by extension and command, atomically saved as 0600. */
+export declare function createPreferenceStore(options: StorageOptions): {
+    read: () => Promise<Preferences>;
+    values: (command: string) => Promise<{
+        [x: string]: import("./storage.js").StorageValue;
+    }>;
+    save: (extension: StorageItems, command: string, values: StorageItems) => Promise<void>;
+};
+export {};

package/dist/preferences.js

@@ -0,0 +1,61 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, basename } from "node:path";
+import { randomUUID } from "node:crypto";
+import { defaultDataDir, storageFile, isStorageValue, } from "./storage.js";
+function items(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every(isStorageValue));
+}
+export function preferenceFile(dataDir, extensionName) {
+    return join(dataDir, "preferences", basename(storageFile(dataDir, extensionName)));
+}
+/** Plaintext preferences, isolated by extension and command, atomically saved as 0600. */
+export function createPreferenceStore(options) {
+    const file = preferenceFile(options.dataDir ?? defaultDataDir(), options.extensionName);
+    const read = async () => {
+        try {
+            const value = JSON.parse(await readFile(file, "utf8"));
+            if (!value ||
+                !items(value.extension) ||
+                !value.commands ||
+                typeof value.commands !== "object" ||
+                Array.isArray(value.commands) ||
+                !Object.values(value.commands).every(items))
+                throw new Error("Invalid preferences file");
+            return value;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { extension: {}, commands: {} };
+            throw error;
+        }
+    };
+    return {
+        read,
+        values: async (command) => {
+            const stored = await read();
+            return { ...stored.extension, ...stored.commands[command] };
+        },
+        save: async (extension, command, values) => {
+            if (![...Object.values(extension), ...Object.values(values)].every(isStorageValue))
+                throw new Error("Invalid preference value");
+            const stored = await read();
+            stored.extension = { ...stored.extension, ...extension };
+            stored.commands = {
+                ...stored.commands,
+                [command]: { ...stored.commands[command], ...values },
+            };
+            await mkdir(dirname(file), { recursive: true });
+            const temporary = `${file}.${randomUUID()}.tmp`;
+            try {
+                await writeFile(temporary, `${JSON.stringify(stored, null, 2)}\n`, { mode: 0o600 });
+                await rename(temporary, file);
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        },
+    };
+}

package/dist/provider.d.ts

@@ -0,0 +1,15 @@
+import { type ModelRequest, type ModelStreamPart, type RegisteredModel } from "@blastlauncher/protocol";
+import { type StartOptions } from "./session.js";
+export declare function startModelProvider(options: Omit<StartOptions, "broker" | "providerResponse"> & {
+    broker?: StartOptions["broker"];
+}): Promise<{
+    shutdown: (options?: {
+        timeoutMs?: number;
+    }) => Promise<import("./session.js").Exit>;
+    exited: Promise<import("./session.js").Exit>;
+    logs: readonly import("@blastlauncher/protocol").LogMessage[];
+    getModels(): Promise<RegisteredModel[]>;
+    stream(model: RegisteredModel, request: ModelRequest, { signal }?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<ModelStreamPart>;
+}>;

package/dist/provider.js

@@ -0,0 +1,102 @@
+import { encodeModelRequest, } from "@blastlauncher/protocol";
+import { createBroker } from "./broker.js";
+import { startCommand } from "./session.js";
+export async function startModelProvider(options) {
+    let nextId = 0;
+    let closed = false;
+    const pending = new Map();
+    const session = await startCommand({
+        ...options,
+        mode: "model-provider",
+        broker: options.broker ?? createBroker({}),
+        providerResponse(message) {
+            pending.get(message.id)?.(message);
+        },
+    });
+    void session.exited.then((exit) => {
+        closed = true;
+        for (const receive of pending.values())
+            receive(exit.error ?? new Error("Model provider exited"));
+        pending.clear();
+    });
+    return {
+        shutdown: session.shutdown,
+        exited: session.exited,
+        logs: session.logs,
+        getModels() {
+            if (closed)
+                return Promise.reject(new Error("Model provider exited"));
+            const id = String(++nextId);
+            return new Promise((resolve, reject) => {
+                pending.set(id, (message) => {
+                    pending.delete(id);
+                    if (message instanceof Error)
+                        reject(message);
+                    else if (message.type === "provider.models")
+                        resolve(message.models);
+                    else if (message.type === "provider.error")
+                        reject(Object.assign(new Error(message.error.message), { code: message.error.code }));
+                    else
+                        reject(new Error("Unexpected model provider response"));
+                });
+                session.sendProvider({ type: "provider.getModels", id });
+            });
+        },
+        async *stream(model, request, { signal } = {}) {
+            if (closed)
+                throw new Error("Model provider exited");
+            const id = String(++nextId);
+            const queue = [];
+            let done = false;
+            let failure;
+            let wake;
+            const abort = () => {
+                failure = new DOMException("The operation was aborted", "AbortError");
+                session.sendProvider({ type: "provider.abort", id });
+                wake?.();
+            };
+            if (signal?.aborted)
+                throw new DOMException("The operation was aborted", "AbortError");
+            pending.set(id, (message) => {
+                if (message instanceof Error)
+                    failure = message;
+                else if (message.type === "provider.error")
+                    failure = Object.assign(new Error(message.error.message), { code: message.error.code });
+                else if (message.type === "provider.part")
+                    queue.push(message.part);
+                else if (message.type === "provider.end")
+                    done = true;
+                else
+                    failure = new Error("Unexpected model provider response");
+                wake?.();
+            });
+            signal?.addEventListener("abort", abort, { once: true });
+            try {
+                session.sendProvider({
+                    type: "provider.stream",
+                    id,
+                    model,
+                    request: encodeModelRequest(request),
+                });
+                while (true) {
+                    if (failure)
+                        throw failure;
+                    if (queue.length)
+                        yield queue.shift();
+                    else if (done)
+                        return;
+                    else
+                        await new Promise((resolve) => {
+                            wake = resolve;
+                        });
+                }
+            }
+            finally {
+                pending.delete(id);
+                signal?.removeEventListener("abort", abort);
+                if (!done)
+                    session.sendProvider({ type: "provider.abort", id });
+            }
+        },
+    };
+}

package/dist/session.d.ts

@@ -0,0 +1,44 @@
+import { type ProviderRequest, type ProviderResponse, type InitEnvironment, type JsonValue, type LogMessage, type SceneMessage } from "@blastlauncher/protocol";
+import type { Broker } from "./broker.js";
+import type { BundledCommand } from "./bundle.js";
+export type StartOptions = Omit<BundledCommand, "bundleMs"> & {
+    broker: Broker;
+    providerResponse?: (message: ProviderResponse) => void;
+    dataDir?: string;
+    preferences?: Record<string, JsonValue>;
+    environment?: InitEnvironment;
+    availableAPIs?: InitEnvironment["availableAPIs"];
+    /** Manifest argument values for this launch, keyed by argument name. */
+    argumentValues?: Record<string, string>;
+    /** The `launchCommand` context, when another command started this one. */
+    launchContext?: Record<string, JsonValue>;
+    fallbackText?: string;
+    nodePath?: string;
+    handshakeTimeoutMs?: number;
+    /** Child environment; defaults to {@link runtimeEnvironment} (an allowlist, not `process.env`). */
+    env?: Record<string, string>;
+    /** Oldest log entries are dropped beyond this many. */
+    maxLogs?: number;
+};
+export declare function runtimeEnvironment(source?: NodeJS.ProcessEnv): Record<string, string>;
+export type Exit = {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    error?: Error;
+};
+export type Session = {
+    readonly latestScene: SceneMessage | undefined;
+    readonly logs: readonly LogMessage[];
+    /** Subscribe to log lines as they arrive (no replay); returns unsubscribe. */
+    onLog(callback: (log: LogMessage) => void): () => void;
+    /** Subscribe to snapshots; immediately replays the latest one if present. */
+    scenes(callback: (scene: SceneMessage) => void): () => void;
+    sendProvider(message: ProviderRequest): void;
+    sendEvent(node: string, handler: string, args: JsonValue[]): void;
+    shutdown(options?: {
+        timeoutMs?: number;
+    }): Promise<Exit>;
+    exited: Promise<Exit>;
+};
+/** Resolves after the version handshake. Startup failures reject only after child cleanup. */
+export declare function startCommand(options: StartOptions): Promise<Session>;