@node-agent/local 0.0.0-stage → 0.1.0

package/dist/proxy.js

@@ -0,0 +1,336 @@
+// node-agent: the optional built-in proxy — one token, one login page, one door in front of the page.
+//
+// Off unless serve.ts is given NODE_AGENT_ACCESS_TOKEN: with it unset this module is never called, no
+// port is opened and the loopback behaviour of the entry is exactly what it was.
+//
+//   GET  /login      the form (inline HTML, so the package carries no extra asset)
+//   POST /login      the token; on a match, one HttpOnly cookie holding sha256(token)
+//   GET  /healthz    liveness, always open, never proxied
+//   everything else  the cookie or `Authorization: Bearer <token>`, then piped to the upstream
+//
+// The cookie never carries the token, comparisons are constant time, `/bus` (WebSocket upgrade) and
+// `/events` (SSE) are piped rather than buffered, and the upstream is fixed — this cannot become an
+// open proxy. TLS is not here: put your own terminator in front (a reverse proxy, a tunnel, or the
+// Caddy of deploy/docker-compose.yml's `public` profile) and set NODE_AGENT_PROXY_SECURE=1 so the
+// cookie is marked Secure. One token is one user.
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { connect } from 'node:net';
+import { createServer, request as sendRequest, } from 'node:http';
+/** The cookie a successful login hands out. Its value is sha256(token) in hex, never the token. */
+export const COOKIE_NAME = 'node_agent_access';
+/** How long a login lasts, in seconds (30 days), the same as the gateway's cookie. */
+export const COOKIE_MAX_AGE = 2_592_000;
+/**
+ * Headers that belong to one connection and must not be forwarded. `cookie` and `host` are handled
+ * separately: the browser's cookie is this door's business, not the stack's.
+ */
+const HOP_BY_HOP = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+const LOGIN_PAGE = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>node-agent</title>
+    <style>
+      :root { color-scheme: light dark; }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        font: 15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif;
+        background: Canvas;
+        color: CanvasText;
+      }
+      form { width: min(22rem, 90vw); }
+      h1 { font-size: 1.1rem; margin: 0 0 0.25rem; }
+      p { margin: 0 0 1.25rem; opacity: 0.7; }
+      label { display: block; margin-bottom: 0.35rem; }
+      input {
+        width: 100%;
+        box-sizing: border-box;
+        padding: 0.6rem 0.7rem;
+        border: 1px solid color-mix(in srgb, CanvasText 25%, transparent);
+        border-radius: 0.5rem;
+        background: Canvas;
+        color: inherit;
+        font: inherit;
+      }
+      button {
+        margin-top: 0.75rem;
+        width: 100%;
+        padding: 0.6rem 0.7rem;
+        border: 0;
+        border-radius: 0.5rem;
+        background: color-mix(in srgb, CanvasText 88%, transparent);
+        color: Canvas;
+        font: inherit;
+        font-weight: 600;
+        cursor: pointer;
+      }
+      .error:empty { display: none; }
+      .error { margin-top: 0.75rem; color: #c0392b; }
+    </style>
+  </head>
+  <body>
+    <form method="post" action="/login">
+      <h1>node-agent</h1>
+      <p>This stack belongs to one person. Enter its token to open it.</p>
+      <label for="token">Token</label>
+      <input id="token" name="token" type="password" autocomplete="current-password"
+        autofocus required />
+      <button type="submit">Open</button>
+      <div class="error"><!--error--></div>
+    </form>
+  </body>
+</html>
+`;
+function page(error = '') {
+    return LOGIN_PAGE.replace('<!--error-->', error);
+}
+/** The one comparison both the cookie and the bearer token go through. */
+function sameDigest(expected, presented) {
+    const digest = createHash('sha256').update(presented).digest();
+    return digest.length === expected.length && timingSafeEqual(digest, expected);
+}
+function sameHex(expected, presentedHex) {
+    const presented = Buffer.from(presentedHex, 'hex');
+    return presented.length === expected.length && timingSafeEqual(presented, expected);
+}
+function cookieOf(req) {
+    for (const part of (req.headers.cookie ?? '').split(';')) {
+        const [name, ...rest] = part.trim().split('=');
+        if (name === COOKIE_NAME)
+            return rest.join('=');
+    }
+    return '';
+}
+function bearerOf(req) {
+    const header = req.headers.authorization ?? '';
+    const [scheme, ...rest] = header.trim().split(/\s+/);
+    if (scheme?.toLowerCase() !== 'bearer')
+        return '';
+    return rest.join(' ');
+}
+/** A request may prove itself with the cookie (browsers) or a bearer token (scripts). */
+function allowed(req, expected) {
+    const cookie = cookieOf(req);
+    if (cookie !== '' && sameHex(expected, cookie))
+        return true;
+    const bearer = bearerOf(req);
+    return bearer !== '' && sameDigest(expected, bearer);
+}
+function body(req, limit = 8_192) {
+    return new Promise((resolve, reject) => {
+        let text = '';
+        req.setEncoding('utf8');
+        req.on('data', (chunk) => {
+            text += chunk;
+            if (text.length > limit)
+                reject(new Error('body too large'));
+        });
+        req.on('end', () => resolve(text));
+        req.on('error', reject);
+    });
+}
+/** Whatever the request carried, the stack behind the door sees only its own headers. */
+function forwardHeaders(req, host) {
+    const named = (req.headers.connection ?? '')
+        .split(',')
+        .map((one) => one.trim().toLowerCase())
+        .filter((one) => one !== '');
+    const drop = new Set([...HOP_BY_HOP, ...named, 'cookie', 'host']);
+    const headers = { host };
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined || drop.has(name.toLowerCase()))
+            continue;
+        headers[name] = value;
+    }
+    return headers;
+}
+/** Response headers travel as they are, minus what belongs to this hop, so pipes stay unbuffered. */
+function replyHeaders(answer) {
+    const headers = {};
+    for (const [name, value] of Object.entries(answer.headers)) {
+        if (value === undefined || HOP_BY_HOP.has(name.toLowerCase()))
+            continue;
+        headers[name] = value;
+    }
+    return headers;
+}
+/**
+ * Start the door. The upstream is fixed at start time; nothing in a request can move it, and an
+ * absolute-form request line (`GET http://elsewhere/`) is refused rather than resolved.
+ */
+export async function startProxy(options) {
+    const token = options.token.trim();
+    if (token === '')
+        throw new Error('startProxy needs a token');
+    const bind = options.bind?.trim() || '127.0.0.1';
+    const port = options.port ?? 8080;
+    const secure = options.secure === true;
+    const upstream = new URL(options.upstream);
+    const upstreamHost = upstream.hostname;
+    const upstreamPort = Number(upstream.port || (upstream.protocol === 'https:' ? 443 : 80));
+    const expected = createHash('sha256').update(token).digest();
+    async function login(req, res) {
+        if (req.method === 'GET' || req.method === 'HEAD') {
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(page());
+            return;
+        }
+        if (req.method !== 'POST') {
+            res.writeHead(405, { allow: 'GET, HEAD, POST' }).end();
+            return;
+        }
+        const form = new URLSearchParams(await body(req));
+        if (!sameDigest(expected, form.get('token') ?? '')) {
+            res
+                .writeHead(401, { 'content-type': 'text/html; charset=utf-8' })
+                .end(page('That token was not the one.'));
+            return;
+        }
+        const attributes = ['Path=/', 'HttpOnly', 'SameSite=Lax', `Max-Age=${COOKIE_MAX_AGE}`];
+        if (secure)
+            attributes.push('Secure');
+        res
+            .writeHead(303, {
+            'set-cookie': `${COOKIE_NAME}=${expected.toString('hex')}; ${attributes.join('; ')}`,
+            location: '/',
+            'content-type': 'text/plain; charset=utf-8',
+            'cache-control': 'no-store',
+        })
+            .end('ok\n');
+    }
+    function proxy(req, res) {
+        const outbound = sendRequest({
+            protocol: upstream.protocol,
+            host: upstreamHost,
+            port: upstreamPort,
+            method: req.method,
+            path: req.url,
+            headers: forwardHeaders(req, upstream.host),
+        }, (answer) => {
+            res.writeHead(answer.statusCode ?? 502, replyHeaders(answer));
+            // pipe, never buffer: /events is a long-lived connection and must reach the browser as it
+            // is written, not when it ends.
+            answer.pipe(res);
+            answer.on('error', () => res.destroy());
+        });
+        outbound.on('error', () => {
+            if (!res.headersSent)
+                res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('the stack behind this door is not answering\n');
+        });
+        res.on('close', () => {
+            if (!res.writableFinished)
+                outbound.destroy();
+        });
+        req.pipe(outbound);
+    }
+    /** A WebSocket (or any upgrade) is piped byte for byte: the gate is the cookie, not the frames. */
+    function tunnel(req, socket, head) {
+        const upstreamSocket = connect(upstreamPort, upstreamHost, () => {
+            const lines = [`${req.method} ${req.url} HTTP/1.1`];
+            for (const [name, value] of Object.entries(req.headers)) {
+                // The upgrade's own hop-by-hop headers are the protocol here, so only the cookie goes.
+                if (name === 'cookie' || name === 'host')
+                    continue;
+                for (const one of Array.isArray(value) ? value : [value ?? '']) {
+                    lines.push(`${name}: ${one}`);
+                }
+            }
+            lines.push(`host: ${upstream.host}`);
+            upstreamSocket.write(`${lines.join('\r\n')}\r\n\r\n`);
+            if (head.length > 0)
+                upstreamSocket.write(head);
+            socket.pipe(upstreamSocket).pipe(socket);
+        });
+        upstreamSocket.on('error', () => socket.destroy());
+        socket.on('error', () => upstreamSocket.destroy());
+        // An upgraded socket is no longer the server's to close, so the pair is closed here.
+        socket.on('close', () => upstreamSocket.destroy());
+        upstreamSocket.on('close', () => socket.destroy());
+    }
+    // Every socket is kept so close() can end the long-lived ones (SSE, WebSocket) instead of waiting
+    // for a stream that by design never ends.
+    const sockets = new Set();
+    const server = createServer((req, res) => {
+        const path = (req.url ?? '/').split('?')[0] ?? '/';
+        // A door, not a proxy: `GET http://elsewhere/` would otherwise be forwarded as written. The
+        // client would have to know the token first, but a fixed upstream is the promise here.
+        if (path.startsWith('//') || /^https?:/i.test(req.url ?? '')) {
+            res.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' }).end('fixed upstream\n');
+            req.resume();
+            return;
+        }
+        if (path === '/login') {
+            login(req, res).catch(() => {
+                if (!res.headersSent)
+                    res.writeHead(400, { 'content-type': 'text/plain' });
+                res.end('bad request\n');
+            });
+            return;
+        }
+        if (path === '/healthz') {
+            res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' }).end('ok\n');
+            req.resume();
+            return;
+        }
+        if (!allowed(req, expected)) {
+            // Browsers get the page; anything else (a script, a fetch) gets the status instead of a
+            // redirect it cannot follow.
+            if (req.method === 'GET' || req.method === 'HEAD') {
+                res.writeHead(303, { location: '/login', 'cache-control': 'no-store' }).end();
+            }
+            else {
+                res.writeHead(401, { 'content-type': 'text/plain; charset=utf-8' }).end('unauthorized\n');
+            }
+            req.resume();
+            return;
+        }
+        proxy(req, res);
+    });
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.on('close', () => sockets.delete(socket));
+    });
+    server.on('upgrade', (req, socket, head) => {
+        if (!allowed(req, expected)) {
+            socket.end('HTTP/1.1 401 Unauthorized\r\nconnection: close\r\n\r\n');
+            return;
+        }
+        tunnel(req, socket, head);
+    });
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, bind, () => {
+            server.removeListener('error', reject);
+            const address = server.address();
+            const bound = address?.port ?? port;
+            const host = bind.includes(':') ? `[${bind}]` : bind;
+            resolve({
+                url: `http://${host}:${bound}`,
+                bind,
+                port: bound,
+                close: () => new Promise((done, fail) => {
+                    // An SSE stream never ends on its own, so closing must end it rather than wait for it.
+                    for (const socket of sockets)
+                        socket.destroy();
+                    sockets.clear();
+                    server.closeAllConnections();
+                    server.close((error) => (error === undefined ? done() : fail(error)));
+                }),
+            });
+        });
+    });
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"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"}

package/dist/runtime/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LKJacky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/runtime/base.d.ts

@@ -0,0 +1,101 @@
+export type RuntimeState = 'starting' | 'running' | 'stopped' | 'failed';
+export type Env = Record<string, string | undefined>;
+/** A small logger, so a runtime can be used from a process that already has one. */
+export interface RuntimeLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+export interface RuntimeServerOptions {
+    /** Runtime-owned state (users, packages). Defaults to `<NODE_AGENT_HOME>/runtime`. */
+    home?: string;
+    /** Address the user's bus listens on. Defaults to loopback. */
+    host?: string;
+    /** Base port for allocation. 0 (the default) asks the OS for a free port. */
+    basePort?: number;
+    /** How many ports above basePort may be tried. Defaults to 100. */
+    portSpan?: number;
+    /** Token used for the bus. A runtime-generated token is used when unset. */
+    token?: string;
+    /** Extra environment for every child, after the runtime's own defaults. */
+    env?: Env;
+    /** Node binary. Defaults to process.execPath. */
+    nodeBinary?: string;
+    /** How a node is isolated: a worker thread in this runtime process, or a child process.
+     *  Worker is the default, so a personal stack is one OS process: bus + every default node. */
+    isolation?: 'worker' | 'process';
+    logger?: RuntimeLogger;
+}
+export interface BusOptions {
+    host?: string;
+    port?: number;
+    token?: string;
+    env?: Env;
+}
+export interface NodeOptions {
+    /** Package root or package name. Defaults to `node` itself. */
+    dir?: string;
+    /** Bus name. Defaults to the package's `node.id`. */
+    name?: string;
+    /** Extra environment for this node only. */
+    env?: Env;
+    /** Extra command line arguments. */
+    args?: readonly string[];
+}
+export interface UserHandle {
+    readonly user: string;
+    readonly home: string;
+    state: 'ready' | 'removed';
+}
+export interface BusHandle {
+    readonly kind: 'bus';
+    readonly host: string;
+    readonly port: number;
+    readonly url: string;
+    readonly token: string;
+    readonly pid: number | undefined;
+    state: RuntimeState;
+    /** Stop this bus. Nodes on it are stopped first. */
+    stop(): Promise<void>;
+}
+export interface NodeHandle {
+    readonly kind: 'node';
+    readonly name: string;
+    readonly version: string;
+    readonly dir: string;
+    readonly pid: number | undefined;
+    state: RuntimeState;
+    /** Stop this node. */
+    stop(): Promise<void>;
+}
+/** The runtime server interface. Every method is async; there is no synchronous twin. */
+export interface Runtime {
+    /** Create a user's persistent home. Idempotent. */
+    createUser(user: string): Promise<UserHandle>;
+    /** Stop the user's bus and nodes, then remove the user's home. Idempotent. */
+    destroyUser(user: string): Promise<void>;
+    /** Start the shared bus; returns the existing one when it is already running. */
+    launchBus(options?: BusOptions): Promise<BusHandle>;
+    /** Stop the shared bus and every node still on it. Idempotent. */
+    stopBus(): Promise<void>;
+    /** Start one shared node against the bus, creating the bus when needed. */
+    launchNode(node: string, options?: NodeOptions): Promise<NodeHandle>;
+    /** Stop one shared node. Idempotent. */
+    stopNode(node: string): Promise<void>;
+    /** Compose: ensure the bus and node, then connect that user to the node. */
+    connect(user: string, node: string, options?: NodeOptions): Promise<NodeHandle>;
+    /** Compose: remove the user's access. The shared node and bus stay up. */
+    disconnect(user: string, node: string): Promise<void>;
+    /** One user's table, or every user's table when no user is named. */
+    sessions(user?: string): Promise<Record<string, unknown>>;
+}
+export type RuntimeErrorCode = 'invalid_user' | 'invalid_node' | 'bus_not_running' | 'bus_start_failed' | 'node_not_running' | 'node_start_failed' | 'package_failed' | 'spawn_failed';
+/** A refusal a caller can show: code is stable, message is for a human. */
+export declare class RuntimeError extends Error {
+    readonly code: RuntimeErrorCode;
+    constructor(code: RuntimeErrorCode, message: string);
+}
+/** A user name is also a directory name: refuse anything that could escape one. */
+export declare function userName(value: string): string;
+/** A node name is a bus name: same rule the package manifest is held to. */
+export declare function nodeName(value: string): string;

package/dist/runtime/base.js

@@ -0,0 +1,32 @@
+// The runtime contract: a server that owns one shared bus and the nodes on it.
+//
+// The interface is deliberately small. A runtime creates and stops two kinds of process — a bus and
+// shared nodes — while a user is only an access relation: connect(user, node) ensures both exist and
+// adds the node to that user's table; disconnect(user, node) removes only the relation.
+//
+// Everything here is transport-neutral. LocalRuntime uses worker threads by default; a remote
+// implementation can implement the same methods over HTTP without changing a caller.
+/** A refusal a caller can show: code is stable, message is for a human. */
+export class RuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'RuntimeError';
+        this.code = code;
+    }
+}
+const USER = /^[a-z][a-z0-9_-]{0,62}$/;
+const NODE = /^[a-z][a-z0-9-]{0,62}$/;
+/** A user name is also a directory name: refuse anything that could escape one. */
+export function userName(value) {
+    if (!USER.test(value))
+        throw new RuntimeError('invalid_user', `not a user name: ${JSON.stringify(value)}`);
+    return value;
+}
+/** A node name is a bus name: same rule the package manifest is held to. */
+export function nodeName(value) {
+    if (!NODE.test(value))
+        throw new RuntimeError('invalid_node', `not a node name: ${JSON.stringify(value)}`);
+    return value;
+}
+//# sourceMappingURL=base.js.map

package/dist/runtime/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,oGAAoG;AACpG,qGAAqG;AACrG,wFAAwF;AACxF,EAAE;AACF,8FAA8F;AAC9F,qFAAqF;AAkHrF,2EAA2E;AAC3E,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAmB;IAEhC,YAAY,IAAsB,EAAE,OAAe;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,IAAI,GAAG,yBAAyB,CAAC;AACvC,MAAM,IAAI,GAAG,wBAAwB,CAAC;AAEtC,mFAAmF;AACnF,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QACnB,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,oBAAoB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACtF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QACnB,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,oBAAoB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACtF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export * from './base.js';
+export * from './server.js';

package/dist/runtime/index.js

@@ -0,0 +1,9 @@
+// @node-agent/runtime: the runtime contract and its HTTP surface.
+//
+//   base.ts    the interface (a bus, nodes, users as access relations)
+//   server.ts  RuntimeServer: the same interface over HTTP, so a runtime can live elsewhere
+//
+// The local, single-user implementation lives in the `node-agent` package.
+export * from './base.js';
+export * from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,uEAAuE;AACvE,4FAA4F;AAC5F,EAAE;AACF,2EAA2E;AAC3E,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}

package/dist/runtime/local.d.ts

@@ -0,0 +1,44 @@
+import { Bus } from 'node-agent-bus';
+import { type BusHandle, type BusOptions, type NodeHandle, type NodeOptions, type Runtime, type RuntimeServerOptions, type UserHandle } from './base.js';
+export declare class LocalRuntime implements Runtime {
+    /** One node launch at a time: two users asking at startup must not spawn the same shared node twice. */
+    private launchQueue;
+    private readonly options;
+    private readonly logger?;
+    private busRecord;
+    private readonly nodes;
+    private readonly knownUsers;
+    constructor(options?: RuntimeServerOptions);
+    /** The shared bus, once it is listening. Used by the process entry to print its user table. */
+    get bus(): Bus | undefined;
+    private home;
+    private nodeHome;
+    /** The bus never sees a display name: it sees a stable digest of the name. */
+    private busId;
+    busUser(user: string): string;
+    private tokenFor;
+    launchBus(options?: BusOptions): Promise<BusHandle>;
+    stopBus(): Promise<void>;
+    launchNode(node: string, options?: NodeOptions): Promise<NodeHandle>;
+    private launchNodeNow;
+    stopNode(node: string): Promise<void>;
+    createUser(user: string): Promise<UserHandle>;
+    destroyUser(user: string): Promise<void>;
+    connect(user: string, node: string, options?: NodeOptions): Promise<NodeHandle>;
+    disconnect(user: string, node: string): Promise<void>;
+    /** Every user this runtime has connected, and the shared nodes each one may reach. */
+    sessions(user?: string): Promise<Record<string, unknown>>;
+    /** The newest package the installer materialized for this user, if there is one. */
+    private installedPackage;
+    private nodeRunning;
+    /** Where the shared page node printed its address, if it has started yet. */
+    private webuiTarget;
+    /** The shared bus, for a trusted caller that has to proxy an outside node. */
+    busTarget(): {
+        url: string;
+        token: string;
+    } | undefined;
+    /** Recent stdout/stderr of one running node, for the entry process to surface its address. */
+    nodeOutput(node: string): string | undefined;
+    stopAll(): Promise<void>;
+}