@kici-dev/agent 0.1.20 → 0.1.22

package/dist/workflow-runner.js

@@ -7,8 +7,8 @@ import os, { homedir, tmpdir } from "node:os";
 import path, { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { $ } from "zx";
 import { createLogger, deriveSharedSecret, initZx, normalizeLineEndings, sha256, sha256File, toErrorMessage } from "@kici-dev/shared";
-import { CacheOutcome, CacheStepType, 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 { CacheOutcome, CacheStepType, CheckMode, CheckStepOutcome, ExecutionJobStatus, ExecutionStepStatus, TimeoutReason } from "@kici-dev/engine";
+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 { calculateJwkThumbprint, decodeJwt, exportJWK, generateKeyPair } from "jose";
@@ -22,6 +22,7 @@ import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { c, x } from "tar";
+import { runIdempotentStep } from "@kici-dev/core/idempotency";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { PNPM_IGNORE_BUILD_GATE_ARG, PackageManager, YarnFlavor, detectPackageManagerFromManifests, detectYarnFlavor } from "@kici-dev/shared/package-manager";
@@ -1116,12 +1117,92 @@ function createRuleContext(event, changedFiles = [], env = {}) {
 }
 //#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).
+*
+* - 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). 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, opts) {
+	if (!step.check) {
+		if (checkMode !== CheckMode.enum.apply) return {
+			checkOutcome: CheckStepOutcome.enum.no_check,
+			status: "skipped",
+			outputs: void 0
+		};
+		return {
+			status: "success",
+			outputs: await step.run(ctx)
+		};
+	}
+	let lastDrift = null;
+	const adapted = {
+		name: step.name,
+		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,
+		...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,
+			line
+		})
+	});
+	const driftSummary = res.drift != null ? step.summarize(res.drift) : void 0;
+	const status = res.outcome === CheckStepOutcome.enum.applied ? "success" : "skipped";
+	const mappedStatus = res.outcome === CheckStepOutcome.enum["dry-run"] ? "success" : status;
+	return {
+		checkOutcome: res.outcome,
+		status: mappedStatus,
+		outputs: res.result,
+		...driftSummary !== void 0 && { driftSummary },
+		...res.drift != null && { drift: res.drift }
+	};
+}
 /**
 * Execute a single step with timeout enforcement.
 *
 * Timeout pattern using Promise.race + AbortController, with IPC status reporting.
 */
-async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, outputsMap, getSecretsAccessLog, getSecretMountRecords, jobDeadlineSignal) {
+async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, outputsMap, getSecretsAccessLog, getSecretMountRecords, jobDeadlineSignal, checkMode, opts) {
 	sendFn({
 		type: "step.start",
 		stepIndex,
@@ -1131,8 +1212,8 @@ async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, output
 	const abortController = new AbortController();
 	const timeoutId = setTimeout(() => abortController.abort(), timeoutMs);
 	try {
-		const result = await Promise.race([
-			step.run(ctx),
+		const phase = await Promise.race([
+			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`));
@@ -1151,22 +1232,26 @@ async function executeStepInLoop(step, stepIndex, ctx, timeoutMs, sendFn, output
 		]);
 		clearTimeout(timeoutId);
 		const durationMs = Date.now() - startTime;
-		const outputsPayload = result != null ? result : void 0;
+		const outputsPayload = phase.outputs != null ? phase.outputs : void 0;
 		if (outputsPayload) outputsMap.set(step.name, outputsPayload);
 		const secretsAccessed = getSecretsAccessLog?.();
 		emitSecretMountEvents(getSecretMountRecords?.(), stepIndex, sendFn);
+		const stepStatus = phase.status === "skipped" ? ExecutionStepStatus.enum.skipped : ExecutionStepStatus.enum.success;
 		sendFn({
 			type: "step.complete",
 			stepIndex,
-			status: ExecutionStepStatus.enum.success,
+			status: stepStatus,
 			durationMs,
 			...outputsPayload && { outputs: outputsPayload },
-			...secretsAccessed !== void 0 && { secretsAccessed }
+			...secretsAccessed !== void 0 && { secretsAccessed },
+			...phase.checkOutcome !== void 0 && { checkOutcome: phase.checkOutcome },
+			...phase.driftSummary !== void 0 && { driftSummary: phase.driftSummary },
+			...phase.drift !== void 0 && { drift: phase.drift }
 		});
 		return {
 			name: step.name,
 			stepIndex,
-			status: ExecutionStepStatus.enum.success,
+			status: stepStatus,
 			durationMs,
 			...outputsPayload && { outputs: outputsPayload }
 		};
@@ -1258,14 +1343,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,
@@ -1381,7 +1469,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);
+			result = await executeStepInLoop(step, stepIndex, ctx, timeoutMs, opts.sendIpc, opts.outputsMap, opts.getSecretsAccessLog, opts.getSecretMountRecords, opts.jobDeadlineSignal, opts.checkMode ?? CheckMode.enum.apply, opts);
 		} finally {
 			await opts.afterStepApplyEnvFiles?.();
 		}
@@ -3023,8 +3111,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.20";
-const AGENT_SDK_BUNDLE_HASH = "8308089347c304e41b457d3867b17bbff11d6b5cd9706b6823e7abdbd849f33f";
+const AGENT_SDK_VERSION = "0.1.22";
+const AGENT_SDK_BUNDLE_HASH = "4b26a42978f77e29db110d47523ec947d3d673c3109fc48141c1a62814bde7a1";
 /**
 * 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
@@ -3386,7 +3474,7 @@ async function applyOverlay(config) {
 */
 init_download();
 init_dep_restore();
-const AGENT_VERSION = "0.1.20";
+const AGENT_VERSION = "0.1.22";
 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`);
@@ -3779,35 +3867,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
@@ -4040,6 +4142,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`).
@@ -4235,7 +4406,11 @@ 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 needs = buildStepNeedsContext(request.jobNeeds, request.upstreamJobOutputs, request.upstreamJobStatuses);
+			return needs ? { needs } : {};
+		})()
 	};
 }
 /** Raw provider webhook body for ctx.rawPayload — nested in the envelope. */
@@ -5099,6 +5274,7 @@ async function main() {
 	const jobStartTime = Date.now();
 	const loopResult = await executeStepLoop({
 		steps: normalizedSteps,
+		checkMode: request.checkMode,
 		createStepContext: createStepCtxWithCapture,
 		sendIpc: maskedSend,
 		defaultTimeoutMs,
@@ -5126,7 +5302,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);
@@ -5212,6 +5389,6 @@ main().catch((error) => {
 	setTimeout(() => process.exit(1), 100);
 });
 //#endregion
-export { createSandboxStepContext, rawPayloadFromEvent };
+export { buildStepNeedsContext, createSandboxStepContext, rawPayloadFromEvent };
 
 //# sourceMappingURL=workflow-runner.js.map

package/dist/ws/orchestrator-client.d.ts

@@ -8,6 +8,12 @@ export interface OrchestratorClientOptions {
     agentId: string;
     /** Agent's label set for job routing. */
     labels: string[];
+    /**
+     * Agent-reported typed host-vars (the `KICI_PROPERTIES` bag). Reported at
+     * registration and shallow-merged into the orchestrator's host roster.
+     * Omitted / empty ⇒ no properties reported.
+     */
+    properties?: Record<string, string | number | boolean>;
     /** Callback invoked when a job.dispatch message is received. */
     onJobDispatch: (dispatch: JobDispatch) => void;
     /** Callback invoked when a job.cancel message is received. */
@@ -94,6 +100,7 @@ export declare class OrchestratorClient {
     private readonly url;
     private readonly agentId;
     private readonly labels;
+    private readonly properties;
     private readonly onJobDispatch;
     private readonly onJobCancel;
     private readonly token?;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/agent",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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.20",
-    "@kici-dev/engine": "0.1.20",
-    "@kici-dev/sdk": "0.1.20",
-    "@kici-dev/shared": "0.1.20"
+    "@kici-dev/core": "0.1.22",
+    "@kici-dev/engine": "0.1.22",
+    "@kici-dev/sdk": "0.1.22",
+    "@kici-dev/shared": "0.1.22"
   },
   "kici": {
     "metrics": {