@kici-dev/agent 0.1.27 → 0.3.0

package/dist/execution/artifacts/artifact-engine.d.ts

@@ -0,0 +1,51 @@
+import type { ArtifactsApi } from '@kici-dev/sdk';
+import type { ArtifactRejectReason, ArtifactUploadOutcome, ArtifactDownloadOutcome } from '@kici-dev/engine';
+import { type CacheRoots } from '../cache/cache-engine.js';
+/** Outcome of a begin-upload grant request. */
+export interface ArtifactBeginUploadResult {
+    outcome: ArtifactUploadOutcome;
+    /** Presigned PUT URL — present only on `granted`. */
+    uploadUrl?: string;
+    /** Storage key echoed back on complete — present only on `granted`. */
+    storageKey?: string;
+    /** Enforcement-gate rejection reason — present only on an enforcement `rejected`. */
+    reason?: ArtifactRejectReason;
+    /**
+     * Non-enforcement refusal detail — present only on `rejected` when no
+     * enforcement `reason` applies (a name that violates the artifact-name
+     * contract, orchestrator misconfiguration, or an internal error). A safe,
+     * fixed string from the orchestrator; never a raw exception.
+     */
+    error?: string;
+}
+/** Outcome of a download lookup. */
+export interface ArtifactDownloadLookup {
+    outcome: ArtifactDownloadOutcome;
+    /** Presigned GET URL — present only on `found`. */
+    downloadUrl?: string;
+    /** Artifact size in bytes — present only on `found`. */
+    sizeBytes?: number;
+    /** SHA-256 (hex) of the tarball bytes — present only on `found`. */
+    sha256?: string;
+    /**
+     * Internal-failure detail — present only on `not_found` when the outcome
+     * reflects an orchestrator failure rather than a genuinely missing artifact. A
+     * safe, fixed string from the orchestrator; never a raw exception.
+     */
+    error?: string;
+}
+/**
+ * Transport the artifacts engine uses to reach the orchestrator over IPC -> WS.
+ * Backed by the agent's request/response relay (mirrors {@link CacheTransport}).
+ */
+export interface ArtifactTransport {
+    /** Request a presigned PUT for `name` at `declaredSizeBytes`; enforced before minting. */
+    beginUpload(name: string, declaredSizeBytes: number): Promise<ArtifactBeginUploadResult>;
+    /** Confirm the upload finished — records the DB row. */
+    completeUpload(name: string, sizeBytes: number, sha256: string, storageKey: string): Promise<void>;
+    /** Resolve a named artifact of this run to a presigned GET + its size/sha256. */
+    download(name: string): Promise<ArtifactDownloadLookup>;
+}
+/** Build the imperative `ctx.artifacts` API bound to a workDir + transport. */
+export declare function createArtifactsApi(workDir: string, transport: ArtifactTransport, roots?: CacheRoots): ArtifactsApi;
+//# sourceMappingURL=artifact-engine.d.ts.map

package/dist/execution/dep-installer.d.ts

@@ -41,9 +41,9 @@ export interface InstallDepsOptions {
  * Install `.kici/` dependencies inline with the repo's package manager.
  *
  * Falls back to this when the dep cache is unavailable or a download fails.
- * The install runs with an isolated cache/store directory (created in
- * `os.tmpdir()`) to prevent cache poisoning between build jobs; the directory
- * is removed after installation.
+ * The install runs with an isolated cache/store directory (allocated under the
+ * global temp base, which honors `KICI_TMPDIR`) to prevent cache poisoning
+ * between build jobs; the directory is removed after installation.
  *
  * If `opts.npmRegistries` / `opts.installEnvSecrets` is provided, a job-scoped
  * `.kici/.npmrc` overlay is synthesized for the install, restored in `finally`,

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

@@ -1,15 +1,13 @@
 import type { AgentToOrchestratorMessage, JobDispatch } from '@kici-dev/engine';
 import type { AppConfig } from '../config.js';
 import { buildNeedsContext } from '@kici-dev/sdk';
-import type { CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './sandbox/index.js';
+import type { CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, ArtifactRequestIpc, ArtifactResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './sandbox/index.js';
 /**
  * Dependencies injected into JobRunner.
  */
 export interface JobRunnerDeps {
-    /** Send function for WS messages (buffered) */
+    /** Send function for WS messages (buffered; replayed on reconnect) */
     send: (msg: AgentToOrchestratorMessage) => void;
-    /** Send direct function (bypasses buffer, for protocol messages) */
-    sendDirect: (msg: AgentToOrchestratorMessage) => void;
     /** Agent config */
     config: AppConfig;
     /** Request a pre-signed S3 upload URL from the orchestrator via WS request-response. */
@@ -99,6 +97,14 @@ export interface JobRunnerDeps {
      * compatibility (callers that don't support provenance).
      */
     relayProvenance?: (jobId: string, request: ProvenanceRequestIpc) => Promise<ProvenanceResponseIpc>;
+    /**
+     * Relay a user-facing artifact request to the orchestrator and await the
+     * response. Translates the sandbox `artifacts.request` IPC into the matching
+     * `artifacts.upload.request` / `.complete` / `artifacts.download.request` WS
+     * message and returns the orchestrator's response mapped back onto the IPC
+     * response shape. Optional for backward compatibility.
+     */
+    requestUserArtifact?: (jobId: string, request: ArtifactRequestIpc) => Promise<ArtifactResponseIpc>;
     /**
      * Relay a step-level approval request to the orchestrator and await the
      * resolution. Translates the sandbox `approval.request` IPC into a
@@ -113,6 +119,17 @@ interface ActiveJob {
     completionPromise: Promise<void>;
     runId: string;
 }
+/**
+ * Derive the self-contained runner bundle path from the resolved runner path.
+ *
+ * The container backend mounts the runner as a single file into the customer
+ * job container, so it must run `workflow-runner-bundle.js` (zx + `@kici-dev/*`
+ * inlined) rather than the external `workflow-runner.js`, which cannot resolve
+ * its bare imports without the agent's node_modules / pnpm workspace. The
+ * bundle is a flat sibling emitted alongside the runner by build-service.mjs.
+ * bwrap / firecracker keep the external runner (they bind the workspace).
+ */
+export declare function resolveRunnerBundlePath(runnerPath: string): string;
 /**
  * Build the result-aware `ctx.needs` for a dynamic eval from its frozen upstream
  * snapshot. Returns undefined for an event-only generator (no snapshot).
@@ -155,7 +172,6 @@ export declare function resolveJobWorkDir(inPlace: boolean, repoUrl: string | un
  */
 export declare class JobRunner {
     private readonly send;
-    private readonly sendDirect;
     private readonly config;
     private readonly requestUploadUrl;
     private readonly sendUploadComplete;
@@ -168,6 +184,7 @@ export declare class JobRunner {
     private readonly _sendApiRequest?;
     private readonly _requestUserCache?;
     private readonly _relayProvenance?;
+    private readonly _requestUserArtifact?;
     private readonly _sendStepApproval?;
     /** Tracks running jobs for concurrency and cancellation */
     readonly activeJobs: Map<string, ActiveJob>;
@@ -222,7 +239,8 @@ export declare class JobRunner {
     /**
      * Drive `sandbox.executeJob` with IPC callbacks wired to the WS pipeline.
      *
-     * Lazily creates per-step LogStreamers, forwards step + log + event-emit +
+     * Lazily populates `logStreamers` (owned by the caller so a throw still
+     * leaves the buffered output flushable), forwards step + log + event-emit +
      * concurrency-report + api-request messages, and emits the
      * `agent.execution.start` / `agent.execution.end` lifecycle events.
      */

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

@@ -1,4 +1,4 @@
-import type { AgentLogChunk } from '@kici-dev/engine';
+import { LogStream, type AgentLogChunk } from '@kici-dev/engine';
 interface LogStreamerOptions {
     /** Callback to send log.chunk messages */
     send: (msg: AgentLogChunk) => void;
@@ -47,6 +47,8 @@ export declare class LogStreamer {
     private flushTimer;
     private totalBytes;
     private truncated;
+    /** Which stream the currently-buffered lines came from. */
+    private bufferStream;
     /** Number of lines dropped due to backpressure (drop mode). */
     private droppedCount;
     /** Whether we are currently in a backpressured state (pause mode). */
@@ -73,8 +75,21 @@ export declare class LogStreamer {
     /**
      * Add a line to the buffer. Triggers flush if threshold reached,
      * otherwise schedules a timer-based flush.
+     *
+     * A chunk carries a single stream, so a kind flip closes the pending chunk
+     * before the new line is buffered. Chunks are delivered in order, so the
+     * stdout/stderr interleaving is preserved across that boundary.
+     *
+     * `bufferStream` is only advanced once the buffer is actually empty. Under
+     * pause-mode backpressure `flush()` deliberately leaves the buffer intact
+     * until the socket drains, so the flip cannot close the pending chunk;
+     * advancing the tag there would relabel the already-buffered lines as the
+     * newly-arrived stream. The buffer keeps the tag of its first lines instead,
+     * which means a chunk assembled while backpressured reports one stream for
+     * lines that came from both — stderr in such a chunk is under-reported as
+     * stdout. Separating them needs a queue of pending per-stream chunks.
      */
-    addLine(line: string): void;
+    addLine(line: string, stream?: LogStream): void;
     /**
      * Flush buffered lines as a log.chunk message.
      * No-op if buffer is empty.

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

@@ -1,13 +1,2 @@
-import type { RuleContext, FanoutPosition } from '@kici-dev/sdk';
-/**
- * Create RuleContext for agent-side rule evaluation.
- *
- * @param event - Event payload from the dispatch message
- * @param changedFiles - List of files changed in this event
- * @param env - Merged environment variables
- * @param dispatchInputs - Operator dispatch inputs (`ctx.dispatchInputs`)
- * @param fanout - Fan-out position (`ctx.fanout`); undefined on a non-fan-out job
- */
-export declare function createRuleContext(event: Record<string, unknown>, changedFiles?: string[], env?: Record<string, string | undefined>, dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>, fanout?: FanoutPosition): RuleContext;
-export { evaluateRules, type RuleEvaluationResult } from '@kici-dev/sdk';
+export { createRuleContext, ChangedFilesUnavailableError, evaluateRules, type RuleEvaluationResult, } from '@kici-dev/sdk';
 //# sourceMappingURL=rule-evaluator.d.ts.map

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

@@ -0,0 +1,80 @@
+/**
+ * Container sandbox hardening posture builder.
+ *
+ * A pure function that produces the dockerode `HostConfig` fragment (plus an
+ * optional top-level `User`) applied to every per-job container sandbox. It
+ * brings the container backend to parity with the bare-metal bwrap sandbox
+ * (`fork-runner.ts`) — which runs rootless, with a read-only system tree,
+ * private dev/proc/tmp, and namespace isolation — and exceeds it with cgroup
+ * resource caps that bwrap (a namespace tool, not a cgroup tool) cannot set.
+ *
+ * The default posture ("hardened"):
+ * - `CapDrop: ['ALL']` — drop every Linux capability (no default add-back).
+ * - `SecurityOpt: ['no-new-privileges']` — a step can never gain privileges via
+ *   setuid binaries, matching bwrap's `--new-session` lifecycle posture.
+ * - `PidsLimit` / `Memory` / `NanoCpus` — cgroup caps bounding fork-bomb, memory
+ *   and CPU DoS against the host.
+ * - `Tmpfs: { '/tmp': '' }` — a private, non-persistent /tmp (mirrors bwrap's
+ *   `--tmpfs /tmp`).
+ * - `User` — honored as configured on the image; an explicit override sets it,
+ *   but a root image is never silently rewritten (parity is best-effort here:
+ *   bwrap runs as the unprivileged invoker uid by construction).
+ * - `ReadonlyRootfs` — OPT-IN only (many images write outside /workspace: npm
+ *   cache, /home, tool state), enabled via the resolved `readonlyRootfs` input.
+ * - `NetworkMode` — `none` for the isolated network posture (bwrap's
+ *   `--unshare-net`); the default (bridge) otherwise.
+ *
+ * The `grant` input is the dispatch-resolved per-job escape hatch (allow-listed
+ * orchestrator-side). It is honored strictly additively on top of the hardened
+ * baseline: requested capabilities become `CapAdd` entries while `CapDrop:
+ * ['ALL']` still applies, and a grant may switch the network to `host` or set
+ * an explicit user / read-only rootfs. The builder never reads an allow-list —
+ * it applies whatever grant dispatch already resolved (single enforcement
+ * point). When `hardened` is false (the documented-temporary
+ * `KICI_SANDBOX_HARDENED` rollback affordance), the builder emits an empty
+ * posture, reproducing the unhardened container behavior.
+ */
+import type Docker from 'dockerode';
+import type { ResolvedSandboxGrant, SandboxNetworkMode } from '@kici-dev/engine';
+export type { ResolvedSandboxGrant, SandboxNetworkMode };
+/** Inputs to the hardening builder, already resolved from agent config + dispatch. */
+export interface SandboxHardeningOptions {
+    /**
+     * Master switch. When false (the `KICI_SANDBOX_HARDENED=false` rollback
+     * affordance) the builder emits an empty posture — the legacy unhardened
+     * container behavior. Defaults are ON in the shipping config.
+     */
+    hardened: boolean;
+    /** Opt-in read-only rootfs (config `KICI_SANDBOX_READONLY_ROOTFS`). */
+    readonlyRootfs: boolean;
+    /** Explicit user override (config `KICI_SANDBOX_USER`); honors the image user when unset. */
+    user?: string;
+    /** Max PIDs in the container cgroup. */
+    pidsLimit: number;
+    /** Memory cap in bytes for the container cgroup. */
+    memoryBytes: number;
+    /** CPU cap in nano-CPUs (1 CPU = 1_000_000_000). */
+    nanoCpus: number;
+    /** Config-derived network posture (`isolated` → `none`, else `default`). */
+    networkMode: SandboxNetworkMode;
+    /** Optional dispatch-resolved escape hatch (Sub-wish B populates this at dispatch). */
+    grant?: ResolvedSandboxGrant;
+}
+/** The builder output: a HostConfig fragment merged into createContainer, plus an optional top-level User. */
+export interface ContainerHardening {
+    hostConfig: Partial<Docker.HostConfig>;
+    user?: string;
+}
+/** Default cgroup caps — operator-visible constants, overridable via scaler `resources`. */
+export declare const DEFAULT_PIDS_LIMIT = 512;
+export declare const DEFAULT_MEMORY_BYTES: number;
+export declare const DEFAULT_NANO_CPUS: number;
+/**
+ * Build the hardened HostConfig fragment for a job sandbox container.
+ *
+ * Pure and side-effect-free: given resolved inputs it returns the fields the
+ * container-sandbox merges into `docker.createContainer`. When `hardened` is
+ * false it returns an empty posture (the rollback affordance).
+ */
+export declare function buildContainerHardening(opts: SandboxHardeningOptions): ContainerHardening;
+//# sourceMappingURL=container-hardening.d.ts.map

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

@@ -17,6 +17,7 @@
  */
 import Docker from 'dockerode';
 import type { ExecutionSandbox, SandboxSetupOptions, JobExecutionOptions, JobExecutionResult } from './types.js';
+import { type SandboxHardeningOptions } from './container-hardening.js';
 interface ContainerSandboxOptions {
     /** Dockerode instance (from orchestrator/scaler or created locally). */
     docker: Docker;
@@ -26,21 +27,39 @@ interface ContainerSandboxOptions {
     runnerPath: string;
     /** Mount target inside container (default: /opt/kici/workflow-runner.js). */
     runnerMountPath?: string;
+    /**
+     * Path to the pure-JS container loader-hook bundle on the HOST (bind-mounted
+     * read-only). Defaults to `container-ts-loader-hook.js` next to `runnerPath`.
+     */
+    hookPath?: 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;
+    /**
+     * Resolved hardening posture for the job container (cap-drop, no-new-privileges,
+     * cgroup caps, tmpfs, user, network). When omitted, no hardening is applied —
+     * the production caller (job-runner) always supplies this from agent config so
+     * the secure-by-default posture is in force; leaving it optional keeps the
+     * constructor testable and lets non-production callers opt out explicitly.
+     */
+    hardening?: SandboxHardeningOptions;
 }
 export declare class ContainerSandbox implements ExecutionSandbox {
     private readonly docker;
     private readonly image;
     private readonly runnerPath;
     private readonly runnerMountPath;
+    /** Host path to the pure-JS container loader-hook bundle (bind-mounted :ro). */
+    private readonly hookHostPath;
     private readonly env;
     private readonly keepFailed;
     private readonly jobId;
+    private readonly hardening?;
+    /** Resolved container user (image-user override / grant), applied to createContainer + each exec. */
+    private resolvedUser?;
     /** The running container instance (set during setup). */
     private container;
     /** The active exec stream (set during executeJob, used for abort). */
@@ -50,7 +69,42 @@ export declare class ContainerSandbox implements ExecutionSandbox {
     /** Container name for logging/debugging. */
     private containerName;
     constructor(options: ContainerSandboxOptions);
+    /**
+     * Ensure the job's container image is present locally, pulling it on demand
+     * when it is not.
+     *
+     * dockerode's `createContainer` — unlike `docker run` / `podman run` — never
+     * auto-pulls a missing image; it fails with `(HTTP code 404) ... No such
+     * image`. A bare-metal executor that aggressively prunes unused images under
+     * disk pressure can leave a container job with nothing to run, so the agent
+     * pulls the image itself. Already-present images (the common case, and how
+     * private images pre-pulled with registry auth stay working) skip the pull.
+     */
+    private ensureImagePresent;
     setup(options: SandboxSetupOptions): Promise<void>;
+    /**
+     * Build the container's read-only bind list.
+     *
+     * The workspace is NOT bound here — it is a container-owned anonymous volume
+     * (`Volumes: { '/workspace': {} }` on the container config), so the container
+     * user can write it on every runtime with `CapDrop: ['ALL']` intact. This
+     * method binds the workflow runner (read-only) plus two parity affordances
+     * that mirror the bare-metal bwrap sandbox — both strictly additive and gated,
+     * so the default posture for a production (https-source, bridge-network) job is
+     * unchanged:
+     *
+     * - **`file://` clone-source dir(s)** (`options.extraReadOnlyBinds`): the
+     *   workflow runner clones the repo from inside the container, so a local
+     *   `file://` source dir must be exposed read-only or `git clone` fails.
+     *   Empty for https/ssh remotes — mirrors fork-runner's `extraReadOnlyBinds`.
+     * - **Host name-resolution files under host networking**: when the effective
+     *   network posture is `host` (`KICI_SANDBOX_NETWORK=host`, or a per-job host
+     *   grant), bind the host's `/etc/hosts` (+ `/etc/nsswitch.conf`) read-only so
+     *   an `/etc/hosts`-only name the host resolves — e.g. a private registry —
+     *   resolves inside the container too. Mirrors fork-runner's
+     *   `--ro-bind /etc/hosts` for the bwrap host-network mode.
+     */
+    private buildBinds;
     executeJob(options: JobExecutionOptions): Promise<JobExecutionResult>;
     /**
      * Phase 1 of executeJob: create the docker exec, start it in hijack mode,

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

@@ -0,0 +1,26 @@
+type ResolveContext = {
+    parentURL?: string;
+    conditions: string[];
+    importAttributes: Record<string, string>;
+};
+type ResolveResult = {
+    url: string;
+    shortCircuit?: boolean;
+    format?: string | null;
+};
+type NextResolve = (specifier: string, context?: ResolveContext) => ResolveResult | Promise<ResolveResult>;
+type LoadContext = {
+    format?: string | null;
+    importAttributes: Record<string, string>;
+    conditions: string[];
+};
+type LoadResult = {
+    format: string;
+    source?: string | ArrayBuffer | Uint8Array;
+    shortCircuit?: boolean;
+};
+type NextLoad = (url: string, context?: LoadContext) => LoadResult | Promise<LoadResult>;
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): ResolveResult | Promise<ResolveResult>;
+export declare function load(url: string, context: LoadContext, nextLoad: NextLoad): Promise<LoadResult>;
+export {};
+//# sourceMappingURL=container-ts-loader-hook.d.ts.map

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

@@ -83,6 +83,20 @@ export declare function buildRequest(dispatch: JobDispatch, workDir: string): Jo
  * is simpler and more secure than selective blocking.
  */
 export declare function buildBwrapArgs(workDir: string, nodeExecPath: string, networkIsolation?: boolean, runnerPath?: string, extraReadOnlyBinds?: string[]): string[];
+/**
+ * Derive the read-only bind path(s) for a `file://` clone source. The workflow
+ * runner clones the repo from inside the sandbox, so a local `file://` URL's
+ * source directory must be exposed read-only or `git clone` fails with
+ * `does not appear to be a git repository`. Returns `[]` for non-`file://`
+ * remotes (https/ssh need no host bind) and for a malformed `file://` URL (the
+ * clone then surfaces the real error rather than being masked here).
+ *
+ * Shared by both sandboxes that clone a local source: the bare-metal (bwrap)
+ * backend threads the result into `buildBwrapArgs`'s `extraReadOnlyBinds`, and
+ * the container backend binds each `<dir>:<dir>:ro` into the job container —
+ * the same clone-source affordance across both isolation models.
+ */
+export declare function fileCloneSourceBinds(repoUrl: string | undefined): string[];
 /**
  * Spawn the workflow runner as a child process with IPC channel.
  *

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

@@ -5,10 +5,11 @@
  *   import { BareMetalSandbox, ContainerSandbox, buildSanitizedEnv } from './sandbox/index.js';
  */
 export type { ExecutionSandbox, SandboxSetupOptions, JobExecutionOptions, JobExecutionResult, SandboxStepResult, } from './types.js';
-export type { RunnerToAgentMessage, AgentToRunnerMessage, EventEmitRequest, EventEmitResponse, CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc, JobExecutionRequest, } from './ipc-protocol.js';
+export type { RunnerToAgentMessage, AgentToRunnerMessage, EventEmitRequest, EventEmitResponse, CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, ArtifactRequestIpc, ArtifactResponseIpc, 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';
 export { FirecrackerSandbox } from './firecracker-sandbox.js';
 export { ContainerSandbox } from './container-sandbox.js';
+export { fileCloneSourceBinds } from './fork-runner.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,4 +1,4 @@
-import type { CheckMode, CheckStepOutcome } from '@kici-dev/engine';
+import type { CheckMode, CheckStepOutcome, LogStream } from '@kici-dev/engine';
 import type { SandboxStepResult } from './types.js';
 /**
  * Structured clone auth. Wire-compatible with `gitAuthSchema` on the
@@ -78,6 +78,8 @@ interface LogLineMessage {
     type: 'log.line';
     stepIndex: number;
     line: string;
+    /** Which subprocess stream the line came from. Absent means stdout. */
+    stream?: LogStream;
 }
 /**
  * Discriminator for {@link StepSecretMountMessage} -- distinguishes a bare
@@ -248,7 +250,32 @@ export interface ProvenanceRequestIpc {
     /** Ephemeral public key JWK the envelope was signed with. `defer` only. */
     publicKey?: unknown;
 }
-export type RunnerToAgentMessage = ReadyMessage | StepStartMessage | StepCompleteMessage | LogLineMessage | StepSecretMountMessage | JobCompleteMessage | EventEmitRequest | ConcurrencyReportMessage | AgentApiRequestIpc | CacheRequestIpc | ProvenanceRequestIpc | StepApprovalRequestIpc;
+/** Which artifact operation to relay. */
+export type ArtifactRequestOp = 'beginUpload' | 'completeUpload' | 'download';
+/**
+ * Request a user-facing artifact operation (runner -> agent). The agent relays
+ * it over the WS as an `artifacts.upload.request` / `.complete` /
+ * `artifacts.download.request` and pipes the response back as an
+ * {@link ArtifactResponseIpc}. Mirrors the {@link CacheRequestIpc} relay pattern.
+ */
+export interface ArtifactRequestIpc {
+    type: 'artifacts.request';
+    /** UUID for correlating the response. */
+    requestId: string;
+    /** Which artifact operation to perform. */
+    op: ArtifactRequestOp;
+    /** Artifact name (all ops). */
+    name: string;
+    /** Packed tarball size in bytes — drives the enforcement gates. `beginUpload` only. */
+    declaredSizeBytes?: number;
+    /** Confirmed tarball size in bytes. `completeUpload` only. */
+    sizeBytes?: number;
+    /** SHA-256 of the tarball bytes. `completeUpload` only. */
+    sha256?: string;
+    /** Storage key echoed from the grant response. `completeUpload` only. */
+    storageKey?: string;
+}
+export type RunnerToAgentMessage = ReadyMessage | StepStartMessage | StepCompleteMessage | LogLineMessage | StepSecretMountMessage | JobCompleteMessage | EventEmitRequest | ConcurrencyReportMessage | AgentApiRequestIpc | CacheRequestIpc | ProvenanceRequestIpc | ArtifactRequestIpc | StepApprovalRequestIpc;
 /** Instruct the workflow runner to execute a job. */
 interface ExecuteMessage {
     type: 'execute';
@@ -353,7 +380,50 @@ export interface ProvenanceResponseIpc {
     /** Error description (present when the relay or orchestrator failed). */
     error?: string;
 }
-export type AgentToRunnerMessage = ExecuteMessage | AbortMessage | EventEmitResponse | ConcurrencyAckMessage | AgentApiResponseIpc | CacheResponseIpc | ProvenanceResponseIpc | StepApprovalResolvedIpc;
+/**
+ * Response to an {@link ArtifactRequestIpc} (agent -> runner). Relayed from the
+ * orchestrator's `artifacts.upload.response` / `artifacts.download.response` WS
+ * message. Carries the union of the upload-grant (`uploadOutcome` / `uploadUrl`
+ * / `storageKey` / `reason`) and download-lookup (`downloadOutcome` /
+ * `downloadUrl` / `sizeBytes` / `sha256`) fields; `completeUpload` resolves with
+ * an empty (no-field) response. `error` is set when the relay itself failed;
+ * `rejectionDetail` carries an orchestrator-side non-enforcement explanation
+ * that the workflow-facing render surfaces without throwing a relay error.
+ */
+export interface ArtifactResponseIpc {
+    type: 'artifacts.response';
+    /** Matches the original request's requestId. */
+    requestId: string;
+    /** beginUpload: `granted` (presigned PUT minted) or `rejected` (named reason). */
+    uploadOutcome?: 'granted' | 'rejected';
+    /** beginUpload: presigned PUT URL (present only on `granted`). */
+    uploadUrl?: string;
+    /** beginUpload: storage key to echo back on complete (present only on `granted`). */
+    storageKey?: string;
+    /** beginUpload: enforcement-gate refusal reason (present only on `rejected`). */
+    reason?: 'duplicate_name' | 'size_cap' | 'run_cap' | 'org_quota';
+    /**
+     * Orchestrator non-enforcement refusal detail — set when a `rejected` upload
+     * or a `not_found` download reflects a name that violates the artifact-name
+     * contract, or an orchestrator problem (artifacts not configured, unresolvable
+     * run, internal error), rather than an enforcement gate or a genuinely missing
+     * artifact. Distinct from `error` below, which is a relay/transport failure
+     * the sandbox turns into a thrown error: this field flows into the normal
+     * rejection render instead.
+     */
+    rejectionDetail?: string;
+    /** download: `found` (presigned GET minted) or `not_found`. */
+    downloadOutcome?: 'found' | 'not_found';
+    /** download: presigned GET URL (present only on `found`). */
+    downloadUrl?: string;
+    /** download: artifact size in bytes (present only on `found`). */
+    sizeBytes?: number;
+    /** download: SHA-256 of the tarball bytes (present only on `found`). */
+    sha256?: string;
+    /** Error description (present when the relay or orchestrator failed). */
+    error?: string;
+}
+export type AgentToRunnerMessage = ExecuteMessage | AbortMessage | EventEmitResponse | ConcurrencyAckMessage | AgentApiResponseIpc | CacheResponseIpc | ProvenanceResponseIpc | ArtifactResponseIpc | StepApprovalResolvedIpc;
 /**
  * All data the workflow runner needs to execute a job inside the sandbox.
  *
@@ -528,6 +598,12 @@ export interface JobExecutionRequest {
     hasConcurrencyGroup?: boolean;
     /** Concurrency group evaluation timeout in milliseconds (default: 30000). */
     concurrencyEvaluationTimeoutMs?: number;
+    /**
+     * Orchestrator-resolved concurrency-slot wait timeout (ms), pushed on
+     * `job.dispatch` from the fleet-wide `cluster_settings.concurrency_wait_timeout_ms`.
+     * Absent for older orchestrators — the runner falls back to its own default.
+     */
+    concurrencyWaitTimeoutMs?: 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(). */

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

@@ -208,6 +208,10 @@ interface StepLoopResult {
     stepResults: SandboxStepResult[];
     failureReason?: string;
 }
+/** Most lines of a failing step's error message that reach the run log. */
+export declare const STEP_FAILURE_LOG_MAX_LINES = 100;
+/** Most characters of a failing step's error message that reach the run log. */
+export declare const STEP_FAILURE_LOG_MAX_CHARS = 8192;
 /**
  * Per-step iteration outcome returned by `runStepIteration`.
  */

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

@@ -1,5 +1,5 @@
-import type { JobDispatch } from '@kici-dev/engine';
-import type { EventEmitRequest, EventEmitResponse, ConcurrencyReportMessage, ConcurrencyAckMessage, CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './ipc-protocol.js';
+import type { JobDispatch, LogStream } from '@kici-dev/engine';
+import type { EventEmitRequest, EventEmitResponse, ConcurrencyReportMessage, ConcurrencyAckMessage, CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, ArtifactRequestIpc, ArtifactResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './ipc-protocol.js';
 /**
  * Common interface for all execution sandbox backends.
  *
@@ -50,6 +50,15 @@ export interface SandboxSetupOptions {
     workDir: string;
     /** Sanitized environment variables (user env + secrets, NO agent credentials). */
     env: Record<string, string>;
+    /**
+     * Extra read-only host paths to expose in the sandbox beyond the workspace +
+     * runner — the `file://` clone-source dir(s) so the in-sandbox `git clone`
+     * can read a local source. Derived from the dispatch `repoUrl` by the
+     * job-runner (empty for https/ssh remotes). The container backend binds each
+     * as `<dir>:<dir>:ro`; the bare-metal backend derives its own equivalent
+     * inside `executeJob`, so it ignores this field.
+     */
+    extraReadOnlyBinds?: string[];
 }
 /** Options for executing a job inside the sandbox. */
 export interface JobExecutionOptions {
@@ -57,8 +66,11 @@ export interface JobExecutionOptions {
     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;
+    /**
+     * Callback for real-time log line forwarding. `stream` names the subprocess
+     * stream the line came from; absent means stdout.
+     */
+    onLogLine: (stepIndex: number, line: string, stream?: LogStream) => void;
     /** Abort signal for cancellation. */
     signal: AbortSignal;
     /**
@@ -97,6 +109,15 @@ export interface JobExecutionOptions {
      * working — the runner falls back to a "not configured" error response.
      */
     onProvenanceRequest?: (request: ProvenanceRequestIpc) => Promise<ProvenanceResponseIpc>;
+    /**
+     * Callback for relaying a user-facing artifact request from the sandbox to the
+     * orchestrator. The sandbox runner sends `artifacts.request` IPC; the agent
+     * wraps it in the matching `artifacts.upload.*` / `artifacts.download.*` WS
+     * message and forwards to the orchestrator. Optional so harnesses that don't
+     * thread artifacts keep working — the runner falls back to a "not configured"
+     * error response.
+     */
+    onArtifactRequest?: (request: ArtifactRequestIpc) => Promise<ArtifactResponseIpc>;
     /**
      * Callback for relaying a step-level approval request from the sandbox to the
      * orchestrator. The sandbox runner sends `approval.request` IPC; the agent