@addai/node 0.27.1 → 0.29.0

package/dist/desktop/learn/recorder.mjs

@@ -0,0 +1,151 @@
+// The CDP recorder. Runs INSIDE the desktop container, next to the browser.
+//
+//   node /conf/learn/recorder.mjs
+//
+// Writes NDJSON on stdout, one event per line, `t` in ms since it attached.
+// The daemon reads that stream directly — no file, no polling — and batches it
+// into the lesson row.
+//
+// Nothing is installed to make this work: the image already has node 22, whose
+// global WebSocket is enough for CDP, and Chrome, which the browser wrapper has
+// already given a debug port. If the port is not there (a browser opened before
+// the wrapper existed) it says so in one line and exits 3, and the lesson goes
+// on without the browser track rather than failing.
+import { injectedSource } from './injected.mjs';
+
+const PORT = Number(process.env.ADDAI_LEARN_PORT || 9222);
+const t0 = Date.now();
+
+const emit = (o) => {
+  try { process.stdout.write(JSON.stringify({ t: Date.now() - t0, ...o }) + '\n'); }
+  catch { /* the daemon went away; nothing to do about it from here */ }
+};
+
+async function version() {
+  // A browser that is starting up refuses for a moment. Three tries over ~3s
+  // covers the case where a lesson begins in the same breath as the browser.
+  for (let i = 0; i < 3; i++) {
+    try {
+      const r = await fetch(`http://127.0.0.1:${PORT}/json/version`);
+      if (r.ok) return await r.json();
+    } catch { /* not up yet */ }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return null;
+}
+
+function client(url) {
+  const ws = new WebSocket(url);
+  let next = 1;
+  const pending = new Map();
+  const handlers = [];
+
+  const send = (method, params = {}, sessionId) =>
+    new Promise((resolve) => {
+      const id = next++;
+      pending.set(id, resolve);
+      const msg = { id, method, params };
+      if (sessionId) msg.sessionId = sessionId;
+      try { ws.send(JSON.stringify(msg)); } catch { pending.delete(id); resolve(null); }
+    });
+
+  ws.addEventListener('message', (ev) => {
+    let m;
+    try { m = JSON.parse(ev.data); } catch { return; }
+    if (m.id && pending.has(m.id)) { pending.get(m.id)(m.result ?? null); pending.delete(m.id); return; }
+    for (const h of handlers) h(m);
+  });
+
+  return {
+    ws,
+    send,
+    on: (fn) => handlers.push(fn),
+    ready: new Promise((resolve, reject) => {
+      ws.addEventListener('open', resolve);
+      ws.addEventListener('error', () => reject(new Error('cdp socket refused')));
+    }),
+  };
+}
+
+async function main() {
+  const v = await version();
+  if (!v || !v.webSocketDebuggerUrl) {
+    emit({ kind: 'no_port' });
+    process.exit(3);
+  }
+
+  const cdp = client(v.webSocketDebuggerUrl);
+  await cdp.ready;
+
+  const source = injectedSource();
+  const attached = new Set();
+
+  const arm = async (sessionId) => {
+    if (attached.has(sessionId)) return;
+    attached.add(sessionId);
+    await cdp.send('Runtime.enable', {}, sessionId);
+    await cdp.send('Page.enable', {}, sessionId);
+    // The binding is how the page talks back. Added before the script that
+    // calls it, or the first click on an already-open page is lost.
+    await cdp.send('Runtime.addBinding', { name: '__addaiLearn' }, sessionId);
+    await cdp.send('Page.addScriptToEvaluateOnNewDocument', { source }, sessionId);
+    // …and once for the document that is already loaded, which the line above
+    // does not cover.
+    await cdp.send('Runtime.evaluate', { expression: source }, sessionId);
+  };
+
+  cdp.on(async (m) => {
+    const s = m.sessionId;
+    if (m.method === 'Target.targetCreated' && m.params?.targetInfo?.type === 'page') {
+      await cdp.send('Target.attachToTarget', { targetId: m.params.targetInfo.targetId, flatten: true });
+      return;
+    }
+    if (m.method === 'Target.attachedToTarget') {
+      const info = m.params?.targetInfo ?? {};
+      if (info.type !== 'page') return;
+      emit({ kind: 'tab_open', url: info.url ?? null });
+      await arm(m.params.sessionId);
+      return;
+    }
+    if (m.method === 'Target.detachedFromTarget') {
+      attached.delete(m.params?.sessionId);
+      emit({ kind: 'tab_close' });
+      return;
+    }
+    if (m.method === 'Runtime.bindingCalled' && m.params?.name === '__addaiLearn') {
+      let ev;
+      try { ev = JSON.parse(m.params.payload); } catch { return; }
+      emit(ev);
+      return;
+    }
+    if (m.method === 'Page.frameNavigated' && !m.params?.frame?.parentId) {
+      emit({ kind: 'url', url: m.params.frame.url ?? null, title: null });
+      // A navigation replaces the execution context; re-arming is cheap and
+      // idempotent, and skipping it loses every click on the new page.
+      if (s) { attached.delete(s); await arm(s); }
+      return;
+    }
+    if (m.method === 'Page.loadEventFired' && s) {
+      const r = await cdp.send('Runtime.evaluate',
+        { expression: 'document.title', returnByValue: true }, s);
+      emit({ kind: 'load', title: r?.result?.value ?? null });
+      return;
+    }
+    if (m.method === 'Page.javascriptDialogOpening') {
+      emit({ kind: 'dialog', dtype: m.params?.type ?? null, message: m.params?.message ?? null });
+    }
+  });
+
+  await cdp.send('Target.setDiscoverTargets', { discover: true });
+  emit({ kind: 'watching' });
+
+  const bye = () => { try { cdp.ws.close(); } catch { /* already gone */ } process.exit(0); };
+  process.on('SIGTERM', bye);
+  process.on('SIGINT', bye);
+  cdp.ws.addEventListener('close', () => process.exit(0));
+}
+
+main().catch((e) => {
+  emit({ kind: 'recorder_error', message: String(e && e.message ? e.message : e) });
+  process.exit(1);
+});

package/dist/desktop/learn/session.d.ts

@@ -0,0 +1,51 @@
+import { DesktopProvider } from '../provider';
+import { DesktopRow } from '../spec';
+export interface PageEvent {
+    t: number;
+    kind: string;
+    [k: string]: unknown;
+}
+/**
+ * Split whole NDJSON lines out of a stream chunk.
+ *
+ * A chunk boundary lands in the middle of a line often enough to matter, so
+ * the remainder comes back for the next call rather than being parsed as junk
+ * and dropped. Junk that is genuinely junk IS dropped: a browser writing to
+ * stderr must not be able to kill a lesson.
+ */
+export declare function parseNdjson(buf: string): {
+    events: PageEvent[];
+    rest: string;
+};
+export type SendEvents = (events: PageEvent[]) => Promise<{
+    status?: string;
+    full?: boolean;
+} | null>;
+export interface Batcher {
+    push(ev: PageEvent): void;
+    flush(): Promise<void>;
+    stop(): void;
+    /** Set once the server says the lesson is over or the row is full. */
+    done: boolean;
+}
+/**
+ * Events go up in batches, not one at a time: a page that fires an input event
+ * per keystroke would otherwise be one HTTP request per keystroke.
+ */
+export declare function createBatcher(send: SendEvents, opts?: {
+    everyMs?: number;
+    max?: number;
+}): Batcher;
+export declare const lessonIsRunning: (recordingId: string) => boolean;
+export interface StartResult {
+    browserTrack: boolean;
+    note?: string;
+}
+export declare function startLesson(opts: {
+    provider: DesktopProvider;
+    row: DesktopRow;
+    recordingId: string;
+    send: SendEvents;
+    onLog?: (s: string) => void;
+}): Promise<StartResult>;
+export declare function stopLesson(recordingId: string): Promise<void>;

package/dist/desktop/learn/session.js

@@ -0,0 +1,224 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lessonIsRunning = void 0;
+exports.parseNdjson = parseNdjson;
+exports.createBatcher = createBatcher;
+exports.startLesson = startLesson;
+exports.stopLesson = stopLesson;
+// Running a lesson's container half.
+//
+// The daemon spawns recorder.mjs inside the desktop and reads its NDJSON on
+// stdout. Two commands bracket it — desktop_record_start and
+// desktop_record_stop — and between them this module owns one child process
+// and one batch of events on its way to the lesson row.
+//
+// Everything the container needs is copied into /conf, which the daemon owns on
+// the host and the container sees as a bind mount. That is why no image change
+// is needed and why there is no `docker cp` anywhere in this feature.
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const provider_1 = require("../provider");
+const win_1 = require("../../win");
+const creds_1 = require("../creds");
+const manager_1 = require("../manager");
+const browser_1 = require("./browser");
+/**
+ * Split whole NDJSON lines out of a stream chunk.
+ *
+ * A chunk boundary lands in the middle of a line often enough to matter, so
+ * the remainder comes back for the next call rather than being parsed as junk
+ * and dropped. Junk that is genuinely junk IS dropped: a browser writing to
+ * stderr must not be able to kill a lesson.
+ */
+function parseNdjson(buf) {
+    const events = [];
+    const parts = buf.split('\n');
+    const rest = parts.pop() ?? '';
+    for (const line of parts) {
+        const s = line.trim();
+        if (!s)
+            continue;
+        try {
+            const o = JSON.parse(s);
+            if (o && typeof o === 'object' && typeof o.kind === 'string')
+                events.push(o);
+        }
+        catch { /* not ours */ }
+    }
+    return { events, rest };
+}
+/**
+ * Events go up in batches, not one at a time: a page that fires an input event
+ * per keystroke would otherwise be one HTTP request per keystroke.
+ */
+function createBatcher(send, opts = {}) {
+    const everyMs = opts.everyMs ?? 2_000;
+    const max = opts.max ?? 50;
+    let queue = [];
+    let timer = null;
+    const b = {
+        done: false,
+        push(ev) {
+            if (b.done)
+                return;
+            queue.push(ev);
+            if (queue.length >= max)
+                void b.flush();
+            else if (!timer)
+                timer = setTimeout(() => { void b.flush(); }, everyMs);
+        },
+        async flush() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            if (queue.length === 0)
+                return;
+            const batch = queue;
+            queue = [];
+            try {
+                const res = await send(batch);
+                // The row said the lesson is over, or it has taken all it will take.
+                if (res && (res.full || (res.status && res.status !== 'recording' && res.status !== 'compiling'))) {
+                    b.done = true;
+                }
+            }
+            catch {
+                // Best effort. Losing a batch costs detail in one lesson; throwing here
+                // would take down the command runner that owns the desktop.
+            }
+        },
+        stop() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            b.done = true;
+            queue = [];
+        },
+    };
+    return b;
+}
+const live = new Map();
+const lessonIsRunning = (recordingId) => live.has(recordingId);
+exports.lessonIsRunning = lessonIsRunning;
+/** Assets the container runs. Copied rather than mounted from anywhere clever:
+ *  /conf is already there, and a copy means the version that started a lesson
+ *  is the version that finishes it even if the daemon rolls mid-recording. */
+function stageAssets(confDir) {
+    const dir = path.join(confDir, 'learn');
+    fs.mkdirSync(dir, { recursive: true });
+    for (const f of ['recorder.mjs', 'injected.mjs']) {
+        fs.copyFileSync(path.join(__dirname, f), path.join(dir, f));
+    }
+    return dir;
+}
+async function startLesson(opts) {
+    const { provider, row, recordingId, send } = opts;
+    const log = opts.onLog ?? (() => { });
+    if (live.has(recordingId))
+        return { browserTrack: live.get(recordingId).browserTrack };
+    const { confDir } = (0, manager_1.ensureDirs)(row.id);
+    stageAssets(confDir);
+    const run = async (cmd) => {
+        const r = await (0, creds_1.execInDesktopCapture)(provider, row, cmd, 20_000);
+        return { ok: r.exitCode === 0, out: r.stdout.toString('utf8') };
+    };
+    const wrapper = await (0, browser_1.ensureBrowserWrapper)(run, confDir);
+    if (wrapper.note)
+        log(`${wrapper.note}\n`);
+    const args = (0, provider_1.buildExecArgs)(row, ['node', '/conf/learn/recorder.mjs'], { cwd: '/work', env: {}, tty: false });
+    const inv = (0, win_1.resolveCliInvocation)(provider.id, args);
+    const child = (0, child_process_1.spawn)(inv.file, inv.args, { env: process.env, windowsHide: true });
+    const batcher = createBatcher(send);
+    const entry = { child, batcher, browserTrack: false };
+    live.set(recordingId, entry);
+    let settle = null;
+    const settled = new Promise((resolve) => { settle = resolve; });
+    const answer = (r) => { if (settle) {
+        settle(r);
+        settle = null;
+    } };
+    let rest = '';
+    child.stdout?.on('data', (b) => {
+        const parsed = parseNdjson(rest + b.toString('utf8'));
+        rest = parsed.rest;
+        for (const ev of parsed.events) {
+            if (ev.kind === 'no_port') {
+                answer({
+                    browserTrack: false,
+                    note: 'The browser was open before recording started, so it had no debugging '
+                        + 'port and the page detail could not be captured.',
+                });
+                continue;
+            }
+            if (ev.kind === 'watching') {
+                entry.browserTrack = true;
+                answer({ browserTrack: true });
+                continue;
+            }
+            batcher.push(ev);
+            if (batcher.done) {
+                stopLesson(recordingId);
+                return;
+            }
+        }
+    });
+    child.stderr?.on('data', (b) => log(b.toString('utf8').slice(0, 500)));
+    child.on('error', (err) => answer({ browserTrack: false, note: `recorder failed to start: ${err.message}` }));
+    child.on('exit', () => {
+        answer({ browserTrack: false, note: 'the browser recorder stopped early' });
+        void batcher.flush();
+        live.delete(recordingId);
+    });
+    // Do not wait forever for a first line: a lesson without the browser track is
+    // still a lesson, and the person is already recording.
+    const timeout = new Promise((resolve) => setTimeout(() => resolve({ browserTrack: entry.browserTrack }), 8_000).unref?.());
+    return Promise.race([settled, timeout]);
+}
+async function stopLesson(recordingId) {
+    const entry = live.get(recordingId);
+    if (!entry)
+        return;
+    live.delete(recordingId);
+    await entry.batcher.flush();
+    entry.batcher.stop();
+    try {
+        entry.child.kill('SIGTERM');
+    }
+    catch { /* already gone */ }
+}

package/dist/desktop/manager.d.ts

@@ -35,6 +35,10 @@ export declare function maxConcurrentDesktops(): number;
  *  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>;
+/** Oldest waiter first, everything else after. Without this the order is
+ *  whatever the listing happened to return, which is how a desktop ends up
+ *  waiting behind one that asked after it. */
+export declare function queueOrder<T extends Pick<DesktopRow, 'status' | 'queued_at'>>(rows: T[]): T[];
 /** 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<{

package/dist/desktop/manager.js

@@ -43,6 +43,7 @@ exports.clampMaxDesktops = clampMaxDesktops;
 exports.setMaxConcurrentDesktops = setMaxConcurrentDesktops;
 exports.maxConcurrentDesktops = maxConcurrentDesktops;
 exports.runningDesktopCount = runningDesktopCount;
+exports.queueOrder = queueOrder;
 exports.desktopStartAllowed = desktopStartAllowed;
 exports.startDesktopManager = startDesktopManager;
 exports.stopDesktopManager = stopDesktopManager;
@@ -68,6 +69,11 @@ function reconcileAction(row, actual) {
         || row.status === 'deleting' || row.status === 'pending'
         || row.status === 'failed')
         return 'none';
+    // Waiting for a slot. The tick retries it every pass; whether there is room
+    // yet is decided there, because it depends on every OTHER desktop, not this
+    // one. Somebody starting it by hand in the meantime just resolves the wait.
+    if (row.status === 'queued')
+        return actual?.running ? 'mark_running' : 'start';
     if (actual === null) {
         // The row says this exists and it does not. Someone pruned it by hand.
         return row.status === 'running' || row.status === 'stopped' ? 'mark_failed' : 'none';
@@ -176,6 +182,23 @@ async function runningDesktopCount(rows) {
     }
     return count;
 }
+/** When a desktop asked for its slot, as a sortable number. A waiter whose
+ *  stamp is missing or unreadable goes to the BACK, not the front: Date.parse
+ *  returns NaN for those, every NaN comparison is false, and a comparator that
+ *  returns NaN is treated as 0 — so the unstamped row would quietly keep
+ *  whatever position the listing gave it and cut in front of real waiters. */
+function waitingSince(row) {
+    if (row.status !== 'queued')
+        return Number.POSITIVE_INFINITY;
+    const at = Date.parse(row.queued_at ?? '');
+    return Number.isFinite(at) ? at : Number.POSITIVE_INFINITY;
+}
+/** Oldest waiter first, everything else after. Without this the order is
+ *  whatever the listing happened to return, which is how a desktop ends up
+ *  waiting behind one that asked after it. */
+function queueOrder(rows) {
+    return [...rows].sort((a, b) => waitingSince(a) - waitingSince(b));
+}
 /** 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) {
@@ -199,7 +222,7 @@ async function tick() {
         if (!provider)
             return; // no engine: nothing to reconcile
         const rows = await listDesktops();
-        for (const row of rows) {
+        for (const row of queueOrder(rows)) {
             const actual = await provider.inspect(row);
             const action = reconcileAction(row, actual);
             if (action === 'none')
@@ -212,7 +235,13 @@ async function tick() {
                     // 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 });
+                        // Stay in the queue rather than dropping out of it. A desktop that
+                        // fell back to 'stopped' here would need asking for all over again,
+                        // which is exactly what waiting is supposed to save you.
+                        // queued_at is stamped by the status RPC, which keeps the
+                        // original on a re-queue — a desktop must not lose its place in
+                        // the line every time the reconciler looks at it.
+                        await setStatus(row.id, { status: 'queued', status_message: room.reason });
                         continue;
                     }
                     await provider.start(row);

package/dist/desktop/provider.d.ts

@@ -7,6 +7,10 @@ export interface EngineInfo {
     running: boolean;
     /** Set when running is false: what to do about it, in words. */
     reason?: string;
+    /** Where the CLI actually is. Carried through so container calls spawn the
+     *  same binary the probe found, not a bare name off a PATH that may not
+     *  have it — see engineBinary(). */
+    binary?: string;
 }
 export interface ExecOpts {
     cwd: string;

package/dist/desktop/spec.d.ts

@@ -13,8 +13,11 @@ export interface DesktopRow {
     enabled_skills: string[];
     enabled_packages: string[];
     autostart: boolean;
-    status: 'pending' | 'creating' | 'starting' | 'running' | 'stopped' | 'failed' | 'deleting';
+    status: 'pending' | 'creating' | 'starting' | 'running' | 'stopped' | 'failed' | 'deleting' | 'queued';
     status_message: string | null;
+    /** Set while this desktop is waiting for a slot on a full machine. The node
+     *  serves its queue oldest-first, so this is the place in the line. */
+    queued_at?: string | null;
     vnc_port: number | null;
     vnc_password: string | null;
 }

package/dist/desktop/start-engine.d.ts

@@ -9,14 +9,17 @@ export interface StartPlan {
     /** Launch and walk away — Docker Desktop is a GUI app that outlives us. */
     detached: boolean;
 }
+export declare const MAC_APP = "/Applications/Docker.app";
 /**
  * Pure, so the choice is testable on any machine.
  *
- * @param programFiles  %ProgramFiles% on Windows. Passed in rather than read
- *                      from the environment so the Windows path is testable
- *                      from a Mac, which is where it is usually written.
+ * @param programFiles     %ProgramFiles% on Windows. Passed in rather than read
+ *                         from the environment so the Windows path is testable
+ *                         from a Mac, which is where it is usually written.
+ * @param macAppInstalled  same reason: a Mac without Docker must still be able
+ *                         to assert what a Mac with Docker does.
  */
-export declare function startPlan(platform: NodeJS.Platform, isRoot: boolean, programFiles?: string): StartPlan;
+export declare function startPlan(platform: NodeJS.Platform, isRoot: boolean, programFiles?: string, macAppInstalled?: boolean): StartPlan;
 /** Build the argv for a privileged start. Password on stdin, never argv —
  *  argv is world-readable through /proc. */
 export declare function sudoStartArgv(): {

package/dist/desktop/start-engine.js

@@ -1,6 +1,39 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.START_TIMEOUT_MS = void 0;
+exports.START_TIMEOUT_MS = exports.MAC_APP = void 0;
 exports.startPlan = startPlan;
 exports.sudoStartArgv = sudoStartArgv;
 exports.runningAsRoot = runningAsRoot;
@@ -19,21 +52,32 @@ exports.startEngine = startEngine;
 // inheriting the install button's sudo round trip on machines that never need
 // it.
 const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
 const win_1 = require("../win");
 const engine_1 = require("./engine");
+exports.MAC_APP = '/Applications/Docker.app';
 /**
  * Pure, so the choice is testable on any machine.
  *
- * @param programFiles  %ProgramFiles% on Windows. Passed in rather than read
- *                      from the environment so the Windows path is testable
- *                      from a Mac, which is where it is usually written.
+ * @param programFiles     %ProgramFiles% on Windows. Passed in rather than read
+ *                         from the environment so the Windows path is testable
+ *                         from a Mac, which is where it is usually written.
+ * @param macAppInstalled  same reason: a Mac without Docker must still be able
+ *                         to assert what a Mac with Docker does.
  */
-function startPlan(platform, isRoot, programFiles) {
+function startPlan(platform, isRoot, programFiles, macAppInstalled = platform === 'darwin' && fs.existsSync(exports.MAC_APP)) {
     if (platform === 'darwin') {
         // `open -a` returns as soon as the app is launching; the daemon comes up
         // a while later, which is why the caller polls rather than trusting exit 0.
+        //
+        // By path when the app is where it should be: `-a Docker` is a
+        // LaunchServices name lookup, and that database has not always caught up
+        // minutes after a fresh install — which is exactly when this button gets
+        // pressed. The name stays as the fallback for a Docker installed
+        // somewhere else.
+        const target = macAppInstalled ? exports.MAC_APP : 'Docker';
         return {
-            file: 'open', args: ['-a', 'Docker'],
+            file: 'open', args: ['-a', target],
             manual: 'open -a Docker', needsRoot: false, detached: false,
         };
     }

package/dist/desktop/vault-extension.d.ts

@@ -0,0 +1,21 @@
+/** Where the extension lives inside a desktop. /conf is the host's confDir. */
+export declare const EXTENSION_DIR = "/conf/vault/extension";
+/** Every file the browser needs. Sourcemaps are deliberately absent: they are
+ *  four times the size of the code and nobody debugs this from inside a
+ *  container. */
+export declare const EXTENSION_FILES: string[];
+/** The vendored copy that ships inside this package. */
+export declare function packagedExtensionDir(): string;
+export interface VaultExtensionResult {
+    /** Whether anything was written this time. */
+    changed: boolean;
+    /** False when this build has no vendored extension to install. */
+    available: boolean;
+}
+/**
+ * Put the extension where the desktop's browser can load it.
+ *
+ * Copies only what differs, by size and mtime, so calling this on every
+ * desktop start is cheap after the first one.
+ */
+export declare function ensureVaultExtension(confDir: string): VaultExtensionResult;