@addai/node 0.24.0 → 0.25.0

package/dist/capabilities.d.ts

@@ -20,6 +20,23 @@ interface BinaryProbe extends AuthShape {
     /** All remote login methods (primary strategy first, then alternates). */
     login_methods?: string[];
 }
+interface FlowsCapability {
+    /** Whether this machine is claiming flow runs. Mirrors the server's switch;
+     *  reported back so the Studio can show agreement rather than intent. */
+    enabled: boolean;
+    /** Version of the shared engine this daemon bundles. */
+    engine_version: string | null;
+    /** 'isolated-vm' or the weaker 'vm' fallback, stated plainly. */
+    sandbox: {
+        kind: string;
+        isolated: boolean;
+        note: string | null;
+    };
+    /** Flow runs in flight, and the ceiling. Its own pool — separate from
+     *  agent runs on purpose, so a flows burst cannot starve a chat. */
+    running: number;
+    max_concurrent: number;
+}
 interface CapabilitiesShape {
     /** Version of @addai/node running. Lets the studio / CodeFlows
      *  UIs show "outdated daemon" hints and helps us debug field issues
@@ -49,6 +66,12 @@ interface CapabilitiesShape {
      *  installed. Studio renders an install card in place of the create
      *  button when this is null. */
     container_engine?: EngineInfo | null;
+    /** What this machine can do about +Ai Flows, and what it is doing right now.
+     *  The Studio's Flows tab is built entirely out of this — whether the pump
+     *  is on, how much room is left, and crucially which sandbox the engine
+     *  resolved, because a UI that implies isolated-vm when the weaker `vm`
+     *  fallback is running is worse than one that says nothing. */
+    flows?: FlowsCapability;
     /** CPU / memory / disk / runs at the moment of this probe. The AiNode page
      *  has read this key since it was written; nothing produced it until now. */
     machine?: MachineSample;

package/dist/capabilities.js

@@ -56,6 +56,8 @@ const harness_registry_1 = require("./harness-registry");
 const autostart_1 = require("./autostart");
 const auto_update_1 = require("./auto-update");
 const machine_metrics_1 = require("./machine-metrics");
+const pump_1 = require("./flows/pump");
+const engine_loader_1 = require("./flows/engine-loader");
 function readDaemonVersion() {
     try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -368,6 +370,51 @@ async function probeGit() {
         authed: true,
     };
 }
+/** Describe this machine's flows support.
+ *
+ *  Deliberately does NOT force the engine to load. The engine is ESM with a
+ *  top-level probe of the optional native sandbox, and loading it on every
+ *  heartbeat — on machines that never run a flow — would be a cost paid by
+ *  everyone for the benefit of a few. Once flows are on and the engine is
+ *  loaded, the real sandbox is reported; until then it says so honestly
+ *  rather than guessing.
+ *
+ *  Never throws: a capabilities probe that could fail would take the whole
+ *  heartbeat with it, and the machine would read offline because it could not
+ *  describe its flows support.
+ */
+async function probeFlows() {
+    let engineVersion = null;
+    try {
+        // JSON, so plain require is safe here — this is not the ESM graph.
+        engineVersion = require('@addai/node-flows/package.json').version ?? null;
+    }
+    catch { /* not installed; reported as null below */ }
+    let sandbox = {
+        kind: 'not-loaded',
+        isolated: false,
+        note: 'The engine loads when flows are switched on for this machine.',
+    };
+    if ((0, engine_loader_1.engineLoaded)()) {
+        try {
+            const { sandboxAvailability } = await (0, engine_loader_1.loadEngine)();
+            sandbox = sandboxAvailability();
+        }
+        catch (err) {
+            sandbox = {
+                kind: 'unavailable', isolated: false,
+                note: `The flows engine failed to load: ${err.message}`,
+            };
+        }
+    }
+    return {
+        enabled: (0, pump_1.flowsEnabled)(),
+        engine_version: engineVersion,
+        sandbox,
+        running: (0, pump_1.inflightFlowCount)(),
+        max_concurrent: (0, pump_1.maxConcurrentFlows)(),
+    };
+}
 async function probeCapabilities() {
     // Binary lookups cache misses; a CLI installed mid-daemon-life (by the
     // command runner or by hand) must show up on the next probe, not after
@@ -403,6 +450,7 @@ async function probeCapabilities() {
         daemon_version: readDaemonVersion(),
         autostart: (0, autostart_1.status)(),
         container_engine: containerEngine,
+        flows: await probeFlows(),
         auto_update: (0, auto_update_1.autoUpdateState)(),
         machine: (0, machine_metrics_1.sampleMachine)(),
         claude: deco('claude', claude),

package/dist/claude-print.d.ts

@@ -13,6 +13,20 @@ export interface ClaudePrintInput {
     /** Restrict to a specific set of tools (claude only). null/undefined = inherit. */
     allowedTools?: string[];
 }
+/**
+ * The text to emit for one flushed block, given what came before.
+ *
+ * The final reply is rebuilt with string_agg(delta, '') — an empty join,
+ * because deltas are partial TOKENS and any separator between them would
+ * corrupt words mid-word. Correct within a block, wrong between them: the
+ * entity narrates, calls a tool, narrates again, and the two blocks own no
+ * whitespace of their own, so they arrive glued as "the chat tool.Let me".
+ * The boundary is known here and nowhere else, so it is marked here.
+ */
+export declare function blockDelta(text: string, opts: {
+    afterTool: boolean;
+    hadTextBefore: boolean;
+}): string;
 export interface ClaudePrintHandle {
     pid: number | undefined;
     sessionId: string | null;

package/dist/claude-print.js

@@ -5,11 +5,29 @@
 // our normalised RuntimeEvent shape, and resolves when the process exits.
 // No PTY needed — Claude detects non-TTY and runs headless.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.blockDelta = blockDelta;
 exports.lineToEvents = lineToEvents;
 exports.spawnClaudePrint = spawnClaudePrint;
 const child_process_1 = require("child_process");
 const claude_binary_1 = require("./claude-binary");
 const win_1 = require("./win");
+/**
+ * The text to emit for one flushed block, given what came before.
+ *
+ * The final reply is rebuilt with string_agg(delta, '') — an empty join,
+ * because deltas are partial TOKENS and any separator between them would
+ * corrupt words mid-word. Correct within a block, wrong between them: the
+ * entity narrates, calls a tool, narrates again, and the two blocks own no
+ * whitespace of their own, so they arrive glued as "the chat tool.Let me".
+ * The boundary is known here and nowhere else, so it is marked here.
+ */
+function blockDelta(text, opts) {
+    if (!opts.afterTool || !opts.hadTextBefore || !text.trim())
+        return text;
+    // Drop leading whitespace the model may already have supplied so a break
+    // is exactly one blank line, never two.
+    return `\n\n${text.replace(/^\s+/, '')}`;
+}
 /**
  * Parse one stream-json line into 0+ RuntimeEvents.
  *
@@ -190,6 +208,16 @@ function spawnClaudePrint(input) {
     let textBuf = '';
     let flushTimer = null;
     let sawDeltaThisMsg = false;
+    // Has any answer text been emitted for this run yet? The final reply is
+    // rebuilt by string_agg(delta, '') — an empty join, because deltas are
+    // partial TOKENS and any separator between them would corrupt words. That
+    // is right within a block and wrong between them: the model narrates, calls
+    // a tool, narrates again, and the two blocks arrive as separate messages
+    // with no whitespace of their own. Glued together they read
+    // "load the chat tool.Let me confirm". So the boundary is marked here,
+    // where it is actually known, rather than guessed at in SQL.
+    let emittedAnyText = false;
+    let blockBreakPending = false;
     // Thinking deltas (extended thinking) — coalesced lazily into 'thinking'
     // events; the chat relay renders them as a collapsed section.
     const THINK_FLUSH_MS = 700;
@@ -212,8 +240,11 @@ function spawnClaudePrint(input) {
             flushTimer = null;
         }
         if (textBuf) {
-            const t = textBuf;
+            let t = textBuf;
             textBuf = '';
+            t = blockDelta(t, { afterTool: blockBreakPending, hadTextBefore: emittedAnyText });
+            blockBreakPending = false;
+            emittedAnyText = true;
             emit({ type: 'assistant_text', delta: t });
         }
     };
@@ -258,6 +289,11 @@ function spawnClaudePrint(input) {
         // was seen for this message, in which case we keep the block (never lose text).
         if (partialStream && (type === 'assistant' || type === 'user' || type === 'result'))
             flushText();
+        // A tool result means the entity stopped talking to go and do something.
+        // Whatever it says next is a new paragraph, not a continuation of the
+        // sentence it was halfway through.
+        if (type === 'user')
+            blockBreakPending = true;
         const suppressText = partialStream && sawDeltaThisMsg && type === 'assistant';
         for (const ev of lineToEvents(parsed, suppressText))
             emit(ev);

package/dist/codex-spawn.js

@@ -52,7 +52,6 @@ const codex_binary_1 = require("./codex-binary");
 const diskguard_1 = require("./diskguard");
 const win_1 = require("./win");
 const events_1 = require("./events");
-const mcp_headers_1 = require("./mcp-headers");
 /** Quote a string as a TOML basic string (double-quoted, escape backslash + quote). */
 function tomlString(s) {
     return '"' + String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n') + '"';
@@ -61,11 +60,6 @@ function tomlString(s) {
  *  Only the NAME goes in config.toml — the value rides on the child env, so
  *  the token never lands on disk. */
 const bearerEnvVar = (slug) => `AINODE_MCP_${slug.replace(/[^A-Za-z0-9]+/g, '_').toUpperCase()}_TOKEN`;
-/** Env var name carrying one HTTP header's value into the codex process.
- *  config.toml references it by name via env_http_headers, so the value
- *  itself never lands on disk. */
-const headerEnvVar = (slug, header) => `AINODE_MCP_${slug.replace(/[^A-Za-z0-9]+/g, '_').toUpperCase()}` +
-    `_H_${header.replace(/[^A-Za-z0-9]+/g, '_').toUpperCase()}`;
 /** Build a config.toml that declares only the supplied MCP servers and
  *  return the CODEX_HOME directory plus any env vars the child needs
  *  (bearer tokens for remote servers). Caller is responsible for cleanup
@@ -80,16 +74,12 @@ function writeCodexHome(servers, workingDirectory) {
         // Remote MCP servers. Registry rows store command='http'|'sse' with
         // args=[url]; codex spells that `url = "..."`, NOT command/args. Writing
         // the row verbatim made codex try to exec a binary called `http`, so the
-        // server never started and its tools silently vanished.
-        //
-        // Credentials go through env_http_headers, which maps a header name to the
-        // NAME of an env var holding its value — so the whole credential set is
-        // forwarded and config.toml still never contains a secret. This adapter
-        // used to send only ONE credential as a bearer token, on the belief that
-        // codex could not send custom headers; it can, and a server needing more
-        // than one header (addai-drive carries three) was arriving half-authorised.
-        if ((0, mcp_headers_1.isRemoteMcp)(s.command)) {
-            const url = (0, mcp_headers_1.remoteMcpUrl)(s.args);
+        // server never started and its tools silently vanished — which is how a
+        // provider-ladder hop to codex dropped an entity's GitHub access without
+        // any error anywhere. The claude path (install.ts) always handled this;
+        // codex and grok did not.
+        if (s.command === 'http' || s.command === 'sse') {
+            const url = Array.isArray(s.args) && typeof s.args[0] === 'string' ? s.args[0] : null;
             if (!url) {
                 console.error(`[codex] MCP ${s.slug}: ${s.command} server has no URL — skipped`);
                 continue;
@@ -97,24 +87,22 @@ function writeCodexHome(servers, workingDirectory) {
             const name = tomlString(s.slug).slice(1, -1);
             toml += `[mcp_servers.${name}]\n`;
             toml += `url = ${tomlString(url)}\n`;
-            const headers = (0, mcp_headers_1.remoteMcpHeaders)(s.env);
-            // An OAuth access token is spelled as codex's native bearer rather than
-            // a hand-rolled Authorization header, so its OAuth handling still applies.
-            const bearer = headers.Authorization;
+            // codex reads the bearer from its OWN environment (--env is stdio-only),
+            // so the value goes on the child env and only the var name in the file.
+            const creds = Object.entries(s.env || {})
+                .filter(([k, v]) => typeof v === 'string' && v.length > 0 && !k.startsWith('OAUTH_REFRESH'));
+            const bearer = creds.find(([k]) => k === 'OAUTH_ACCESS_TOKEN') ?? creds[0];
             if (bearer) {
-                delete headers.Authorization;
                 const varName = bearerEnvVar(s.slug);
-                extraEnv[varName] = bearer.replace(/^Bearer\s+/i, '');
+                extraEnv[varName] = String(bearer[1]);
                 toml += `bearer_token_env_var = ${tomlString(varName)}\n`;
-            }
-            const entries = Object.entries(headers);
-            if (entries.length > 0) {
-                // Sub-table must follow the parent table's scalar keys.
-                toml += `[mcp_servers.${name}.env_http_headers]\n`;
-                for (const [header, value] of entries) {
-                    const varName = headerEnvVar(s.slug, header);
-                    extraEnv[varName] = value;
-                    toml += `${tomlString(header)} = ${tomlString(varName)}\n`;
+                if (creds.length > 1) {
+                    // codex carries one bearer and no arbitrary headers. Anything that
+                    // authenticates with several custom headers is only partly wired,
+                    // and saying so beats a server that 401s for no visible reason.
+                    console.error(`[codex] MCP ${s.slug}: only ${bearer[0]} is forwarded as a bearer token; ` +
+                        `codex cannot send custom headers, so ${creds.length - 1} other credential ` +
+                        `field(s) were dropped`);
                 }
             }
             toml += '\n';

package/dist/command-runner.js

@@ -577,6 +577,7 @@ async function runSetAutostart(cmd) {
 const DESKTOP_KINDS = [
     'desktop_create', 'desktop_start', 'desktop_stop',
     'desktop_delete', 'desktop_rebuild', 'desktop_sync_logins',
+    'desktop_exec',
 ];
 /** Setup scripts run as a FILE, never as a `sh -c` string: a script with
  *  quotes or newlines must not need escaping to survive. */
@@ -592,7 +593,12 @@ async function runDesktopCommand(cmd) {
     }
     // force: a user who just installed Docker should not have to restart the
     // daemon for their first desktop to build.
-    const provider = await (0, docker_1.getProvider)(true);
+    // Re-detect the engine for the RARE lifecycle commands: someone who has
+    // just installed Docker should not have to restart the daemon for a create
+    // or a start to find it. desktop_exec is the opposite — an entity driving a
+    // remote desktop makes dozens of these, and `docker info` costs seconds on
+    // Docker Desktop (measured: 4.2s on a Mac), so it uses the cached engine.
+    const provider = await (0, docker_1.getProvider)(cmd.kind !== 'desktop_exec');
     if (!provider) {
         const why = 'No container engine on this machine. Install Docker Desktop or Podman, then try again.';
         await update(cmd.id, 'failed', undefined, why);
@@ -650,11 +656,18 @@ async function runDesktopCommand(cmd) {
                 }
                 break;
             }
-            case 'desktop_start':
+            case 'desktop_start': {
+                // Someone pressed start, so this one fails loudly rather than
+                // deferring quietly the way autostart does. They are owed an answer
+                // they can act on: which limit, and where to change it.
+                const room = await (0, manager_1.desktopStartAllowed)(await (0, manager_1.listDesktops)(), row.id);
+                if (!room.allowed)
+                    throw new Error(room.reason);
                 await (0, manager_1.setStatus)(row.id, { status: 'starting' });
                 await provider.start(row);
                 await (0, manager_1.setStatus)(row.id, { status: 'running', status_message: null });
                 break;
+            }
             case 'desktop_stop':
                 await provider.stop(row);
                 await (0, manager_1.setStatus)(row.id, { status: 'stopped', status_message: null });
@@ -671,6 +684,26 @@ async function runDesktopCommand(cmd) {
             case 'desktop_sync_logins':
                 await (0, creds_1.syncCredentials)(provider, row, onLog);
                 break;
+            case 'desktop_exec': {
+                // An entity on ANOTHER machine driving this desktop. The MCP used to
+                // run `docker exec` locally, so an entity could only ever touch a
+                // desktop that happened to live on the node it was dispatched to.
+                // This is that same exec, arriving over the wire.
+                const argv = Array.isArray(cmd.input?.argv) ? cmd.input.argv : null;
+                if (!argv || argv.length === 0)
+                    throw new Error('desktop_exec needs an argv array');
+                const timeoutMs = Math.min(Math.max(Number(cmd.input?.timeout_ms) || 60_000, 1_000), 10 * 60_000);
+                const res = await (0, creds_1.execInDesktopCapture)(provider, row, argv, timeoutMs);
+                // stdout is base64 because it is frequently a PNG. A non-zero exit is
+                // reported as a completed command carrying that code — the command
+                // ran; what it returned is the entity's problem to read.
+                await update(cmd.id, 'completed', {
+                    stdout_b64: res.stdout.toString('base64'),
+                    stderr: res.stderr.slice(0, 8000),
+                    exit_code: res.exitCode,
+                });
+                return;
+            }
         }
         await update(cmd.id, 'completed', { log });
     }

package/dist/desktop/creds.d.ts

@@ -5,3 +5,18 @@ export declare function stripMcpServers(raw: string): string;
 /** Run a command inside a desktop, streaming output to onLog. */
 export declare function execInDesktop(provider: DesktopProvider, row: DesktopRow, cmd: string[], onLog: (c: string) => void): Promise<void>;
 export declare function syncCredentials(provider: DesktopProvider, row: DesktopRow, onLog: (c: string) => void): Promise<void>;
+/**
+ * Run a command inside a desktop and CAPTURE its output.
+ *
+ * execInDesktop streams to a log, which is right for an install and useless
+ * for a screenshot: the caller needs the bytes back, exactly, and a PNG does
+ * not survive being treated as UTF-8. This is the remote arm of the desktop
+ * MCP — an entity running on one machine driving a desktop on another — so
+ * the result has to cross the wire intact and a non-zero exit is a RESULT,
+ * not a transport failure.
+ */
+export declare function execInDesktopCapture(provider: DesktopProvider, row: DesktopRow, cmd: string[], timeoutMs?: number): Promise<{
+    stdout: Buffer;
+    stderr: string;
+    exitCode: number;
+}>;

package/dist/desktop/creds.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripMcpServers = stripMcpServers;
 exports.execInDesktop = execInDesktop;
 exports.syncCredentials = syncCredentials;
+exports.execInDesktopCapture = execInDesktopCapture;
 // Harness logins are COPIED into a desktop, never bind-mounted.
 //
 // Bind-mounting ~/.claude would hand the box write access to every transcript
@@ -132,3 +133,30 @@ async function syncCredentials(provider, row, onLog) {
         }
     }
 }
+/**
+ * Run a command inside a desktop and CAPTURE its output.
+ *
+ * execInDesktop streams to a log, which is right for an install and useless
+ * for a screenshot: the caller needs the bytes back, exactly, and a PNG does
+ * not survive being treated as UTF-8. This is the remote arm of the desktop
+ * MCP — an entity running on one machine driving a desktop on another — so
+ * the result has to cross the wire intact and a non-zero exit is a RESULT,
+ * not a transport failure.
+ */
+function execInDesktopCapture(provider, row, cmd, timeoutMs = 60_000) {
+    const args = (0, provider_1.buildExecArgs)(row, cmd, { cwd: '/work', env: {}, tty: false });
+    const inv = (0, win_1.resolveCliInvocation)(provider.id, args);
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(inv.file, inv.args, {
+            env: process.env, windowsHide: true, timeout: timeoutMs,
+        });
+        const out = [];
+        let err = '';
+        child.stdout?.on('data', (b) => out.push(b));
+        child.stderr?.on('data', (b) => { err += b.toString('utf8'); });
+        child.on('error', reject);
+        child.on('close', code => resolve({
+            stdout: Buffer.concat(out), stderr: err, exitCode: code ?? -1,
+        }));
+    });
+}

package/dist/desktop/manager.d.ts

@@ -24,6 +24,25 @@ export declare function ensureDirs(desktopId: string): {
     confDir: string;
     workDir: string;
 };
+export declare const DEFAULT_MAX_CONCURRENT_DESKTOPS = 2;
+export declare function clampMaxDesktops(value: unknown): number;
+/** Pushed in by the heartbeat. Lowering it never stops a running desktop —
+ *  killing someone's live session to satisfy a number they just typed would
+ *  be a worse surprise than being one over the cap for a while. */
+export declare function setMaxConcurrentDesktops(value: unknown): void;
+export declare function maxConcurrentDesktops(): number;
+/** How many desktops are running right now, asked of the engine rather than
+ *  tracked in a counter. A counter would drift the moment somebody stopped a
+ *  container by hand, and drift upward means refusing to start anything. */
+export declare function runningDesktopCount(rows: DesktopRow[]): Promise<number>;
+/** Whether one more may start. Returns the reason when it may not, so the
+ *  caller can say something better than "failed". */
+export declare function desktopStartAllowed(rows: DesktopRow[], excludeId?: string): Promise<{
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+}>;
 export declare function startDesktopManager(): void;
 export declare function stopDesktopManager(): void;
 /** Bring a desktop up and wait for it, for the run path. Returns the row when

package/dist/desktop/manager.js

@@ -33,11 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_CONCURRENT_DESKTOPS = void 0;
 exports.reconcileAction = reconcileAction;
 exports.listDesktops = listDesktops;
 exports.setStatus = setStatus;
 exports.allocateVncPort = allocateVncPort;
 exports.ensureDirs = ensureDirs;
+exports.clampMaxDesktops = clampMaxDesktops;
+exports.setMaxConcurrentDesktops = setMaxConcurrentDesktops;
+exports.maxConcurrentDesktops = maxConcurrentDesktops;
+exports.runningDesktopCount = runningDesktopCount;
+exports.desktopStartAllowed = desktopStartAllowed;
 exports.startDesktopManager = startDesktopManager;
 exports.stopDesktopManager = stopDesktopManager;
 exports.ensureRunning = ensureRunning;
@@ -118,6 +124,70 @@ function ensureDirs(desktopId) {
     fs.mkdirSync(workDir, { recursive: true, mode: 0o700 });
     return { confDir, workDir };
 }
+// How many desktops may be RUNNING on this machine at once.
+//
+// There was never a ceiling here, and the failure it allows is not subtle:
+// four containers each sized for a browser will take a Mac mini down, and
+// when they do they take the agent runs and the flow runs with them. Its own
+// pool, like flows and agent runs, because the three compete for the same box
+// but answer to different people.
+//
+// Absent means "keep what you had", never 0 — a server that has not had the
+// migration must not be able to stop every desktop on every machine.
+exports.DEFAULT_MAX_CONCURRENT_DESKTOPS = 2;
+const MAX_MAX_CONCURRENT_DESKTOPS = 16;
+let maxDesktops = exports.DEFAULT_MAX_CONCURRENT_DESKTOPS;
+function clampMaxDesktops(value) {
+    if (typeof value !== 'number' && typeof value !== 'string')
+        return exports.DEFAULT_MAX_CONCURRENT_DESKTOPS;
+    if (typeof value === 'string' && value.trim() === '')
+        return exports.DEFAULT_MAX_CONCURRENT_DESKTOPS;
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n))
+        return exports.DEFAULT_MAX_CONCURRENT_DESKTOPS;
+    return Math.min(MAX_MAX_CONCURRENT_DESKTOPS, Math.max(1, Math.floor(n)));
+}
+/** Pushed in by the heartbeat. Lowering it never stops a running desktop —
+ *  killing someone's live session to satisfy a number they just typed would
+ *  be a worse surprise than being one over the cap for a while. */
+function setMaxConcurrentDesktops(value) {
+    const next = clampMaxDesktops(value);
+    if (next === maxDesktops)
+        return;
+    console.log(`[desktops] desktops at once: ${maxDesktops} -> ${next}`);
+    maxDesktops = next;
+}
+function maxConcurrentDesktops() { return maxDesktops; }
+/** How many desktops are running right now, asked of the engine rather than
+ *  tracked in a counter. A counter would drift the moment somebody stopped a
+ *  container by hand, and drift upward means refusing to start anything. */
+async function runningDesktopCount(rows) {
+    const provider = await (0, docker_1.getProvider)();
+    if (!provider)
+        return 0;
+    let count = 0;
+    for (const row of rows) {
+        try {
+            const actual = await provider.inspect(row);
+            if (actual?.running)
+                count++;
+        }
+        catch { /* unknown state counts as not running; the reconcile will fix it */ }
+    }
+    return count;
+}
+/** Whether one more may start. Returns the reason when it may not, so the
+ *  caller can say something better than "failed". */
+async function desktopStartAllowed(rows, excludeId) {
+    const running = await runningDesktopCount(rows.filter(r => r.id !== excludeId));
+    if (running < maxDesktops)
+        return { allowed: true };
+    return {
+        allowed: false,
+        reason: `This machine is already running ${running} desktop${running === 1 ? '' : 's'}, `
+            + `its limit. Stop one, or raise the limit on the machine's page.`,
+    };
+}
 let timer = null;
 let inflight = false;
 async function tick() {
@@ -136,6 +206,15 @@ async function tick() {
                 continue;
             try {
                 if (action === 'start') {
+                    // Autostart is the quiet path to blowing the cap: a machine that
+                    // reboots would bring every desktop back at once regardless of what
+                    // the box can take. Over the line, it defers and says so rather than
+                    // failing — nothing is wrong with the desktop, there is just no room.
+                    const room = await desktopStartAllowed(rows, row.id);
+                    if (!room.allowed) {
+                        await setStatus(row.id, { status: 'stopped', status_message: room.reason });
+                        continue;
+                    }
                     await provider.start(row);
                     await setStatus(row.id, { status: 'running', status_message: null });
                 }
@@ -196,6 +275,14 @@ async function ensureRunning(desktopId, timeoutMs = 60_000) {
         return row;
     if (!actual)
         return null; // never created / pruned: cannot start
+    // At the cap, the run falls back to the host rather than starting an
+    // eleventh container. Returning null is how this function already says
+    // "could not start it" and the caller already handles it.
+    const room = await desktopStartAllowed(rows, row.id);
+    if (!room.allowed) {
+        console.warn(`[desktops] not starting ${row.id} for a run — ${room.reason}`);
+        return null;
+    }
     const deadline = Date.now() + timeoutMs;
     try {
         await provider.start(row);

package/dist/desktop/relay-client.js

@@ -164,10 +164,24 @@ async function connect() {
         catch {
             return;
         }
+        // Every way a bridge can fail used to fail SILENTLY: the viewer's socket
+        // stayed open, noVNC went on reporting 'connected', and the last frame sat
+        // there looking live while every keystroke was dropped on the floor. A
+        // frozen picture you cannot tell from a working one is the worst possible
+        // failure, so each of these now says so and the viewer is disconnected.
+        const gone = (viewerId, reason) => {
+            bridges.get(viewerId)?.destroy();
+            bridges.delete(viewerId);
+            if (sock.readyState === ws_1.default.OPEN) {
+                sock.send(JSON.stringify({ type: 'gone', viewerId, reason }));
+            }
+        };
         if (msg.type === 'attach') {
             const row = (await (0, manager_1.listDesktops)()).find(d => d.id === msg.desktopId);
-            if (!row?.vnc_port)
+            if (!row?.vnc_port) {
+                gone(msg.viewerId, 'desktop is not running');
                 return;
+            }
             // Loopback only - the container published its RFB on 127.0.0.1 and this
             // process is the only thing on the machine that reaches it.
             const tcp = net.connect(row.vnc_port, '127.0.0.1');
@@ -178,15 +192,25 @@ async function connect() {
                     }));
                 }
             });
-            const forget = () => { bridges.delete(msg.viewerId); };
-            tcp.on('close', forget);
-            tcp.on('error', forget);
+            // Refused connection (container up, x11vnc not listening) and a bridge
+            // that dies mid-stream are different words but the same outcome for the
+            // person watching: there is no screen any more, and they must be told.
+            tcp.on('error', () => gone(msg.viewerId, 'lost the desktop connection'));
+            tcp.on('close', () => gone(msg.viewerId, 'the desktop closed the connection'));
             bridges.get(msg.viewerId)?.destroy();
             bridges.set(msg.viewerId, tcp);
             return;
         }
         if (msg.type === 'data' && msg.b64) {
-            bridges.get(msg.viewerId)?.write(Buffer.from(msg.b64, 'base64'));
+            const bridge = bridges.get(msg.viewerId);
+            // Input for a bridge that no longer exists. Dropping it quietly is how
+            // "take control does nothing" happens: the pointer never moves and the
+            // viewer has no idea why.
+            if (!bridge) {
+                gone(msg.viewerId, 'no longer connected to the desktop');
+                return;
+            }
+            bridge.write(Buffer.from(msg.b64, 'base64'));
             return;
         }
         if (msg.type === 'wake') {

package/dist/flows/engine-loader.d.ts

@@ -0,0 +1,8 @@
+type EngineModule = typeof import('@addai/node-flows');
+/** Load the engine once and reuse it. The promise is cached rather than the
+ *  module, so concurrent first calls share one load instead of racing. */
+export declare function loadEngine(): Promise<EngineModule>;
+/** Has the engine been loaded already? Lets the capabilities probe report the
+ *  sandbox without forcing a load on a machine that does not run flows. */
+export declare function engineLoaded(): boolean;
+export {};