@kici-dev/agent 0.1.21 → 0.1.23

package/dist/workflow-runner.js

@@ -8,9 +8,9 @@ import path, { dirname, isAbsolute, join, relative, resolve, sep } from "node:pa
 import { $ } from "zx";
 import { createLogger, deriveSharedSecret, initZx, normalizeLineEndings, sha256, sha256File, toErrorMessage } from "@kici-dev/shared";
 import { CacheOutcome, CacheStepType, CheckMode, CheckStepOutcome, ExecutionJobStatus, ExecutionStepStatus, TimeoutReason } from "@kici-dev/engine";
-import { buildKiciApi, createStepSecrets, evaluateRules, isDynamicJobFn, normalizeCacheSpecs, normalizeRequireApproval, provenanceSubjectIsPath, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
+import { buildKiciApi, buildNeedsContext, createStepSecrets, evaluateRules, isDynamicJobFn, normalizeApproval, normalizeCacheSpecs, provenanceSubjectIsPath, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
 import { OIDC_TOKEN_REQUEST_METHOD } from "@kici-dev/engine/protocol/messages/oidc-token-relay";
-import { sha256File as sha256File$1 } from "@kici-dev/core";
+import { computeBackoffDelay, sha256File as sha256File$1 } from "@kici-dev/core";
 import { calculateJwkThumbprint, decodeJwt, exportJWK, generateKeyPair } from "jose";
 import { IN_TOTO_PAYLOAD_TYPE, KICI_PROVENANCE_AUDIENCE, KICI_PROVENANCE_BUNDLE_MEDIA_TYPE } from "@kici-dev/engine/provenance/bundle";
 import { IN_TOTO_STATEMENT_TYPE, KICI_WORKFLOW_BUILD_TYPE, SLSA_PROVENANCE_PREDICATE_TYPE } from "@kici-dev/engine/provenance/schema";
@@ -1106,17 +1106,28 @@ initZx();
 * @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
 */
-function createRuleContext(event, changedFiles = [], env = {}) {
+function createRuleContext(event, changedFiles = [], env = {}, dispatchInputs = {}, fanout) {
 	return {
 		event,
 		changedFiles,
 		env,
+		dispatchInputs,
+		...fanout && { fanout },
 		$
 	};
 }
 //#endregion
 //#region src/execution/sandbox/step-loop.ts
+/** Result of a rejected drift gate: the run was declined by a reviewer. */
+var DriftGateRejectedError = class extends Error {
+	constructor(reason) {
+		super(reason ? `approval rejected: ${reason}` : "approval rejected");
+		this.name = "DriftGateRejectedError";
+	}
+};
 /**
 * Run one step honoring the run-level {@link CheckMode}, reusing the
 * `runIdempotentStep` primitive for checked steps (never hand-rolled branching).
@@ -1124,10 +1135,13 @@ function createRuleContext(event, changedFiles = [], env = {}) {
 * - Plain step (no `check`): in apply mode, runs as today; in any check mode it
 *   is skipped with `no_check` (a side-effecting step can't be safely previewed).
 * - Checked step: adapted into an `IdempotentStep` and driven by the primitive
-*   with `dryRun` set in check mode (so `apply`/`run` never fires) and `yes: true`
-*   (v0 has no mid-run confirm). On drift the summary is emitted as a log line.
+*   with `dryRun` set in check mode (so `apply`/`run` never fires). On drift the
+*   summary is emitted as a log line. A `approval: { when: 'drift' }` step in
+*   apply mode passes a `confirm` callback that round-trips a payload-bearing
+*   step-approval; on reject the gate throws (fail-stop). Any other apply-mode
+*   step uses `yes: true`.
 */
-async function runStepWithCheckMode(step, stepIndex, ctx, checkMode, sendFn) {
+async function runStepWithCheckMode(step, stepIndex, ctx, checkMode, sendFn, opts) {
 	if (!step.check) {
 		if (checkMode !== CheckMode.enum.apply) return {
 			checkOutcome: CheckStepOutcome.enum.no_check,
@@ -1139,15 +1153,37 @@ async function runStepWithCheckMode(step, stepIndex, ctx, checkMode, sendFn) {
 			outputs: await step.run(ctx)
 		};
 	}
-	const res = await runIdempotentStep({
+	let lastDrift = null;
+	const adapted = {
 		name: step.name,
-		check: () => step.check(ctx),
+		check: async () => {
+			lastDrift = await step.check(ctx);
+			return lastDrift;
+		},
 		summarize: step.summarize,
 		apply: (drift) => step.run(ctx, drift),
 		whenInSync: step.whenInSync ? () => step.whenInSync(ctx) : void 0
-	}, {
+	};
+	const driftGate = step.approval !== void 0 && normalizeApproval(step.approval).when === "drift" && checkMode === CheckMode.enum.apply && opts.awaitStepApprovalWithPayload !== void 0;
+	const res = await runIdempotentStep(adapted, {
 		dryRun: checkMode !== CheckMode.enum.apply,
-		yes: true,
+		...driftGate ? { confirm: async () => {
+			const norm = normalizeApproval(step.approval);
+			const summaryMarkdown = step.summarize(lastDrift);
+			const resolution = await opts.awaitStepApprovalWithPayload({
+				stepIndex,
+				stepName: step.name,
+				clauses: norm.clauses,
+				reason: norm.reason ?? `Approval required for drift in '${step.name}'`,
+				...norm.timeoutSeconds !== void 0 && { timeoutSeconds: norm.timeoutSeconds },
+				payload: {
+					summaryMarkdown,
+					drift: lastDrift
+				}
+			});
+			if (resolution.outcome === "approved") return true;
+			throw new DriftGateRejectedError(resolution.outcome === "expired" ? "approval expired" : resolution.reason);
+		} } : { yes: true },
 		log: (line) => sendFn({
 			type: "log.line",
 			stepIndex,
@@ -1170,7 +1206,7 @@ async function runStepWithCheckMode(step, stepIndex, ctx, checkMode, sendFn) {
 *
 * Timeout pattern using Promise.race + AbortController, with IPC status reporting.
 */
-async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, outputsMap, getSecretsAccessLog, getSecretMountRecords, jobDeadlineSignal, checkMode = CheckMode.enum.apply) {
+async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, outputsMap, getSecretsAccessLog, getSecretMountRecords, jobDeadlineSignal, checkMode, opts) {
 	sendFn({
 		type: "step.start",
 		stepIndex,
@@ -1181,7 +1217,7 @@ async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, output
 	const timeoutId = setTimeout(() => abortController.abort(), timeoutMs);
 	try {
 		const phase = await Promise.race([
-			runStepWithCheckMode(step, stepIndex, ctx, checkMode, sendFn),
+			runStepWithCheckMode(step, stepIndex, ctx, checkMode, sendFn, opts),
 			new Promise((_, reject) => {
 				abortController.signal.addEventListener("abort", () => {
 					reject(/* @__PURE__ */ new Error(`Step '${step.name}' timed out after ${timeoutMs}ms`));
@@ -1284,7 +1320,7 @@ function extractSignal(error) {
 */
 async function evaluateStepRulesAndMaybeSkip(step, stepIndex, opts) {
 	if (!step.rules || step.rules.length === 0) return null;
-	const ruleCtx = createRuleContext(opts.event, [], opts.env);
+	const ruleCtx = createRuleContext(opts.event, [], opts.env, opts.dispatchInputs ?? {}, opts.fanout);
 	const ruleResult = await evaluateRules(step.rules, ruleCtx, step.name);
 	if (ruleResult.allPassed) return null;
 	opts.sendIpc({
@@ -1311,14 +1347,17 @@ async function evaluateStepRulesAndMaybeSkip(step, stepIndex, opts) {
 	};
 }
 /**
-* Manual approval gate for a step. When the step declares `requireApproval`
-* and the harness wired `awaitStepApproval`, block until the orchestrator
-* resolves the hold. Returns a failed `StepIterationOutcome` (breaking the
-* loop) on reject/expired; returns null when approved or when no gate applies.
+* Pre-step manual approval gate. When the step declares `approval` with
+* `when: 'always'` and the harness wired `awaitStepApproval`, block until the
+* orchestrator resolves the hold. A `when: 'drift'` gate is NOT handled here —
+* it fires mid-execution inside `runStepWithCheckMode` once `check()` returns
+* drift. Returns a failed `StepIterationOutcome` (breaking the loop) on
+* reject/expired; returns null when approved or when no gate applies.
 */
 async function maybeGateStepApproval(step, stepIndex, opts) {
-	if (step.requireApproval === void 0 || !opts.awaitStepApproval) return null;
-	const normalized = normalizeRequireApproval(step.requireApproval);
+	if (step.approval === void 0 || !opts.awaitStepApproval) return null;
+	const normalized = normalizeApproval(step.approval);
+	if (normalized.when === "drift") return null;
 	opts.sendIpc({
 		type: "log.line",
 		stepIndex,
@@ -1407,6 +1446,39 @@ async function runObserverHook(args) {
 * `ctx.secrets.mountFile` tmpdir, any env vars set via `exposeFile`) is
 * removed even when the step throws, times out, or rule-skips.
 */
+/**
+* Run a step through its retry policy. Each call to `executeStepInLoop` is one
+* attempt: it sets up its own per-attempt timeout from `step.timeout` and returns
+* a `SandboxStepResult` (it never throws — a failed attempt is reported as a
+* `failed` status with an `error`). A failed attempt is retried while attempts
+* remain AND `retryIf(reconstructedError)` is true; backoff sleeps between
+* attempts. The retry loop runs to completion BEFORE the caller applies
+* `continueOnError` to the final outcome.
+*/
+async function runStepWithRetry(step, stepIndex, ctx, timeoutMs, opts) {
+	const retry = step.retry;
+	const max = retry?.maxAttempts ?? 1;
+	let result;
+	for (let n = 1; n <= max; n++) {
+		result = await executeStepInLoop(step, stepIndex, ctx, timeoutMs, opts.sendIpc, opts.outputsMap, opts.getSecretsAccessLog, opts.getSecretMountRecords, opts.jobDeadlineSignal, opts.checkMode ?? CheckMode.enum.apply, opts);
+		if (result.status !== ExecutionStepStatus.enum.failed) return result;
+		const err = new Error(result.error?.message ?? `Step '${step.name}' failed`);
+		if (!(n < max && (retry?.retryIf?.(err) ?? true))) break;
+		const delay = computeBackoffDelay(n, {
+			maxAttempts: max,
+			delayMs: retry.delayMs,
+			backoff: retry.backoff,
+			maxDelayMs: retry.maxDelayMs
+		});
+		opts.sendIpc({
+			type: "log.line",
+			stepIndex,
+			line: `[kici] Step '${step.name}' attempt ${n}/${max} failed: ${err.message}; retrying in ${delay}ms`
+		});
+		await new Promise((r) => setTimeout(r, delay));
+	}
+	return result;
+}
 async function runStepIteration(step, stepIndex, opts) {
 	const skippedResult = await evaluateStepRulesAndMaybeSkip(step, stepIndex, opts);
 	if (skippedResult) {
@@ -1434,7 +1506,7 @@ async function runStepIteration(step, stepIndex, opts) {
 		const timeoutMs = step.timeout ?? opts.defaultTimeoutMs;
 		let result;
 		try {
-			result = await executeStepInLoop(step, stepIndex, ctx, timeoutMs, opts.sendIpc, opts.outputsMap, opts.getSecretsAccessLog, opts.getSecretMountRecords, opts.jobDeadlineSignal, opts.checkMode ?? CheckMode.enum.apply);
+			result = await runStepWithRetry(step, stepIndex, ctx, timeoutMs, opts);
 		} finally {
 			await opts.afterStepApplyEnvFiles?.();
 		}
@@ -3076,8 +3148,8 @@ function logSubprocessStreams(e, tokens) {
 * no Rolldown step at runtime. `@kici-dev/sdk` and host-repo deps resolve via
 * Node's normal ESM lookup against `.kici/node_modules/`.
 */
-const AGENT_SDK_VERSION = "0.1.21";
-const AGENT_SDK_BUNDLE_HASH = "8308089347c304e41b457d3867b17bbff11d6b5cd9706b6823e7abdbd849f33f";
+const AGENT_SDK_VERSION = "0.1.23";
+const AGENT_SDK_BUNDLE_HASH = "3a83610d2d122b9f9b0f924b225a47050d0b35f00a8f3256a3e15f3ff3bf7ddc";
 /**
 * Register the `@kici-dev/core/ts-loader-hook` oxc-transform ESM loader hook so
 * subsequent dynamic `import()` calls for `.ts` / `.tsx` files transform on the
@@ -3439,7 +3511,7 @@ async function applyOverlay(config) {
 */
 init_download();
 init_dep_restore();
-const AGENT_VERSION = "0.1.21";
+const AGENT_VERSION = "0.1.23";
 process.on("uncaughtException", (err) => {
 	process.stderr.write(`[workflow-runner] UNCAUGHT EXCEPTION: ${err.message}\n`);
 	if (err.stack) process.stderr.write(`[workflow-runner] Stack: ${err.stack}\n`);
@@ -3832,35 +3904,49 @@ function waitForApprovalResolution(requestId) {
 	});
 }
 /**
-* Build the `awaitStepApproval` callback the step loop uses to block on a
-* `requireApproval` step. Sends an `approval.request` IPC (relayed by the agent
-* over the WS as a `step.approval-request`) and awaits the matching
-* `approval.resolved`. A relay error is treated as a fail-closed reject.
+* Send a step-approval `approval.request` IPC (relayed by the agent over the WS
+* as a `step.approval-request`), await the matching `approval.resolved`, and map
+* it onto a `StepApprovalResolution`. A relay error is treated as a fail-closed
+* reject. Shared by the `when: 'always'` and `when: 'drift'` callbacks; the
+* latter carries a drift `payload`.
 */
-function buildAwaitStepApproval() {
-	return async (req) => {
-		const requestId = randomUUID();
-		sendMessage({
-			type: "approval.request",
-			requestId,
-			stepIndex: req.stepIndex,
-			stepName: req.stepName,
-			clauses: req.clauses,
-			reason: req.reason,
-			...req.timeoutSeconds !== void 0 && { timeoutSeconds: req.timeoutSeconds }
-		});
-		const resolution = await waitForApprovalResolution(requestId);
-		if (resolution.error) return {
-			outcome: "rejected",
-			reason: resolution.error
-		};
-		return {
-			outcome: resolution.outcome ?? "rejected",
-			...resolution.reason !== void 0 && { reason: resolution.reason }
-		};
+async function requestStepApproval(req) {
+	const requestId = randomUUID();
+	sendMessage({
+		type: "approval.request",
+		requestId,
+		stepIndex: req.stepIndex,
+		stepName: req.stepName,
+		clauses: req.clauses,
+		reason: req.reason,
+		...req.timeoutSeconds !== void 0 && { timeoutSeconds: req.timeoutSeconds },
+		...req.payload !== void 0 && { payload: req.payload }
+	});
+	const resolution = await waitForApprovalResolution(requestId);
+	if (resolution.error) return {
+		outcome: "rejected",
+		reason: resolution.error
+	};
+	return {
+		outcome: resolution.outcome ?? "rejected",
+		...resolution.reason !== void 0 && { reason: resolution.reason }
 	};
 }
 /**
+* Build the `awaitStepApproval` callback the step loop uses to block on an
+* `approval` step (`when: 'always'`).
+*/
+function buildAwaitStepApproval() {
+	return (req) => requestStepApproval(req);
+}
+/**
+* Build the `awaitStepApprovalWithPayload` callback the step loop uses to block
+* on a `when: 'drift'` step mid-execution, carrying the computed drift payload.
+*/
+function buildAwaitStepApprovalWithPayload() {
+	return (req) => requestStepApproval(req);
+}
+/**
 * Build the {@link CacheTransport} the sandbox-side cache engine uses to reach
 * the orchestrator. Each method sends a `cache.request` IPC (relayed by the
 * agent over the WS as a `cache.user.*` message) and awaits the matching
@@ -4093,6 +4179,75 @@ function createIpcLogger(stepIndex, stepName, sendFn) {
 		}
 	};
 }
+/** A lock needs entry maps to a base name (single/matrix/host) or a group name. */
+function needBaseName(need) {
+	if (typeof need === "string") return {
+		kind: "job",
+		key: need
+	};
+	if (need && typeof need === "object") {
+		if ("group" in need) return {
+			kind: "group",
+			key: need.group
+		};
+		if ("name" in need) return {
+			kind: "job",
+			key: need.name
+		};
+	}
+	return null;
+}
+/**
+* Build `ctx.needs` for a job's steps from the dispatch envelope. Reconstructs
+* an {@link UpstreamSnapshot} from `upstreamJobOutputs` (flat per single job;
+* `byMatrix` / `byHost` envelopes per fan-out) + `upstreamJobStatuses` (keyed by
+* each upstream job/child name), then resolves the job's declared needs into the
+* `{ result, status }` / ordered-array shape via the shared SDK builder. Returns
+* undefined when the job declares no needs.
+*/
+function buildStepNeedsContext(declaredNeeds, upstreamJobOutputs, upstreamJobStatuses) {
+	if (!declaredNeeds || declaredNeeds.length === 0) return void 0;
+	const statuses = upstreamJobStatuses ?? {};
+	const jobs = {};
+	const groups = {};
+	const snapStatuses = {};
+	const resolvedNeeds = [];
+	for (const need of declaredNeeds) {
+		const base = needBaseName(need);
+		if (!base) continue;
+		const childNames = Object.keys(statuses).filter((n) => n.startsWith(`${base.key} (`));
+		if (base.kind === "group" || childNames.length > 0) {
+			groups[base.key] = [...childNames].sort();
+			const envelope = upstreamJobOutputs?.[base.key];
+			const bySuffix = envelopeChildOutputs(envelope);
+			for (const child of childNames) {
+				jobs[child] = bySuffix[child.slice(base.key.length + 2, -1)] ?? {};
+				snapStatuses[child] = statuses[child];
+			}
+			resolvedNeeds.push({ group: base.key });
+		} else {
+			jobs[base.key] = upstreamJobOutputs?.[base.key] ?? {};
+			if (statuses[base.key]) snapStatuses[base.key] = statuses[base.key];
+			resolvedNeeds.push(base.key);
+		}
+	}
+	return buildNeedsContext({
+		jobs,
+		groups,
+		statuses: snapStatuses
+	}, resolvedNeeds);
+}
+/**
+* Extract per-child output records from a fan-out outputs envelope, keyed by the
+* combination suffix (matrix `byMatrix`) or hostname (`runsOnAll` `byHost`).
+* Returns an empty map for a non-envelope value.
+*/
+function envelopeChildOutputs(envelope) {
+	if (!envelope) return {};
+	const byMatrix = envelope.byMatrix;
+	const byHost = envelope.byHost;
+	return byMatrix ?? byHost ?? {};
+}
 /**
 * Build StepSecrets from the job execution request, wired with the per-step
 * file-mount host (used by `ctx.secrets.mountFile` / `exposeFile`).
@@ -4288,7 +4443,31 @@ function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedS
 		...request.provider && { provider: request.provider },
 		...request.matrixValues && { matrix: request.matrixValues },
 		...request.host && { host: request.host },
-		...request.agent && { agent: request.agent }
+		...request.agent && { agent: request.agent },
+		...(() => {
+			const fanout = deriveFanout(request);
+			return fanout ? { fanout } : {};
+		})(),
+		dispatchInputs: request.dispatchInputs ?? {},
+		...(() => {
+			const needs = buildStepNeedsContext(request.jobNeeds, request.upstreamJobOutputs, request.upstreamJobStatuses);
+			return needs ? { needs } : {};
+		})()
+	};
+}
+/**
+* Derive the fan-out position (`ctx.fanout`) from a dispatch request. Returns
+* `undefined` for a non-fan-out job (no `fanoutTotal`), so `ctx.fanout` is only
+* set for `runsOnAll` host children and matrix combinations.
+*/
+function deriveFanout(request) {
+	if (request.fanoutTotal === void 0) return void 0;
+	const index = request.fanoutIndex ?? 0;
+	return {
+		index,
+		total: request.fanoutTotal,
+		first: index === 0,
+		last: index === request.fanoutTotal - 1
 	};
 }
 /** Raw provider webhook body for ctx.rawPayload — nested in the envelope. */
@@ -4904,7 +5083,7 @@ function buildOutputInfrastructure(request, refMap) {
 */
 async function maybeSkipJobOnRules(job, request, normalizedSteps) {
 	if (!job?.rules || job.rules.length === 0) return false;
-	const ruleCtx = createRuleContext(request.event ?? {}, [], process.env);
+	const ruleCtx = createRuleContext(request.event ?? {}, [], process.env, request.dispatchInputs ?? {}, deriveFanout(request));
 	if ((await evaluateRules(job.rules, ruleCtx, request.jobName)).allPassed) return false;
 	const skippedResults = normalizedSteps.map((s, i) => ({
 		name: s.name,
@@ -5159,6 +5338,8 @@ async function main() {
 		outputsMap,
 		event: request.event ?? {},
 		env: process.env,
+		dispatchInputs: request.dispatchInputs ?? {},
+		fanout: deriveFanout(request),
 		jobHooks,
 		cachePhaseDeps,
 		isAborted: () => aborted,
@@ -5180,7 +5361,8 @@ async function main() {
 		},
 		beforeStepEnvFiles: stepEnvHooks.beforeStepEnvFiles,
 		afterStepApplyEnvFiles: stepEnvHooks.afterStepApplyEnvFiles,
-		awaitStepApproval: buildAwaitStepApproval()
+		awaitStepApproval: buildAwaitStepApproval(),
+		awaitStepApprovalWithPayload: buildAwaitStepApprovalWithPayload()
 	});
 	jobDeadline.clear();
 	await maybeSaveJobCache(jobCacheSpecs, jobCacheRestore, cachePhaseDeps, !aborted && loopResult.status === ExecutionStepStatus.enum.success);
@@ -5266,6 +5448,6 @@ main().catch((error) => {
 	setTimeout(() => process.exit(1), 100);
 });
 //#endregion
-export { createSandboxStepContext, rawPayloadFromEvent };
+export { buildStepNeedsContext, createSandboxStepContext, deriveFanout, rawPayloadFromEvent };
 
 //# sourceMappingURL=workflow-runner.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/agent",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Customer-deployable agent for the KiCI CI/CD stack. Connects to an orchestrator, clones the workflow repo, executes steps, and streams logs back.",
   "keywords": [
     "ci",
@@ -64,10 +64,10 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.21",
-    "@kici-dev/engine": "0.1.21",
-    "@kici-dev/sdk": "0.1.21",
-    "@kici-dev/shared": "0.1.21"
+    "@kici-dev/core": "0.1.23",
+    "@kici-dev/engine": "0.1.23",
+    "@kici-dev/sdk": "0.1.23",
+    "@kici-dev/shared": "0.1.23"
   },
   "kici": {
     "metrics": {