@bakers-build/conductor 0.4.1-next.499 → 0.4.1-next.536

package/dist/src/commands/conductor.js

@@ -9,6 +9,7 @@ import { composeConductorConfig, loadConductorConfig } from '../config.js';
 import { Conductor } from '../core/conductor.js';
 import { hostKeyOf } from '../core/host-key.js';
 import { selectAgents, selectExecutor, selectRemote, selectWorkspace, } from '../plugins/plugins.js';
+import { sandboxFailures } from '../plugins/sandbox-preflight.js';
 /** Default host bases for connection/plugin resolution when none is injected. */
 function defaultHost() {
     return { resolveBases: [import.meta.url, `${process.cwd()}/`] };
@@ -202,6 +203,16 @@ async function cmdPoll(deps, log = {}) {
     await conductor.start();
     await conductor.tick();
 }
+/** `bakers oven check`: whether each enabled agent can start its sandbox. */
+async function cmdCheck(deps) {
+    const config = await resolveConfig(deps);
+    for (const agent of deps.agents ?? (await selectAgents(config))) {
+        const [failure] = await sandboxFailures([agent]);
+        console.log(failure ?? `${agent.alias ?? agent.id}: sandbox ok`);
+        if (failure)
+            process.exitCode = 1;
+    }
+}
 async function cmdReap(deps, log = {}) {
     const config = await resolveConfig(deps, undefined, true);
     const checkoutRoot = await checkoutRootOf(config);
@@ -562,6 +573,14 @@ async function cmdStartBody(deps, log, force = false) {
     const logger = loggerFor(checkoutRoot, log);
     if (!(await ensureAuthenticated(config, logger)))
         return;
+    // The loop withholds claims while this fails; say so before it starts.
+    // Best-effort: an agent config the loop cannot load fails there, as before.
+    try {
+        for (const line of await sandboxFailures(deps.agents ?? (await selectAgents(config)))) {
+            console.warn(`warning: ${line}`);
+        }
+    }
+    catch { }
     const remote = await resolveRemote(deps, config);
     const id = conductorIdOf(config);
     const thisHostKey = hostKeyOf(config);
@@ -783,6 +802,12 @@ Examples:
         .action(async function () {
         await cmdPoll(deps, logOptsOf(this));
     });
+    conductor
+        .command('check')
+        .description('check that every enabled agent can start its sandbox on this machine (exit 1 if one cannot)')
+        .action(async () => {
+        await cmdCheck(deps);
+    });
     conductor
         .command('clean')
         .description('tear down herdr worktrees of finished-but-uncleaned tickets (recovers orphans a live tick missed: conductor was down at done, restarted, or reassigned)')

package/dist/src/contract.d.ts

@@ -9,5 +9,6 @@ export { resolveAgent, selectAgent, selectAgents, selectExecutor, selectRemote,
 export { type ConductorAddonEntry, type ConductorContributions, narrowConductorContributions, type Preset, } from './plugins/preset.js';
 export type { HerdrHost } from './plugins/process-host.js';
 export type { ActiveRun, AddonDefinitionV2, AddonRegistration, BbRemote, ClaimedRun, ClaimOptions, ClaimWithheld, ConductorRegistration, ConductorStatus, FinalizableRun, FrozenTicket, InboxMessage, InboxSnapshot, RunMetrics, RunWriteAttributes, Ticket, TicketMetric, UncleanTicket, } from './plugins/remote.js';
+export { installCommand, lastLine, type SandboxHost, type SandboxPreflight, sandboxFailures, systemSandboxHost, } from './plugins/sandbox-preflight.js';
 export type { BbWorkspace, EnsuredWorkspace, } from './plugins/workspace.js';
 export type { ConductorEngineConfig, ConductorFileConfig, ConductorSettings, } from './types.js';

package/dist/src/contract.js

@@ -17,3 +17,4 @@ export { detectKnownOverrides, resolveAgentCliOptions, resolveSecurityOptions, S
 export { loadInbox, validateRequestPayload, } from './plugins/message.js';
 export { resolveAgent, selectAgent, selectAgents, selectExecutor, selectRemote, selectWorkspace, } from './plugins/plugins.js';
 export { narrowConductorContributions, } from './plugins/preset.js';
+export { installCommand, lastLine, sandboxFailures, systemSandboxHost, } from './plugins/sandbox-preflight.js';

package/dist/src/core/conductor.js

@@ -3,6 +3,7 @@ import { basename, dirname, join } from 'node:path';
 import { shellQuote, stemForConfigFile, } from '@bakers-build/core';
 import { DEFAULT_ENV_DENY, matchesEnvDeny, } from '../plugins/agent.js';
 import { resolveAgent } from '../plugins/plugins.js';
+import { sandboxFailures } from '../plugins/sandbox-preflight.js';
 import { ActionQueue } from './action-queue.js';
 import { attemptFamily } from './attempt.js';
 import { hostKeyOf } from './host-key.js';
@@ -278,6 +279,9 @@ export class Conductor {
             const log = this.inboxAddons.empty ? this.logger.warn : this.logger.error;
             log.call(this.logger, { conductorId: this.id, err: String(err) }, 'addon registration failed');
         }
+        for (const line of await sandboxFailures(this.agents)) {
+            this.logger.error({ conductorId: this.id }, line);
+        }
     }
     /** One tick that also waits for its actions: `bakers oven once`, tests. */
     async tick() {
@@ -335,9 +339,15 @@ export class Conductor {
         await this.step('reap', () => this.enqueueReap());
         await this.step('freeze', () => this.observeFreezes());
         await runInbox(this.remote, this.inboxAddons, this.id, this.logger, this.queue);
+        // A run that cannot start its sandbox would only fail and count against
+        // the retry cap; claim nothing until every enabled agent can start.
+        const unavailable = machineLoad < maxParallel ? await sandboxFailures(this.agents) : [];
+        for (const line of unavailable) {
+            this.logger.warn({ conductorId: this.id }, `claims withheld: ${line}`);
+        }
         let claimed = 0;
-        let withheld = false;
-        while (machineLoad < maxParallel) {
+        let withheld = unavailable.length > 0;
+        while (!withheld && machineLoad < maxParallel) {
             const run = await this.remote.claimNext({
                 leaseSeconds: this.config.lease_seconds,
                 conductorId: this.id,
@@ -441,7 +451,7 @@ export class Conductor {
             // server change is needed and no empty log is written.
             const uploadedLog = (this.config.capture_logs ?? true) ? captured.log : '';
             await this.remote.finalizeRun(r.runUuid, uploadedLog, captured.metrics);
-            this.logger.info({ run: r.runUuid, footprint: captured.metrics }, 'run finalised');
+            this.logger.info({ run: r.runUuid, state: r.state, footprint: captured.metrics }, 'run finalised');
         }
         catch (err) {
             this.logger.warn({ run: r.runUuid, err: String(err) }, 'run finalise failed');
@@ -1041,6 +1051,10 @@ export class Conductor {
             defaultAgent: this.config.default_agent,
             warn: (message) => this.logger.warn({ ticket: t.identifier }, message),
         });
+        // The tick's gate may be stale by now; spawn nothing that cannot start.
+        const [unavailable] = await sandboxFailures([chosen]);
+        if (unavailable)
+            throw new Error(unavailable);
         const baseRef = t.baseBranch ? `origin/${t.baseBranch}` : undefined;
         // Resolve the run env once (per-ticket env_vars + core BB_* vars) and
         // inject it into BOTH the executor-owned lifecycle hooks AND the agent run

package/dist/src/plugins/agent.d.ts

@@ -1,3 +1,4 @@
+import type { SandboxHost, SandboxPreflight } from './sandbox-preflight.js';
 /**
  * Per-agent effort footprint parsed from that agent's run transcript
  * (BB-132). The metrics are transcript-derived and therefore
@@ -136,4 +137,11 @@ export interface BbAgent {
      * {@link emptyAgentFootprint}.
      */
     parseFootprint(log: string): AgentFootprint;
+    /**
+     * Whether this agent's OS sandbox can start on this machine. The conductor
+     * withholds claims and refuses to spawn while it reports a cause. Returns
+     * ok without probing when the agent does not run sandboxed. Optional: an
+     * agent without it is never checked.
+     */
+    sandboxPreflight?(host?: SandboxHost): Promise<SandboxPreflight>;
 }

package/dist/src/plugins/remote.d.ts

@@ -122,6 +122,8 @@ export interface ConductorStatus {
 }
 export interface FinalizableRun {
     runUuid: string;
+    /** The run's terminal state; a `cancelled` run is stopped like a `done` one. */
+    state: 'done' | 'cancelled';
     /** Numeric run id (the `#<runId>` tab-label token); scopes the run's tab-close at finalise (BB-183). */
     runId: number;
     /**

package/dist/src/plugins/sandbox-preflight.d.ts

@@ -0,0 +1,35 @@
+/** Whether an agent's sandbox can start on this machine; see {@link BbAgent.sandboxPreflight}. */
+export type SandboxPreflight = {
+    ok: true;
+} | {
+    ok: false;
+    cause: string;
+    fix: string;
+};
+/** The machine a preflight inspects; injected by tests. */
+export interface SandboxHost {
+    platform: NodeJS.Platform;
+    /** Whether `name` is an executable on `PATH`. */
+    onPath(name: string): boolean;
+    /** Runs a probe command; never throws. */
+    run(cmd: string, args: string[]): Promise<{
+        ok: boolean;
+        stderr: string;
+    }>;
+}
+export declare function systemSandboxHost(env?: NodeJS.ProcessEnv): SandboxHost;
+/** The last non-empty line of a probe's stderr: the error, after any warnings. */
+export declare function lastLine(text: string): string;
+/** The platform's install command for `packages`, from the package manager on `PATH`. */
+export declare function installCommand(host: SandboxHost, packages: string[]): string;
+/**
+ * One `sandbox unavailable: …` line per agent whose sandbox cannot start;
+ * empty when every agent can start (or declares no preflight).
+ */
+export declare function sandboxFailures(agents: readonly {
+    id: string;
+    alias?: string;
+    agent: {
+        sandboxPreflight?(): Promise<SandboxPreflight>;
+    };
+}[]): Promise<string[]>;

package/dist/src/plugins/sandbox-preflight.js

@@ -0,0 +1,56 @@
+import { execFile } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+export function systemSandboxHost(env = process.env) {
+    return {
+        platform: process.platform,
+        onPath: (name) => (env.PATH ?? '').split(delimiter).some((dir) => {
+            try {
+                accessSync(join(dir, name), constants.X_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }),
+        run: (cmd, args) => new Promise((resolve) => {
+            execFile(cmd, args, { env, timeout: 15_000 }, (err, _out, stderr) => {
+                resolve({ ok: !err, stderr: String(stderr || err?.message || '') });
+            });
+        }),
+    };
+}
+/** The last non-empty line of a probe's stderr: the error, after any warnings. */
+export function lastLine(text) {
+    return (text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .pop() ?? 'no error output');
+}
+/** The platform's install command for `packages`, from the package manager on `PATH`. */
+export function installCommand(host, packages) {
+    const managers = [
+        ['apt-get', 'sudo apt-get install -y'],
+        ['dnf', 'sudo dnf install -y'],
+        ['pacman', 'sudo pacman -S --needed'],
+    ];
+    const found = managers.find(([bin]) => host.onPath(bin));
+    return found
+        ? `${found[1]} ${packages.join(' ')}`
+        : `your package manager (packages: ${packages.join(', ')})`;
+}
+/**
+ * One `sandbox unavailable: …` line per agent whose sandbox cannot start;
+ * empty when every agent can start (or declares no preflight).
+ */
+export async function sandboxFailures(agents) {
+    const lines = [];
+    for (const { id, alias, agent } of agents) {
+        const result = (await agent.sandboxPreflight?.()) ?? { ok: true };
+        if (!result.ok) {
+            lines.push(`sandbox unavailable: ${alias ?? id}: ${result.cause} — ${result.fix} (see https://bakers.build/docs/advanced/run-security#sandbox-prerequisites)`);
+        }
+    }
+    return [...new Set(lines)]; // unaliased entries of one harness report the same line
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakers-build/conductor",
-  "version": "0.4.1-next.499",
+  "version": "0.4.1-next.536",
   "description": "bakers.build conductor engine + CLI: registers, claims tickets via JSON:API, dispatches agents.",
   "type": "module",
   "license": "MIT",
@@ -32,8 +32,8 @@
   "dependencies": {
     "@dropsh/plugin-jsonapi-schema": "^0.8.2",
     "@dropsh/plugin-oauth2": "^0.8.2",
-    "@bakers-build/core": "^0.4.1-next.499",
-    "@bakers-build/message": "^0.4.1-next.499",
+    "@bakers-build/core": "^0.4.1-next.536",
+    "@bakers-build/message": "^0.4.1-next.536",
     "commander": "^12.1.0",
     "dropsh": "^0.8.2"
   }