@kici-dev/orchestrator 0.0.0 → 0.1.1

package/dist/scaler/firecracker-backend.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Firecracker scaler backend implementation.
+ *
+ * Manages ephemeral agent microVMs using the Firecracker VMM via the jailer.
+ * Handles full VM lifecycle: prepare chroot, hardlink rootfs+kernel, create overlay drive,
+ * invoke jailer, inject MMDS metadata, and destroy with cleanup.
+ *
+ * Log capture: Firecracker backend handles log forwarding internally.
+ * The jailer is spawned as a non-daemonized detached child with stdout redirected to a
+ * serial console log file and VMM logs captured via --log-path. Both files are tailed
+ * using fs.watchFile() and forwarded with distinct logsSource tags ('firecracker-serial',
+ * 'firecracker-vmm'). The serial-console path is best-effort only: Firecracker's Rust
+ * BufWriter around stdout + jailer's uid drop make sparse userspace writes unreliable,
+ * so it's treated as defense-in-depth. The canonical agent log path is WS agent.log
+ * (attached unconditionally by the agent; see packages/agent/src/server.ts step 6).
+ *
+ * Follows the Docker backend pattern closely for consistency.
+ */
+import { type ToolRequirement } from '@kici-dev/shared';
+import type { IpAllocator, IpAllocationResult } from './ip-allocator.js';
+import type { AgentTokenStore } from '../agent/token-store.js';
+import type { ScalerBackend, ScalerEntry, ManagedAgent, LabelSetConfig, ScalerEventCallback, ValidationResult, EffectiveLimits } from './types.js';
+/**
+ * Infrastructure interfaces that share the `kici-` prefix but must NEVER be
+ * deleted by the orphan sweep. Bridges (kici-br0/kici-br1) carry all VM
+ * traffic; kici-m01 is the staging metadata interface. Losing any of these
+ * kills all running VMs.
+ */
+export declare const PROTECTED_INTERFACES: readonly string[];
+/** Extended ManagedAgent that includes the allocated IP for cleanup */
+export interface FirecrackerManagedAgent extends ManagedAgent {
+    /** Allocated IP address for TAP/IP release during destroy */
+    ip: string;
+    /** TAP device name for cleanup */
+    tapDevice: string;
+}
+export interface FirecrackerScalerBackendOptions {
+    /** Human-readable name for this scaler */
+    name: string;
+    /** Label sets this backend can provision */
+    labelSets: LabelSetConfig[];
+    /** Maximum concurrent agents */
+    maxAgents: number;
+    /** Shared IP allocator instance */
+    ipAllocator: IpAllocator;
+    /** Path to firecracker binary */
+    firecrackerPath: string;
+    /** Path to jailer binary */
+    jailerPath: string;
+    /** Default kernel image path */
+    kernelPath: string;
+    /** Jailer chroot base directory @default '/srv/jailer' */
+    chrootBaseDir?: string;
+    /** Jailer uid */
+    uid: number;
+    /** Jailer gid */
+    gid: number;
+    /** Default vCPU count @default 2 */
+    vcpuCount?: number;
+    /** Default memory in MiB @default 512 */
+    memSizeMib?: number;
+    /** Bridge interface name for TAP attachment */
+    bridgeName: string;
+    /** Gateway IP for guest networking */
+    gateway: string;
+    /** Netmask for guest networking */
+    netmask: string;
+    /** Token store for creating ephemeral agent auth tokens. Optional -- when undefined, no token is injected. */
+    tokenStore?: AgentTokenStore;
+    /** TTL for ephemeral agent tokens in ms. Default: 1 hour. */
+    tokenTtlMs?: number;
+    /** Agent roles for this scaler. undefined = all, [] = execution only. */
+    roles?: string[];
+    /**
+     * Wrap privileged commands (`ip`, `chown`) with `sudo -n`. Required when the
+     * orchestrator runs as a non-root user (e.g. user-mode systemd on edge worker
+     * nodes) and operators have set up a sudoers NOPASSWD rule for those binaries.
+     * On hosts where the orchestrator already runs as root, leave this false.
+     * @default false
+     */
+    requireSudo?: boolean;
+}
+export declare class FirecrackerScalerBackend implements ScalerBackend {
+    readonly type: "firecracker";
+    readonly maxAgents: number;
+    readonly logsSource = "firecracker-serial";
+    /** AbortControllers for file tailing per managed VM (keyed by agent ID) */
+    private readonly tailAbortControllers;
+    private _labelSets;
+    private readonly name;
+    private readonly ipAllocator;
+    private readonly firecrackerPath;
+    private readonly jailerPath;
+    private readonly kernelPath;
+    private readonly chrootBaseDir;
+    private readonly uid;
+    private readonly gid;
+    private readonly vcpuCount;
+    private readonly memSizeMib;
+    private readonly bridgeName;
+    private readonly gateway;
+    private readonly netmask;
+    private readonly tokenStore?;
+    private readonly tokenTtlMs;
+    private readonly roles;
+    private readonly requireSudo;
+    /** Tracks all managed VM agents by ManagedAgent.id */
+    private readonly agents;
+    /** Periodic orphan sweep timer (null when stopped). */
+    private orphanSweepTimer;
+    /** Guard against re-entrant sweeps if a single run takes longer than the interval. */
+    private orphanSweepInFlight;
+    constructor(options: FirecrackerScalerBackendOptions);
+    /**
+     * Declare required tools for a firecracker scaler entry.
+     */
+    static getRequiredTools(entry: ScalerEntry): ToolRequirement[];
+    get labelSets(): LabelSetConfig[];
+    getActiveCount(): number;
+    spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits): Promise<ManagedAgent>;
+    getScalerContext(agentId: string): Record<string, unknown> | undefined;
+    destroy(managedId: string): Promise<void>;
+    shutdownAll(): Promise<void>;
+    /**
+     * Clear MMDS data for an agent after receiving config.ack via WS.
+     * Belt-and-suspenders: even though MMDS only contains orchestrator URL,
+     * clearing it reduces the attack surface to zero post-startup.
+     *
+     * Note: Wiring from agent-handler is done in Plan 04.
+     *
+     * @param agentId - The agent ID whose VM MMDS should be cleared
+     */
+    clearAgentMmds(agentId: string): Promise<void>;
+    reload(labelSets: LabelSetConfig[]): ValidationResult;
+    /**
+     * Clean up orphaned VMs.
+     *
+     * Safe to call both at startup AND periodically while the backend is active
+     * (see startPeriodicOrphanSweep): each pass explicitly skips VMs that are
+     * currently tracked in-memory (spawning / running / destroying), and Pass 3
+     * re-reads DB allocations after listing host interfaces to close the spawn
+     * race (allocate → ip tuntap add is not atomic).
+     *
+     * Three passes:
+     * 1. DB allocations: check if VM process is still running, clean dead ones
+     * 2. Filesystem: scan chroot dir for directories not in DB allocations
+     * 3. Network: scan host interfaces for orphan TAP devices
+     *
+     * Returns the count of cleaned orphans.
+     */
+    cleanupOrphans(): Promise<number>;
+    /**
+     * Default interval for periodic orphan sweeps (15 minutes).
+     *
+     * Long-running orchestrators need in-process orphan sweeps because the
+     * external kici-leak-sweep timer skips TAP cleanup while a staging
+     * orchestrator is active (to avoid racing spawns). Without this, leaked
+     * TAPs accumulate until the orchestrator restarts — which can be weeks.
+     */
+    private static readonly ORPHAN_SWEEP_INTERVAL_MS;
+    /**
+     * Start a periodic orphan sweep. Idempotent — calling twice has no effect
+     * beyond the first call. Use stopPeriodicOrphanSweep() to stop.
+     *
+     * @param intervalMs override the default interval (primarily for tests)
+     */
+    startPeriodicOrphanSweep(intervalMs?: number): void;
+    /**
+     * Stop the periodic orphan sweep started by startPeriodicOrphanSweep().
+     * Safe to call when the sweep was never started.
+     */
+    stopPeriodicOrphanSweep(): void;
+    /**
+     * Build the merged forwarded-env map for an agent's MMDS payload.
+     *
+     * Mirrors bare-metal/container precedence: KICI_AGENT_ENV_*-prefixed vars from the
+     * orchestrator's process.env (prefix stripped) are seeded first, then scalers.yaml
+     * `env:` overlays them (yaml wins on conflict).
+     *
+     * Two safety filters apply:
+     * - Keys must match POSIX_ENV_NAME_PATTERN. Otherwise rejected to keep MMDS path
+     *   construction safe inside the VM and to prevent the guest from being asked to
+     *   `export` something the shell can't represent.
+     * - The cumulative byte cost (key + value + 2-byte overhead per entry) must stay
+     *   under MMDS_FORWARDED_ENV_BUDGET_BYTES. Once exceeded, remaining entries are
+     *   skipped and warnings logged. This protects the ~51 KiB MMDS data store cap
+     *   from being blown by an accidentally-huge env value.
+     */
+    buildForwardedEnv(matchedLabelSet: LabelSetConfig, agentId: string): Record<string, string>;
+    /**
+     * Build the Firecracker VM configuration JSON.
+     *
+     * Resolution order for vcpu_count and mem_size_mib:
+     *   1. effectiveLimits (resolved by ScalerManager from job/scaler/global caps) — wins if set.
+     *   2. label-set's vcpuCount/memSizeMib.
+     *   3. backend-level default vcpuCount/memSizeMib.
+     *
+     * Firecracker requires integer vCPUs and integer MiB. We round CPUs UP via
+     * Math.ceil to never under-provision (a 0.5-CPU request still gets a whole vCPU)
+     * and floor-divide bytes -> MiB. A debug log is emitted when rounding actually
+     * changes the value, so operators can spot frequent fractional requests.
+     */
+    buildVmConfig(alloc: IpAllocationResult, labelSet: LabelSetConfig, effectiveLimits?: EffectiveLimits): Record<string, unknown>;
+    /**
+     * Create a sparse ext4 overlay drive for per-VM writable layer.
+     * The file is sparse (allocates no disk blocks until written) and
+     * pre-formatted as ext4 so the guest can mount it immediately.
+     */
+    private createOverlayDrive;
+    /**
+     * Promisified execFile wrapper with 30s timeout.
+     */
+    private execAsync;
+    /**
+     * Get the API socket path for an agent's Firecracker VM.
+     */
+    getSocketPath(agentId: string): string;
+    /**
+     * Get the chroot directory path for an agent.
+     */
+    getChrootDir(agentId: string): string;
+    /**
+     * Check if a VM process is still alive by reading its PID file and sending signal 0.
+     */
+    private isVmProcessAlive;
+    /**
+     * Wait for a VM's jailer process to exit within a timeout.
+     */
+    private waitForProcessExit;
+    /**
+     * Clean up resources after a failed spawn attempt.
+     */
+    private cleanupFailedSpawn;
+    /**
+     * Start tailing serial console and VMM log files, forwarding lines directly
+     * via forwardLine() with distinct logsSource tags.
+     *
+     * Also monitors the jailer child process for early exit (boot failure detection).
+     * Forwarding is handled internally (not through ScalerManager/AgentLogForwarder)
+     * because Firecracker has two distinct log sources per VM.
+     */
+    private startLogTailing;
+    /**
+     * Tail a single log file and forward each line via forwardLine().
+     * For serial console lines: non-JSON lines (kernel boot output) are wrapped
+     * as debug-level JSON; failure patterns (kernel panic, init failure) are elevated to error.
+     */
+    private tailAndForward;
+    /**
+     * Check if a serial console line matches known boot failure patterns.
+     */
+    private isFailurePattern;
+    /**
+     * Read the serial console log file and detect the type of boot failure.
+     */
+    private detectFailureType;
+    /**
+     * Read and forward any remaining log file content for an orphaned/dead VM.
+     * Called during cleanupOrphans() before deleting the chroot directory.
+     */
+    private forwardRemainingLogs;
+}
+//# sourceMappingURL=firecracker-backend.d.ts.map

package/dist/scaler/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Agent auto-scaler module.
+ *
+ * Provides pluggable backend-agnostic agent provisioning for the orchestrator.
+ * Supports Docker, bare-metal, and Firecracker backends with YAML configuration,
+ * label-set matching, and warm pool management.
+ */
+export type { ResourceLimits, LabelSetConfig, ManagedAgent, ScaleResult, ValidationResult, ScalerBackend, ScalerConfig, ScalerEntry, WarmPoolConfig, FirecrackerNetworkConfig, } from './types.js';
+export { loadScalerConfig, scalerFileSchema, firecrackerNetworkSchema, parseMemoryString, } from './config.js';
+export { normalizeLabelSet, labelSetsMatch, detectLabelSetOverlaps, findBackendForLabels, } from './label-matcher.js';
+export { ContainerScalerBackend, detectRuntime } from './container-backend.js';
+export type { ContainerScalerBackendOptions, DetectedRuntime } from './container-backend.js';
+export { BareMetalScalerBackend } from './bare-metal-backend.js';
+export type { BareMetalScalerBackendOptions } from './bare-metal-backend.js';
+export { FirecrackerScalerBackend } from './firecracker-backend.js';
+export type { FirecrackerScalerBackendOptions, FirecrackerManagedAgent, } from './firecracker-backend.js';
+export { FirecrackerApi, FirecrackerApiError } from './firecracker-api.js';
+export { ScalerManager } from './manager.js';
+export type { ScalerStatus } from './manager.js';
+export { WarmPoolManager } from './warm-pool.js';
+export type { WarmPoolCallbacks } from './warm-pool.js';
+export { DbIpAllocator, InMemoryIpAllocator, parseCidr, ipToNumber, numberToIp, generateMac, generateTapName, } from './ip-allocator.js';
+export type { IpAllocator, IpAllocationResult, IpAllocationRecord, CidrRange, } from './ip-allocator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/scaler/ip-allocator.d.ts

@@ -0,0 +1,177 @@
+/**
+ * CIDR IP allocator for Firecracker VM networking.
+ *
+ * Two implementations behind a shared interface:
+ *
+ * - `DbIpAllocator` — persists allocations to PostgreSQL. Used by
+ *   coordinators where the cluster Postgres is reachable. Allocations
+ *   survive orchestrator restarts so a long-lived VM keeps its IP across
+ *   coord bounces.
+ *
+ * - `InMemoryIpAllocator` — Map-backed, no persistence. Used by worker
+ *   peers where the cluster DB is not reachable. The firecracker backend's
+ *   existing `cleanupOrphans()` Pass-2/Pass-3 walks the jailer chroot
+ *   tree + host TAP devices on every spawn and during the leak sweep, so
+ *   any worker-orch restart starts the allocator empty and the next
+ *   cleanup pass reaps the leftover chroots and TAPs naturally — no
+ *   recovery state needs to live in the allocator itself.
+ *
+ * Each orch has its own bridge with its own subnet (coord A: `kici`,
+ * coord B: `kici_b`, Pi worker: `kici-br0`), so allocator state is
+ * per-orch by design. No two orchs share an IP space.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/**
+ * Result of a successful IP allocation.
+ */
+export interface IpAllocationResult {
+    /** Allocated IP address */
+    ip: string;
+    /** Gateway IP for guest networking */
+    gateway: string;
+    /** Subnet mask for guest networking */
+    netmask: string;
+    /** Deterministic MAC address derived from IP */
+    mac: string;
+    /** TAP device name on the host */
+    tapDevice: string;
+}
+/**
+ * Parsed CIDR range.
+ */
+export interface CidrRange {
+    /** Network address as a 32-bit number */
+    networkAddress: number;
+    /** Prefix length (e.g. 24 for /24) */
+    prefixLength: number;
+    /** First usable IP (network address + 1) as a 32-bit number */
+    startIp: number;
+    /** Last usable IP (broadcast - 1) as a 32-bit number */
+    endIp: number;
+}
+/**
+ * Parse an IPv4 address string to a 32-bit unsigned integer.
+ */
+export declare function ipToNumber(ip: string): number;
+/**
+ * Convert a 32-bit unsigned integer back to an IPv4 address string.
+ */
+export declare function numberToIp(n: number): string;
+/**
+ * Parse a CIDR notation string into a CidrRange.
+ *
+ * @example parseCidr('10.0.0.0/24')
+ * // => { networkAddress: 167772160, prefixLength: 24, startIp: 167772161, endIp: 167772414 }
+ */
+export declare function parseCidr(cidr: string): CidrRange;
+/**
+ * Generate a deterministic MAC address from an IP address.
+ *
+ * Uses the locally-administered unicast prefix 06:00:AC followed by
+ * the last 3 octets of the IP address encoded as hex.
+ *
+ * @example generateMac('10.0.0.5')  // => '06:00:AC:00:00:05'
+ * @example generateMac('10.0.1.42') // => '06:00:AC:00:01:2A'
+ */
+export declare function generateMac(ip: string): string;
+/**
+ * Generate a TAP device name from a VM ID.
+ * Linux interface names are limited to 15 characters (IFNAMSIZ).
+ * Format: kici-XXXXXXXX (5 + 8 = 13 chars, well within limit).
+ *
+ * Uses the LAST 8 characters of the vmId to avoid collisions.
+ * VM IDs have format "scaler-firecracker-XXXXXXXX" where the unique
+ * random suffix is at the end. Using slice(0, 8) would always produce
+ * "scaler-f" for all Firecracker VMs.
+ */
+export declare function generateTapName(vmId: string): string;
+/**
+ * Shape of one row returned by `IpAllocator.getAllocations()` /
+ * `getAllocationForVm()`. Matches the `ip_allocations` table columns so
+ * the firecracker-backend's `cleanupOrphans()` can read both impls
+ * uniformly.
+ */
+export interface IpAllocationRecord {
+    ip: string;
+    vm_id: string;
+    scaler_name: string;
+    tap_device: string;
+    mac_address: string;
+}
+/**
+ * Per-orch CIDR IP allocator interface.
+ *
+ * Two implementations: `DbIpAllocator` (Postgres, coordinator) and
+ * `InMemoryIpAllocator` (Map-backed, worker). The firecracker-backend
+ * depends only on this interface — never on the concrete class — so a
+ * single backend implementation works in both deploy modes.
+ */
+export interface IpAllocator {
+    allocate(vmId: string, scalerName: string): Promise<IpAllocationResult>;
+    release(vmId: string): Promise<void>;
+    releaseByIp(ip: string): Promise<void>;
+    getAllocations(): Promise<IpAllocationRecord[]>;
+    getAllocationForVm(vmId: string): Promise<IpAllocationRecord | null>;
+}
+/**
+ * DB-backed CIDR IP allocator.
+ *
+ * Allocates IPs from a configurable range, skipping the gateway.
+ * All allocations are persisted in PostgreSQL — used by coordinators
+ * where the cluster DB is reachable. Allocations survive orch restarts
+ * so a long-lived VM keeps its IP across coord bounces.
+ */
+export declare class DbIpAllocator implements IpAllocator {
+    private readonly db;
+    private readonly range;
+    private readonly gateway;
+    private readonly gatewayNum;
+    private readonly netmask;
+    constructor(opts: {
+        db: Kysely<Database>;
+        cidr: string;
+        gateway: string;
+        netmask: string;
+    });
+    allocate(vmId: string, scalerName: string): Promise<IpAllocationResult>;
+    release(vmId: string): Promise<void>;
+    releaseByIp(ip: string): Promise<void>;
+    getAllocations(): Promise<IpAllocationRecord[]>;
+    getAllocationForVm(vmId: string): Promise<IpAllocationRecord | null>;
+}
+/**
+ * In-memory CIDR IP allocator.
+ *
+ * Used by worker peers where the cluster Postgres is not reachable. State
+ * lives in a `Map<vmId, IpAllocationRecord>` for the lifetime of the
+ * orch process; on restart the allocator starts empty and the
+ * firecracker-backend's existing `cleanupOrphans()` Pass-2/Pass-3 walks
+ * the jailer chroot tree + host TAP devices (matching `VM_TAP_PATTERN`)
+ * to reap any leftover state. No persistence and no chroot recovery
+ * inside the allocator — the filesystem is the source of truth, and the
+ * cleanup pass already consults it.
+ *
+ * Each orch has its own bridge with its own subnet, so per-process
+ * state is by design. No locking needed: every method is synchronous on
+ * the in-memory Map and only awaits to satisfy the async interface.
+ */
+export declare class InMemoryIpAllocator implements IpAllocator {
+    private readonly range;
+    private readonly gateway;
+    private readonly gatewayNum;
+    private readonly netmask;
+    private readonly byVmId;
+    private readonly allocatedIps;
+    constructor(opts: {
+        cidr: string;
+        gateway: string;
+        netmask: string;
+    });
+    allocate(vmId: string, scalerName: string): Promise<IpAllocationResult>;
+    release(vmId: string): Promise<void>;
+    releaseByIp(ip: string): Promise<void>;
+    getAllocations(): Promise<IpAllocationRecord[]>;
+    getAllocationForVm(vmId: string): Promise<IpAllocationRecord | null>;
+}
+//# sourceMappingURL=ip-allocator.d.ts.map

package/dist/scaler/label-matcher.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Label-set matching and overlap detection for the scaler module.
+ *
+ * Label sets are normalized (sorted, deduplicated, lowercased) for
+ * deterministic comparison.
+ *
+ * findBackendForLabels uses subset matching: a job requiring ['macos']
+ * matches a scaler with ['macos', 'darwin', 'bare-metal']. This is
+ * consistent with peer routing (findPeersWithCapacity) and allows
+ * workflows to target broad labels like 'macos' without listing every
+ * label the scaler defines.
+ */
+/**
+ * Normalize a label set for comparison.
+ * Sorts alphabetically, deduplicates, and lowercases all labels.
+ * Produces a deterministic string key for comparison.
+ *
+ * @example
+ * normalizeLabelSet(['Docker', 'linux', 'linux']) // => "docker,linux"
+ * normalizeLabelSet([]) // => ""
+ */
+export declare function normalizeLabelSet(labels: string[]): string;
+/**
+ * Check if two label sets are exactly equal after normalization.
+ * Subsets do NOT match -- ["linux"] does not match ["linux", "docker"].
+ */
+export declare function labelSetsMatch(a: string[], b: string[]): boolean;
+/**
+ * Detect overlapping label sets across different scalers.
+ * Returns all pairs of scalers that share the same normalized label set.
+ *
+ * Intra-scaler duplicates are allowed (same scaler, duplicate label sets).
+ * Only cross-scaler overlaps are flagged.
+ *
+ * Used at startup to reject configs with ambiguous routing.
+ */
+export declare function detectLabelSetOverlaps(scalers: Array<{
+    name: string;
+    labelSets: Array<{
+        labels: string[];
+    }>;
+}>): Array<{
+    labels: string;
+    scaler1: string;
+    scaler2: string;
+}>;
+/**
+ * Find which scaler backend handles a given set of labels.
+ * Returns the scaler name and label-set index, or null if no match.
+ *
+ * Uses subset matching: job labels must be a subset of the scaler's label set.
+ * ['macos'] matches ['macos', 'darwin', 'bare-metal']. This is consistent
+ * with peer routing (findPeersWithCapacity) which uses the same semantics.
+ *
+ * In addition, every label declared in a scaler's `mandatoryLabels` must be
+ * present in the job's `runsOn`. This is the Kubernetes-taint-style opt-in
+ * gate: a scaler with `mandatoryLabels: ['gpu']` only accepts jobs that
+ * explicitly include `gpu` in `runsOn`.
+ *
+ * When multiple backends match, the one with the smallest label set wins
+ * (most specific match).
+ */
+export declare function findBackendForLabels(labels: string[], scalers: Array<{
+    name: string;
+    labelSets: Array<{
+        labels: string[];
+    }>;
+    mandatoryLabels?: string[];
+}>, excludeLabels?: string[]): {
+    scalerName: string;
+    labelSetIndex: number;
+} | null;
+//# sourceMappingURL=label-matcher.d.ts.map

package/dist/scaler/log-forwarder.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Agent log forwarding: enriches agent log lines with metadata and writes
+ * them to a writable stream (typically orchestrator stdout for ELK ingestion).
+ *
+ * Handles both JSON and non-JSON log lines:
+ * - JSON lines are parsed, enriched with agent/context metadata, and re-serialized.
+ * - Non-JSON lines are wrapped as info-level JSON objects.
+ *
+ * The `service` field identifies the originating tier for forwarded logs that flow
+ * through orchestrator stdout (where `kici.service` from container name would say
+ * `orchestrator`). This is NOT a rename of `app.source` -- it serves the different
+ * purpose of identifying forwarded log origin for scaler-managed agents only.
+ */
+import type { LogCapture } from './types.js';
+/** Context fields merged into each forwarded log line. */
+interface ForwardContext {
+    runId?: string;
+    requestId?: string;
+    jobId?: string;
+}
+/**
+ * Enrich and forward a single log line to an output stream.
+ *
+ * Standalone function for use in the WS agent.log path (agent-handler).
+ *
+ * @param line - Raw log line from the agent
+ * @param agentId - The agent that produced the line
+ * @param output - Writable stream to write enriched JSON to
+ * @param context - Optional trace context fields
+ * @param logsSource - Optional log source identifier (e.g. 'docker', 'podman', 'bare-metal', 'firecracker-serial')
+ */
+export declare function forwardLine(line: string, agentId: string, output: NodeJS.WritableStream, context?: ForwardContext, logsSource?: string): void;
+/**
+ * Consumes a LogCapture stream and forwards enriched log lines to an output stream.
+ *
+ * Used by scaler backends (container, bare-metal, Firecracker) to forward
+ * agent stdout/stderr to orchestrator stdout for ELK ingestion.
+ */
+export declare class AgentLogForwarder {
+    private readonly agentId;
+    private readonly output;
+    constructor(agentId: string, output?: NodeJS.WritableStream);
+    /**
+     * Forward all lines from a LogCapture to the output stream.
+     * Resolves when the capture's async iterable ends.
+     *
+     * @param capture - LogCapture to consume
+     * @param context - Optional trace context fields
+     * @param logsSource - Optional log source identifier (e.g. 'docker', 'podman', 'bare-metal')
+     */
+    forward(capture: LogCapture, context?: ForwardContext, logsSource?: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=log-forwarder.d.ts.map