@prohost/cli 0.14.0 → 0.16.0

package/dist/host/pair.js

@@ -0,0 +1,219 @@
+/**
+ * `prohost host pair` — add this computer to a workspace.
+ *
+ * Two ways in:
+ *
+ * - **Device code** (default). The CLI asks for a code, prints it with the
+ *   page to enter it on, and polls until someone in the workspace approves it
+ *   (`/v1/computers/pairing/start` then `/poll`). Nothing secret is printed:
+ *   the code is only good for the person who approves it, for 15 minutes.
+ * - **Redeem token** (`--token`). The signed-in desktop app asks the server
+ *   for a one-time token and hands it here (`/v1/computers/pairing/redeem`).
+ *   The token is a secret and is never printed.
+ *
+ * Either way the answer is the computer credential, stored in
+ * `$PROHOST_HOME/host/computer.json` (0600). `--expect-account` refuses — and
+ * does not store — a credential for any other workspace.
+ *
+ * A program that runs this reads `$PROHOST_PAIR_RESULT_FILE` (the same
+ * variable `agent pair` writes), never the output: `{version: 1, outcome,
+ * computer_id, account: {id, name}, message}`.
+ */
+import { chmodSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { wsUrlFromBaseUrl } from '../agent/credentials.js';
+import { PAIR_RESULT_FILE_ENV } from '../agent/pair_result.js';
+import { PAIRING_POLL_PATH, PAIRING_REDEEM_PATH, PAIRING_START_PATH, callJson, revokeComputer } from './api.js';
+import { machineFacts, saveComputer } from './computer.js';
+export const HOST_PAIR_OUTCOMES = [
+    'paired',
+    /** The device code ran out before anyone approved it. */
+    'expired',
+    /** The redeem token was refused: invalid, used, expired, or for another person. */
+    'token_rejected',
+    /** Approved, but not in the workspace `--expect-account` named. Nothing was saved. */
+    'workspace_unconfirmed',
+    /** Approved, and the person answered no to "Add this computer to <workspace>?". Revoked, nothing saved. */
+    'declined',
+    'rate_limited',
+    'unreachable',
+    'invalid_arguments',
+    'failed',
+];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Poll no faster than this, whatever the server says. */
+const MIN_POLL_MS = 2_000;
+/** Give up this long after `expires_in` even if the server never says 410. */
+const EXPIRY_GRACE_MS = 30_000;
+function result(outcome, message, computerId = null, account = null) {
+    return { version: 1, outcome, computer_id: computerId, account, message };
+}
+/** Write the result file, atomically and 0600, when `$PROHOST_PAIR_RESULT_FILE` asks for one. */
+export function writeHostPairResult(value, env = process.env, warn = (line) => process.stderr.write(`${line}\n`)) {
+    const target = env[PAIR_RESULT_FILE_ENV];
+    if (target === undefined)
+        return;
+    if (!path.isAbsolute(target)) {
+        warn(`! $${PAIR_RESULT_FILE_ENV} must be an absolute path; no pairing result was written.`);
+        return;
+    }
+    const temp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.tmp`);
+    try {
+        writeFileSync(temp, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: 'wx' });
+        chmodSync(temp, 0o600);
+        renameSync(temp, target);
+    }
+    catch (err) {
+        rmSync(temp, { force: true });
+        warn(`! Could not write the pairing result: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function accountFrom(value) {
+    const account = value;
+    if (!account || typeof account !== 'object' || typeof account.id !== 'string' || !UUID.test(account.id))
+        return null;
+    return { id: account.id, name: typeof account.name === 'string' ? account.name : null };
+}
+/** Turn a 200 pairing answer into what is stored, or say what is missing. */
+export function credentialsFrom(body, baseUrl, facts) {
+    if (!body)
+        return 'the answer was not JSON';
+    const account = accountFrom(body.account);
+    if (typeof body.computer_id !== 'string' || !body.computer_id)
+        return 'the answer named no computer';
+    if (typeof body.api_key !== 'string' || !body.api_key)
+        return 'the answer carried no computer key';
+    if (!account)
+        return 'the answer named no workspace';
+    const wsUrl = typeof body.ws_url === 'string' && body.ws_url ? body.ws_url : wsUrlFromBaseUrl(baseUrl);
+    if (!wsUrl)
+        return 'the answer carried no event stream address';
+    return {
+        version: 1,
+        computer_id: body.computer_id,
+        account,
+        api_key: body.api_key,
+        webhook_secret: typeof body.webhook_secret === 'string' ? body.webhook_secret : null,
+        ...(typeof body.subscription_id === 'string' ? { subscription_id: body.subscription_id } : {}),
+        ws_url: wsUrl,
+        mcp_url: typeof body.mcp_url === 'string' ? body.mcp_url : '',
+        base_url: baseUrl,
+        machine_id: facts.machine_id,
+        name: facts.name,
+        paired_at: new Date().toISOString(),
+    };
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Pair this computer. Never throws for an outcome; the result says what
+ * happened and is what the command prints and writes to the result file.
+ */
+export async function runHostPair(options) {
+    const env = options.env ?? process.env;
+    const log = options.log ?? ((line) => process.stdout.write(`${line}\n`));
+    const sleep = options.sleep ?? defaultSleep;
+    const now = options.now ?? Date.now;
+    const api = { baseUrl: options.baseUrl, fetchImpl: options.fetchImpl };
+    if (options.expectAccount !== undefined && !UUID.test(options.expectAccount)) {
+        return result('invalid_arguments', '--expect-account must be a workspace id (a UUID).');
+    }
+    if (options.token !== undefined && !options.token.trim()) {
+        return result('invalid_arguments', '--token needs a value.');
+    }
+    let facts;
+    try {
+        facts = options.facts ?? machineFacts({ env, name: options.name });
+    }
+    catch (err) {
+        return result('failed', err instanceof Error ? err.message : String(err));
+    }
+    const finish = async (body) => {
+        const stored = credentialsFrom(body, options.baseUrl, facts);
+        if (typeof stored === 'string')
+            return result('failed', `Pairing answered, but ${stored}. Nothing was saved.`);
+        const expected = options.expectAccount?.toLowerCase();
+        /** Revoke the key that won't be kept; the words say whether that landed. */
+        const discard = async () => {
+            const revoked = await revokeComputer({ baseUrl: options.baseUrl, apiKey: stored.api_key, fetchImpl: options.fetchImpl }, stored.computer_id).catch(() => ({ result: 'failed' }));
+            return revoked.result === 'failed'
+                ? `its key could not be revoked, so it may still be listed in ${stored.account.name ?? 'that workspace'}: remove it there`
+                : 'its key was revoked';
+        };
+        if (expected && stored.account.id.toLowerCase() !== expected) {
+            // Not kept, so not left working either.
+            const revoked = await discard();
+            return result('workspace_unconfirmed', `This computer was approved in another workspace than the one expected (${expected}). Nothing was saved, ` +
+                `and ${revoked}.`, stored.computer_id, stored.account);
+        }
+        log(`Approved in workspace: ${stored.account.name ?? stored.account.id}`);
+        if (!expected && options.confirm && !(await options.confirm(stored.account))) {
+            const revoked = await discard();
+            return result('declined', `Not added: nothing was saved, and ${revoked}.`, stored.computer_id, stored.account);
+        }
+        saveComputer(stored, env);
+        const where = stored.account.name ? ` to ${stored.account.name}` : '';
+        return result('paired', `Added "${stored.name}"${where}.`, stored.computer_id, stored.account);
+    };
+    if (options.token !== undefined) {
+        const response = await callJson(api, PAIRING_REDEEM_PATH, { redeem_token: options.token.trim(), ...facts });
+        if (response.status === 200 || response.status === 201)
+            return await finish(response.body);
+        if (response.status === 0)
+            return result('unreachable', `Could not reach ProhostAI: ${response.error ?? 'no answer'}.`);
+        if (response.status === 429)
+            return result('rate_limited', 'Too many attempts; wait a minute and try again.');
+        if ([400, 401, 403, 404, 410].includes(response.status)) {
+            return result('token_rejected', 'That sign-in token was refused: it expired, was already used, or is not yours.');
+        }
+        return result('failed', `Pairing failed (HTTP ${response.status}).`);
+    }
+    const started = await callJson(api, PAIRING_START_PATH, facts);
+    if (started.status === 0)
+        return result('unreachable', `Could not reach ProhostAI: ${started.error ?? 'no answer'}.`);
+    if (started.status === 429)
+        return result('rate_limited', 'Too many attempts; wait a minute and try again.');
+    const start = started.body;
+    if ((started.status !== 200 && started.status !== 201) ||
+        !start ||
+        typeof start.device_code !== 'string' ||
+        typeof start.user_code !== 'string') {
+        return result('failed', `Could not start pairing (HTTP ${started.status}).`);
+    }
+    const verificationUrl = typeof start.verification_url === 'string' ? start.verification_url : undefined;
+    const expiresInMs = (typeof start.expires_in === 'number' ? start.expires_in : 900) * 1000;
+    let intervalMs = Math.max(MIN_POLL_MS, (typeof start.interval === 'number' ? start.interval : 5) * 1000);
+    log(`To add "${facts.name}", open ${verificationUrl ?? 'ProhostAI → AI Employees → Computers → Add a computer'}`);
+    log(`and enter this code: ${start.user_code}`);
+    log(`(The code works for ${Math.round(expiresInMs / 60_000)} minutes. Waiting for approval…)`);
+    const deadline = now() + expiresInMs + EXPIRY_GRACE_MS;
+    let unreachableSince;
+    while (now() < deadline) {
+        if (options.signal?.aborted)
+            return result('failed', 'Stopped before the code was approved.');
+        await sleep(intervalMs);
+        const polled = await callJson(api, PAIRING_POLL_PATH, { device_code: start.device_code });
+        if (polled.status === 200 || polled.status === 201)
+            return await finish(polled.body);
+        if (polled.status === 428 || (polled.status === 400 && polled.body?.status === 'pending')) {
+            unreachableSince = undefined;
+            continue;
+        }
+        if (polled.status === 410)
+            return result('expired', 'The code expired before it was approved. Run this again for a new one.');
+        if (polled.status === 429) {
+            intervalMs += 5_000;
+            continue;
+        }
+        if (polled.status === 0 || polled.status >= 500) {
+            // A wifi blip is not a failed pairing: keep asking until the code expires.
+            unreachableSince ??= now();
+            continue;
+        }
+        return result('failed', `Pairing failed (HTTP ${polled.status}).`);
+    }
+    return unreachableSince !== undefined
+        ? result('unreachable', 'Could not reach ProhostAI before the code expired.')
+        : result('expired', 'The code expired before it was approved. Run this again for a new one.');
+}

package/dist/host/peak_memory.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Each run's peak memory: the resident memory of its agent process and
+ * everything that process started, sampled while it runs.
+ *
+ * One process listing per sample covers every run: `ps -A -o pid=,ppid=,rss=`
+ * on macOS and Linux (RSS in KiB), `Win32_Process` through PowerShell on
+ * Windows (working set in bytes). A sample that can't be taken is skipped —
+ * the peak is a lower bound, never invented.
+ */
+export interface ProcessRow {
+    pid: number;
+    ppid: number;
+    /** Resident memory in bytes. */
+    rssBytes: number;
+}
+/** `ps -A -o pid=,ppid=,rss=` → rows (RSS reported in KiB). */
+export declare function parsePs(text: string): ProcessRow[];
+/** `"<pid>,<ppid>,<bytes>"` lines from the PowerShell listing. */
+export declare function parseWindowsProcesses(text: string): ProcessRow[];
+/** Memory of `root` and all its descendants in one listing, in bytes. */
+export declare function treeBytes(rows: readonly ProcessRow[], root: number): number;
+export type ProcessLister = () => Promise<ProcessRow[] | undefined>;
+export declare function defaultProcessLister(platform?: NodeJS.Platform): ProcessLister;
+/** Default sampling interval. */
+export declare const PEAK_SAMPLE_MS = 5000;
+/** Tracks each run's root process and keeps its peak. */
+export declare class PeakMemory {
+    private readonly list;
+    private readonly intervalMs;
+    private readonly roots;
+    private readonly peaks;
+    private timer;
+    private sampling;
+    constructor(list?: ProcessLister, intervalMs?: number);
+    /** A process started for `runId` (a run may start more than one: a retry). */
+    addProcess(runId: string, pid: number | undefined): void;
+    /** The run's peak so far, in MB (rounded up); `undefined` before any sample. */
+    peakMb(runId: string): number | undefined;
+    /** Stop tracking a run; returns its peak in MB. */
+    finish(runId: string): number | undefined;
+    sample(): Promise<void>;
+    stop(): void;
+    private start;
+}

package/dist/host/peak_memory.js

@@ -0,0 +1,139 @@
+/**
+ * Each run's peak memory: the resident memory of its agent process and
+ * everything that process started, sampled while it runs.
+ *
+ * One process listing per sample covers every run: `ps -A -o pid=,ppid=,rss=`
+ * on macOS and Linux (RSS in KiB), `Win32_Process` through PowerShell on
+ * Windows (working set in bytes). A sample that can't be taken is skipped —
+ * the peak is a lower bound, never invented.
+ */
+import { execFile } from 'node:child_process';
+/** `ps -A -o pid=,ppid=,rss=` → rows (RSS reported in KiB). */
+export function parsePs(text) {
+    return text.split('\n').flatMap((line) => {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length < 3)
+            return [];
+        const [pid, ppid, rss] = parts.map((p) => Number.parseInt(p, 10));
+        return Number.isFinite(pid) && Number.isFinite(ppid) && Number.isFinite(rss)
+            ? [{ pid: pid, ppid: ppid, rssBytes: rss * 1024 }]
+            : [];
+    });
+}
+/** `"<pid>,<ppid>,<bytes>"` lines from the PowerShell listing. */
+export function parseWindowsProcesses(text) {
+    return text.split(/\r?\n/).flatMap((line) => {
+        const parts = line.trim().replace(/"/g, '').split(',');
+        if (parts.length < 3)
+            return [];
+        const [pid, ppid, bytes] = parts.map((p) => Number.parseInt(p, 10));
+        return Number.isFinite(pid) && Number.isFinite(ppid) && Number.isFinite(bytes)
+            ? [{ pid: pid, ppid: ppid, rssBytes: bytes }]
+            : [];
+    });
+}
+/** Memory of `root` and all its descendants in one listing, in bytes. */
+export function treeBytes(rows, root) {
+    const children = new Map();
+    for (const row of rows) {
+        const list = children.get(row.ppid) ?? [];
+        list.push(row);
+        children.set(row.ppid, list);
+    }
+    const self = rows.find((row) => row.pid === root);
+    if (!self)
+        return 0;
+    let total = 0;
+    const stack = [self];
+    const seen = new Set();
+    while (stack.length > 0) {
+        const row = stack.pop();
+        if (seen.has(row.pid))
+            continue;
+        seen.add(row.pid);
+        total += row.rssBytes;
+        for (const child of children.get(row.pid) ?? [])
+            if (child.pid !== row.pid)
+                stack.push(child);
+    }
+    return total;
+}
+const WINDOWS_SCRIPT = 'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId),$($_.ParentProcessId),$($_.WorkingSetSize)" }';
+export function defaultProcessLister(platform = process.platform) {
+    return () => new Promise((resolve) => {
+        const [file, args, parse] = platform === 'win32'
+            ? ['powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', WINDOWS_SCRIPT], parseWindowsProcesses]
+            : ['ps', ['-A', '-o', 'pid=,ppid=,rss='], parsePs];
+        execFile(file, [...args], { timeout: 5_000, maxBuffer: 8 * 1024 * 1024 }, (error, stdout) => {
+            resolve(error ? undefined : parse(String(stdout)));
+        });
+    });
+}
+/** Default sampling interval. */
+export const PEAK_SAMPLE_MS = 5_000;
+/** Tracks each run's root process and keeps its peak. */
+export class PeakMemory {
+    list;
+    intervalMs;
+    roots = new Map();
+    peaks = new Map();
+    timer;
+    sampling = false;
+    constructor(list = defaultProcessLister(), intervalMs = PEAK_SAMPLE_MS) {
+        this.list = list;
+        this.intervalMs = intervalMs;
+    }
+    /** A process started for `runId` (a run may start more than one: a retry). */
+    addProcess(runId, pid) {
+        if (!pid)
+            return;
+        const roots = this.roots.get(runId) ?? [];
+        roots.push(pid);
+        this.roots.set(runId, roots);
+        this.start();
+        void this.sample();
+    }
+    /** The run's peak so far, in MB (rounded up); `undefined` before any sample. */
+    peakMb(runId) {
+        const bytes = this.peaks.get(runId);
+        return bytes === undefined ? undefined : Math.ceil(bytes / (1024 * 1024));
+    }
+    /** Stop tracking a run; returns its peak in MB. */
+    finish(runId) {
+        const peak = this.peakMb(runId);
+        this.roots.delete(runId);
+        this.peaks.delete(runId);
+        if (this.roots.size === 0)
+            this.stop();
+        return peak;
+    }
+    async sample() {
+        if (this.sampling || this.roots.size === 0)
+            return;
+        this.sampling = true;
+        try {
+            const rows = await this.list();
+            if (!rows)
+                return;
+            for (const [runId, roots] of this.roots) {
+                const bytes = roots.reduce((sum, root) => sum + treeBytes(rows, root), 0);
+                if (bytes > (this.peaks.get(runId) ?? 0))
+                    this.peaks.set(runId, bytes);
+            }
+        }
+        finally {
+            this.sampling = false;
+        }
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => void this.sample(), this.intervalMs);
+        this.timer.unref?.();
+    }
+}

package/dist/host/scheduler.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Which waiting run starts next on this computer.
+ *
+ * One computer serves many employees, so "oldest first" alone would let one
+ * busy employee crowd out the rest. The order is:
+ *
+ * 1. **Someone waiting** — a mention, a DM, a customer's message — before
+ *    background work (a trigger, a scheduled job).
+ * 2. **Take turns between employees** — the employee with the fewest runs going,
+ *    then the one that started a run longest ago.
+ * 3. **Oldest first.**
+ *
+ * And these always hold:
+ *
+ * - Runs in one conversation take turns: only the oldest run of a lane can
+ *   start, and never while another run of that lane is going (a session is
+ *   what two overlapping turns would corrupt).
+ * - Capacity counts terminal sessions too. Terminal sessions never wait — the
+ *   person is at the keyboard — so they shrink what the employees get.
+ * - An employee's "Up to N" (`max_concurrent`) caps its own runs.
+ * - "Keep one ready" (`keep_one_ready`) keeps one slot free for an employee
+ *   that has nothing running, so its next run starts at once: other employees
+ *   cannot take that slot.
+ * - Held (paused, memory pressure, battery): nothing new starts.
+ */
+export interface QueuedRun {
+    runId: string;
+    agentId: string;
+    /** Runs sharing a lane (employee + conversation) never overlap. */
+    lane: string;
+    /** Someone is waiting on this run. */
+    waiting: boolean;
+    /** When it was queued (ms). Earlier first, among equals. */
+    queuedAt: number;
+}
+export interface EmployeeLimits {
+    /** `null`: no limit of its own. */
+    maxConcurrent: number | null;
+    keepOneReady: boolean;
+}
+export declare const NO_LIMITS: EmployeeLimits;
+export interface SchedulerConfig {
+    capacity: number;
+    held: boolean;
+    /** Terminal sessions open now. */
+    terminals: number;
+    /** Every employee placed here, with its limits. */
+    employees: ReadonlyMap<string, EmployeeLimits>;
+}
+export declare class HostScheduler<T extends QueuedRun = QueuedRun> {
+    private queue;
+    private readonly running;
+    private readonly lastStarted;
+    private tick;
+    /** Queue a run. A run already queued or running is ignored (returns false). */
+    add(run: T): boolean;
+    /** Drop a queued run (it was claimed elsewhere, cancelled, or moved off). */
+    remove(runId: string): T | undefined;
+    /** Every queued run, oldest first. */
+    queued(): readonly T[];
+    has(runId: string): boolean;
+    get busy(): number;
+    runningFor(agentId: string): number;
+    /**
+     * The next run to start under `config`, or `undefined`. `eligible` lets the
+     * caller veto a run it can't start yet (its AI login is resting); a vetoed
+     * run keeps its place and does not block the others.
+     *
+     * Taking it marks it running; call {@link finish} when it is done.
+     */
+    take(config: SchedulerConfig, eligible?: (run: T) => boolean): T | undefined;
+    /** A started run is done. */
+    finish(runId: string): void;
+    /** A taken run could not start after all: back in the queue, in its old place. */
+    requeue(run: T): void;
+    /** Slots kept for "keep one ready" employees other than `agentId` that have nothing running. */
+    private reservedFor;
+    private compare;
+}
+/**
+ * Whether someone is waiting on a run: the server's own `waiting` when it says,
+ * else a mention / DM / customer message that expects a reply.
+ */
+export declare function someoneWaiting(data: Record<string, unknown>): boolean;
+/** The lane a run waits on: its employee and conversation (or task / cleaning), else itself. */
+export declare function laneOf(data: Record<string, unknown>, runId: string): string;

package/dist/host/scheduler.js

@@ -0,0 +1,186 @@
+/**
+ * Which waiting run starts next on this computer.
+ *
+ * One computer serves many employees, so "oldest first" alone would let one
+ * busy employee crowd out the rest. The order is:
+ *
+ * 1. **Someone waiting** — a mention, a DM, a customer's message — before
+ *    background work (a trigger, a scheduled job).
+ * 2. **Take turns between employees** — the employee with the fewest runs going,
+ *    then the one that started a run longest ago.
+ * 3. **Oldest first.**
+ *
+ * And these always hold:
+ *
+ * - Runs in one conversation take turns: only the oldest run of a lane can
+ *   start, and never while another run of that lane is going (a session is
+ *   what two overlapping turns would corrupt).
+ * - Capacity counts terminal sessions too. Terminal sessions never wait — the
+ *   person is at the keyboard — so they shrink what the employees get.
+ * - An employee's "Up to N" (`max_concurrent`) caps its own runs.
+ * - "Keep one ready" (`keep_one_ready`) keeps one slot free for an employee
+ *   that has nothing running, so its next run starts at once: other employees
+ *   cannot take that slot.
+ * - Held (paused, memory pressure, battery): nothing new starts.
+ */
+export const NO_LIMITS = Object.freeze({ maxConcurrent: null, keepOneReady: false });
+export class HostScheduler {
+    queue = [];
+    running = new Map();
+    lastStarted = new Map();
+    tick = 0;
+    /** Queue a run. A run already queued or running is ignored (returns false). */
+    add(run) {
+        if (this.running.has(run.runId) || this.queue.some((q) => q.runId === run.runId))
+            return false;
+        this.queue.push(run);
+        return true;
+    }
+    /** Drop a queued run (it was claimed elsewhere, cancelled, or moved off). */
+    remove(runId) {
+        const index = this.queue.findIndex((q) => q.runId === runId);
+        if (index === -1)
+            return undefined;
+        return this.queue.splice(index, 1)[0];
+    }
+    /** Every queued run, oldest first. */
+    queued() {
+        return this.queue;
+    }
+    has(runId) {
+        return this.running.has(runId) || this.queue.some((q) => q.runId === runId);
+    }
+    get busy() {
+        return this.running.size;
+    }
+    runningFor(agentId) {
+        let count = 0;
+        for (const entry of this.running.values())
+            if (entry.agentId === agentId)
+                count += 1;
+        return count;
+    }
+    /**
+     * The next run to start under `config`, or `undefined`. `eligible` lets the
+     * caller veto a run it can't start yet (its AI login is resting); a vetoed
+     * run keeps its place and does not block the others.
+     *
+     * Taking it marks it running; call {@link finish} when it is done.
+     */
+    take(config, eligible = () => true) {
+        if (config.held)
+            return undefined;
+        const busyLanes = new Set([...this.running.values()].map((r) => r.lane));
+        const seenLanes = new Set();
+        const candidates = [];
+        for (const run of this.queue) {
+            // Only the oldest run of each lane is a candidate: later ones wait their turn.
+            if (seenLanes.has(run.lane))
+                continue;
+            seenLanes.add(run.lane);
+            if (busyLanes.has(run.lane))
+                continue;
+            candidates.push(run);
+        }
+        const free = config.capacity - this.running.size - config.terminals;
+        if (free <= 0)
+            return undefined;
+        const ordered = candidates.sort((a, b) => this.compare(a, b));
+        for (const run of ordered) {
+            const limits = config.employees.get(run.agentId) ?? NO_LIMITS;
+            const mine = this.runningFor(run.agentId);
+            if (limits.maxConcurrent !== null && mine >= limits.maxConcurrent)
+                continue;
+            // A "keep one ready" employee with nothing going takes the slot kept for
+            // it; anyone else must leave the kept slots free.
+            const ownReserved = limits.keepOneReady && mine === 0 && limits.maxConcurrent !== 0;
+            if (!ownReserved && free - this.reservedFor(config, run.agentId) < 1)
+                continue;
+            if (!eligible(run))
+                continue;
+            this.queue = this.queue.filter((q) => q !== run);
+            this.running.set(run.runId, { agentId: run.agentId, lane: run.lane });
+            this.tick += 1;
+            this.lastStarted.set(run.agentId, this.tick);
+            return run;
+        }
+        return undefined;
+    }
+    /** A started run is done. */
+    finish(runId) {
+        this.running.delete(runId);
+    }
+    /** A taken run could not start after all: back in the queue, in its old place. */
+    requeue(run) {
+        this.running.delete(run.runId);
+        if (this.queue.some((q) => q.runId === run.runId))
+            return;
+        const index = this.queue.findIndex((q) => q.queuedAt > run.queuedAt);
+        if (index === -1)
+            this.queue.push(run);
+        else
+            this.queue.splice(index, 0, run);
+    }
+    /** Slots kept for "keep one ready" employees other than `agentId` that have nothing running. */
+    reservedFor(config, agentId) {
+        let reserved = 0;
+        for (const [other, limits] of config.employees) {
+            if (other === agentId || !limits.keepOneReady)
+                continue;
+            if (limits.maxConcurrent === 0)
+                continue;
+            if (this.runningFor(other) === 0)
+                reserved += 1;
+        }
+        return reserved;
+    }
+    compare(a, b) {
+        if (a.waiting !== b.waiting)
+            return a.waiting ? -1 : 1;
+        const runningA = this.runningFor(a.agentId);
+        const runningB = this.runningFor(b.agentId);
+        if (runningA !== runningB)
+            return runningA - runningB;
+        const lastA = this.lastStarted.get(a.agentId) ?? 0;
+        const lastB = this.lastStarted.get(b.agentId) ?? 0;
+        if (lastA !== lastB)
+            return lastA - lastB;
+        return a.queuedAt - b.queuedAt;
+    }
+}
+/**
+ * Run kinds where a person is waiting on the answer (`AIAgentRunKind`): a
+ * mention anywhere, a guest's message the employee owns (`autopilot`), "Run
+ * now", and a chat turn. Heartbeats, schedules, assignments and code reviews
+ * are background work.
+ */
+const WAITING_KINDS = new Set(['mention', 'autopilot', 'manual', 'ask_ai', 'dm', 'direct_message', 'customer_message', 'guest_message']);
+/** Trigger surfaces where a person is waiting (`trigger.source`). */
+const WAITING_SOURCES = new Set(['team_chat', 'dm', 'direct_message', 'conversation', 'guest_message', 'customer_message', 'task_comment', 'cleaning_comment', 'desk', 'ask_ai']);
+/**
+ * Whether someone is waiting on a run: the server's own `waiting` when it says,
+ * else a mention / DM / customer message that expects a reply.
+ */
+export function someoneWaiting(data) {
+    if (typeof data.waiting === 'boolean')
+        return data.waiting;
+    if (data.reply_expected === false)
+        return false;
+    const kind = typeof data.kind === 'string' ? data.kind.toLowerCase() : '';
+    const trigger = data.trigger && typeof data.trigger === 'object' ? data.trigger : {};
+    const rawSource = typeof trigger.source === 'string' ? trigger.source : data.trigger_source;
+    const source = typeof rawSource === 'string' ? rawSource.toLowerCase() : '';
+    return WAITING_KINDS.has(kind) || kind.endsWith('_mention') || WAITING_SOURCES.has(source);
+}
+/** The lane a run waits on: its employee and conversation (or task / cleaning), else itself. */
+export function laneOf(data, runId) {
+    const agent = typeof data.agent_id === 'string' ? data.agent_id : 'agent';
+    const surface = typeof data.conversation_id === 'string' && data.conversation_id
+        ? `conversation:${data.conversation_id}`
+        : typeof data.task_id === 'string' && data.task_id
+            ? `task:${data.task_id}`
+            : typeof data.cleaning_id === 'string' && data.cleaning_id
+                ? `cleaning:${data.cleaning_id}`
+                : undefined;
+    return surface ? `${agent}/${surface}` : `run:${runId}`;
+}