@kici-dev/agent 0.0.0 → 0.1.1

package/dist/execution/sandbox/container-sandbox.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Container execution sandbox implementation.
+ *
+ * The strongest isolation model: the agent runs on the host while the entire
+ * job lifecycle (clone, dependency install, compile, step execution) runs
+ * inside a disposable Docker/Podman container. Communication uses stdin/stdout
+ * JSON-lines via dockerode's exec API.
+ *
+ * Key properties:
+ * - Container stays alive for the entire job (sleep infinity)
+ * - Workflow runner is bind-mounted read-only into the container
+ * - Agent-internal credentials (KICI_*, KICI_DATABASE_URL, etc.) NEVER enter the container
+ * - IPC uses demuxed Docker stream with JSON-line parsing on stdout
+ *
+ * The container image MUST have Node.js installed (a kici/runner base image
+ * is deferred -- for now this is a documented requirement).
+ */
+import Docker from 'dockerode';
+import type { ExecutionSandbox, SandboxSetupOptions, JobExecutionOptions, JobExecutionResult } from './types.js';
+interface ContainerSandboxOptions {
+    /** Dockerode instance (from orchestrator/scaler or created locally). */
+    docker: Docker;
+    /** Container image to use (from job config or scaler label-set). */
+    image: string;
+    /** Path to workflow-runner.js on the HOST (will be bind-mounted). */
+    runnerPath: string;
+    /** Mount target inside container (default: /opt/kici/workflow-runner.js). */
+    runnerMountPath?: string;
+    /** Pre-sanitized environment variables for the container. */
+    env: Record<string, string>;
+    /** Whether to keep failed containers for debugging. */
+    keepFailed?: boolean;
+    /** Job ID for container labeling and orphan cleanup. */
+    jobId?: string;
+}
+export declare class ContainerSandbox implements ExecutionSandbox {
+    private readonly docker;
+    private readonly image;
+    private readonly runnerPath;
+    private readonly runnerMountPath;
+    private readonly env;
+    private readonly keepFailed;
+    private readonly jobId;
+    /** The running container instance (set during setup). */
+    private container;
+    /** The active exec stream (set during executeJob, used for abort). */
+    private execStream;
+    /** Whether the job failed (used in teardown for keepFailed). */
+    private jobFailed;
+    /** Container name for logging/debugging. */
+    private containerName;
+    constructor(options: ContainerSandboxOptions);
+    setup(options: SandboxSetupOptions): Promise<void>;
+    executeJob(options: JobExecutionOptions): Promise<JobExecutionResult>;
+    /**
+     * Phase 1 of executeJob: create the docker exec, start it in hijack mode,
+     * demux the multiplexed stream into stdout / stderr passthroughs, capture
+     * stderr lines for crash diagnostics, and install the abort listener.
+     */
+    private attachExecStream;
+    /**
+     * Phase 2 of executeJob: drive the readline IPC loop until job.complete,
+     * exec exit, or crash. Returns the final job status, accumulated step
+     * results, and any captured outputs.
+     */
+    private awaitJobCompletion;
+    /**
+     * Dispatch one parsed RunnerToAgentMessage. Mutates `state`, `stepNames`,
+     * and `stepResults` in place; writes responses back through `stream` for
+     * the relay messages (event.emit / concurrency.report / agent.api.request).
+     *
+     * Returns `true` when the caller should resolve the awaitJobCompletion
+     * promise (only for `job.complete`); `false` otherwise.
+     */
+    private dispatchRunnerMessage;
+    /**
+     * Phase 3 of executeJob: apply abort-signal short-circuit, set jobFailed,
+     * and assemble the final JobExecutionResult.
+     */
+    private buildExecutionResult;
+    abort(): Promise<void>;
+    teardown(): Promise<void>;
+    /**
+     * Send the execute request to the workflow runner via the exec's stdin.
+     *
+     * The runner in stdio mode reads from stdin. We write a single JSON object
+     * (the execute message) followed by a newline, then signal end of input.
+     *
+     * Reuses buildRequest() from fork-runner.ts to ensure consistent field
+     * mapping from JobDispatch to JobExecutionRequest.
+     */
+    private sendExecuteRequest;
+    /**
+     * Handle abort: write abort message to stdin, wait for grace period,
+     * then kill the container if still running.
+     */
+    private handleAbort;
+}
+export {};
+//# sourceMappingURL=container-sandbox.d.ts.map

package/dist/execution/sandbox/env-sanitizer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Environment sanitization for sandbox execution.
+ *
+ * Uses an explicit allowlist approach: only known-safe system variables are
+ * copied from the host process.env. Agent-internal credentials (KICI_*,
+ * DATABASE_URL, PLATFORM_TOKEN, WEBHOOK_SECRET, etc.) are NEVER included.
+ *
+ * 7-layer merge precedence (later overrides earlier):
+ *   1. Allowed system vars from process.env
+ *   2. Sandbox defaults (FORCE_COLOR=1, etc.)
+ *   3. KICI_* system vars (orchestrator-generated, from userEnv)
+ *   4. Org-level environment vars (from orchestrator via environmentVars)
+ *   5. Source-level environment overrides (merged into environmentVars by orchestrator)
+ *   6. Job env (from lock file env field, evaluated by orchestrator)
+ *   7. setEnv() calls (runtime -- applied at step execution, not here)
+ */
+/**
+ * Build a sanitized environment for sandbox execution.
+ *
+ * Constructs an environment from scratch using the 7-layer merge:
+ * 1. Explicitly allowed system variables from process.env
+ * 2. Sandbox default variables (FORCE_COLOR, etc.)
+ * 3. User-defined env vars (KICI_* system vars from orchestrator)
+ * 4-5. Environment vars (org-level + source overrides, pre-merged by orchestrator)
+ * 6. Job env (SDK-defined, evaluated by orchestrator)
+ * 7. setEnv() calls (runtime -- not handled here)
+ *
+ * Secrets are NOT injected into environment variables by this function.
+ * They flow through IPC to ctx.secrets and are only exposed via ctx.secrets.expose().
+ *
+ * Agent-internal credentials (KICI_ORCHESTRATOR_URL, DATABASE_URL,
+ * PLATFORM_TOKEN, WEBHOOK_SECRET, etc.) are never included because they
+ * are not in the allowlist.
+ *
+ * @param userEnv - Environment variables from workflow config and orchestrator
+ * @param options - Optional extended options for environment layers
+ * @returns A new Record with only safe environment variables
+ */
+export declare function buildSanitizedEnv(userEnv: Record<string, string>, options?: {
+    environmentVars?: Record<string, string>;
+    jobEnv?: Record<string, string>;
+}): Record<string, string>;
+//# sourceMappingURL=env-sanitizer.d.ts.map

package/dist/execution/sandbox/firecracker-sandbox.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Firecracker execution sandbox (defense-in-depth).
+ *
+ * The Firecracker backend already provides VM-level isolation (separate kernel,
+ * filesystem, network namespace). This sandbox adds defense-in-depth by running
+ * the workflow runner as a child process with sanitized environment inside the VM.
+ *
+ * This prevents customer workflow code from:
+ * - Accessing MMDS metadata (orchestrator URL, agent config)
+ * - Reading agent environment variables (KICI_*, DATABASE_URL, etc.)
+ * - Interfering with the agent process directly
+ *
+ * The fork mechanism is identical to BareMetalSandbox (sandbox=false) -- no
+ * bwrap needed since the VM itself provides PID/IPC/network/filesystem isolation.
+ *
+ * VM lifecycle (start/stop) is managed by the Firecracker scaler backend,
+ * NOT by this sandbox. The sandbox only manages the child process within the VM.
+ */
+import type { ExecutionSandbox, SandboxSetupOptions, JobExecutionOptions, JobExecutionResult } from './types.js';
+/** Configuration options for FirecrackerSandbox. */
+interface FirecrackerSandboxOptions {
+    /** Absolute path to the compiled workflow-runner.js inside the VM. */
+    runnerPath: string;
+    /** Pre-sanitized environment variables (system allowlist + user env). */
+    env: Record<string, string>;
+}
+/**
+ * Firecracker execution sandbox implementation.
+ *
+ * Thin defense-in-depth wrapper that forks the workflow runner with sanitized
+ * environment inside a Firecracker VM. The VM provides the real isolation;
+ * this sandbox ensures credential separation within the VM.
+ */
+export declare class FirecrackerSandbox implements ExecutionSandbox {
+    private readonly runnerPath;
+    private readonly env;
+    private runner;
+    private workDir;
+    constructor(options: FirecrackerSandboxOptions);
+    /**
+     * No-op: VM is already running, managed by the Firecracker scaler backend.
+     */
+    setup(options: SandboxSetupOptions): Promise<void>;
+    /**
+     * Execute a job by forking the workflow runner with sanitized environment.
+     *
+     * Identical to BareMetalSandbox (sandbox=false) -- no bwrap needed since
+     * the VM itself provides full isolation.
+     */
+    executeJob(options: JobExecutionOptions): Promise<JobExecutionResult>;
+    /**
+     * Abort the running job.
+     *
+     * Sends abort IPC message, then SIGTERM after 10s, SIGKILL after 15s.
+     */
+    abort(): Promise<void>;
+    /**
+     * Kill child process if still running.
+     *
+     * VM lifecycle (shutdown) is managed by the scaler backend, not this sandbox.
+     */
+    teardown(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=firecracker-sandbox.d.ts.map

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

@@ -0,0 +1,94 @@
+/**
+ * Shared fork-based execution logic used by BareMetalSandbox and FirecrackerSandbox.
+ *
+ * Both backends use child_process.fork() (or spawn via bwrap) with Node.js IPC
+ * channel for communication. This module extracts the common fork + IPC dispatch
+ * logic to avoid duplication.
+ */
+import { type ChildProcess } from 'node:child_process';
+import type { JobDispatch } from '@kici-dev/engine';
+import type { JobExecutionOptions, JobExecutionResult } from './types.js';
+import type { JobExecutionRequest } from './ipc-protocol.js';
+/** Options for creating a fork-based runner. */
+interface ForkRunnerOptions {
+    /** Absolute path to the compiled workflow-runner.js. */
+    runnerPath: string;
+    /** Pre-sanitized base environment (system + user vars). */
+    env: Record<string, string>;
+    /** If true, wrap execution in bubblewrap for namespace isolation. */
+    useBwrap?: boolean;
+    /** Working directory for the child process. */
+    workDir?: string;
+    /**
+     * If true, enable network isolation via bwrap --unshare-net.
+     * Creates a network namespace with only loopback -- no external connectivity.
+     * Intentionally strict: bare-metal is for trusted environments only.
+     * Only effective when useBwrap is also true.
+     */
+    networkIsolation?: boolean;
+    /**
+     * Extra absolute host paths to bind read-only into the bwrap sandbox.
+     * Used by the bare-metal sandbox to expose `file://` clone source dirs
+     * (internal provider, dev/E2E) to the workflow runner so its `git clone`
+     * step can read from them. Ignored when useBwrap=false.
+     */
+    extraReadOnlyBinds?: string[];
+    /**
+     * Agent-level maximum grace period in milliseconds.
+     * The effective grace period is Math.min(jobGracePeriod, maxGracePeriodMs).
+     * Defaults to 30_000 (30 seconds).
+     */
+    maxGracePeriodMs?: number;
+}
+/** State of a running fork-based child process. */
+export interface ForkRunnerHandle {
+    /** The child process instance. */
+    child: ChildProcess;
+    /** Promise that resolves when the job completes. */
+    result: Promise<JobExecutionResult>;
+    /** Abort the running job (SIGTERM -> SIGKILL). Legacy method -- prefer cancel(). */
+    abort: () => Promise<void>;
+    /** Kill the child process if still running. */
+    kill: () => void;
+    /**
+     * Cancel the running job with two-level support.
+     *
+     * @param force If false: graceful cancel (SIGTERM, grace period, then SIGKILL).
+     *              If true: force cancel (SIGKILL immediately, skip hooks).
+     * @param gracePeriodMs Grace period in ms before escalating to SIGKILL (graceful only).
+     *                      Capped by the agent's maxGracePeriodMs.
+     */
+    cancel: (force: boolean, gracePeriodMs?: number) => void;
+}
+/**
+ * Build a JobExecutionRequest from a JobDispatch.
+ *
+ * Maps orchestrator dispatch fields to the subset needed by the workflow runner.
+ */
+export declare function buildRequest(dispatch: JobDispatch, workDir: string): JobExecutionRequest;
+/**
+ * Build bubblewrap (bwrap) arguments for namespace isolation.
+ *
+ * Creates a sandboxed filesystem view with:
+ * - Read-only bind mounts for system directories (/usr, /lib, /bin, etc.)
+ * - Read-only bind mount for Node.js binary
+ * - Writable bind mount for the workspace directory
+ * - Private /dev, /proc, /tmp
+ * - PID and IPC namespace isolation
+ * - Die-with-parent and new-session for process lifecycle safety
+ *
+ * When networkIsolation is true, --unshare-net creates a separate network namespace
+ * with only loopback (no external connectivity). This is intentionally strict:
+ * bare-metal mode is for trusted environments only, and full network isolation
+ * is simpler and more secure than selective blocking.
+ */
+export declare function buildBwrapArgs(workDir: string, nodeExecPath: string, networkIsolation?: boolean, runnerPath?: string, extraReadOnlyBinds?: string[]): string[];
+/**
+ * Spawn the workflow runner as a child process with IPC channel.
+ *
+ * In non-bwrap mode: uses child_process.fork() which sets up a native IPC channel.
+ * In bwrap mode: uses child_process.spawn('bwrap', ...) with stdio IPC fd.
+ */
+export declare function createForkRunner(options: ForkRunnerOptions, execOptions: JobExecutionOptions): ForkRunnerHandle;
+export {};
+//# sourceMappingURL=fork-runner.d.ts.map

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

@@ -0,0 +1,14 @@
+/**
+ * Barrel export for execution sandbox types and implementations.
+ *
+ * Provides clean imports for the job runner:
+ *   import { BareMetalSandbox, ContainerSandbox, buildSanitizedEnv } from './sandbox/index.js';
+ */
+export type { ExecutionSandbox, SandboxSetupOptions, JobExecutionOptions, JobExecutionResult, SandboxStepResult, } from './types.js';
+export type { RunnerToAgentMessage, AgentToRunnerMessage, EventEmitRequest, EventEmitResponse, JobExecutionRequest, } from './ipc-protocol.js';
+export { buildSanitizedEnv } from './env-sanitizer.js';
+export { ALLOWED_SYSTEM_VARS, KICI_AGENT_ENV_PREFIX, AGENT_REQUIRED_KICI_VARS, } from '@kici-dev/engine';
+export { BareMetalSandbox } from './bare-metal-sandbox.js';
+export { FirecrackerSandbox } from './firecracker-sandbox.js';
+export { ContainerSandbox } from './container-sandbox.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/execution/sandbox/ipc-protocol.d.ts

@@ -0,0 +1,311 @@
+import type { SandboxStepResult } from './types.js';
+/**
+ * Structured clone auth. Wire-compatible with `gitAuthSchema` on the
+ * orchestrator-agent protocol and `GitAuth` in `checkout/git-clone.ts`.
+ * Declared independently here so the sandbox IPC module has no runtime
+ * dependency on the engine protocol package.
+ */
+export interface GitAuthDispatch {
+    kind: 'basic' | 'ssh';
+    user?: string;
+    secret: string;
+    sshHostKeyPolicy?: 'accept-new' | 'pinned';
+    sshKnownHostsPem?: string;
+}
+/** Workflow runner is initialized and ready to receive a job. */
+interface ReadyMessage {
+    type: 'ready';
+}
+/** A step has started executing. */
+interface StepStartMessage {
+    type: 'step.start';
+    stepIndex: number;
+    stepName: string;
+    /** Distinguishes regular steps from hook executions (e.g., 'hook:onCancel', 'hook:cleanup'). Defaults to 'step'. */
+    step_type?: string;
+}
+/** A step has completed (success or failure). */
+interface StepCompleteMessage {
+    type: 'step.complete';
+    stepIndex: number;
+    status: 'success' | 'failed';
+    durationMs: number;
+    error?: {
+        message: string;
+        exitCode?: number;
+        signal?: string;
+    };
+    /** Step return value (outputs). Present on success when step returns non-void. */
+    outputs?: Record<string, unknown>;
+    /** Distinguishes regular steps from hook executions (e.g., 'hook:onCancel', 'hook:cleanup'). Defaults to 'step'. */
+    step_type?: string;
+    /** Secret key names accessed by this step via ctx.secrets.get() or ctx.secrets.expose(). Never contains values. */
+    secretsAccessed?: string[];
+}
+/** A single log line from step execution. */
+interface LogLineMessage {
+    type: 'log.line';
+    stepIndex: number;
+    line: string;
+}
+/**
+ * Discriminator for {@link StepSecretMountMessage} -- distinguishes a bare
+ * `ctx.secrets.mountFile` call from a `ctx.secrets.exposeFile` call (the
+ * latter additionally sets an env var on the step's process).
+ */
+export type StepSecretMountKind = 'mountFile' | 'exposeFile';
+/**
+ * Audit event emitted once per `ctx.secrets.mountFile` / `exposeFile` call.
+ * Carries only key names + the resulting path / env var -- never the file
+ * content. Persisted by the orchestrator alongside `secretsAccessed` so the
+ * dashboard can render the materialised-file audit trail.
+ */
+interface StepSecretMountMessage {
+    type: 'step.secret_mount';
+    stepIndex: number;
+    /** Source secret keys (in concatenation order). */
+    sources: string[];
+    /** Absolute path the file was materialised to inside the step sandbox. */
+    target: string;
+    /** Env var set when `kind === 'exposeFile'`; otherwise omitted. */
+    envVar?: string;
+    /** Discriminator between `mountFile` and `exposeFile`. */
+    kind: StepSecretMountKind;
+}
+/** The entire job has completed. */
+interface JobCompleteMessage {
+    type: 'job.complete';
+    status: 'success' | 'failed';
+    stepResults: SandboxStepResult[];
+    /** Error message when the job failed before step execution (e.g. clone, deps, compile). */
+    error?: string;
+    /** Aggregated step outputs by step name. Present on success when steps produce outputs. */
+    outputs?: Record<string, Record<string, unknown>>;
+    /** Secret output values collected during step execution (plaintext -- encryption happens in the agent before WS send). */
+    secretOutputs?: Record<string, string>;
+    /** Names of sibling jobs dropped by DynamicJobFn re-evaluation drift. */
+    droppedJobs?: string[];
+}
+/** Request to emit a custom event from a workflow step (runner -> agent). */
+export interface EventEmitRequest {
+    type: 'event.emit';
+    /** Unique ID for correlating the response back to the caller. */
+    requestId: string;
+    /** Custom event name (e.g. 'deploy-complete'). */
+    eventName: string;
+    /** Event payload (arbitrary JSON-serializable data). */
+    payload: Record<string, unknown>;
+    /** Optional targeting for cross-repo delivery. */
+    target?: {
+        repos?: string[];
+    };
+}
+/** Report evaluated concurrency group key (runner -> agent -> orchestrator). */
+export interface ConcurrencyReportMessage {
+    type: 'concurrency.report';
+    /** Evaluated concurrency group key (e.g. 'deploy-main'). */
+    group: string;
+}
+/**
+ * Discriminated union of all messages sent from the workflow runner to the agent.
+ *
+ * The workflow runner sends these via:
+ * - Node.js IPC channel (`process.send()`) for bare-metal/Firecracker backends
+ * - stdout JSON-lines for container backend (`docker exec`)
+ */
+/** API request from runner to agent (relayed to orchestrator via WS). */
+export interface AgentApiRequestIpc {
+    type: 'agent.api.request';
+    /** UUID for correlating the response. */
+    requestId: string;
+    /** Dot-namespaced method name (e.g., 'infrastructure.list'). */
+    method: string;
+    /** Method-specific parameters. */
+    params: Record<string, unknown>;
+}
+export type RunnerToAgentMessage = ReadyMessage | StepStartMessage | StepCompleteMessage | LogLineMessage | StepSecretMountMessage | JobCompleteMessage | EventEmitRequest | ConcurrencyReportMessage | AgentApiRequestIpc;
+/** Instruct the workflow runner to execute a job. */
+interface ExecuteMessage {
+    type: 'execute';
+    request: JobExecutionRequest;
+}
+/** Instruct the workflow runner to abort the current job. */
+interface AbortMessage {
+    type: 'abort';
+    /** When true, force-cancel immediately (SIGKILL, skip hooks). When false, graceful cancel (run hooks). */
+    force?: boolean;
+}
+/** Response confirming event delivery (agent -> runner). */
+export interface EventEmitResponse {
+    type: 'event.emit.response';
+    /** Correlates to the original EventEmitRequest.requestId. */
+    requestId: string;
+    /** Delivery ID assigned by the orchestrator (present on success). */
+    deliveryId?: string;
+    /** Error description (present on failure). */
+    error?: string;
+}
+/** Concurrency ack from orchestrator relayed to runner (agent -> runner). */
+export interface ConcurrencyAckMessage {
+    type: 'concurrency.ack';
+    /** Action to take: proceed with execution, wait (release slot), or cancel the job. */
+    action: 'proceed' | 'wait' | 'cancel';
+    /** Optional reason for wait or cancel. */
+    reason?: string;
+}
+/**
+ * Discriminated union of all messages sent from the agent to the workflow runner.
+ *
+ * The agent sends these via:
+ * - Node.js IPC channel (`child.send()`) for bare-metal/Firecracker backends
+ * - stdin JSON-line for container backend (`docker exec`)
+ */
+/** API response from agent to runner (relayed from orchestrator via WS). */
+export interface AgentApiResponseIpc {
+    type: 'agent.api.response';
+    /** Matches the original request's requestId. */
+    requestId: string;
+    /** Method result (present on success). */
+    result?: unknown;
+    /** Error description (present on failure). */
+    error?: string;
+}
+export type AgentToRunnerMessage = ExecuteMessage | AbortMessage | EventEmitResponse | ConcurrencyAckMessage | AgentApiResponseIpc;
+/**
+ * All data the workflow runner needs to execute a job inside the sandbox.
+ *
+ * Sent from the agent to the runner as part of the `execute` message.
+ * The runner uses this to clone, install deps, compile, and execute steps.
+ */
+export interface JobExecutionRequest {
+    /** Working directory inside the sandbox (e.g. /workspace). */
+    workDir: string;
+    /** Repository URL for git clone. */
+    repoUrl: string;
+    /** Git ref to checkout (branch or tag). */
+    ref: string;
+    /** Git commit SHA. */
+    sha: string;
+    /**
+     * Short-lived clone token (optional, for private repos).
+     *
+     * Deprecated in favour of `sourceAuth` / `workflowAuth` — retained as a
+     * back-compat field so same-provider GitHub App flows keep working while
+     * universal-git / cross-provider dispatches migrate to structured auth.
+     */
+    token?: string;
+    /**
+     * Structured auth for the source repo clone (Phase 4). When set, the
+     * workflow runner uses this instead of `token`.
+     */
+    sourceAuth?: GitAuthDispatch;
+    /**
+     * Structured auth for the workflow repo clone (global workflows only,
+     * Phase 4). Falls back to `sourceAuth` → `token` when absent.
+     */
+    workflowAuth?: GitAuthDispatch;
+    /** URL to a pre-packed `.kici/` source tarball (skip clone if present). */
+    sourceTarUrl?: string;
+    /** SHA-256 hash of the source tarball bytes for integrity verification. */
+    sourceTarHash?: string;
+    /** URL to pre-built dependency tarball (skip install if present). */
+    depsUrl?: string;
+    /** SHA-256 hash of the dependency tarball for integrity verification. */
+    depsHash?: string;
+    /** Workflow name to execute. */
+    workflowName: string;
+    /** Job name within the workflow. */
+    jobName: string;
+    /** Runs-on label for the job. */
+    runsOn: string;
+    /** Secrets to merge into step environment (highest precedence). */
+    secrets?: Record<string, string>;
+    /** Namespaced secrets by context name for ctx.secrets['context-name'].KEY access. */
+    namespacedSecrets?: Record<string, Record<string, string>>;
+    /** Secret metadata from resolveForJobWithMeta (backend + scope per key). */
+    secretMeta?: Record<string, {
+        value: string;
+        backend: string;
+        scope: string;
+    }>;
+    /** Source file path for workflow compilation (relative to repo root). */
+    sourceFile?: string;
+    /** Content hash of the source file for cache key. */
+    contentHash?: string;
+    /** Resolved hash files for content-addressed caching. */
+    resolvedHashFiles?: string[];
+    /** Max log size per step in bytes (runner enforces truncation). */
+    maxLogSizeBytes?: number;
+    /** Default step timeout in milliseconds. */
+    defaultStepTimeoutMs?: number;
+    /** Container configuration passthrough (for container-aware steps). */
+    container?: Record<string, unknown>;
+    /** Webhook event payload for rule evaluation context. */
+    event?: Record<string, unknown>;
+    /** Git provider that originated the triggering event (e.g. 'github', 'forgejo'). */
+    provider?: string;
+    /** Whether to checkout the repo (default: true). */
+    checkout?: boolean;
+    /** Whether this job is part of a test run triggered by `kici test`. */
+    isTestRun?: boolean;
+    /** When true, skip git clone -- use overlay tarball as complete workspace. */
+    fullRepo?: boolean;
+    /** URL to download the encrypted overlay tarball (test runs with uncommitted changes). */
+    tarballUrl?: string;
+    /** Base64-encoded CLI ephemeral public key for overlay decryption (DER/SPKI). */
+    cliPublicKey?: string;
+    /** Base64-encoded orchestrator ephemeral private key for overlay decryption (DER/PKCS8). */
+    orchestratorPrivateKey?: string;
+    /** Base64-encoded X25519 public key for the run (for encrypting secret outputs). */
+    runPublicKey?: string;
+    /** Deployment environment name (resolved by orchestrator). */
+    environment?: string;
+    /** Environment variables from orchestrator (org-level + source overrides, layers 4-5). */
+    environmentVars?: Record<string, string>;
+    /** Job env from lock file env field (layer 6, evaluated by orchestrator). */
+    jobEnv?: Record<string, string>;
+    /** Whether this is a global workflow (dual-clone: workflow repo + source repo). */
+    isGlobalWorkflow?: boolean;
+    /** Clone URL for the workflow (registering) repo. Only set when isGlobalWorkflow is true. */
+    workflowRepoUrl?: string;
+    /** Git ref for the workflow repo. */
+    workflowRef?: string;
+    /** Git commit SHA for the workflow repo. */
+    workflowSha?: string;
+    /** Repository identifier for the workflow repo (e.g., "org/workflow-repo"). */
+    workflowRepoIdentifier?: string;
+    /** Whether the workflow has a concurrency group function to evaluate. */
+    hasConcurrencyGroup?: boolean;
+    /** Concurrency group evaluation timeout in milliseconds (default: 30000). */
+    concurrencyEvaluationTimeoutMs?: number;
+    /** Git branch for concurrency group context. */
+    branch?: string;
+    /** Plain outputs from upstream jobs (keyed by job name, then by step name). For ctx.jobOutputs(). */
+    upstreamJobOutputs?: Record<string, Record<string, unknown>>;
+    /** Resolved private npm registries for `npm install` auth (token bytes already filled). */
+    npmRegistries?: ReadonlyArray<{
+        url: string;
+        scope?: string;
+        alwaysAuth: boolean;
+        token: string;
+    }>;
+    /** Bare-name secrets to project as install-subprocess env vars. */
+    installEnvSecrets?: Record<string, string>;
+    /** Short job-scoped nonce — used as suffix on synthesized npm-token env vars. */
+    jobIdShort?: string;
+    /**
+     * Source of a dynamically generated job (from DynamicJobFn).
+     * When set, the workflow runner re-evaluates the DynamicJobFn to extract
+     * step functions instead of looking up the job in the static jobs array.
+     */
+    dynamicSource?: {
+        /** Index of the DynamicJobFn in the workflow's jobs array. */
+        index: number;
+        /** Original event payload (passed to DynamicJobFn for re-evaluation). */
+        event: Record<string, unknown>;
+        /** Expected job names from the original eval (for determinism validation). */
+        expectedJobNames?: string[];
+    };
+}
+export {};
+//# sourceMappingURL=ipc-protocol.d.ts.map

package/dist/execution/sandbox/log-masker.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Secret value masking for log lines.
+ *
+ * Replaces all occurrences of registered secret values with '***' in log output.
+ * Used by the workflow runner to prevent secret leaks in IPC log messages.
+ *
+ * Performance: Builds a single combined regex from all secret values, so each
+ * log line is scanned in a single pass (not O(secrets * lines)).
+ */
+/**
+ * Masks secret values in log lines.
+ *
+ * Usage:
+ * ```ts
+ * const masker = new LogMasker();
+ * masker.registerSecrets({ TOKEN: 'abc123', SHORT: 'ab' });
+ * masker.mask('Token is abc123'); // 'Token is ***'
+ * // 'ab' is NOT masked (< 3 chars)
+ * ```
+ */
+export declare class LogMasker {
+    private pattern;
+    /**
+     * Register secret values to be masked in log output.
+     *
+     * Values shorter than 3 characters are skipped to avoid false positives.
+     * Base64-encoded variants of each qualifying secret are also registered,
+     * preventing leaks when secrets appear base64-encoded in logs (e.g.,
+     * Authorization: Basic headers, base64-encoded config values).
+     * Values are sorted by length descending so longer values are matched first
+     * (prevents partial masking when one secret is a substring of another).
+     */
+    registerSecrets(secrets: Record<string, string>): void;
+    /**
+     * Mask all registered secret values in a log line.
+     *
+     * Returns the line unchanged if no secrets are registered.
+     */
+    mask(line: string): string;
+    /**
+     * Returns true if any maskable secrets are registered.
+     */
+    hasSecrets(): boolean;
+}
+//# sourceMappingURL=log-masker.d.ts.map