@kici-dev/agent 0.0.0 → 0.1.2

package/dist/execution/job-runner.d.ts

@@ -0,0 +1,266 @@
+import type { AgentToOrchestratorMessage, JobDispatch } from '@kici-dev/engine';
+import type { AppConfig } from '../config.js';
+/**
+ * Dependencies injected into JobRunner.
+ */
+export interface JobRunnerDeps {
+    /** Send function for WS messages (buffered) */
+    send: (msg: AgentToOrchestratorMessage) => void;
+    /** Send direct function (bypasses buffer, for protocol messages) */
+    sendDirect: (msg: AgentToOrchestratorMessage) => void;
+    /** Agent config */
+    config: AppConfig;
+    /** Request a pre-signed S3 upload URL from the orchestrator via WS request-response. */
+    requestUploadUrl: (jobId: string, cacheType: 'source' | 'deps', key: {
+        contentHash?: string;
+        lockfileHash?: string;
+        platform: string;
+        arch: string;
+    }) => Promise<string>;
+    /** Notify orchestrator that an S3 upload is complete (for metadata initialization). */
+    sendUploadComplete: (jobId: string, cacheType: 'source' | 'deps', key: {
+        contentHash?: string;
+        lockfileHash?: string;
+        platform: string;
+        arch: string;
+        depsHash?: string;
+    }) => void;
+    /**
+     * Send an event.emit WS message to the orchestrator and await the response.
+     * Used to relay ctx.emit() from the sandbox through the WS connection.
+     */
+    sendEventEmit: (jobId: string, requestId: string, eventName: string, payload: Record<string, unknown>, target?: {
+        repos?: string[];
+    }) => Promise<{
+        requestId: string;
+        deliveryId?: string;
+        error?: string;
+    }>;
+    /** Get WS send buffer size in bytes. Used by LogStreamer for backpressure detection. */
+    getBufferedAmount?: () => number;
+    /** Register a one-time callback for the WS 'drain' event. */
+    onDrain?: (callback: () => void) => void;
+    /**
+     * Send a job.context message to the orchestrator with execution environment details.
+     */
+    sendJobContext: (runId: string, jobId: string, context: {
+        envVars?: Array<{
+            name: string;
+            value: string;
+            category: 'system' | 'user' | 'inherited' | 'secret';
+        }>;
+        runtime?: {
+            nodeVersion?: string;
+            os?: string;
+            arch?: string;
+        };
+        sandboxType?: string;
+        labels?: string[];
+        workingDirectory?: string;
+        gitRef?: string;
+    }) => void;
+    /**
+     * Send a run.event message to the orchestrator for infrastructure lifecycle tracking.
+     */
+    sendRunEvent: (runId: string, eventType: string, opts?: {
+        jobId?: string;
+        metadata?: Record<string, unknown>;
+        durationMs?: number;
+    }) => void;
+    /**
+     * Send a job.concurrency.report WS message and wait for job.concurrency.ack.
+     * Returns the orchestrator's ack with action (proceed/wait/cancel).
+     */
+    sendConcurrencyReport: (runId: string, jobId: string, group: string) => Promise<{
+        action: 'proceed' | 'wait' | 'cancel';
+        reason?: string;
+    }>;
+    /**
+     * Send an agent.api.request WS message and await the response.
+     * Used to relay kici.* API calls from the sandbox through the WS connection.
+     * Optional for backward compatibility.
+     */
+    sendApiRequest?: (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+}
+interface ActiveJob {
+    abortController: AbortController;
+    completionPromise: Promise<void>;
+    runId: string;
+}
+/**
+ * Top-level job execution orchestrator for the agent.
+ *
+ * When a `job.dispatch` is received, the runner:
+ * 1. Creates a temp work directory
+ * 2. Selects the appropriate sandbox backend (container, bare-metal, firecracker)
+ * 3. Delegates execution to the sandbox (clone, compile, run steps)
+ * 4. Wires sandbox IPC callbacks to the WS message pipeline
+ * 5. Reports status (running -> success/failed/cancelled/skipped)
+ * 6. Cleans up work directory and sandbox
+ *
+ * Customer code runs in an isolated child process -- NEVER in the agent's V8 isolate.
+ * Build jobs still run in-process (they don't execute customer workflow steps).
+ */
+export declare class JobRunner {
+    private readonly send;
+    private readonly sendDirect;
+    private readonly config;
+    private readonly requestUploadUrl;
+    private readonly sendUploadComplete;
+    private readonly sendEventEmit;
+    private readonly getBufferedAmount?;
+    private readonly onDrain?;
+    private readonly _sendJobContext;
+    private readonly _sendRunEvent;
+    private readonly _sendConcurrencyReport;
+    private readonly _sendApiRequest?;
+    /** Tracks running jobs for concurrency and cancellation */
+    readonly activeJobs: Map<string, ActiveJob>;
+    /** Active sandbox for the current job (used for abort). */
+    private activeSandbox;
+    constructor(deps: JobRunnerDeps);
+    /**
+     * Execute a dispatched job through its full lifecycle.
+     *
+     * Creates a temp directory, delegates to the appropriate sandbox,
+     * reports status, and cleans up.
+     */
+    execute(dispatch: JobDispatch): Promise<void>;
+    /**
+     * Cancel a running job by signaling its abort controller
+     * and aborting the active sandbox.
+     *
+     * @param force When true, force-cancel (SIGKILL, skip hooks). When false, graceful cancel.
+     */
+    cancel(jobId: string, reason: string, _force?: boolean): void;
+    /**
+     * Internal job execution pipeline.
+     *
+     * For execution jobs: delegates to an ExecutionSandbox (customer code in
+     * isolated child process). For build-only jobs: runs in-process (no customer
+     * workflow steps).
+     */
+    private runJob;
+    /**
+     * Route init-only / dynamicJobFn / build-only jobs to their dedicated handlers.
+     *
+     * Returns `true` when one of the special handlers ran (caller must early-return);
+     * `false` when the job is a standard execution job that should hit the sandbox path.
+     */
+    private dispatchSpecialJobType;
+    /**
+     * Run a standard execution job through its full sandbox lifecycle.
+     *
+     * Heartbeat timer + try/finally wrap sandbox creation, setup, execution, and
+     * teardown. Errors during execution are caught and reported as a failed job
+     * status; the sandbox is always torn down in the finally block.
+     */
+    private executeStandardJob;
+    /**
+     * Determine execution mode, build sanitized env, create + setup the sandbox,
+     * and emit the job.context message.
+     *
+     * Returns `null` if the abort signal fires before / during setup (the caller
+     * has already received a `cancelled` status via `sendJobStatus`).
+     */
+    private setupSandboxForExecution;
+    /**
+     * Drive `sandbox.executeJob` with IPC callbacks wired to the WS pipeline.
+     *
+     * Lazily creates per-step LogStreamers, forwards step + log + event-emit +
+     * concurrency-report + api-request messages, and emits the
+     * `agent.execution.start` / `agent.execution.end` lifecycle events.
+     */
+    private runSandboxExecution;
+    /**
+     * Tear down log streamers, record step Prometheus metrics, log sandbox
+     * failure diagnostics, and send the terminal `job.status` message.
+     */
+    private reportExecutionResult;
+    /**
+     * Handle a build-only job.
+     *
+     * Build jobs install dependencies, pack them into a tarball,
+     * and optionally compile the workflow bundle. They report
+     * status back to the orchestrator but do not execute workflow steps.
+     */
+    private handleBuildJob;
+    /**
+     * Phase 1 of build: clone the source repo (with Prometheus timing) and apply
+     * an overlay tarball if the dispatch carries one (test runs with
+     * uncommitted changes).
+     */
+    private cloneAndApplyOverlay;
+    /**
+     * Phase 2 of build: install dependencies locally if needed for the build,
+     * and (when the orchestrator has flagged the dep cache as stale) pack
+     * `.kici/node_modules/` into a tarball and upload it to the deps cache.
+     */
+    private packAndUploadDeps;
+    /**
+     * Phase 3 of build: verify the cloned workflow source against the lock
+     * file's expected `contentHash`, pack `.kici/` into a tarball, and upload
+     * it to the source cache.
+     */
+    private packAndUploadSource;
+    /**
+     * Handle an init-only job.
+     *
+     * Init jobs evaluate dynamic functions (environment, env, concurrencyGroup)
+     * from a compiled workflow bundle and report the resolved values back to the
+     * orchestrator via job.status data payload. They do not execute workflow steps.
+     *
+     * A synthetic step 0 "init" LogStreamer carries console.log / structured log
+     * output so operators get the same visibility into init jobs that they get
+     * for regular steps. Module top-level code and each dynamic field function
+     * run inside a runCaptured scope so their console.* writes land on this log.
+     */
+    private handleInitJob;
+    /**
+     * Handle DynamicJobFn evaluation jobs.
+     *
+     * Loads the workflow bundle, extracts the DynamicJobFn by index, calls it
+     * with a DynamicJobContext, serializes the returned Job[] to LockJob[],
+     * and sends the result back to the orchestrator.
+     */
+    private handleDynamicJobFn;
+    /**
+     * Create the appropriate sandbox backend based on execution mode.
+     */
+    private createSandbox;
+    /**
+     * Collect relevant environment variables for the job.context message.
+     *
+     * Returns KICI_* system vars (visible) and user-defined workflow vars.
+     * Secret values are masked as '***'. Full process.env is NOT sent
+     * to avoid leaking host configuration.
+     */
+    private collectEnvVars;
+    /**
+     * Emit a run.event message to the orchestrator for infrastructure lifecycle tracking.
+     */
+    private emitRunEvent;
+    /**
+     * Create a LogStreamer for a synthetic step (build, evaluate, etc.).
+     */
+    private createStepStreamer;
+    /**
+     * Send a job.status message to the orchestrator.
+     *
+     * When secretOutputs are provided (encrypted envelopes from the sandbox),
+     * they are included as a top-level field on the WS message (not nested in data).
+     */
+    private sendJobStatus;
+    /**
+     * Send a step.status message to the orchestrator.
+     *
+     * @param logBytesStreamed total raw stream bytes accumulated by this step's
+     *   LogStreamer. Set on terminal step states so the orchestrator can
+     *   accumulate per-job and per-run totals for the operator-side
+     *   `kici_org_log_bytes` capacity-planning gauge. Undefined for the
+     *   `running` transition.
+     */
+    private sendStepStatus;
+}
+export {};
+//# sourceMappingURL=job-runner.d.ts.map

package/dist/execution/log-streamer.d.ts

@@ -0,0 +1,126 @@
+import type { AgentLogChunk } from '@kici-dev/engine';
+interface LogStreamerOptions {
+    /** Callback to send log.chunk messages */
+    send: (msg: AgentLogChunk) => void;
+    /** Run ID for log.chunk messages */
+    runId: string;
+    /** Job ID for log.chunk messages */
+    jobId: string;
+    /** Step index for log.chunk messages */
+    stepIndex: number;
+    /** Max log bytes per step (default: 10MB). Truncates after this limit. */
+    maxLogSizeBytes?: number;
+    /** Flush interval in ms (default: 100ms) */
+    flushIntervalMs?: number;
+    /** Flush line threshold (default: 50 lines) */
+    flushLineThreshold?: number;
+    /** Get current WS send buffer size in bytes. When provided, enables backpressure. */
+    getBufferedAmount?: () => number;
+    /** Backpressure mode: 'pause' stops the source stream, 'drop' discards lines. Default: 'pause'. */
+    backpressureMode?: 'pause' | 'drop';
+    /** Callback invoked when backpressure is detected (pause mode) -- caller should pause child stdout. */
+    onBackpressure?: () => void;
+    /** Callback invoked when backpressure clears (pause mode) -- caller should resume child stdout. */
+    onBackpressureClear?: () => void;
+    /** Register a one-time drain event listener on the WS. */
+    onWsDrain?: (callback: () => void) => void;
+}
+/** WS send buffer threshold in bytes before backpressure kicks in (1MB). */
+export declare const BACKPRESSURE_THRESHOLD = 1048576;
+/**
+ * Batches step output lines and flushes them as log.chunk messages.
+ *
+ * Optimizes WS delivery by collecting lines and flushing either:
+ * - When the line count reaches the flush threshold (default: 50 lines)
+ * - After a timer fires (default: 100ms)
+ *
+ * Enforces a maximum total log size per step. After exceeding the limit,
+ * a truncation notice is sent and further lines are silently dropped.
+ *
+ * Supports sender-side backpressure with two modes:
+ * - **pause**: Pauses the child process stdout via callback, resumes on WS drain event.
+ *   Includes a 30s safety timeout that temporarily switches to drop mode to prevent deadlocks.
+ * - **drop**: Discards buffered lines when backpressure is detected, emits a count marker on resume.
+ */
+export declare class LogStreamer {
+    private buffer;
+    private flushTimer;
+    private totalBytes;
+    private truncated;
+    /** Number of lines dropped due to backpressure (drop mode). */
+    private droppedCount;
+    /** Whether we are currently in a backpressured state (pause mode). */
+    private paused;
+    /** Whether drop mode is currently shedding lines. Tracked separately from
+     *  `paused` so the Prometheus `kici_agent_log_backpressure_active` gauge
+     *  reflects the actual shedding state (not just pause mode). */
+    private dropping;
+    /** Safety timeout timer for pause mode. */
+    private pauseSafetyTimer;
+    private readonly send;
+    private readonly runId;
+    private readonly jobId;
+    private readonly stepIndex;
+    private readonly maxLogSizeBytes;
+    private readonly flushIntervalMs;
+    private readonly flushLineThreshold;
+    private readonly getBufferedAmount?;
+    private readonly backpressureMode;
+    private readonly onBackpressure?;
+    private readonly onBackpressureClear?;
+    private readonly onWsDrain?;
+    constructor(options: LogStreamerOptions);
+    /**
+     * Add a line to the buffer. Triggers flush if threshold reached,
+     * otherwise schedules a timer-based flush.
+     */
+    addLine(line: string): void;
+    /**
+     * Flush buffered lines as a log.chunk message.
+     * No-op if buffer is empty.
+     *
+     * When backpressure is enabled (getBufferedAmount provided), checks the WS
+     * send buffer before sending:
+     * - **drop mode**: Discards buffered lines and increments droppedCount.
+     * - **pause mode**: Signals the caller to pause the child process, registers
+     *   a drain listener to resume, and sets a 30s safety timeout.
+     */
+    flush(): void;
+    /**
+     * Flush remaining buffer and clean up. Call at end of step.
+     */
+    destroy(): void;
+    /**
+     * Total bytes tracked across all lines added.
+     */
+    getTotalBytes(): number;
+    /**
+     * Number of lines dropped due to backpressure.
+     * Exposed for testing.
+     */
+    getDroppedCount(): number;
+    /**
+     * Whether backpressure pause is currently active.
+     * Exposed for testing.
+     */
+    isPaused(): boolean;
+    /**
+     * Build the lines array, prepending a drop marker if lines were dropped.
+     */
+    private buildLinesWithDropMarker;
+    /**
+     * Force send all buffered lines, bypassing backpressure checks.
+     * Used during destroy() to ensure remaining data is sent.
+     */
+    private forceSend;
+    /**
+     * Register a WS drain listener that resumes sending after backpressure clears.
+     * Includes a 30s safety timeout that temporarily switches to drop mode.
+     */
+    private registerDrainResume;
+    private clearPauseSafetyTimer;
+    private scheduleFlush;
+    private clearTimer;
+}
+export {};
+//# sourceMappingURL=log-streamer.d.ts.map

package/dist/execution/npm-registry-config.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Apply private-npm-registry auth to a workflow's `.kici/.npmrc` for the
+ * lifetime of one `npm install` invocation, then restore the file on cleanup.
+ *
+ * Why a closure-cleanup pattern (mirrors `setupSshAuth.cleanup()` in
+ * `packages/agent/src/checkout/git-clone.ts`): the customer's committed
+ * `.kici/.npmrc` may carry literal `${VAR}` placeholders or an unrelated
+ * scope mapping. We must NOT clobber it permanently — we just want to
+ * append the agent-managed registry/auth lines for this single install,
+ * then revert.
+ *
+ * Token bytes never end up in the on-disk `.npmrc`. Each registry's token
+ * is exposed as a job-scoped env var (`KICI_NPM_TOKEN_${jobIdShort}_<i>`)
+ * and the on-disk auth line carries the env var reference (`${VAR}`). npm
+ * substitutes at read time. The job-scoped nonce makes the env var name
+ * unguessable from outside the install subprocess.
+ *
+ * Merge order: customer-committed `.npmrc` lines come FIRST, agent-generated
+ * lines come LAST. npm's last-wins semantics make the agent's line shadow
+ * any literal `_authToken=...` the customer accidentally committed for a
+ * registry KiCI manages — refuses to let a committed secret beat a managed
+ * one.
+ *
+ * `installEnvSecrets` is a separate channel for customers who prefer the
+ * "commit a `.kici/.npmrc` with `${MY_TOKEN}` and supply MY_TOKEN as a
+ * scoped secret" pattern (Option C in the design doc). Each entry becomes
+ * an env var on the install subprocess; the customer's existing `.npmrc`
+ * uses it as `${MY_TOKEN}`.
+ */
+/** Registry spec carried on the dispatch message (token already resolved). */
+export interface NpmRegistrySpec {
+    url: string;
+    scope?: string;
+    alwaysAuth: boolean;
+    token: string;
+}
+export interface ApplyNpmRegistryConfigArgs {
+    /** Absolute path to the workflow's `.kici/` directory. */
+    kiciDir: string;
+    /** Resolved registries from the orchestrator. Empty/undefined = no-op. */
+    npmRegistries: readonly NpmRegistrySpec[] | undefined;
+    /** Bare-name resolved secrets to project as install env vars. */
+    installEnvSecrets: Record<string, string> | undefined;
+    /** Short (8 char) job-scoped nonce — used as suffix on synthesized env-var names. */
+    jobIdShort: string;
+}
+export interface ApplyNpmRegistryConfigResult {
+    /** Env vars to merge into the install subprocess (token vars + installEnvSecrets). */
+    extraEnv: Record<string, string>;
+    /** Token bytes the caller MUST mask out of stdout/stderr before logging. */
+    tokensForRedaction: string[];
+    /** Restore `.kici/.npmrc` to its pre-call state. Idempotent; never throws. */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Apply the merged `.npmrc` and return env + redaction + cleanup. Caller
+ * runs the npm install with `extraEnv` merged in, then awaits cleanup()
+ * inside the install's `finally`.
+ */
+export declare function applyNpmRegistryConfig(args: ApplyNpmRegistryConfigArgs): Promise<ApplyNpmRegistryConfigResult>;
+/** Mask every token in `tokensForRedaction` out of `input` before logging. */
+export declare function redactNpmOutput(input: string, tokens: readonly string[]): string;
+//# sourceMappingURL=npm-registry-config.d.ts.map

package/dist/execution/npm-resolver.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Resolve the npm CLI path relative to the running Node.js binary.
+ *
+ * Used both at startup (builder role readiness check) and at install time
+ * (dep-installer). Centralizes the resolution logic so it stays consistent.
+ *
+ * Resolution strategy:
+ * 1. Check standard Node.js layout paths relative to process.execPath
+ * 2. Fall back to bare 'npm' on PATH (development environments)
+ */
+/** Result of npm resolution. */
+interface NpmResolution {
+    /** Absolute path to npm-cli.js, or undefined if using bare 'npm' from PATH. */
+    npmCliPath: string | undefined;
+    /** The Node.js executable path (process.execPath). */
+    nodeExe: string;
+    /** Directory containing the Node.js binary. */
+    nodeDir: string;
+}
+/**
+ * Resolve the npm CLI path from the current Node.js binary.
+ *
+ * Checks standard Node.js distribution layout paths:
+ * - {nodeDir}/../lib/node_modules/npm/bin/npm-cli.js (Linux/macOS installed)
+ * - {nodeDir}/node_modules/npm/bin/npm-cli.js (Windows / some layouts)
+ *
+ * Returns undefined npmCliPath if neither is found (caller can fall back to PATH).
+ */
+export declare function resolveNpm(): NpmResolution;
+/**
+ * Verify that npm is usable by running `npm --version`.
+ *
+ * Called at agent startup when the builder role is active.
+ * Throws a descriptive error if npm cannot be executed.
+ *
+ * @returns The npm version string (e.g., "10.8.1")
+ */
+export declare function verifyNpmAvailable(): string;
+export {};
+//# sourceMappingURL=npm-resolver.d.ts.map

package/dist/execution/overlay-applier.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Agent-side overlay application.
+ *
+ * Downloads an encrypted tarball uploaded by the CLI, decrypts it using
+ * X25519 ECDH shared secret, verifies file checksums from the manifest,
+ * and applies the overlay (file additions/modifications + deletions)
+ * on top of the cloned repository.
+ *
+ * Wire format: [12-byte IV][16-byte auth tag][ciphertext]
+ * Same encryption scheme as packages/compiler/src/remote/encryption.ts.
+ */
+/**
+ * Configuration for applying an overlay to a cloned repo.
+ */
+interface OverlayConfig {
+    /** URL to download the encrypted tarball from (S3 pre-signed URL) */
+    tarballUrl: string;
+    /** Base64-encoded CLI ephemeral public key (DER/SPKI format) */
+    cliPublicKey: string;
+    /** Base64-encoded orchestrator ephemeral private key (DER/PKCS8 format) */
+    orchestratorPrivateKey: string;
+    /** Path to the cloned repository directory */
+    repoDir: string;
+}
+/**
+ * Result of applying an overlay.
+ */
+interface OverlayResult {
+    /** Number of files copied/overwritten in the repo */
+    filesApplied: number;
+    /** Number of files deleted from the repo */
+    filesDeleted: number;
+    /** Whether all checksums were verified successfully */
+    verified: boolean;
+}
+/**
+ * Apply an overlay tarball to a cloned repository.
+ *
+ * Flow:
+ * 1. Download encrypted tarball from tarballUrl
+ * 2. Derive ECDH shared secret from orchestratorPrivateKey + cliPublicKey
+ * 3. Decrypt tarball using AES-256-GCM
+ * 4. Extract tar.gz to temp directory
+ * 5. Read manifest.json and verify checksums
+ * 6. Copy files to repoDir preserving directory structure
+ * 7. Apply deletions from manifest
+ * 8. Clean up temp files
+ */
+export declare function applyOverlay(config: OverlayConfig): Promise<OverlayResult>;
+export {};
+//# sourceMappingURL=overlay-applier.d.ts.map

package/dist/execution/rule-evaluator.d.ts

@@ -0,0 +1,11 @@
+import type { RuleContext } from '@kici-dev/sdk';
+/**
+ * Create RuleContext for agent-side rule evaluation.
+ *
+ * @param event - Event payload from the dispatch message
+ * @param changedFiles - List of files changed in this event
+ * @param env - Merged environment variables
+ */
+export declare function createRuleContext(event: Record<string, unknown>, changedFiles?: string[], env?: Record<string, string | undefined>): RuleContext;
+export { evaluateRules, type RuleEvaluationResult } from '@kici-dev/sdk';
+//# sourceMappingURL=rule-evaluator.d.ts.map

package/dist/execution/sandbox/bare-metal-sandbox.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Bare-metal execution sandbox.
+ *
+ * Uses child_process.fork() with sanitized environment and optional bubblewrap
+ * (bwrap) namespace isolation. The workflow runner runs as a separate Node.js
+ * process with only explicitly allowed environment variables.
+ *
+ * Security model:
+ * - Environment sanitization: only ALLOWED_SYSTEM_VARS + user env + secrets
+ * - Optional bwrap: PID/IPC namespace isolation, read-only system mounts
+ * - Network isolation via --unshare-net when bwrap is enabled (loopback only)
+ *
+ * Without bwrap (sandbox=false), the runner process has full filesystem and
+ * network access. This mode provides credential isolation only and should
+ * be used in trusted environments.
+ */
+import type { ExecutionSandbox, SandboxSetupOptions, JobExecutionOptions, JobExecutionResult } from './types.js';
+/** Configuration options for BareMetalSandbox. */
+interface BareMetalSandboxOptions {
+    /** Absolute path to the compiled workflow-runner.js entry point. */
+    runnerPath: string;
+    /** Whether to use bubblewrap (bwrap) for namespace isolation. */
+    sandbox: boolean;
+    /**
+     * Network mode when sandbox=true.
+     * - 'isolated' (default): bwrap --unshare-net (loopback only).
+     * - 'host': keep the host network namespace so workflows can talk to npm,
+     *   git, package registries, etc.
+     * Ignored when sandbox=false.
+     */
+    sandboxNetwork?: 'isolated' | 'host';
+    /** Pre-sanitized environment variables (system allowlist + user env). */
+    env: Record<string, string>;
+}
+/**
+ * Bare-metal execution sandbox implementation.
+ *
+ * Forks the workflow runner as a child process with sanitized environment.
+ * Optionally wraps execution in bubblewrap for PID/IPC/filesystem isolation.
+ */
+export declare class BareMetalSandbox implements ExecutionSandbox {
+    private readonly runnerPath;
+    private readonly useBwrap;
+    private readonly sandboxNetwork;
+    private readonly env;
+    private runner;
+    private workDir;
+    constructor(options: BareMetalSandboxOptions);
+    /**
+     * Validate that the runner path exists and bwrap is available (if needed).
+     */
+    setup(options: SandboxSetupOptions): Promise<void>;
+    /**
+     * Execute a job by forking the workflow runner with sanitized environment.
+     */
+    executeJob(options: JobExecutionOptions): Promise<JobExecutionResult>;
+    /**
+     * Abort the running job.
+     *
+     * Sends abort IPC message, then SIGTERM after 10s, SIGKILL after 15s.
+     */
+    abort(): Promise<void>;
+    /**
+     * Clean up the child process if still running.
+     */
+    teardown(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=bare-metal-sandbox.d.ts.map