@wpelevator/tug 0.3.0 → 0.5.0

package/dist/docker-api.js

@@ -0,0 +1,428 @@
+// Typed client for the Docker Engine API over the daemon's unix socket. The agent reconciles
+// containers through this seam instead of running the `docker` CLI; tests inject a fake `DockerApi`.
+import http from 'node:http';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+/** Oldest Engine API the agent speaks (Docker 20.10+, which the nested daemons in the integration tests run). */
+export const API_VERSION = 'v1.41';
+export const DEFAULT_SOCKET = '/var/run/docker.sock';
+/** An Engine API error; `status` is the HTTP status and `message` the daemon's own text. */
+export class DockerError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'DockerError';
+        this.status = status;
+    }
+}
+export const isNotFound = (error) => error instanceof DockerError && error.status === 404;
+/** Splits a reference into `fromImage` and `tag` for `POST /images/create`. */
+export function splitImageRef(ref) {
+    const digest = ref.indexOf('@');
+    if (digest >= 0) {
+        const name = ref.slice(0, digest);
+        const colon = name.lastIndexOf(':');
+        return {
+            fromImage: colon > name.lastIndexOf('/') ? name.slice(0, colon) : name,
+            tag: ref.slice(digest + 1),
+        };
+    }
+    const colon = ref.lastIndexOf(':');
+    if (colon > ref.lastIndexOf('/'))
+        return { fromImage: ref.slice(0, colon), tag: ref.slice(colon + 1) };
+    return { fromImage: ref, tag: 'latest' };
+}
+/**
+ * Splits the 8-byte-header multiplexed stream (`[stream, 0, 0, 0, size(4, big endian)]` frames) that
+ * non-TTY attach, exec and logs use into `stdout` and `stderr`. `end` fires once the source ends.
+ */
+export function demux(source, stdout, stderr) {
+    let buffer = Buffer.alloc(0);
+    source.on('data', (chunk) => {
+        buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
+        while (buffer.length >= 8) {
+            const size = buffer.readUInt32BE(4);
+            if (buffer.length < 8 + size)
+                break;
+            const frame = buffer.subarray(8, 8 + size);
+            (buffer[0] === 2 ? stderr : stdout).write(frame);
+            buffer = buffer.subarray(8 + size);
+        }
+    });
+    const end = () => {
+        stdout.end();
+        stderr.end();
+    };
+    source.on('end', end);
+    source.on('close', end);
+    source.on('error', (error) => {
+        stdout.destroy(error);
+        stderr.destroy();
+    });
+}
+function filtersParam(filter) {
+    const filters = {};
+    if (filter.label?.length)
+        filters.label = filter.label;
+    if (filter.ancestor)
+        filters.ancestor = [filter.ancestor];
+    if (filter.name)
+        filters.name = [filter.name];
+    return JSON.stringify(filters);
+}
+async function readBody(res) {
+    const chunks = [];
+    for await (const chunk of res)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** `unix:///path` or a bare path from `DOCKER_HOST`; the agent talks to the local daemon only. */
+export function socketFromEnv(env = process.env) {
+    const host = env.DOCKER_HOST;
+    if (!host)
+        return DEFAULT_SOCKET;
+    if (host.startsWith('unix://'))
+        return host.slice('unix://'.length);
+    throw new Error(`unsupported DOCKER_HOST ${host} (the agent uses the local unix socket)`);
+}
+export class DockerEngine {
+    socketPath;
+    constructor(socketPath = socketFromEnv()) {
+        this.socketPath = socketPath;
+    }
+    request(method, path, options = {}) {
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries(options.query || {}))
+            if (value !== undefined)
+                query.set(key, value);
+        const qs = query.size ? `?${query}` : '';
+        return new Promise((resolve, reject) => {
+            const headers = { ...options.headers };
+            let payload;
+            if (options.body !== undefined) {
+                payload = Buffer.from(JSON.stringify(options.body));
+                headers['content-type'] = 'application/json';
+                headers['content-length'] = String(payload.length);
+            }
+            const req = http.request({ socketPath: this.socketPath, method, path: `/${API_VERSION}${path}${qs}`, headers }, resolve);
+            req.on('error', reject);
+            if (payload)
+                req.end(payload);
+            else if (Buffer.isBuffer(options.stream))
+                req.end(options.stream);
+            else if (options.stream) {
+                options.stream.on('error', (error) => req.destroy(error));
+                options.stream.pipe(req);
+            }
+            else
+                req.end();
+        });
+    }
+    /** Reads the response; non-2xx becomes a `DockerError` carrying the daemon's message. */
+    async call(method, path, options) {
+        const res = await this.request(method, path, options);
+        const text = await readBody(res);
+        const status = res.statusCode || 0;
+        if (status >= 200 && status < 300)
+            return text;
+        let message = text.trim();
+        try {
+            message = JSON.parse(text).message || message;
+        }
+        catch {
+            /* not JSON */
+        }
+        throw new DockerError(status, message || `Docker API ${method} ${path}: HTTP ${status}`);
+    }
+    async json(method, path, options) {
+        const text = await this.call(method, path, options);
+        return (text ? JSON.parse(text) : undefined);
+    }
+    /** Consumes the JSON-lines progress stream of pull and load; a line with `error` fails the call. */
+    async progress(res, what) {
+        const status = res.statusCode || 0;
+        const text = await readBody(res);
+        if (status < 200 || status >= 300) {
+            let message = text.trim();
+            try {
+                message = JSON.parse(text).message || message;
+            }
+            catch {
+                /* not JSON */
+            }
+            throw new DockerError(status, message || `${what}: HTTP ${status}`);
+        }
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (event.error)
+                throw new Error(`${what}: ${event.error}`);
+        }
+    }
+    version = () => this.json('GET', '/version');
+    info = () => this.json('GET', '/info');
+    listContainers(filter = {}, all = true) {
+        return this.json('GET', '/containers/json', {
+            query: { all: all ? '1' : '0', filters: filtersParam(filter) },
+        });
+    }
+    inspectContainer = (id) => this.json('GET', `/containers/${encodeURIComponent(id)}/json`);
+    async createContainer(name, body) {
+        const created = await this.json('POST', '/containers/create', {
+            query: { name },
+            body,
+        });
+        return created.Id;
+    }
+    async startContainer(id) {
+        try {
+            await this.call('POST', `/containers/${encodeURIComponent(id)}/start`);
+        }
+        catch (error) {
+            if (error instanceof DockerError && error.status === 304)
+                return;
+            throw error;
+        }
+    }
+    async stopContainer(id, timeoutSeconds) {
+        try {
+            await this.call('POST', `/containers/${encodeURIComponent(id)}/stop`, {
+                query: { t: timeoutSeconds === undefined ? undefined : String(timeoutSeconds) },
+            });
+        }
+        catch (error) {
+            if (error instanceof DockerError && error.status === 304)
+                return;
+            throw error;
+        }
+    }
+    async restartContainer(id) {
+        await this.call('POST', `/containers/${encodeURIComponent(id)}/restart`);
+    }
+    async removeContainer(id) {
+        try {
+            await this.call('DELETE', `/containers/${encodeURIComponent(id)}`, {
+                query: { force: '1' },
+            });
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+        }
+    }
+    async connectNetwork(network, container, aliases = []) {
+        await this.call('POST', `/networks/${encodeURIComponent(network)}/connect`, {
+            body: { Container: container, EndpointConfig: { Aliases: aliases } },
+        });
+    }
+    async logs(id, options = {}) {
+        const tty = await this.isTty(id);
+        const res = await this.request('GET', `/containers/${encodeURIComponent(id)}/logs`, {
+            query: {
+                stdout: '1',
+                stderr: '1',
+                follow: options.follow === false ? '0' : '1',
+                tail: String(options.tail ?? 100),
+                timestamps: options.timestamps ? '1' : '0',
+            },
+        });
+        if ((res.statusCode || 0) >= 300) {
+            const text = await readBody(res);
+            throw new DockerError(res.statusCode || 0, text.trim() || 'cannot read container logs');
+        }
+        return this.attachedFromStream(res, tty, () => res.destroy(), null, async () => 0);
+    }
+    async isTty(id) {
+        const inspected = (await this.inspectContainer(id));
+        return Boolean(inspected.Config?.Tty);
+    }
+    /**
+     * Wraps a response or hijacked socket as a process whose output is demultiplexed unless a TTY.
+     * `close` fires with `exitCode()` once the source and both output streams have ended.
+     */
+    attachedFromStream(source, tty, destroy, stdin, exitCode) {
+        const stdout = new PassThrough();
+        const stderr = new PassThrough();
+        const proc = Object.assign(new EventEmitter(), {
+            stdin,
+            stdout,
+            stderr,
+            kill: () => {
+                destroy();
+                return true;
+            },
+        });
+        if (tty) {
+            source.pipe(stdout);
+            source.on('end', () => stderr.end());
+            source.on('close', () => stderr.end());
+        }
+        else
+            demux(source, stdout, stderr);
+        source.on('error', (error) => proc.emit('error', error));
+        const ended = (stream) => new Promise((resolve) => {
+            stream.once('end', resolve);
+            stream.once('close', resolve);
+            stream.once('error', () => resolve());
+        });
+        void Promise.all([ended(source), ended(stdout), ended(stderr)]).then(async () => proc.emit('close', await exitCode().catch(() => null), null));
+        return proc;
+    }
+    async putArchive(id, dir, tar) {
+        await this.call('PUT', `/containers/${encodeURIComponent(id)}/archive`, {
+            query: { path: dir },
+            stream: tar,
+            headers: { 'content-type': 'application/x-tar' },
+        });
+    }
+    async execRun(id, cmd) {
+        const proc = await this.execStart(id, { cmd });
+        const out = [];
+        const err = [];
+        proc.stdout.on('data', (d) => out.push(d));
+        proc.stderr.on('data', (d) => err.push(d));
+        const code = await new Promise((resolve, reject) => {
+            proc.on('error', reject);
+            proc.on('close', (c) => resolve(c ?? -1));
+        });
+        return {
+            code,
+            out: Buffer.concat(out).toString('utf8'),
+            err: Buffer.concat(err).toString('utf8'),
+        };
+    }
+    async execStart(id, options) {
+        const tty = Boolean(options.tty);
+        const created = await this.json('POST', `/containers/${encodeURIComponent(id)}/exec`, {
+            body: {
+                AttachStdin: options.stdin === true,
+                AttachStdout: true,
+                AttachStderr: true,
+                Tty: tty,
+                Cmd: options.cmd,
+                ...(tty && options.rows && options.columns
+                    ? { ConsoleSize: [options.rows, options.columns] }
+                    : {}),
+            },
+        });
+        const execId = created.Id;
+        const payload = Buffer.from(JSON.stringify({ Detach: false, Tty: tty }));
+        // Exec start hijacks the connection: the daemon answers `101 UPGRADE` and the socket becomes the stream.
+        const socket = await new Promise((resolve, reject) => {
+            const req = http.request({
+                socketPath: this.socketPath,
+                method: 'POST',
+                path: `/${API_VERSION}/exec/${execId}/start`,
+                headers: {
+                    'content-type': 'application/json',
+                    'content-length': String(payload.length),
+                    connection: 'Upgrade',
+                    upgrade: 'tcp',
+                },
+            }, async (res) => reject(new DockerError(res.statusCode || 0, (await readBody(res)).trim())));
+            req.on('upgrade', (_res, sock, head) => {
+                if (head.length)
+                    sock.unshift(head);
+                resolve(sock);
+            });
+            req.on('error', reject);
+            req.end(payload);
+        });
+        const proc = this.attachedFromStream(socket, tty, () => socket.destroy(), options.stdin ? socket : null, async () => (await this.json('GET', `/exec/${execId}/json`)).ExitCode ??
+            0);
+        if (tty) {
+            proc.resize = (columns, rows) => void this.resizeExec(execId, columns, rows);
+            // ConsoleSize at create needs API 1.42; resizing once started works on every supported daemon.
+            if (options.columns && options.rows)
+                proc.resize(options.columns, options.rows);
+        }
+        return proc;
+    }
+    async resizeExec(execId, columns, rows) {
+        await this.call('POST', `/exec/${execId}/resize`, {
+            query: { h: String(rows), w: String(columns) },
+        }).catch(() => { });
+    }
+    async inspectNetwork(name) {
+        try {
+            return await this.json('GET', `/networks/${encodeURIComponent(name)}`);
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return null;
+            throw error;
+        }
+    }
+    async createNetwork(name, labels) {
+        await this.call('POST', '/networks/create', {
+            body: { Name: name, Driver: 'bridge', CheckDuplicate: true, Labels: labels },
+        });
+    }
+    async inspectVolume(name) {
+        try {
+            return await this.json('GET', `/volumes/${encodeURIComponent(name)}`);
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return null;
+            throw error;
+        }
+    }
+    async createVolume(name, options) {
+        await this.call('POST', '/volumes/create', {
+            body: {
+                Name: name,
+                Driver: options.driver || 'local',
+                DriverOpts: options.opts || {},
+                Labels: options.labels || {},
+            },
+        });
+    }
+    async removeVolume(name) {
+        await this.call('DELETE', `/volumes/${encodeURIComponent(name)}`);
+    }
+    async inspectImage(ref) {
+        try {
+            return await this.json('GET', `/images/${encodeURI(ref)}/json`);
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return null;
+            throw error;
+        }
+    }
+    async pullImage(ref, auth) {
+        const { fromImage, tag } = splitImageRef(ref);
+        const res = await this.request('POST', '/images/create', {
+            query: { fromImage, tag },
+            // Docker uses Go's padded base64.URLEncoding; Node's base64url encoding omits required '='.
+            headers: auth
+                ? {
+                    'x-registry-auth': Buffer.from(JSON.stringify(auth))
+                        .toString('base64')
+                        .replaceAll('+', '-')
+                        .replaceAll('/', '_'),
+                }
+                : {},
+        });
+        await this.progress(res, `pull ${ref}`);
+    }
+    async loadImage(archive) {
+        const res = await this.request('POST', '/images/load', {
+            query: { quiet: '1' },
+            stream: archive,
+            headers: { 'content-type': 'application/x-tar' },
+        });
+        await this.progress(res, 'load image');
+    }
+    async removeImage(ref) {
+        await this.call('DELETE', `/images/${encodeURI(ref)}`);
+    }
+}

package/dist/ingress.d.ts

@@ -1,5 +1,5 @@
 import type { DesiredState, IngressRoute, IngressStatus, IngressWork, ProjectStatus, ServiceEndpoints } from './protocol.ts';
-import type { DockerRunner } from './runners.ts';
+import type { DockerApi } from './docker-api.ts';
 export declare const CADDY_CONTAINER = "tug-caddy";
 export declare const DEFAULT_CADDY_IMAGE = "caddy:2-alpine";
 export interface NodeView {
@@ -43,15 +43,15 @@ export declare function renderCaddyfile(routes: IngressRoute[], opts?: {
 }): string;
 export declare function ingressConfigHash(work: Pick<IngressWork, 'caddyfile' | 'files'>): string;
 export interface IngressContext {
-    docker: DockerRunner;
+    docker: DockerApi;
     stateDir: string;
     caddyImage?: string;
 }
 /**
- * Makes the Caddy container match the control-rendered config. Config is copied into the
- * container (`docker cp`, so it works whether the agent runs on the host or in a container) and
- * applied with `caddy reload`, which swaps config gracefully without dropping connections. If
- * Caddy rejects the new config the previous one is restored and the error reported.
+ * Makes the Caddy container match the control-rendered config. Config is uploaded into the
+ * container with the archive endpoint (so it works whether the agent runs on the host or in a
+ * container) and applied with `caddy reload`, which swaps config gracefully without dropping
+ * connections. If Caddy rejects the new config the previous one is restored and the error reported.
  */
 export declare function reconcileIngress(ctx: IngressContext, work: IngressWork): Promise<IngressStatus>;
 /** Removes the Caddy container when a node stops being an ingress node; ACME data volumes are kept. */

package/dist/ingress.js

@@ -6,6 +6,8 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { loopbackIngressServices, publishedPort } from "./compose.js";
 import { ensureDir, errMessage } from "./util.js";
+import * as tar from 'tar';
+import { isNotFound } from "./docker-api.js";
 export const CADDY_CONTAINER = 'tug-caddy';
 export const DEFAULT_CADDY_IMAGE = 'caddy:2-alpine';
 const CADDY_ETC = '/etc/caddy';
@@ -133,11 +135,35 @@ async function writeStage(dir, work) {
         await fs.writeFile(file, body, { mode: name.endsWith('.key') ? 0o600 : 0o644 });
     }
 }
+async function tarOf(dir) {
+    const chunks = [];
+    for await (const chunk of tar.c({ cwd: dir, portable: true }, ['.']))
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+async function ensureImage(ctx) {
+    const image = ctx.caddyImage || DEFAULT_CADDY_IMAGE;
+    if (!(await ctx.docker.inspectImage(image)))
+        await ctx.docker.pullImage(image);
+    return image;
+}
+async function reload(ctx) {
+    const r = await ctx.docker.execRun(CADDY_CONTAINER, [
+        'caddy',
+        'reload',
+        '--config',
+        `${CADDY_ETC}/Caddyfile`,
+        '--adapter',
+        'caddyfile',
+    ]);
+    if (r.code !== 0)
+        throw new Error(`caddy reload failed (${r.code}): ${(r.err || r.out).trim()}`);
+}
 /**
- * Makes the Caddy container match the control-rendered config. Config is copied into the
- * container (`docker cp`, so it works whether the agent runs on the host or in a container) and
- * applied with `caddy reload`, which swaps config gracefully without dropping connections. If
- * Caddy rejects the new config the previous one is restored and the error reported.
+ * Makes the Caddy container match the control-rendered config. Config is uploaded into the
+ * container with the archive endpoint (so it works whether the agent runs on the host or in a
+ * container) and applied with `caddy reload`, which swaps config gracefully without dropping
+ * connections. If Caddy rejects the new config the previous one is restored and the error reported.
  */
 export async function reconcileIngress(ctx, work) {
     const root = path.join(ctx.stateDir, 'ingress');
@@ -145,57 +171,45 @@ export async function reconcileIngress(ctx, work) {
     const applied = path.join(root, 'applied');
     const configHash = ingressConfigHash(work);
     const routes = work.routes.length;
-    const running = await ctx
-        .docker(['container', 'inspect', '-f', '{{.State.Running}}', CADDY_CONTAINER])
-        .then((r) => r.out.trim() === 'true', () => null);
+    const existing = await ctx.docker.inspectContainer(CADDY_CONTAINER).catch((e) => {
+        if (isNotFound(e))
+            return null;
+        throw e;
+    });
+    const running = existing ? Boolean(existing.State?.Running) : null;
     const appliedHash = await fs.readFile(path.join(root, 'applied.hash'), 'utf8').then((s) => s.trim(), () => '');
     if (running && appliedHash === configHash)
         return { state: 'serving', configHash, routes };
     await writeStage(stage, work);
     try {
         if (running === null) {
-            await ctx.docker([
-                'create',
-                '--name',
-                CADDY_CONTAINER,
-                '--restart',
-                'unless-stopped',
-                '--network',
-                'host',
-                '-v',
-                'tug-caddy-data:/data',
-                '-v',
-                'tug-caddy-config:/config',
-                '-v',
-                `tug-caddy-etc:${CADDY_ETC}`,
-                ctx.caddyImage || DEFAULT_CADDY_IMAGE,
-            ]);
-            await ctx.docker(['cp', `${stage}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]);
-            await ctx.docker(['start', CADDY_CONTAINER]);
+            const image = await ensureImage(ctx);
+            await ctx.docker.createContainer(CADDY_CONTAINER, {
+                Image: image,
+                Labels: { 'tug.managed': 'ingress' },
+                HostConfig: {
+                    NetworkMode: 'host',
+                    RestartPolicy: { Name: 'unless-stopped' },
+                    Binds: ['tug-caddy-data:/data', 'tug-caddy-config:/config', `tug-caddy-etc:${CADDY_ETC}`],
+                },
+            });
+            await ctx.docker.putArchive(CADDY_CONTAINER, CADDY_ETC, await tarOf(stage));
+            await ctx.docker.startContainer(CADDY_CONTAINER);
         }
         else if (running === false) {
-            await ctx.docker(['cp', `${stage}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]);
-            await ctx.docker(['start', CADDY_CONTAINER]);
+            await ctx.docker.putArchive(CADDY_CONTAINER, CADDY_ETC, await tarOf(stage));
+            await ctx.docker.startContainer(CADDY_CONTAINER);
         }
         else {
             try {
-                await ctx.docker(['exec', CADDY_CONTAINER, 'rm', '-rf', `${CADDY_ETC}/certs`]);
-                await ctx.docker(['cp', `${stage}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`]);
-                await ctx.docker([
-                    'exec',
-                    CADDY_CONTAINER,
-                    'caddy',
-                    'reload',
-                    '--config',
-                    `${CADDY_ETC}/Caddyfile`,
-                    '--adapter',
-                    'caddyfile',
-                ]);
+                await ctx.docker.execRun(CADDY_CONTAINER, ['rm', '-rf', `${CADDY_ETC}/certs`]);
+                await ctx.docker.putArchive(CADDY_CONTAINER, CADDY_ETC, await tarOf(stage));
+                await reload(ctx);
             }
             catch (e) {
                 if (await fs.stat(applied).then(() => true, () => false))
-                    await ctx
-                        .docker(['cp', `${applied}/.`, `${CADDY_CONTAINER}:${CADDY_ETC}/`])
+                    await ctx.docker
+                        .putArchive(CADDY_CONTAINER, CADDY_ETC, await tarOf(applied))
                         .catch(() => { });
                 throw e;
             }
@@ -215,7 +229,7 @@ export async function removeIngress(ctx) {
     const root = path.join(ctx.stateDir, 'ingress');
     if (!(await fs.stat(root).then(() => true, () => false)))
         return false;
-    await ctx.docker(['rm', '-f', CADDY_CONTAINER]).catch(() => { });
+    await ctx.docker.removeContainer(CADDY_CONTAINER).catch(() => { });
     await fs.rm(root, { recursive: true, force: true });
     return true;
 }

package/dist/live.d.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'node:events';
+import type { DockerApi } from './docker-api.ts';
 import type { Readable, Writable } from 'node:stream';
 export interface LiveProcess extends EventEmitter {
     stdin: Writable | null;
@@ -8,7 +9,6 @@ export interface LiveProcess extends EventEmitter {
     /** PTY adapters implement this in terminal columns and rows. */
     resize?(columns: number, rows: number): void;
 }
-export type LiveSpawn = (file: string, args: string[]) => LiveProcess;
 export type LiveRequest = {
     operation: 'exec';
     sessionId: string;
@@ -53,21 +53,24 @@ export type LiveEvent = {
 };
 export interface LiveEngineOptions {
     emit: (event: LiveEvent) => void;
-    spawn?: LiveSpawn;
-    /** A real PTY adapter is required for interactive Docker exec. */
-    spawnTty?: LiveSpawn;
+    /** The Engine API: exec (with a real PTY), logs, `ps` and `inspect` all go through it. */
+    docker: DockerApi;
     maxSessions?: number;
-    maxResultBytes?: number;
     maxSessionMs?: number;
     queryTimeoutMs?: number;
 }
-/** Owns Docker process lifetimes; callers own authentication, authorization and transport backpressure. */
+/** Owns Engine API streams and their lifetimes; callers own authentication, authorization and transport backpressure. */
 export declare class LiveOperationEngine {
     private readonly options;
     private readonly sessions;
+    /** Sessions whose container stream is still being opened; a cancel marks them so they close on arrival. */
+    private readonly starting;
     constructor(options: LiveEngineOptions);
     get activeSessions(): number;
-    start(value: unknown): void;
+    start(value: unknown): Promise<void>;
+    /** `ps` and `inspect` are one Engine API call whose JSON result is the whole session. */
+    private query;
+    private open;
     /** Returns the writable backpressure signal; callers must pause transport input on false. */
     stdin(sessionId: string, data: Uint8Array): boolean;
     endStdin(sessionId: string): void;