@tetherto/mdk-cli 0.0.0 → 0.12.1

package/dist/lib/runtime.js

@@ -0,0 +1,683 @@
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { isLocalPackagePath, unresolvedEnvRef } from './spec.js';
+import { DEFAULT_HOST, findFreePort, isPortFree } from './ports.js';
+import { APP_MANIFEST } from './app-package.js';
+import { WORKER_CONTRACT } from './worker-package.js';
+import { theme, tick, arrow } from './theme.js';
+import { appChildFile, appChildPid } from './run-lock.js';
+const require = createRequire(import.meta.url);
+/** Lazily loads the `@tetherto/mdk-core` runtime (a workspace dependency). */
+function mdkCore() {
+    return require('@tetherto/mdk-core');
+}
+/** Lazily loads the `@tetherto/mdk-worker` runtime host (a workspace dependency). */
+function mdkWorker() {
+    return require('@tetherto/mdk-worker');
+}
+export function localDiscovery() {
+    return require('@tetherto/mdk-core/lib/local-discovery');
+}
+/** Lazily loads the `@tetherto/mdk-mcp` runtime (a workspace dependency). */
+function mdkMcp() {
+    return require('@tetherto/mdk-mcp');
+}
+/** Lazily loads the `@tetherto/mdk-app-runtime` package (a workspace dependency). */
+function mdkAppRuntime() {
+    return require('@tetherto/mdk-app-runtime');
+}
+// --- project-local runtime state ------------------------------------------
+// Everything `mdk run` writes lives under `<project>/.mdk` — gitignored and safe
+// to delete. Each component gets its own data root so no two of them share a
+// directory, while the two cross-process handoff artifacts sit at the top level
+// where either side can find them: `kernel.key` (read by the gateway) and
+// `keys/` (written by workers, watched by the kernel). This leaves room for
+// `logs/` and `run/` when `mdk logs` and `mdk status` land.
+/** Absolute runtime-state root for a project — `<project>/.mdk`. */
+export function mdkDir(projectDir) {
+    return resolve(projectDir, '.mdk');
+}
+/** A path under `.mdk`, e.g. `componentDir(dir, 'workers', name)`. */
+function componentDir(projectDir, ...parts) {
+    return join(mdkDir(projectDir), ...parts);
+}
+/** Shared Kernel HRPC key file — how a separate gateway process discovers the Kernel. */
+export function kernelKeyFile(projectDir) {
+    return componentDir(projectDir, 'kernel.key');
+}
+/** Where the Gateway publishes its public key; app runtimes accept calls from it and the MCP server's. */
+export function gatewayKeyFile(projectDir) {
+    return componentDir(projectDir, 'gateway.key');
+}
+/** Where the MCP server publishes the key it calls app runtimes with. */
+export function mcpKeyFile(projectDir) {
+    return componentDir(projectDir, 'mcp.key');
+}
+/** Where an app runtime publishes its public key, for the Gateway to find it. */
+export function appKeyFile(projectDir, name) {
+    return componentDir(projectDir, 'apps', name, 'runtime.key');
+}
+/**
+ * Shared worker-key dir for `discovery: { mode: 'local' }`, passed *explicitly*
+ * to both sides. mdk-core otherwise defaults it to `<root>/.worker-keys`, which
+ * would nest it inside whichever component's data root was passed — the Kernel
+ * and its workers must agree on one path independent of their own roots.
+ */
+export function workerKeysDir(projectDir) {
+    return componentDir(projectDir, 'keys');
+}
+/**
+ * Shared trusted-keys dir. The Kernel and every Worker reject unknown RPC
+ * callers, so each component publishes the key it dials with here
+ * (`kernel.pub`, `gateway.pub`, `mcp.pub`, `app-<name>.pub`): the Kernel admits callers from it
+ * and separately-run workers allow what they find in it.
+ */
+export function trustedKeysDir(projectDir) {
+    return componentDir(projectDir, 'trusted-keys');
+}
+/** Default gap between the Gateway's port and the MCP server's, when `spec.mcp.port` is not set. */
+export const DEFAULT_MCP_PORT_OFFSET = 100;
+/**
+ * Splits a spec `package` into the npm package to resolve and the subdirectory
+ * inside it, if any: `@scope/pkg/plugin-a` is one installed package and one
+ * directory within it, not a package called `.../plugin-a`.
+ *
+ * Subpaths exist for packages that ship several plugins as subdirectories of a
+ * single package, with no `package.json` of their own.
+ */
+function splitPackageSubpath(pkgName) {
+    const parts = pkgName.split('/');
+    const nameLength = pkgName.startsWith('@') ? 2 : 1;
+    return { pkg: parts.slice(0, nameLength).join('/'), subpath: parts.slice(nameLength).join('/') };
+}
+/** The spec the project's package.json gives `pkg`, if it lists it. */
+function declaredDependency(projectDir, pkg) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(resolve(projectDir), 'package.json'), 'utf8'));
+        return manifest.dependencies?.[pkg] ?? manifest.devDependencies?.[pkg];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolves an installed package's root directory from the target project's
+ * `node_modules` (via its `package.json`), or a subdirectory of one. Throws an
+ * actionable error naming the missing package — a package `mdk.yaml` declares
+ * must be installed into the project first.
+ */
+export function resolveProjectPackageDir(projectDir, pkgName) {
+    const { pkg, subpath } = splitPackageSubpath(pkgName);
+    let root;
+    try {
+        root = dirname(require.resolve(`${pkg}/package.json`, { paths: [resolve(projectDir)] }));
+    }
+    catch {
+        // A dependency package.json already declares (a `file:` app, say) only needs
+        // `npm install`; naming it would fetch an unrelated registry package. The
+        // install command names the *package*: `npm install @scope/pkg/plugin-a`
+        // is not a thing npm can do.
+        const declared = declaredDependency(projectDir, pkg);
+        throw new Error(`Package "${pkgName}" is not installed in ${resolve(projectDir)}.\n` +
+            (declared
+                ? `package.json declares it ("${declared}"), so run: npm install`
+                : `Install it first, e.g.: npm install ${pkg}`));
+    }
+    if (!subpath)
+        return root;
+    // A subpath that is not there is a typo in mdk.yaml, not a missing install, and
+    // the two want different fixes. Whether the directory holds a plugin manifest
+    // (or a worker contract) is left to whoever loads it — that check belongs with
+    // the loader that knows which of the two it wanted.
+    const dir = join(root, subpath);
+    if (!existsSync(dir)) {
+        throw new Error(`Package "${pkgName}" is installed as "${pkg}", but it has no "${subpath}" in it (looked in ${dir}).\n` +
+            `Check the subpath — e.g. package: "${pkg}/<dir>".`);
+    }
+    return dir;
+}
+/** Boots the Kernel (local discovery, project-local state), logging its key. */
+export async function runKernel(projectDir) {
+    const core = mdkCore();
+    const root = componentDir(projectDir, 'kernel');
+    mkdirSync(root, { recursive: true });
+    process.stderr.write(`${theme.muted('Starting kernel')} ${arrow} ${theme.value(root)}\n`);
+    const kernel = await core.getKernel({
+        root,
+        keyFile: kernelKeyFile(projectDir),
+        discovery: { mode: 'local', dir: workerKeysDir(projectDir) },
+        trustedKeysDir: trustedKeysDir(projectDir),
+    });
+    const key = typeof kernel.getPublicKey === 'function' ? kernel.getPublicKey() : undefined;
+    const keyHex = key ? key.toString('hex') : '(unknown)';
+    process.stderr.write(`${tick} ${theme.label('kernel')} ready ${theme.muted(keyHex)}\n`);
+    return kernel;
+}
+/**
+ * Shared by assertGatewayPortFree/assertMcpPortFree below: unlike a mock port,
+ * these are published endpoints (the dashboard proxies to the gateway's, agents
+ * dial the MCP one directly), so neither is ever relocated behind the
+ * operator's back — fail with the fix instead of a bare EADDRINUSE from deep
+ * inside the server. One implementation keeps the two messages from drifting
+ * apart as the wording around them changes.
+ */
+async function assertPortFree(port, label, specKey) {
+    if (await isPortFree(port))
+        return;
+    throw new Error(`${label} port ${port} is already in use.\n` +
+        `Another stack is probably running — stop it, or change \`${specKey}\` in mdk.yaml.`);
+}
+/** Exported so `run all` can check the gateway's port before booting anything. */
+export async function assertGatewayPortFree(port) {
+    return assertPortFree(port, 'Gateway', 'spec.gateway.port');
+}
+/** Neither runs app code, so an app's config goes to its runtime only. */
+function forwardedApps(projectDir, apps) {
+    return apps.map((a) => ({
+        name: a.name,
+        appDir: resolveAppPackageDir(projectDir, a.package),
+        keyFile: appKeyFile(projectDir, a.name),
+        ...(a.mount !== undefined ? { mount: a.mount } : {}),
+    }));
+}
+/**
+ * Boots the Gateway. When `kernel` is provided the connection is in-process
+ * (target `all`); otherwise the Kernel key is resolved from the shared key
+ * file written by a separate `mdk run kernel` process.
+ */
+export async function runGateway(projectDir, spec, kernel) {
+    const core = mdkCore();
+    // Resolve every path to an absolute one *before* the chdir below, so nothing
+    // depends on the (about-to-change) working directory.
+    const keyFile = kernelKeyFile(projectDir);
+    const root = componentDir(projectDir, 'gateway');
+    const ownKeyFile = gatewayKeyFile(projectDir);
+    const trustDir = trustedKeysDir(projectDir);
+    const apps = forwardedApps(projectDir, spec.spec.apps);
+    // Out-of-process gateway: the Kernel must already be running so its HRPC key
+    // is on disk. Fail early with an actionable message instead of silently
+    // booting a gateway that can never reach a Kernel.
+    if (!kernel && !existsSync(keyFile)) {
+        throw new Error('Kernel is not running (no key file found).\nStart it first: `mdk run kernel`.');
+    }
+    await assertGatewayPortFree(spec.spec.gateway.port);
+    mkdirSync(root, { recursive: true });
+    // The gateway's corestore (`store/http`) is created relative to the working
+    // directory (tether-wrk-base convention — the mvp-site example likewise runs
+    // each process with its own `cwd`). Run from the gateway state root so that
+    // store nests under `.mdk/gateway/` instead of polluting the project.
+    process.chdir(root);
+    process.stderr.write(`${theme.muted('Starting gateway')} ${arrow} ${theme.value(`:${spec.spec.gateway.port}`)}\n`);
+    const gateway = await core.startGateway({
+        root,
+        port: spec.spec.gateway.port,
+        ...(kernel ? { kernel } : { keyFile }),
+        apps,
+        gatewayKeyFile: ownKeyFile,
+        // Admits the gateway's client key on the Kernel and on workers in other processes.
+        trustedKeysDir: trustDir,
+        ...(Object.keys(spec.spec.gateway.config ?? {}).length ? { common: spec.spec.gateway.config } : {}),
+        // `auth: true` routes (the agent chat) admit callers on this machine unless
+        // mdk.yaml names another built-in verifier in gateway.config.authVerifier.
+        ...(spec.spec.gateway.config?.authVerifier === undefined ? { authVerifier: 'loopback' } : {}),
+    });
+    process.stderr.write(`${tick} ${theme.label('gateway')} listening on ${theme.value(`http://localhost:${spec.spec.gateway.port}`)}\n`);
+    return gateway;
+}
+/** Same reasoning as `assertGatewayPortFree` — see `assertPortFree` above. */
+export async function assertMcpPortFree(port) {
+    return assertPortFree(port, 'MCP', 'spec.mcp.port');
+}
+/** The Kernel's public key (hex): from an in-process handle, else from the key file `mdk run kernel` wrote. */
+function resolveKernelKey(projectDir, kernel) {
+    if (kernel) {
+        const key = typeof kernel.getPublicKey === 'function' ? kernel.getPublicKey() : undefined;
+        return key ? (Buffer.isBuffer(key) ? key.toString('hex') : String(key)) : undefined;
+    }
+    const keyFile = kernelKeyFile(projectDir);
+    if (existsSync(keyFile))
+        return readFileSync(keyFile, 'utf8').trim();
+    throw new Error('Kernel is not running (no key file found).\nStart it first: `mdk run kernel`.');
+}
+/**
+ * Boots the standalone MCP server, pointed at the apps `mdk.yaml` declares
+ * under `spec.apps` — their routes become MCP
+ * tools with no separate mcp-specific plugin authoring required, each call
+ * forwarded to the app's runtime, so an app's tools answer once `mdk run` has
+ * started it. Requires the
+ * Kernel to already be reachable: an in-process `kernel` handle (target
+ * `all`, if this is ever wired into it), or the shared key file written by a
+ * separately-running `mdk run kernel` — the same contract `runGateway` uses.
+ */
+export async function runMcp(projectDir, spec, kernel, flags = {}) {
+    // An unset variable leaves the literal `${NAME}` as the token: /mcp would look
+    // protected while accepting a bearer anyone can read in mdk.yaml.
+    const token = spec.spec.mcp.token;
+    const unresolved = token ? unresolvedEnvRef(token) : undefined;
+    if (unresolved) {
+        throw new Error(`\`spec.mcp.token\` uses \${${unresolved}}, but ${unresolved} is not set in the environment or the project .env.\n` +
+            `Set ${unresolved}, or remove \`spec.mcp.token\` to run /mcp without a bearer token.`);
+    }
+    const mcp = mdkMcp();
+    const root = componentDir(projectDir, 'mcp');
+    const apps = forwardedApps(projectDir, spec.spec.apps);
+    const kernelKey = resolveKernelKey(projectDir, kernel);
+    const port = spec.spec.mcp.port ?? spec.spec.gateway.port + DEFAULT_MCP_PORT_OFFSET;
+    await assertMcpPortFree(port);
+    mkdirSync(root, { recursive: true });
+    // A persistent caller identity every tool plugin's client dials with
+    // (config.kernelKeyPair), admitted on the in-process Kernel and published
+    // for a separately-running Kernel and its workers.
+    const discovery = localDiscovery();
+    const kernelKeyPair = discovery.callerKeyPair(join(root, 'identity'));
+    if (kernel && typeof kernel.allowKey === 'function')
+        kernel.allowKey(kernelKeyPair.publicKey);
+    discovery.publishTrustedKey(trustedKeysDir(projectDir), 'mcp', kernelKeyPair.publicKey);
+    process.stderr.write(`${theme.muted('Starting mcp')} ${arrow} ${theme.value(`:${port}`)}\n`);
+    // Like the Gateway, the MCP server runs no app code: every tool call is
+    // forwarded to the app's runtime (started by `mdk run`), bounded by
+    // `spec.gateway.config.appTimeoutMs`.
+    const server = await mcp.createMcpServer(root, port, { ...(spec.spec.gateway.config ?? {}), kernelKey, kernelKeyPair }, 
+    // `pluginDirs` (native, author-written `mcp-plugin.json` tools) is not yet
+    // reachable from `mdk.yaml` — there is no `spec.mcp.plugins` list. App
+    // route tools (via `apps` below) are deliberately the only
+    // CLI path today: every declared app's routes already become
+    // tools with no separate authoring, which covers the common case. Add a
+    // `spec.mcp.plugins` list here if native MCP-only plugins need a CLI path.
+    [], apps, {
+        // Write tools are opt-in: `--allow-write` or `spec.mcp.allowWrite`.
+        allowWrite: flags.allowWrite === true || spec.spec.mcp.allowWrite === true,
+        ...(spec.spec.mcp.allowTools ? { allowTools: spec.spec.mcp.allowTools } : {}),
+        ...(spec.spec.mcp.token ? { token: spec.spec.mcp.token } : {}),
+        ...(spec.spec.mcp.identity ? { identity: spec.spec.mcp.identity } : {}),
+        // The CLI owns SIGINT/SIGTERM (installShutdown) and stops via close().
+        handleSignals: false,
+        // Every app runtime allow-lists this key (resolveAppOptions).
+        keyFile: mcpKeyFile(projectDir),
+    });
+    process.stderr.write(`${tick} ${theme.label('mcp')} listening on ${theme.value(`http://localhost:${port}/mcp`)}\n`);
+    return { stop: () => new Promise((resolve) => server.close(() => resolve())) };
+}
+/**
+ * Waits until a freshly created mock is actually accepting connections.
+ *
+ * The mock framework binds differently per transport, so neither signal alone is
+ * enough: HTTP mocks hand back a Fastify instance and expose the bind as a
+ * `ready` promise, while TCP mocks hand back a `net.Server` that has already
+ * been told to listen and reports it by emitting `'listening'`. Waiting on the
+ * event alone would hang forever on a Fastify instance (it never emits it), and
+ * waiting on `ready` alone would return before a TCP mock is bound.
+ */
+async function awaitMockReady(mock) {
+    if (mock.ready)
+        await mock.ready;
+    const server = mock.server;
+    // `listening` is the tell for a real net.Server; guarding on it also avoids
+    // waiting for an event that has already fired.
+    if (server?.on && server.listening === false) {
+        await once(server, 'listening');
+    }
+}
+/** Frees the listener now, whether the mock is Fastify-shaped or net.Server-shaped. */
+function dropMockConnections(mock) {
+    mock.server?.closeAllConnections?.();
+    mock.server?.server?.closeAllConnections?.();
+}
+/**
+ * Resolves each seed device's mock port to one that is actually bindable.
+ *
+ * A mock port is a private contract between the simulator this CLI starts and
+ * the plugin that dials it — nothing outside the process cares which number it
+ * is. So when the configured port is taken (a second stack on the machine, a
+ * worker left running, two devices sharing a port), relocating beats refusing to
+ * boot. The configured port is always tried first, so a free one stays stable
+ * and matches mdk.yaml. Real (non-mock) devices are never touched: their port
+ * belongs to the hardware.
+ */
+async function resolveMockPorts(workerName, seeds, reserved) {
+    // Seeded with the ports later workers have declared but not yet bound, so one
+    // squatter cannot cascade: a relocated worker steps over its neighbours'
+    // ports instead of pushing each of them along in turn.
+    const claimed = new Set(reserved ?? []);
+    const resolved = [];
+    for (const d of seeds) {
+        const opts = { ...(d.opts ?? {}) };
+        const wanted = opts.port;
+        if (typeof wanted === 'number') {
+            const host = typeof opts.host === 'string' ? opts.host : DEFAULT_HOST;
+            const available = !claimed.has(wanted) && (await isPortFree(wanted, host));
+            const port = available ? wanted : await findFreePort({ start: wanted + 1, host, taken: claimed });
+            if (port !== wanted) {
+                process.stderr.write(theme.muted(`  mock port ${wanted} is in use — device "${d.id}" of "${workerName}" moved to ${port}\n`));
+            }
+            opts.port = port;
+            claimed.add(port);
+        }
+        resolved.push(opts);
+    }
+    return resolved;
+}
+/** Mock ports a worker's seed devices ask for — what a later boot must avoid. */
+export function declaredMockPorts(worker) {
+    const config = worker.config;
+    if (!config.mock || !Array.isArray(config.devices))
+        return [];
+    return config.devices
+        .map((d) => d.opts?.port)
+        .filter((port) => typeof port === 'number');
+}
+/**
+ * Resolves a spec `package` to its directory, the one way `run`, `status` and
+ * `add` all do it: a **local path** (`./…`, `../…` or absolute, resolved against
+ * the project dir) or an installed package, optionally with a subpath (see
+ * `resolveProjectPackageDir`). Throws naming the fix when it does not resolve.
+ */
+export function resolvePackageDir(projectDir, pkg) {
+    if (!isLocalPackagePath(pkg))
+        return resolveProjectPackageDir(projectDir, pkg);
+    const dir = resolve(projectDir, pkg);
+    if (!existsSync(dir)) {
+        throw new Error(`Package path "${pkg}" does not exist (looked in ${dir}).`);
+    }
+    return dir;
+}
+/**
+ * Resolves a worker package to its directory, and confirms it is a
+ * contract-first Worker Plugin (an `mdk-contract.json` at its root) — the only
+ * shape `mdk run worker` supports. Checked here, rather than left to surface
+ * as `WorkerRuntimeV2`'s own `ERR_CONTRACT_NOT_FOUND`/`ERR_WORKER_DIR_REQUIRED`,
+ * so a misshapen package gets a message that names the fix.
+ */
+function resolveWorkerContractDir(projectDir, pkg) {
+    const dir = resolvePackageDir(projectDir, pkg);
+    if (!existsSync(join(dir, WORKER_CONTRACT))) {
+        throw new Error(`Worker package "${pkg}" has no ${WORKER_CONTRACT} — mdk run only supports contract-first ` +
+            'Worker Plugins (a directory with mdk-contract.json at its root; `mdk create worker` scaffolds one).');
+    }
+    return dir;
+}
+/**
+ * Boots one worker on WorkerRuntimeV2, exactly the way the mvp-site example
+ * does: start a mock device server per seed device (so the plugin talks to a
+ * simulator instead of hardware), build the runtime's device set from
+ * `config.devices`, then register with the Kernel.
+ *
+ * Discovery follows the same contract as the rest of MDK: an in-process
+ * `kernel` handle registers the worker by key (target `all`); otherwise the
+ * worker publishes its RPC key to the shared keys dir for a separately-running
+ * local-mode Kernel to pick up.
+ */
+export async function runWorker(projectDir, worker, kernel, opts = {}) {
+    const dir = resolveWorkerContractDir(projectDir, worker.package);
+    const config = worker.config;
+    const seeds = Array.isArray(config.devices) ? config.devices : [];
+    if (seeds.length === 0) {
+        throw new Error(`Worker "${worker.name}" has no \`config.devices\` in mdk.yaml — nothing to run.`);
+    }
+    // Per-worker persistent state: plugin SQLite under storeDir, DHT/RPC seeds
+    // under storeDir/identity so the worker's public key survives restarts.
+    const storeDir = componentDir(projectDir, 'workers', worker.name);
+    mkdirSync(storeDir, { recursive: true });
+    const dbPath = join(storeDir, 'data.db');
+    const identityDir = join(storeDir, 'identity');
+    // Holds the worker's key seeds: owner-only, also for a dir an older CLI made.
+    mkdirSync(identityDir, { recursive: true, mode: 0o700 });
+    chmodSync(identityDir, 0o700);
+    process.stderr.write(`${theme.muted('Starting worker')} ${arrow} ${theme.value(worker.name)} ` +
+        `${theme.muted(`(${seeds.length} device${seeds.length === 1 ? '' : 's'})`)}\n`);
+    // Per-device options, with mock ports resolved to something actually bindable
+    // before anything starts. Both the mock and the plugin read from this same
+    // list, so they cannot disagree about which port the device is on.
+    const deviceOpts = config.mock
+        ? await resolveMockPorts(worker.name, seeds, opts.reservedPorts)
+        : seeds.map((d) => ({ ...(d.opts ?? {}) }));
+    // Mock device servers — one per seed device, from `<pkg>/mock/server`.
+    const mocks = [];
+    if (config.mock) {
+        const mockPath = join(dir, 'mock', 'server.js');
+        if (!existsSync(mockPath)) {
+            throw new Error(`config.mock is set but ${worker.package} has no mock/server.js.`);
+        }
+        const mockMod = require(mockPath);
+        for (const [i, d] of seeds.entries()) {
+            const opts = deviceOpts[i];
+            try {
+                const m = mockMod.createServer(opts);
+                mocks.push(m);
+                // Wait until the mock is actually listening — the plugin's connect()
+                // probes the device on boot, so a not-yet-bound port would fail startup.
+                await awaitMockReady(m);
+            }
+            catch (error) {
+                throw new Error(`Could not start the mock device for worker "${worker.name}", device "${d.id}" ` +
+                    `on ${String(opts.host ?? DEFAULT_HOST)}:${String(opts.port)}: ` +
+                    `${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    // Device set: `config.devices[].opts` is the plugin's own per-device config;
+    // dbPath is threaded through for the sample plugin's SQLite persistence.
+    const devices = seeds.map((d, i) => ({ deviceId: d.id, config: { ...deviceOpts[i], dbPath } }));
+    // Worker RPC is fail-closed: allow the Kernel's client key and the callers
+    // it admitted (in process), or what the Kernel and Gateway published to the
+    // trusted-keys dir (separate process), and keep following later admissions.
+    const discovery = localDiscovery();
+    const trustDir = trustedKeysDir(projectDir);
+    let allowedKeys;
+    if (kernel) {
+        const client = typeof kernel.getClientPublicKey === 'function' ? kernel.getClientPublicKey() : null;
+        if (!client)
+            throw new Error('Kernel has no client key (is HRPC enabled?) — cannot admit it on the worker.');
+        allowedKeys = [client, ...(kernel.listAllowedKeys?.('write') ?? [])];
+    }
+    else {
+        const trusted = discovery.readTrustedKeys(trustDir);
+        if (!trusted.some((k) => k.name === 'kernel')) {
+            throw new Error('Kernel is not running (no kernel key in the trusted-keys dir).\nStart it first: `mdk run kernel`.');
+        }
+        allowedKeys = trusted.map((k) => k.key);
+    }
+    const { WorkerRuntimeV2 } = mdkWorker();
+    const runtime = new WorkerRuntimeV2(dir, {
+        workerId: worker.name,
+        devices,
+        env: worker.env ?? {},
+        storeDir: identityDir,
+        allowedKeys,
+    });
+    const trust = kernel ? discovery.trustKernel(runtime, kernel) : discovery.trustKeysFromDir(runtime, trustDir);
+    try {
+        await runtime.start();
+    }
+    catch (error) {
+        trust.stop();
+        throw error;
+    }
+    const rpcKeyHex = runtime.getPublicKey().toString('hex');
+    if (kernel) {
+        await kernel.registerWorker(runtime.getPublicKey());
+        if (Array.isArray(kernel._cleanup)) {
+            kernel._cleanup.push(() => {
+                trust.stop();
+                return runtime.stop();
+            });
+        }
+    }
+    else {
+        discovery.publishWorkerKey(workerKeysDir(projectDir), worker.name, rpcKeyHex);
+    }
+    process.stderr.write(`${tick} ${theme.label('worker')} ${theme.value(worker.name)} ready ${theme.muted(rpcKeyHex.slice(0, 16))}\n`);
+    // Signals are owned by the `run` command (see lib/shutdown.ts), which stops
+    // every component in reverse boot order and exits even if one of them wedges.
+    const stop = async () => {
+        trust.stop();
+        await runtime.stop();
+        for (const m of mocks) {
+            try {
+                m.exit();
+                // `server.close()` only stops new connections; a keep-alive socket from
+                // the plugin's poller would hold the listener (and its port) open.
+                dropMockConnections(m);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    };
+    return { runtime, mocks, stop };
+}
+// --- app runtimes ---------------------------------------------------------
+/**
+ * Resolves an app package's directory — a local path (resolved against the
+ * project dir) or an installed package, optionally with a subpath — and
+ * confirms it holds an `mdk-app.yaml`.
+ */
+export function resolveAppPackageDir(projectDir, pkg) {
+    const dir = resolvePackageDir(projectDir, pkg);
+    if (!existsSync(join(dir, APP_MANIFEST))) {
+        throw new Error(`App package "${pkg}" has no ${APP_MANIFEST} (looked in ${dir}).`);
+    }
+    return dir;
+}
+/** The `createAppRuntime` options for one `spec.apps[]` entry. */
+export function resolveAppOptions(projectDir, app, kernel) {
+    return {
+        name: app.name,
+        appDir: resolveAppPackageDir(projectDir, app.package),
+        config: app.config,
+        kernelKey: resolveKernelKey(projectDir, kernel),
+        storeDir: componentDir(projectDir, 'apps', app.name, 'store'),
+        // Read per connection by the runtime, so the Gateway and MCP server may start after the app.
+        allowedKeyFiles: [gatewayKeyFile(projectDir), mcpKeyFile(projectDir)],
+        keyFile: appKeyFile(projectDir, app.name),
+        // The Kernel is fail-closed and admits every `<name>.pub` in the trusted-keys dir.
+        kernelKeyFile: join(trustedKeysDir(projectDir), `app-${app.name}.pub`),
+    };
+}
+/** Boots one app runtime in this process (`mdk run app <name>`); the Kernel must already be running. */
+export async function runApp(projectDir, app) {
+    const options = resolveAppOptions(projectDir, app);
+    mkdirSync(options.storeDir, { recursive: true });
+    process.stderr.write(`${theme.muted('Starting app')} ${arrow} ${theme.value(app.name)}\n`);
+    const runtime = mdkAppRuntime().createAppRuntime(options);
+    await runtime.start();
+    process.stderr.write(`${tick} ${theme.label('app')} ${theme.value(app.name)} ready\n`);
+    return { stop: () => runtime.stop() };
+}
+const APP_STARTUP_TIMEOUT_MS = 30_000;
+/** First restart delay; doubled after each crash, up to the max. */
+const APP_RESTART_DELAY_MS = 1000;
+const APP_RESTART_MAX_MS = 30_000;
+/** A child that ran this long before exiting was healthy: its restart starts the backoff over. */
+const APP_STABLE_MS = 60_000;
+const APP_STOP_GRACE_MS = 3000;
+/**
+ * Runs one app runtime as a child process (`mdk run`). Resolves once the child
+ * reports `ready`; rejects if it reports an `error`, exits first, or stays
+ * silent past the startup timeout. An exit `stop()` did not ask for is
+ * restarted, with a delay that doubles while the app keeps crashing. `entry`
+ * defaults to the runtime's `bin/run-app.js`.
+ */
+export async function superviseApp(projectDir, app, kernel, entry = require.resolve('@tetherto/mdk-app-runtime/bin/run-app.js')) {
+    const options = resolveAppOptions(projectDir, app, kernel);
+    mkdirSync(options.storeDir, { recursive: true });
+    // Resolved now: a restart runs after the CLI has chdir'd into the Gateway's state root.
+    const cwd = resolve(projectDir);
+    // The options carry the app's config, so they go in the environment, not argv.
+    const env = { ...process.env, MDK_APP_RUNTIME_OPTIONS: JSON.stringify(options) };
+    const log = (line) => process.stderr.write(`${line}\n`);
+    const childFile = appChildFile(projectDir, app.name);
+    let child;
+    let stopped = false;
+    let restartTimer;
+    let restartDelay = APP_RESTART_DELAY_MS;
+    let readyAt = 0;
+    const launch = () => new Promise((resolveReady, rejectReady) => {
+        // `cwd` is pinned because the CLI later chdirs into the Gateway's state
+        // root. `detached` keeps a terminal Ctrl+C from reaching the child: the
+        // CLI stops it, and the child exits by itself when its IPC channel closes.
+        const proc = spawn(process.execPath, [entry], {
+            stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+            env,
+            cwd,
+            // On Windows `detached` opens a console window per child instead.
+            detached: process.platform !== 'win32',
+        });
+        child = proc;
+        let ready = false;
+        const fail = (error) => {
+            clearTimeout(timer);
+            proc.kill('SIGKILL');
+            rejectReady(error);
+        };
+        const timer = setTimeout(() => fail(new Error(`App "${app.name}" did not report ready within ${APP_STARTUP_TIMEOUT_MS}ms.`)), APP_STARTUP_TIMEOUT_MS);
+        proc.on('message', (raw) => {
+            const msg = (raw ?? {});
+            if (ready)
+                return;
+            if (msg.type === 'ready') {
+                ready = true;
+                readyAt = Date.now();
+                clearTimeout(timer);
+                mkdirSync(dirname(childFile), { recursive: true });
+                writeFileSync(childFile, String(proc.pid));
+                resolveReady();
+            }
+            else if (msg.type === 'error') {
+                fail(new Error(msg.message ?? 'unknown error'));
+            }
+        });
+        proc.on('error', fail);
+        proc.on('exit', (code, signal) => {
+            clearTimeout(timer);
+            if (child === proc)
+                child = undefined;
+            if (appChildPid(projectDir, app.name) === proc.pid)
+                rmSync(childFile, { force: true });
+            const how = signal ? `signal ${signal}` : `code ${code}`;
+            if (!ready) {
+                rejectReady(new Error(`App "${app.name}" exited before it was ready (${how}).`));
+            }
+            else if (!stopped) {
+                if (Date.now() - readyAt >= APP_STABLE_MS)
+                    restartDelay = APP_RESTART_DELAY_MS;
+                log(`${theme.warn('!')} app ${theme.value(app.name)} exited unexpectedly (${how}); ` +
+                    `restarting in ${Math.round(restartDelay / 1000)}s`);
+                scheduleRestart();
+            }
+        });
+    });
+    const scheduleRestart = () => {
+        const delay = restartDelay;
+        restartDelay = Math.min(restartDelay * 2, APP_RESTART_MAX_MS);
+        restartTimer = setTimeout(() => {
+            launch().then(() => log(`${tick} ${theme.label('app')} ${theme.value(app.name)} restarted`), (error) => {
+                if (stopped)
+                    return;
+                log(`${theme.warn('!')} app ${theme.value(app.name)} failed to restart: ${error.message}`);
+                scheduleRestart();
+            });
+        }, delay);
+    };
+    log(`${theme.muted('Starting app')} ${arrow} ${theme.value(app.name)}`);
+    await launch();
+    log(`${tick} ${theme.label('app')} ${theme.value(app.name)} ready`);
+    return {
+        stop: async () => {
+            stopped = true;
+            clearTimeout(restartTimer);
+            const proc = child;
+            if (!proc)
+                return;
+            const killTimer = setTimeout(() => proc.kill('SIGKILL'), APP_STOP_GRACE_MS);
+            const exited = once(proc, 'exit');
+            proc.kill('SIGTERM');
+            await exited;
+            clearTimeout(killTimer);
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map