@kici-dev/agent 0.0.0 → 0.1.1

package/dist/execution/sandbox/secret-encryption.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Agent-side encryption for cross-job secret outputs.
+ *
+ * When a workflow step calls ctx.setSecretOutput(), the plaintext values flow
+ * through IPC from the sandbox runner to the agent process. Before sending them
+ * over the WebSocket to the orchestrator, the agent encrypts each value using
+ * X25519 ECDH + HKDF + AES-256-GCM.
+ *
+ * Protocol:
+ * 1. Generate a fresh ephemeral X25519 key pair (shared across all outputs in one call)
+ * 2. ECDH: sharedSecret = agentPrivateKey x runPublicKey
+ * 3. HKDF(sha256, sharedSecret, salt='', info='kici-run-secret-outputs', 32) -> AES key
+ * 4. AES-256-GCM encrypt each value independently (unique IV per value)
+ * 5. Pack as IV (12B) || AuthTag (16B) || Ciphertext, base64 encode
+ *
+ * The orchestrator decrypts using the run's private key and the agent's public key
+ * (via the same ECDH derivation from the other side).
+ */
+/** Encrypted envelope for a single secret output value. */
+export interface EncryptedSecretOutput {
+    /** Base64-encoded agent ephemeral X25519 public key (DER SPKI). */
+    agentPublicKey: string;
+    /** Base64-encoded encrypted value: IV (12B) || AuthTag (16B) || Ciphertext. */
+    encrypted: string;
+}
+/**
+ * Encrypt secret output values for transport to the orchestrator.
+ *
+ * Generates a single ephemeral X25519 key pair per call (shared across all outputs
+ * in this batch -- one ECDH derivation, unique IV per value).
+ *
+ * @param outputs - Plaintext secret output key-value pairs
+ * @param runPublicKeyBase64 - Base64-encoded run X25519 public key (DER SPKI)
+ * @returns Map of key -> encrypted envelope
+ */
+export declare function encryptSecretOutputs(outputs: Record<string, string>, runPublicKeyBase64: string): Record<string, EncryptedSecretOutput>;
+//# sourceMappingURL=secret-encryption.d.ts.map

package/dist/execution/sandbox/secret-merge.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Secret merging utilities for the workflow runner.
+ *
+ * Separated from workflow-runner.ts to allow unit testing without
+ * triggering the runner's top-level side effects (process handlers, main()).
+ */
+/**
+ * Merge orchestrator-level secrets with auto-flattened context keys.
+ *
+ * Precedence (last wins):
+ * 1. Orchestrator-level secrets (lowest)
+ * 2. Context-flattened keys in declaration order (each context's keys overlay previous)
+ *
+ * This means: context-flattened keys override orchestrator-level secrets,
+ * and for collisions between contexts, last declared context wins.
+ */
+export declare function buildMergedFlatSecrets(orchestratorSecrets: Record<string, string>, namespacedSecrets: Record<string, Record<string, string>>): Record<string, string>;
+//# sourceMappingURL=secret-merge.d.ts.map

package/dist/execution/sandbox/step-loop.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Step loop -- extracted step execution logic with hook integration and step rules.
+ *
+ * This module contains the core step execution loop that the workflow-runner calls.
+ * Extracted for testability: the workflow-runner's main() handles IPC, clone, deps,
+ * module loading, and calls this loop for step execution with hooks.
+ */
+import type { Step, StepContext, HookInput, OutputsMap, StepSecretMountRecord } from '@kici-dev/sdk';
+import type { RunnerToAgentMessage } from './ipc-protocol.js';
+import type { SandboxStepResult } from './types.js';
+/** Job-level hooks passed to the step loop. */
+export interface JobHooks {
+    beforeStep?: HookInput;
+    afterStep?: HookInput;
+    onSuccess?: HookInput;
+    onFailure?: HookInput;
+    onCancel?: HookInput;
+    cleanup?: HookInput;
+}
+/** Options for the step execution loop. */
+interface StepLoopOptions {
+    steps: Step[];
+    /** Factory that creates a StepContext for a given step index and name. */
+    createStepContext: (stepIndex: number, stepName: string) => StepContext;
+    sendIpc: (msg: RunnerToAgentMessage) => void;
+    defaultTimeoutMs: number;
+    outputsMap: OutputsMap;
+    /** Event payload for rule context. */
+    event: Record<string, unknown>;
+    /** Environment variables for rule context. */
+    env: Record<string, string | undefined>;
+    /** Job-level hooks. */
+    jobHooks?: JobHooks;
+    /** Abort check callback. Returns true if job was aborted. */
+    isAborted?: () => boolean;
+    /** Job start time (epoch ms) for outcome metadata duration. */
+    startTime?: number;
+    /**
+     * Returns the secret key names accessed by the most recently created step context.
+     * Called after each step completes to include in step.complete IPC messages.
+     */
+    getSecretsAccessLog?: () => string[];
+    /**
+     * Tear down per-step state created by the most recent `createStepContext`
+     * call. Invoked from the step-loop's `finally` after the step completes
+     * (success, failure, rule-skip, or timeout) so resources like the
+     * `ctx.secrets.mountFile` tmpdir get removed even on the failure paths.
+     * Never throws -- errors are logged by the wired implementation.
+     */
+    disposeStepResources?: () => Promise<void>;
+    /**
+     * Returns the IPC `step.secret_mount` records collected by the most
+     * recently created step context. Emitted on step completion so the
+     * orchestrator can persist the audit trail alongside `secretsAccessed`.
+     */
+    getSecretMountRecords?: () => StepSecretMountRecord[];
+}
+/** Result of the step execution loop. */
+interface StepLoopResult {
+    status: 'success' | 'failed' | 'aborted';
+    stepResults: SandboxStepResult[];
+    failureReason?: string;
+}
+/**
+ * Execute the step loop with hook integration and step-level rule evaluation.
+ *
+ * Hook execution order:
+ * - beforeStep -> step -> afterStep (per step)
+ * - onSuccess or onFailure (after all steps)
+ * - cleanup (always, after onSuccess/onFailure)
+ *
+ * Hooks are observers: beforeStep/afterStep failures do NOT affect step execution.
+ * Only completion hooks (onSuccess/onFailure/cleanup) can change job status to failed.
+ */
+export declare function executeStepLoop(opts: StepLoopOptions): Promise<StepLoopResult>;
+export {};
+//# sourceMappingURL=step-loop.d.ts.map

package/dist/execution/sandbox/types.d.ts

@@ -0,0 +1,142 @@
+import type { JobDispatch } from '@kici-dev/engine';
+import type { EventEmitRequest, EventEmitResponse, ConcurrencyReportMessage, ConcurrencyAckMessage } from './ipc-protocol.js';
+/**
+ * Common interface for all execution sandbox backends.
+ *
+ * All three backends (container, bare-metal, Firecracker) implement this
+ * interface to provide isolated code execution with a consistent lifecycle:
+ *   setup -> executeJob -> teardown (with abort available at any time)
+ *
+ * The sandbox isolates customer code from agent-internal credentials and
+ * resources. The agent process never loads or executes customer code directly.
+ */
+export interface ExecutionSandbox {
+    /**
+     * Prepare the sandbox environment.
+     *
+     * - Container: create + start disposable container
+     * - Bare-metal: validate bwrap availability
+     * - Firecracker: no-op (VM already running, managed by scaler)
+     */
+    setup(options: SandboxSetupOptions): Promise<void>;
+    /**
+     * Execute the full job lifecycle inside the sandbox.
+     *
+     * Handles: clone, dependency install, compile, step execution.
+     * Returns step results via callbacks as they complete.
+     */
+    executeJob(options: JobExecutionOptions): Promise<JobExecutionResult>;
+    /**
+     * Abort a running job.
+     *
+     * Sends SIGTERM to the sandbox process, waits a grace period (~10s),
+     * then sends SIGKILL if the process has not exited.
+     */
+    abort(): Promise<void>;
+    /**
+     * Tear down the sandbox environment.
+     *
+     * - Container: docker rm -f
+     * - Bare-metal: process cleanup
+     * - Firecracker: no-op (VM lifecycle managed by scaler)
+     */
+    teardown(): Promise<void>;
+}
+/** Options for preparing the sandbox environment. */
+export interface SandboxSetupOptions {
+    /** Container image (container backend only, e.g. 'node:20-alpine'). */
+    image?: string;
+    /** Working directory for the job on the host. */
+    workDir: string;
+    /** Sanitized environment variables (user env + secrets, NO agent credentials). */
+    env: Record<string, string>;
+}
+/** Options for executing a job inside the sandbox. */
+export interface JobExecutionOptions {
+    /** Dispatch data from the orchestrator (repo URL, ref, sha, token, etc.). */
+    dispatch: JobDispatch;
+    /** Callback for real-time step status updates (start, success, failed). */
+    onStepStatus: (stepIndex: number, name: string, state: string, data?: Record<string, unknown>) => void;
+    /** Callback for real-time log line forwarding. */
+    onLogLine: (stepIndex: number, line: string) => void;
+    /** Abort signal for cancellation. */
+    signal: AbortSignal;
+    /**
+     * Callback for relaying event.emit requests from the sandbox to the orchestrator.
+     * The sandbox runner sends event.emit IPC messages; the agent wraps them in WS
+     * protocol and forwards to the orchestrator. Returns the orchestrator's response.
+     */
+    onEventEmit: (request: EventEmitRequest) => Promise<EventEmitResponse>;
+    /**
+     * Callback for relaying concurrency.report from the sandbox to the orchestrator.
+     * Returns the orchestrator's ack (proceed/wait/cancel).
+     */
+    onConcurrencyReport: (report: ConcurrencyReportMessage) => Promise<ConcurrencyAckMessage>;
+    /**
+     * Callback for relaying agent.api.request from the sandbox to the orchestrator.
+     * Returns the orchestrator's response (result or error).
+     *
+     * Optional for backward compatibility (callers that don't support the agent API).
+     */
+    onApiRequest?: (method: string, params: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Callback fired once per `ctx.secrets.mountFile` / `exposeFile` call the
+     * workflow runner performs. Carries only key names + the resulting path /
+     * env var -- never the file content. Optional so backends that don't yet
+     * thread the event through (CT / unit-style harnesses) keep working.
+     */
+    onSecretMount?: (event: {
+        stepIndex: number;
+        sources: string[];
+        target: string;
+        envVar?: string;
+        kind: 'mountFile' | 'exposeFile';
+    }) => void;
+}
+/** Aggregated result of a job execution. */
+export interface JobExecutionResult {
+    /** Overall job status. */
+    status: 'success' | 'failed' | 'cancelled';
+    /** Per-step results in execution order. */
+    stepResults: SandboxStepResult[];
+    /** Total job duration in milliseconds. */
+    durationMs: number;
+    /** Error message when the runner process crashed (no job.complete received). */
+    error?: string;
+    /** Aggregated step outputs by step name (present on success when steps return values). */
+    outputs?: Record<string, Record<string, unknown>>;
+    /** Encrypted secret outputs (present on success when steps called ctx.setSecretOutput). */
+    secretOutputs?: Record<string, {
+        agentPublicKey: string;
+        encrypted: string;
+    }>;
+    /** Names of sibling jobs dropped by DynamicJobFn re-evaluation drift. */
+    droppedJobs?: string[];
+}
+/**
+ * Result of a single step execution within the sandbox.
+ *
+ * Self-contained step result type for the sandbox execution model.
+ */
+export interface SandboxStepResult {
+    /** Step name from the workflow definition. */
+    name: string;
+    /** Zero-based index of the step within the job. */
+    stepIndex: number;
+    /** Step execution status. */
+    status: 'success' | 'failed' | 'skipped';
+    /** Step duration in milliseconds. */
+    durationMs: number;
+    /** Error details when status is 'failed'. */
+    error?: {
+        /** Human-readable error message. */
+        message: string;
+        /** Process exit code (non-zero on failure). */
+        exitCode?: number;
+        /** Signal that terminated the process (e.g. 'SIGTERM', 'SIGKILL'). */
+        signal?: string;
+    };
+    /** Step return value (outputs). Present on success when step returns non-void. */
+    outputs?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/execution/sandbox/workflow-runner.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Workflow Runner -- standalone entry point that runs INSIDE the sandbox.
+ *
+ * This is the code that actually executes customer workflows in isolation.
+ * The agent process never loads or executes customer code -- only this runner does.
+ *
+ * Supports two IPC modes:
+ * - Fork IPC: Used by bare-metal (bwrap) and Firecracker backends. Messages go
+ *   via Node.js IPC channel (process.send / process.on('message')).
+ * - Stdio IPC: Used by container backend (docker exec). JSON-line messages flow
+ *   bidirectionally: agent writes to container stdin, runner writes to stdout.
+ *
+ * This file is compiled alongside the agent by rolldown (existing build), but
+ * runs as a SEPARATE process spawned by the sandbox backend.
+ */
+export {};
+//# sourceMappingURL=workflow-runner.d.ts.map

package/dist/execution/source-packer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `.kici/` source tarball creation for build agents.
+ *
+ * After cloning a customer repo, packs the `.kici/` directory (excluding
+ * `node_modules/` — that lives in its own cached tarball per `dep-packer.ts`)
+ * into a deterministic gzip tarball. The tarball bytes are hashed for
+ * integrity verification on the execution-job side.
+ *
+ * The artifact is content-addressed by the compiler's `contentHash` (hash of
+ * the raw workflow entry + asset digest), not by the tarball bytes — so the
+ * orchestrator's cache lookup keys unchanged while the stored bytes switch
+ * from a Rolldown bundle to a raw-source tarball.
+ */
+export declare function packKiciSource(workDir: string): Promise<{
+    tarball: Buffer;
+    hash: string;
+}>;
+//# sourceMappingURL=source-packer.d.ts.map

package/dist/execution/source-restore.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `.kici/` source tarball restoration for execution agents.
+ *
+ * Downloads a pre-built `.kici/` source tarball from the orchestrator's cache
+ * and extracts it into `workDir/` so the workflow entry point becomes
+ * importable. Mirrors the shape of `dep-restore.ts` but without the streaming
+ * optimization — source tarballs are tiny (kilobytes, not the hundreds of
+ * megabytes a `node_modules/` tarball carries).
+ *
+ * Note on integrity: `dispatch.sourceTarHash` is the workflow `contentHash`
+ * (computed over the raw source per `workflow-loader.ts::computeContentHash`),
+ * not the SHA-256 of the tarball bytes. The shared S3 cache key is derived
+ * from that same contentHash, so a signed GET URL from the orchestrator
+ * already establishes provenance for restored tarballs. Every
+ * `loadWorkflowSource` call site — build, init, and dynamic eval — passes
+ * the dispatched `contentHash` (and `resolvedHashFiles` when present) so
+ * the lock-vs-source drift gate fires at each author-TS load site, not
+ * only the build phase. That closes the corner cases where init or eval
+ * runs without a preceding build (cache infrastructure unavailable, or a
+ * build job that failed but left dynamic dispatch in flight).
+ */
+export declare function restoreSource(workDir: string, sourceTarUrl: string): Promise<void>;
+//# sourceMappingURL=source-restore.d.ts.map

package/dist/execution/timeout-util.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared timeout utility for wrapping async operations with a deadline.
+ *
+ * Used by init-runner (dynamic field evaluation) and dynamic job function evaluation.
+ */
+/**
+ * Execute a function with a timeout using Promise.race.
+ * Throws if the function does not resolve within the given timeout.
+ */
+export declare function withTimeout<T>(fn: () => T | Promise<T>, timeoutMs: number, label: string): Promise<T>;
+//# sourceMappingURL=timeout-util.d.ts.map

package/dist/execution/workflow-loader.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Workflow module loading: transforms `.ts` workflow files on import via the
+ * shared oxc-transform ESM loader hook. Customer workflow code is imported
+ * directly from the cloned / extracted source tree — no intermediate bundle,
+ * no Rolldown step at runtime. `@kici-dev/sdk` and host-repo deps resolve via
+ * Node's normal ESM lookup against `.kici/node_modules/`.
+ */
+import type { Workflow, StepInput, DynamicJobFn } from '@kici-dev/sdk';
+/**
+ * Compile schema version — must match `@kici-dev/compiler` lockfile/hasher.ts.
+ * Mixed into the content hash so compilation-approach changes produce different
+ * hashes. Bumped 3 → 4 when the artifact model switched from a Rolldown-bundled
+ * `.compiled.mjs` to a raw-source tarball consumed by the oxc-transform ESM
+ * loader hook. Bumped 4 → 5 when the hash input started normalizing line
+ * endings (CRLF → LF) so a Windows agent's checked-out CRLF source matches a
+ * Linux compiler's LF source.
+ */
+export declare const COMPILE_SCHEMA_VERSION = 5;
+export declare function ensureLoaderHookRegistered(): void;
+/**
+ * Load a workflow module by dynamic-importing its source file.
+ *
+ * Registers the oxc-transform loader hook (idempotent), then dynamic-imports
+ * the `.ts` file. Transitive imports resolve against the workspace's
+ * `node_modules/` the same way any `tsx`-style runner would — so host-repo
+ * helpers and `@kici-dev/sdk` Just Work.
+ *
+ * When `expectedContentHash` is provided, verifies the raw source matches
+ * the hash in the lock file. Drift between source and lock file produces a
+ * descriptive error that surfaces the baked agent SDK fingerprint (useful
+ * when debugging "is the agent running a stale build?").
+ */
+export declare function loadWorkflowSource(workDir: string, sourceFile: string, expectedContentHash?: string, resolvedHashFiles?: string[]): Promise<{
+    module: Record<string, unknown>;
+}>;
+/**
+ * Extract a workflow by name from a module's exports.
+ *
+ * Searches:
+ * 1. Default export (single Workflow or array of Workflows)
+ * 2. Named exports
+ */
+export declare function extractWorkflow(module: Record<string, unknown>, workflowName: string): Workflow;
+/**
+ * Extract a dynamic job function from a workflow by index.
+ */
+export declare function extractDynamicJobFn(workflow: Workflow, index: number): DynamicJobFn;
+/**
+ * Extract steps from a static job within a workflow.
+ */
+export declare function extractSteps(workflow: Workflow, jobName: string): readonly StepInput[];
+/**
+ * Extract steps from a job generated by a DynamicJobFn.
+ *
+ * Re-evaluates the DynamicJobFn to get the generated Job[] array, then finds
+ * the job by name and returns its steps. This is necessary because
+ * DynamicJobFn-generated jobs' step functions are closures that can only be
+ * obtained by calling the DynamicJobFn again.
+ *
+ * The function must be deterministic: given the same event context, it should
+ * return the same jobs with the same step functions. When `expectedJobNames`
+ * is provided, the re-evaluated output is compared against the original eval.
+ * A sibling mismatch logs a warning; a missing target job throws a clear
+ * determinism error.
+ */
+export declare function extractStepsFromDynamicJob(workflow: Workflow, dynamicIndex: number, jobName: string, event: Record<string, unknown>, env: Record<string, string | undefined>, apiTransport?: (method: string, params?: Record<string, unknown>) => Promise<unknown>, expectedJobNames?: string[]): Promise<{
+    steps: readonly StepInput[];
+    droppedJobs: string[];
+}>;
+//# sourceMappingURL=workflow-loader.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { loadConfig, type AppConfig } from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,128 @@
+import { fileURLToPath as __cjs_fileURLToPath } from "node:url";
+import { dirname as __cjs_dirname } from "node:path";
+__cjs_dirname(__cjs_fileURLToPath(import.meta.url));
+import "node:module";
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { LOGGER_ENV_VARS, defineEnv, validateUnknownKiciVars } from "@kici-dev/shared/env";
+import { KNOWN_ROLES, validateNoReservedLabels } from "@kici-dev/engine";
+import.meta.url;
+//#endregion
+//#region src/config.ts
+/** Execution mode for the agent's sandbox backend. Mirrors the runtime enum. */
+const ExecutionMode = z.enum([
+	"container",
+	"bare-metal",
+	"firecracker"
+]);
+/**
+* Env-var definition for the agent. Exported so the docs generator and the
+* deploy-stg pre-validator can inspect / re-parse without round-tripping
+* through process.env.
+*/
+const envDef = defineEnv({
+	service: "agent",
+	schema: z.object({
+		orchestratorUrl: z.string().url().min(1, "KICI_ORCHESTRATOR_URL is required"),
+		agentId: z.string().optional(),
+		labels: z.string().default("").transform((s) => s.split(",").filter(Boolean)),
+		roles: z.string().optional().transform((s) => {
+			if (s === void 0) return void 0;
+			if (s === "") return [];
+			return s.split(",").filter(Boolean);
+		}).refine((roles) => {
+			if (roles === void 0) return true;
+			const validValues = [...KNOWN_ROLES, "all"];
+			return roles.every((r) => validValues.includes(r));
+		}, { message: `KICI_ROLES must contain only: ${[...KNOWN_ROLES, "all"].join(", ")}` }).transform((roles) => {
+			if (roles === void 0) return void 0;
+			if (roles.includes("all")) return void 0;
+			if (roles.length === 0) return [];
+			return roles.filter((r) => r !== "all");
+		}),
+		port: z.coerce.number().default(8080),
+		logLevel: z.enum([
+			"debug",
+			"info",
+			"warn",
+			"error"
+		]).default("info"),
+		agentToken: z.string().optional(),
+		githubToken: z.string().optional(),
+		maxLogSizeBytes: z.coerce.number().default(10 * 1024 * 1024),
+		defaultStepTimeoutMs: z.coerce.number().default(1800 * 1e3),
+		dockerKeepFailed: z.string().default("false").transform((s) => s === "true"),
+		jobHeartbeatIntervalMs: z.coerce.number().default(6e4),
+		backpressureMode: z.enum(["pause", "drop"]).default("pause"),
+		sandbox: z.string().default("false").transform((s) => s === "true"),
+		sandboxNetwork: z.enum(["isolated", "host"]).default("isolated"),
+		scalerManaged: z.string().optional().transform((s) => s === "1"),
+		scalerIdleTimeoutMs: z.coerce.number().default(5e3),
+		scalerPendingDispatchTimeoutMs: z.coerce.number().default(6e4),
+		executionMode: ExecutionMode.optional(),
+		otelExporterOtlpEndpoint: z.string().optional(),
+		concurrencyWaitTimeoutMs: z.coerce.number().int().min(1e3).default(36e5)
+	}),
+	envMap: {
+		orchestratorUrl: "KICI_ORCHESTRATOR_URL",
+		agentId: "KICI_AGENT_ID",
+		labels: "KICI_LABELS",
+		roles: "KICI_ROLES",
+		port: "KICI_PORT",
+		logLevel: "KICI_LOG_LEVEL",
+		agentToken: "KICI_AGENT_TOKEN",
+		githubToken: "KICI_GITHUB_TOKEN",
+		maxLogSizeBytes: "KICI_MAX_LOG_SIZE_BYTES",
+		defaultStepTimeoutMs: "KICI_DEFAULT_STEP_TIMEOUT_MS",
+		dockerKeepFailed: "KICI_DOCKER_KEEP_FAILED",
+		jobHeartbeatIntervalMs: "KICI_JOB_HEARTBEAT_INTERVAL_MS",
+		backpressureMode: "KICI_BACKPRESSURE_MODE",
+		sandbox: "KICI_SANDBOX",
+		sandboxNetwork: "KICI_SANDBOX_NETWORK",
+		scalerManaged: "KICI_SCALER_MANAGED",
+		scalerIdleTimeoutMs: "KICI_SCALER_IDLE_TIMEOUT",
+		scalerPendingDispatchTimeoutMs: "KICI_SCALER_PENDING_DISPATCH_TIMEOUT",
+		executionMode: "KICI_EXECUTION_MODE",
+		otelExporterOtlpEndpoint: "OTEL_EXPORTER_OTLP_ENDPOINT",
+		concurrencyWaitTimeoutMs: "KICI_CONCURRENCY_WAIT_TIMEOUT_MS"
+	}
+});
+/**
+* Load and validate agent configuration from environment variables.
+*
+* Maps env vars with KICI_ prefix:
+* - KICI_ORCHESTRATOR_URL (required)
+* - KICI_AGENT_ID (optional, auto-generated from hostname-uuid8)
+* - KICI_LABELS (comma-separated, e.g. "linux,docker"). Labels with 'kici-' prefix are reserved.
+* - KICI_ROLES (comma-separated agent roles, e.g. "builder,init-runner". undefined=all, empty=execution-only)
+* - KICI_PORT (default: 8080)
+* - KICI_LOG_LEVEL (default: info)
+* - KICI_AGENT_TOKEN (optional, kat_ prefixed PSK for orchestrator authentication)
+* - KICI_GITHUB_TOKEN (optional)
+* - KICI_MAX_LOG_SIZE_BYTES (default: 10MB)
+* - KICI_DEFAULT_STEP_TIMEOUT_MS (default: 30 min)
+* - KICI_DOCKER_KEEP_FAILED (default: false)
+* - KICI_JOB_HEARTBEAT_INTERVAL_MS (default: 60000)
+* - KICI_BACKPRESSURE_MODE (default: pause, options: pause | drop)
+* - KICI_SANDBOX (default: false) — enable bubblewrap (bwrap) namespace isolation for bare-metal execution
+* - KICI_SANDBOX_NETWORK (default: isolated, options: isolated | host) — when sandbox=true, controls bwrap network namespace
+* - KICI_SCALER_MANAGED (set to "1" by the orchestrator's auto-scaler — agent self-shuts down on idle)
+* - KICI_SCALER_IDLE_TIMEOUT (ms, default 5000) — how long a scaler-managed agent waits before shutdown after going idle
+* - KICI_SCALER_PENDING_DISPATCH_TIMEOUT (ms, default 60000) — extended idle window when register.ack signals a queued bound job
+* - KICI_EXECUTION_MODE (optional, options: container | bare-metal | firecracker) — override the runner's mode-pick logic
+* - KICI_CONCURRENCY_WAIT_TIMEOUT_MS (default: 3_600_000) — workflow-runner timeout when long-polling for a slot-release follow-up `concurrency.ack`
+*/
+function loadConfig() {
+	const data = envDef.parse();
+	if (!data.scalerManaged) validateNoReservedLabels(data.labels, "KICI_LABELS");
+	validateUnknownKiciVars([...envDef.listKnownEnvVars(), ...LOGGER_ENV_VARS]);
+	return {
+		...data,
+		agentId: data.agentId ?? `${hostname()}-${randomUUID().slice(0, 8)}`
+	};
+}
+//#endregion
+export { loadConfig };
+
+//# sourceMappingURL=index.js.map

package/dist/metrics/metrics-reporter.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Periodic metrics reporter that collects OTel metrics and pushes them
+ * to the orchestrator via WebSocket as `agent.metrics` messages.
+ *
+ * The orchestrator aggregates these metrics from all agents and exposes
+ * them on its `/metrics` endpoint for Prometheus scraping.
+ */
+import type { AgentMetrics } from '@kici-dev/engine';
+export declare class MetricsReporter {
+    private timer?;
+    private readonly agentId;
+    private readonly send;
+    private readonly intervalMs;
+    constructor(opts: {
+        agentId: string;
+        send: (msg: AgentMetrics) => void;
+        intervalMs?: number;
+    });
+    /** Start periodic metric collection and push. */
+    start(): void;
+    /** Stop the periodic reporter. */
+    stop(): void;
+    /** Collect current metrics and send as agent.metrics message. */
+    collectAndSend(): Promise<void>;
+    /** Collect a snapshot of all current OTel metrics. */
+    collectSnapshot(): Promise<AgentMetrics['metrics']>;
+    /** Map OTel DataPointType to wire format type string. */
+    private mapDataPointType;
+    /** Extract string labels from OTel Attributes. */
+    private extractLabels;
+}
+//# sourceMappingURL=metrics-reporter.d.ts.map