@kici-dev/agent 0.1.14 → 0.1.16

package/README.md

@@ -1 +1,13 @@
-TBD
+# @kici-dev/agent
+
+Customer-deployable agent for the KiCI CI/CD stack. Connects to an orchestrator, clones the workflow repository, executes steps, and streams logs back.
+
+You normally don't install this package directly: agents are spawned by the orchestrator's auto-scaler or run from the published container image `quay.io/kici-dev/kici-agent`.
+
+Part of [KiCI](https://kici.dev) — CI/CD workflows as TypeScript code: author them with full language power, dry-run them locally, and run them on your own infrastructure.
+
+## Links
+
+- Documentation: <https://docs.kici.dev/operator/agent/getting-started/>
+- Source: <https://github.com/kici-dev/kici-public/tree/main/packages/agent>
+- License: AGPL-3.0-only

package/dist/diagnostics/mini-bundle.d.ts

@@ -0,0 +1,9 @@
+export interface AgentMiniBundleOptions {
+    agentId: string;
+    logDir?: string;
+    logWindowHours: number;
+    config: Record<string, unknown>;
+    metricsText?: string;
+}
+export declare function buildAgentMiniBundle(opts: AgentMiniBundleOptions): Promise<Buffer>;
+//# sourceMappingURL=mini-bundle.d.ts.map

package/dist/execution/cache/cache-engine.d.ts

@@ -0,0 +1,62 @@
+import type { CacheSpec, CacheRestoreResult } from '@kici-dev/sdk';
+/** Override roots — exposed for tests so the home destination is sandboxable. */
+export interface CacheRoots {
+    /** Home root override (defaults to `os.homedir()`). */
+    home?: string;
+}
+/**
+ * Resolve a cache path. `~`-prefixed -> home root; otherwise repo-root-relative.
+ * Rejects absolute paths and `..` escapes so a workflow cannot read or clobber
+ * files outside its tree / home.
+ */
+export declare function resolveCachePath(workDir: string, p: string, roots?: CacheRoots): string;
+/**
+ * Pack the spec's paths into a gzip tarball + its SHA-256.
+ *
+ * Each path is copied into a staging dir under its anchor prefix
+ * (`__repo__/<rel>` or `__home__/<rel>`), the staging dir is tarred (portable
+ * mode strips uid/gid/mtime), and the staging dir is removed. The resulting
+ * tarball self-describes which root each entry restores to.
+ */
+export declare function packCachePaths(workDir: string, paths: string[], roots?: CacheRoots): Promise<{
+    tarball: Buffer;
+    hash: string;
+}>;
+/**
+ * Extract a cache tarball buffer, verifying its SHA-256 first, then move each
+ * anchored group into place (repo entries under `workDir`, home entries under
+ * the home root). Extracts into a scratch dir so a partial restore never
+ * leaves half-written paths in the live tree.
+ */
+export declare function extractCacheTarball(tarball: Buffer, workDir: string, expectedHash: string, roots?: CacheRoots): Promise<void>;
+/**
+ * Stream-download a presigned URL, verify its SHA-256 on the fly (mirrors
+ * dep-restore's response -> hash -> gunzip -> tar pipeline), then move the
+ * anchored groups into place. Extracts into a scratch dir so a failed download
+ * never half-writes the live tree.
+ */
+export declare function downloadAndExtractCache(url: string, workDir: string, expectedHash: string, roots?: CacheRoots): Promise<void>;
+/**
+ * Transport the cache engine uses to reach the orchestrator over IPC -> WS.
+ * Backed by the agent's request/response relay (added to the IPC protocol in a
+ * later wiring task).
+ */
+export interface CacheTransport {
+    restore(key: string, restoreKeys?: string[]): Promise<{
+        hit: boolean;
+        matchedKey?: string;
+        downloadUrl?: string;
+        tarHash?: string;
+    }>;
+    beginSave(key: string): Promise<{
+        skip: boolean;
+        uploadUrl?: string;
+    }>;
+    completeSave(key: string, tarHash: string, sizeBytes: number): Promise<void>;
+}
+/** Build the imperative `ctx.cache` API bound to a workDir + transport. */
+export declare function createCacheApi(workDir: string, transport: CacheTransport, roots?: CacheRoots): {
+    restore(spec: CacheSpec): Promise<CacheRestoreResult>;
+    save(spec: CacheSpec): Promise<void>;
+};
+//# sourceMappingURL=cache-engine.d.ts.map

package/dist/execution/cache/cache-phase.d.ts

@@ -0,0 +1,29 @@
+import type { CacheSpec, CacheApi } from '@kici-dev/sdk';
+import type { RunnerToAgentMessage } from '../sandbox/ipc-protocol.js';
+/** The restore outcome remembered per spec key so the save phase can skip exact hits. */
+export interface CacheRestoreOutcome {
+    hit: boolean;
+    matchedKey?: string;
+}
+export interface CachePhaseDeps {
+    /** Imperative cache API (the same one bound to `ctx.cache`). */
+    cache: CacheApi;
+    /** Emit a runner→agent IPC message (the masked send). */
+    sendIpc: (msg: RunnerToAgentMessage) => void;
+    /** Monotonic pseudo-step index allocator (continues after real steps + hooks). */
+    nextStepIndex: () => number;
+}
+/**
+ * Restore every spec, surfacing each as a `cache:restore` pseudo-step. Returns
+ * a map keyed by spec key recording whether the EXACT key hit (so the save
+ * phase can skip a redundant save of an entry that already exists).
+ */
+export declare function restoreCacheSpecs(specs: CacheSpec[], deps: CachePhaseDeps): Promise<Map<string, CacheRestoreOutcome>>;
+/**
+ * Save every spec whose EXACT key did not already hit on restore (immutable +
+ * no redundant save), surfacing each as a `cache:save` pseudo-step. A spec
+ * whose restore matched a different key via a `restoreKeys` prefix is still
+ * saved under its exact key.
+ */
+export declare function saveCacheSpecs(specs: CacheSpec[], restoreResults: Map<string, CacheRestoreOutcome>, deps: CachePhaseDeps): Promise<void>;
+//# sourceMappingURL=cache-phase.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * User-facing cache engine barrel (sandbox-side).
+ *
+ * Re-exports the pure pack/extract/checksum helpers and the imperative
+ * `ctx.cache` API factory plus its transport interface.
+ */
+export { createCacheApi, packCachePaths, extractCacheTarball, downloadAndExtractCache, resolveCachePath, type CacheTransport, type CacheRoots, } from './cache-engine.js';
+export { restoreCacheSpecs, saveCacheSpecs, type CachePhaseDeps, type CacheRestoreOutcome, } from './cache-phase.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/execution/dynamic-job-serializer.d.ts

@@ -18,6 +18,17 @@
 import type { $ as Shell } from 'zx';
 import type { Job, Logger } from '@kici-dev/sdk';
 import type { LockJob } from '@kici-dev/engine';
+/**
+ * Thrown when resolving a job's dynamic matrix fails (the matrix function threw
+ * or timed out, or returned an unsupported value). Lets the agent attribute the
+ * failure to the matrix_expansion init-failure category instead of the generic
+ * dynamic_eval bucket.
+ */
+export declare class MatrixExpansionError extends Error {
+    readonly jobName: string;
+    readonly name = "MatrixExpansionError";
+    constructor(jobName: string, message: string);
+}
 /** Maximum number of jobs a single DynamicJobFn can generate. */
 export declare const MAX_DYNAMIC_JOBS = 100;
 /**
@@ -27,7 +38,7 @@ export declare const MAX_DYNAMIC_JOBS = 100;
  * we thread it through the serializer rather than re-creating it.
  */
 export interface SerializerContext {
-    /** Webhook event payload — passed as the first argument to env/environment/concurrencyGroup fns. */
+    /** Normalized event envelope — passed as the first argument to env/environment/concurrencyGroup fns. */
     event: Record<string, unknown>;
     /** zx shell — passed to dynamic matrix fns. */
     $: typeof Shell;

package/dist/execution/env-init/init-phase.d.ts

@@ -0,0 +1,64 @@
+import type { $ as Shell } from 'zx';
+import type { GenericInitConfig, CacheSpec } from '@kici-dev/sdk';
+import { TimeoutReason } from '@kici-dev/engine';
+import type { RunnerToAgentMessage } from '../sandbox/ipc-protocol.js';
+/**
+ * Cache engine port (P2). Init reuses the same imperative cache API bound to
+ * `ctx.cache` (and used by the declarative job/step cache phase) — restore the
+ * spec's paths before the command, save them after on an exact-key miss. The
+ * shape mirrors `@kici-dev/sdk`'s `CacheApi` (`restore`/`save`).
+ */
+export interface InitCachePort {
+    restore(spec: CacheSpec): Promise<{
+        hit: boolean;
+        matchedKey?: string;
+    }>;
+    save(spec: CacheSpec): Promise<void>;
+}
+/**
+ * Env-handoff port (P1). Mirrors the KICI_ENV / KICI_PATH file contract that
+ * steps use: before the command the agent allocates fresh KICI_ENV / KICI_PATH
+ * files and points the shell env at them (`beginCapture`); after a successful
+ * command it reads + parses those files into an EnvDelta and applies it through
+ * `applyEnvDelta` (operator-secret guard + PATH-prepend order), then truncates
+ * the files (`applyDelta`). P1 owns the file lifecycle and the parse; the init
+ * phase only sequences the two calls around the command.
+ */
+export interface InitEnvPort {
+    /** Allocate fresh KICI_ENV/KICI_PATH files for this init; the shell's env points at them. */
+    beginCapture(): Promise<void>;
+    /** Read+parse the files, apply via applyEnvDelta (operator-secret guard + masking), then truncate. */
+    applyDelta(): Promise<void>;
+}
+export interface RunInitPhaseOptions {
+    /** Init specs to run, in order. Empty / undefined => no-op (ok:true). */
+    specs: GenericInitConfig[];
+    /**
+     * Returns the sandbox shell to run the i-th init command with.
+     * The workflow-runner builds a fresh zx$ shell (cwd=clone root, env=process.env,
+     * log->IPC) per init so each spec's `env` overlay + KICI_ENV/KICI_PATH files apply.
+     */
+    shellFor: (spec: GenericInitConfig, index: number) => typeof Shell;
+    /** Masked IPC sender (same as the step loop's maskedSend). */
+    sendIpc: (msg: RunnerToAgentMessage) => void;
+    /** stepIndex for init:0; subsequent specs use base+1, base+2, … (after user steps + hook indices). */
+    stepIndexBase: number;
+    /** Cache engine (P2). When a spec sets `cache`, restore before / save-on-miss after. */
+    cache?: InitCachePort;
+    /** Env-handoff port (P1). When set, capture before each init and apply the delta after success. */
+    env?: InitEnvPort;
+}
+export interface RunInitPhaseResult {
+    ok: boolean;
+    /** Index of the init spec that failed (when ok=false). */
+    failedInitIndex?: number;
+    /** Failure message (when ok=false). */
+    error?: string;
+    /** True when the failure was a wall-clock timeout (init exceeded `timeout`). */
+    timedOut?: boolean;
+    /** Distinct P3 timeout reason (`job_timeout`) when `timedOut` is true. */
+    reason?: TimeoutReason;
+}
+/** Run all init specs in order; stop + fail at the first non-zero / timeout. */
+export declare function runInitPhase(opts: RunInitPhaseOptions): Promise<RunInitPhaseResult>;
+//# sourceMappingURL=init-phase.d.ts.map

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

@@ -21,7 +21,7 @@ export interface InitResult {
  *
  * @param workflow - The extracted Workflow object
  * @param jobName - Name of the job whose dynamic fields to evaluate
- * @param event - Normalized webhook event data, passed as argument to dynamic functions
+ * @param event - Normalized event envelope — same shape every dynamic-function call site receives.
  * @param flags - Which fields are dynamic and need evaluation
  * @param timeoutMs - Timeout per dynamic function call (default 60_000ms)
  */

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

@@ -1,5 +1,6 @@
 import type { AgentToOrchestratorMessage, JobDispatch } from '@kici-dev/engine';
 import type { AppConfig } from '../config.js';
+import type { CacheRequestIpc, CacheResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './sandbox/index.js';
 /**
  * Dependencies injected into JobRunner.
  */
@@ -81,6 +82,23 @@ export interface JobRunnerDeps {
      * Optional for backward compatibility.
      */
     sendApiRequest?: (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Relay a user-facing cache request to the orchestrator and await the
+     * response. Translates the sandbox `cache.request` IPC into the matching
+     * `cache.user.restore.request` / `cache.user.save.request` /
+     * `cache.user.save.complete` WS message and returns the orchestrator's
+     * `cache.user.*.response` mapped back onto the IPC response shape.
+     * Optional for backward compatibility (callers that don't support the cache).
+     */
+    requestUserCache?: (jobId: string, request: CacheRequestIpc) => Promise<CacheResponseIpc>;
+    /**
+     * Relay a step-level approval request to the orchestrator and await the
+     * resolution. Translates the sandbox `approval.request` IPC into a
+     * `step.approval-request` WS message and returns the orchestrator's
+     * `step.approval-resolved` mapped onto the IPC response shape. Optional for
+     * backward compatibility (callers that don't support approvals).
+     */
+    sendStepApproval?: (runId: string, jobId: string, request: StepApprovalRequestIpc) => Promise<StepApprovalResolvedIpc>;
 }
 interface ActiveJob {
     abortController: AbortController;
@@ -114,6 +132,8 @@ export declare class JobRunner {
     private readonly _sendRunEvent;
     private readonly _sendConcurrencyReport;
     private readonly _sendApiRequest?;
+    private readonly _requestUserCache?;
+    private readonly _sendStepApproval?;
     /** Tracks running jobs for concurrency and cancellation */
     readonly activeJobs: Map<string, ActiveJob>;
     /** Active sandbox for the current job (used for abort). */
@@ -240,6 +260,16 @@ export declare class JobRunner {
      * Emit a run.event message to the orchestrator for infrastructure lifecycle tracking.
      */
     private emitRunEvent;
+    /**
+     * Emit a `cache.restore` / `cache.save` run event for a cache pseudo-step.
+     *
+     * The cache phase tags its `step.complete` IPC with a {@link CacheStepType}
+     * `step_type` and a `data.cacheOutcome` ({@link CacheOutcome}); when one of
+     * those terminal pseudo-step statuses arrives here, mirror it onto the run
+     * timeline as a `run.event` so hit/miss/saved/skipped/error is recorded for
+     * the dashboard. A no-op for regular steps and hooks.
+     */
+    private maybeEmitCacheRunEvent;
     /**
      * Create a LogStreamer for a synthetic step (build, evaluate, etc.).
      */

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

@@ -0,0 +1,44 @@
+/**
+ * Shared environment-delta applier.
+ *
+ * This is the single code path behind the JS API (ctx.setEnv / ctx.addPath) and
+ * the shell-side KICI_ENV / KICI_PATH file contract. Routing both through one
+ * helper guarantees they share the operator-secret guard and the PATH-prepend
+ * ordering. The generic init phase applies its captured delta through the same
+ * function so the init command and a step export env identically.
+ */
+/** A parsed environment delta to apply to process.env. */
+export interface EnvDelta {
+    /** KEY -> value pairs to set (last-write-wins). */
+    env: Record<string, string>;
+    /** Directories to prepend to PATH, in order (first entry ends up first on PATH). */
+    pathPrepends: string[];
+}
+/** Outcome of applying a delta -- used for logging / tests. */
+export interface ApplyEnvDeltaResult {
+    /** Keys that were applied to the target env. */
+    appliedKeys: string[];
+    /** Keys that were rejected because they collide with an operator secret. */
+    rejectedKeys: string[];
+    /** Directories prepended to PATH (in the order they ended up on PATH). */
+    appliedPaths: string[];
+}
+/** Options controlling how a delta is applied. */
+export interface ApplyEnvDeltaOptions {
+    /** Keys that must never be overridden (operator-injected secrets + reserved ctx keys). */
+    operatorSecretKeys: Set<string>;
+    /** Environment object to mutate. Defaults to process.env. */
+    target?: NodeJS.ProcessEnv;
+    /** Invoked once per rejected key (e.g. to emit a masked log warning). */
+    onReject?: (key: string) => void;
+}
+/**
+ * Apply an environment delta to `target` (defaults to process.env), honoring the
+ * operator-secret guard.
+ *
+ * - env keys present in `operatorSecretKeys` are rejected (never override an
+ *   operator secret); `onReject` fires once per rejected key.
+ * - pathPrepends are applied so the FIRST array entry ends up FIRST on PATH.
+ */
+export declare function applyEnvDelta(delta: EnvDelta, options: ApplyEnvDeltaOptions): ApplyEnvDeltaResult;
+//# sourceMappingURL=env-delta.d.ts.map

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

@@ -0,0 +1,39 @@
+/**
+ * KICI_ENV / KICI_PATH temp-file contract.
+ *
+ * Before each step the agent points the KICI_ENV and KICI_PATH env vars at fresh
+ * temp files. A step's shell commands append `KEY=value` lines to $KICI_ENV and
+ * one directory per line to $KICI_PATH. After the step the agent parses both
+ * files into an EnvDelta and feeds it through applyEnvDelta() -- the same path
+ * the JS API (ctx.setEnv / ctx.addPath) uses -- then truncates the files for the
+ * next step.
+ *
+ * Format v1: single-line `KEY=value` for env (no embedded newlines); one
+ * directory per line for path. Blank lines and lines without `=` are ignored.
+ */
+import type { EnvDelta } from './env-delta.js';
+/** The pair of temp files the step's shell appends to. */
+export interface EnvFiles {
+    /** Path of the file steps append `KEY=value` lines to (KICI_ENV). */
+    envFile: string;
+    /** Path of the file steps append one directory per line to (KICI_PATH). */
+    pathFile: string;
+}
+/**
+ * Parse `KEY=value` lines into a record. Blank lines, lines without `=`, and
+ * lines with an empty key are ignored. The split is on the first `=` only, so a
+ * value may contain `=`. The key is trimmed; the value is taken verbatim after
+ * the first `=`. Last assignment to a key wins.
+ */
+export declare function parseEnvFileContent(content: string): Record<string, string>;
+/** Parse one trimmed directory per non-blank line, preserving order. */
+export declare function parsePathFileContent(content: string): string[];
+/** Create fresh, empty env + path files inside a private temp dir under `baseDir`. */
+export declare function createEnvFiles(baseDir: string): Promise<EnvFiles>;
+/** Convenience: create env files under the OS temp dir. */
+export declare function createEnvFilesInTmp(): Promise<EnvFiles>;
+/** Read + parse both files into an EnvDelta. Missing/empty files yield an empty delta. */
+export declare function readEnvDelta(files: EnvFiles): Promise<EnvDelta>;
+/** Truncate both files to empty so the next step starts clean. */
+export declare function truncateEnvFiles(files: EnvFiles): Promise<void>;
+//# sourceMappingURL=env-file.d.ts.map

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

@@ -5,7 +5,7 @@
  *   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 type { RunnerToAgentMessage, AgentToRunnerMessage, EventEmitRequest, EventEmitResponse, CacheRequestIpc, CacheResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc, 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';

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

@@ -41,6 +41,12 @@ interface StepCompleteMessage {
     step_type?: string;
     /** Secret key names accessed by this step via ctx.secrets.get() or ctx.secrets.expose(). Never contains values. */
     secretsAccessed?: string[];
+    /**
+     * Structured per-step metadata forwarded to the orchestrator's `step.status`
+     * `data` field (and persisted for the dashboard timeline). The cache
+     * pseudo-steps carry `{ cacheOutcome, key, matchedKey?, bytes? }` here.
+     */
+    data?: Record<string, unknown>;
 }
 /** A single log line from step execution. */
 interface LogLineMessage {
@@ -123,7 +129,63 @@ export interface AgentApiRequestIpc {
     /** Method-specific parameters. */
     params: Record<string, unknown>;
 }
-export type RunnerToAgentMessage = ReadyMessage | StepStartMessage | StepCompleteMessage | LogLineMessage | StepSecretMountMessage | JobCompleteMessage | EventEmitRequest | ConcurrencyReportMessage | AgentApiRequestIpc;
+/**
+ * Operation requested by a user-facing cache IPC message.
+ *
+ * - `restore` — look up a cache entry (exact key + prefix fallbacks).
+ * - `beginSave` — request a presigned PUT (declined when the immutable key exists).
+ * - `completeSave` — confirm the upload so the orchestrator commits temp -> final.
+ */
+export type CacheRequestOp = 'restore' | 'beginSave' | 'completeSave';
+/**
+ * Request a user-facing cache operation (runner -> agent). The sandbox runner
+ * can't open a WS, so it sends this IPC; the agent relays it to the
+ * orchestrator over the WS as a `cache.user.*` message and pipes the response
+ * back as a {@link CacheResponseIpc}. Mirrors the {@link AgentApiRequestIpc}
+ * relay pattern.
+ */
+export interface CacheRequestIpc {
+    type: 'cache.request';
+    /** UUID for correlating the response. */
+    requestId: string;
+    /** Which cache operation to perform. */
+    op: CacheRequestOp;
+    /** Exact cache key (all ops). */
+    key: string;
+    /** Ordered prefix fallbacks (newest matching entry wins). `restore` only. */
+    restoreKeys?: string[];
+    /** SHA-256 of the uploaded tarball bytes. `completeSave` only. */
+    tarHash?: string;
+    /** Tarball size in bytes (drives quota accounting). `completeSave` only. */
+    sizeBytes?: number;
+}
+/**
+ * Request a step-level approval hold (runner -> agent). The sandbox runner
+ * blocks the step loop before a `requireApproval` step; the agent relays this
+ * as a `step.approval-request` WS message and pipes the orchestrator's
+ * resolution back as a {@link StepApprovalResolvedIpc}. Mirrors the
+ * {@link CacheRequestIpc} relay pattern.
+ */
+export interface StepApprovalRequestIpc {
+    type: 'approval.request';
+    /** UUID for correlating the response. */
+    requestId: string;
+    /** Step index within the job. */
+    stepIndex: number;
+    /** Step name (for the hold reason / logs). */
+    stepName: string;
+    /** AND-list of approver clauses (empty = any approval-capable member). */
+    clauses: Array<{
+        team: string;
+    } | {
+        user: string;
+    }>;
+    /** Human label for the gate. */
+    reason: string;
+    /** Per-gate timeout override (seconds) from the SDK `requireApproval.timeout`. */
+    timeoutSeconds?: number;
+}
+export type RunnerToAgentMessage = ReadyMessage | StepStartMessage | StepCompleteMessage | LogLineMessage | StepSecretMountMessage | JobCompleteMessage | EventEmitRequest | ConcurrencyReportMessage | AgentApiRequestIpc | CacheRequestIpc | StepApprovalRequestIpc;
 /** Instruct the workflow runner to execute a job. */
 interface ExecuteMessage {
     type: 'execute';
@@ -170,7 +232,51 @@ export interface AgentApiResponseIpc {
     /** Error description (present on failure). */
     error?: string;
 }
-export type AgentToRunnerMessage = ExecuteMessage | AbortMessage | EventEmitResponse | ConcurrencyAckMessage | AgentApiResponseIpc;
+/**
+ * Response to a {@link CacheRequestIpc} (agent -> runner). Relayed from the
+ * orchestrator's `cache.user.*.response` WS message. Carries the union of the
+ * restore-response (`hit` / `matchedKey` / `downloadUrl` / `tarHash`) and
+ * save-response (`skip` / `uploadUrl`) fields; `completeSave` resolves with an
+ * empty (no-field) response. `error` is set when the relay or orchestrator
+ * failed.
+ */
+export interface CacheResponseIpc {
+    type: 'cache.response';
+    /** Matches the original request's requestId. */
+    requestId: string;
+    /** Restore: true when an entry matched (exact or prefix). */
+    hit?: boolean;
+    /** Restore: full key that matched (exact key or matched prefix entry's key). */
+    matchedKey?: string;
+    /** Restore: presigned GET URL for the matched tarball (present only on hit). */
+    downloadUrl?: string;
+    /** Restore: SHA-256 of the tarball bytes for download integrity verification. */
+    tarHash?: string;
+    /** Save: true when the immutable key already exists (upload skipped). */
+    skip?: boolean;
+    /** Save: presigned PUT URL to the temp object (absent when `skip`). */
+    uploadUrl?: string;
+    /** Error description (present when the relay or orchestrator failed). */
+    error?: string;
+}
+/**
+ * Resolution of a step-level approval hold (agent -> runner). Relayed from the
+ * orchestrator's `step.approval-resolved` WS message. On `approved` the runner
+ * runs the step; on `rejected`/`expired` it fails the job. `error` is set when
+ * the relay itself failed (treated as a fail-closed reject by the runner).
+ */
+export interface StepApprovalResolvedIpc {
+    type: 'approval.resolved';
+    /** Matches the original request's requestId. */
+    requestId: string;
+    /** Outcome of the hold. */
+    outcome?: 'approved' | 'rejected' | 'expired';
+    /** Optional human reason (e.g. the reject reason). */
+    reason?: string;
+    /** Error description (present when the relay or orchestrator failed). */
+    error?: string;
+}
+export type AgentToRunnerMessage = ExecuteMessage | AbortMessage | EventEmitResponse | ConcurrencyAckMessage | AgentApiResponseIpc | CacheResponseIpc | StepApprovalResolvedIpc;
 /**
  * All data the workflow runner needs to execute a job inside the sandbox.
  *
@@ -238,9 +344,11 @@ export interface JobExecutionRequest {
     maxLogSizeBytes?: number;
     /** Default step timeout in milliseconds. */
     defaultStepTimeoutMs?: number;
+    /** Total job wall-clock timeout in milliseconds (init + all steps + hooks). When set, the runner aborts the job on breach and reports TimeoutReason.job_timeout. From the lock job's `timeout`. */
+    jobTimeoutMs?: number;
     /** Container configuration passthrough (for container-aware steps). */
     container?: Record<string, unknown>;
-    /** Webhook event payload for rule evaluation context. */
+    /** Normalized event envelope (type/action/targetBranch/payload…) for rule evaluation and step context. */
     event?: Record<string, unknown>;
     /** Git provider that originated the triggering event (e.g. 'github', 'forgejo'). */
     provider?: string;

package/dist/execution/sandbox/job-deadline.d.ts

@@ -0,0 +1,13 @@
+import { TimeoutReason } from '@kici-dev/engine';
+/** Handle returned by armJobDeadline; call clear() to cancel the timer. */
+export interface JobDeadlineHandle {
+    clear(): void;
+}
+/**
+ * Arm a job-level wall-clock deadline. When `timeoutMs` is set and elapses
+ * before clear() is called, invokes `onTimeout` with the distinct
+ * `job_timeout` reason and the configured budget. A no-op when `timeoutMs`
+ * is undefined (no job-level cap configured).
+ */
+export declare function armJobDeadline(timeoutMs: number | undefined, onTimeout: (reason: TimeoutReason, timeoutMs: number) => void): JobDeadlineHandle;
+//# sourceMappingURL=job-deadline.d.ts.map

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

@@ -8,6 +8,7 @@
 import type { Step, StepContext, HookInput, OutputsMap, StepSecretMountRecord } from '@kici-dev/sdk';
 import type { RunnerToAgentMessage } from './ipc-protocol.js';
 import type { SandboxStepResult } from './types.js';
+import { type CachePhaseDeps } from '../cache/index.js';
 /** Job-level hooks passed to the step loop. */
 export interface JobHooks {
     beforeStep?: HookInput;
@@ -18,7 +19,7 @@ export interface JobHooks {
     cleanup?: HookInput;
 }
 /** Options for the step execution loop. */
-interface StepLoopOptions {
+export interface StepLoopOptions {
     steps: Step[];
     /** Factory that creates a StepContext for a given step index and name. */
     createStepContext: (stepIndex: number, stepName: string) => StepContext;
@@ -31,8 +32,24 @@ interface StepLoopOptions {
     env: Record<string, string | undefined>;
     /** Job-level hooks. */
     jobHooks?: JobHooks;
+    /**
+     * Declarative cache phase dependencies (cache API + IPC + pseudo-step index
+     * allocator). When set, each step's own `cache` specs are restored before the
+     * step's `run` and saved after (on an exact-key miss), surfacing as
+     * `cache:restore` / `cache:save` pseudo-steps. Absent ⇒ no step-level cache.
+     */
+    cachePhaseDeps?: CachePhaseDeps;
     /** Abort check callback. Returns true if job was aborted. */
     isAborted?: () => boolean;
+    /**
+     * Aborted when the job-level wall-clock deadline (the lock job's `timeout`)
+     * is breached. Threaded into each step's run race so an in-flight step is
+     * interrupted immediately on breach — the between-steps `isAborted()` check
+     * alone cannot unwind a single long-running step that has no per-step
+     * `timeout`. When the signal fires, the step rejects with a job_timeout
+     * error and the loop stops.
+     */
+    jobDeadlineSignal?: AbortSignal;
     /** Job start time (epoch ms) for outcome metadata duration. */
     startTime?: number;
     /**
@@ -54,6 +71,41 @@ interface StepLoopOptions {
      * orchestrator can persist the audit trail alongside `secretsAccessed`.
      */
     getSecretMountRecords?: () => StepSecretMountRecord[];
+    /**
+     * Before a step's run function executes, point KICI_ENV / KICI_PATH at fresh
+     * temp files for this step. Invoked once per executed step (NOT for rule-skipped
+     * steps). The workflow-runner owns the file lifecycle.
+     */
+    beforeStepEnvFiles?: () => Promise<void>;
+    /**
+     * After a step's run function completes (success OR failure), read the
+     * KICI_ENV / KICI_PATH files, apply the delta via applyEnvDelta, and truncate
+     * them for the next step. Never throws -- errors are logged by the wired impl.
+     */
+    afterStepApplyEnvFiles?: () => Promise<void>;
+    /**
+     * Block a `requireApproval` step pending an orchestrator-side approval hold.
+     * The runner sends the normalized requirement and awaits the resolution; the
+     * agent keeps job heartbeats flowing during the wait so the agent isn't
+     * reaped. Absent ⇒ approvals are not gated (CT / unit harnesses) and steps
+     * run unconditionally.
+     */
+    awaitStepApproval?: (req: {
+        stepIndex: number;
+        stepName: string;
+        clauses: Array<{
+            team: string;
+        } | {
+            user: string;
+        }>;
+        reason: string;
+        timeoutSeconds?: number;
+    }) => Promise<StepApprovalResolution>;
+}
+/** Outcome of an awaited step-level approval hold. */
+export interface StepApprovalResolution {
+    outcome: 'approved' | 'rejected' | 'expired';
+    reason?: string;
 }
 /** Result of the step execution loop. */
 interface StepLoopResult {

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

@@ -1,5 +1,5 @@
 import type { JobDispatch } from '@kici-dev/engine';
-import type { EventEmitRequest, EventEmitResponse, ConcurrencyReportMessage, ConcurrencyAckMessage } from './ipc-protocol.js';
+import type { EventEmitRequest, EventEmitResponse, ConcurrencyReportMessage, ConcurrencyAckMessage, CacheRequestIpc, CacheResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './ipc-protocol.js';
 /**
  * Common interface for all execution sandbox backends.
  *
@@ -79,6 +79,25 @@ export interface JobExecutionOptions {
      * Optional for backward compatibility (callers that don't support the agent API).
      */
     onApiRequest?: (method: string, params: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Callback for relaying a user-facing cache request from the sandbox to the
+     * orchestrator. The sandbox runner sends `cache.request` IPC; the agent wraps
+     * it in the matching `cache.user.*` WS message and forwards to the
+     * orchestrator. Returns the orchestrator's response (or an error response).
+     *
+     * Optional so backends / harnesses that don't thread the cache through keep
+     * working — the runner falls back to a "not configured" cache response.
+     */
+    onCacheRequest?: (request: CacheRequestIpc) => Promise<CacheResponseIpc>;
+    /**
+     * Callback for relaying a step-level approval request from the sandbox to the
+     * orchestrator. The sandbox runner sends `approval.request` IPC; the agent
+     * wraps it in a `step.approval-request` WS message and forwards to the
+     * orchestrator, awaiting the `step.approval-resolved` response which it pipes
+     * back as `approval.resolved`. Optional so harnesses that don't thread
+     * approvals keep working — the runner falls back to a fail-closed reject.
+     */
+    onApprovalRequest?: (request: StepApprovalRequestIpc) => Promise<StepApprovalResolvedIpc>;
     /**
      * Callback fired once per `ctx.secrets.mountFile` / `exposeFile` call the
      * workflow runner performs. Carries only key names + the resulting path /