@kici-dev/agent 0.1.15 → 0.1.16

package/dist/workflow-runner.js

@@ -8,7 +8,7 @@ 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, ExecutionJobStatus, ExecutionStepStatus, TimeoutReason } from "@kici-dev/engine";
-import { buildKiciApi, createStepSecrets, evaluateRules, isDynamicJobFn, normalizeCacheSpecs, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
+import { buildKiciApi, createStepSecrets, evaluateRules, isDynamicJobFn, normalizeCacheSpecs, normalizeRequireApproval, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
@@ -1123,6 +1123,65 @@ 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.
+*/
+async function maybeGateStepApproval(step, stepIndex, opts) {
+	if (step.requireApproval === void 0 || !opts.awaitStepApproval) return null;
+	const normalized = normalizeRequireApproval(step.requireApproval);
+	opts.sendIpc({
+		type: "log.line",
+		stepIndex,
+		line: `[kici] Step '${step.name}' awaiting approval...`
+	});
+	const resolution = await opts.awaitStepApproval({
+		stepIndex,
+		stepName: step.name,
+		clauses: normalized.clauses,
+		reason: normalized.reason ?? `Approval required for step '${step.name}'`,
+		timeoutSeconds: normalized.timeoutSeconds
+	});
+	if (resolution.outcome === "approved") {
+		opts.sendIpc({
+			type: "log.line",
+			stepIndex,
+			line: `[kici] Step '${step.name}' approved.`
+		});
+		return null;
+	}
+	const why = resolution.outcome === "expired" ? "approval expired" : `approval rejected${resolution.reason ? `: ${resolution.reason}` : ""}`;
+	opts.sendIpc({
+		type: "step.start",
+		stepIndex,
+		stepName: step.name
+	});
+	opts.sendIpc({
+		type: "step.complete",
+		stepIndex,
+		status: ExecutionStepStatus.enum.failed,
+		durationMs: 0
+	});
+	opts.sendIpc({
+		type: "log.line",
+		stepIndex,
+		line: `[kici] Step '${step.name}' ${why}.`
+	});
+	await opts.disposeStepResources?.();
+	return {
+		result: {
+			name: step.name,
+			stepIndex,
+			status: ExecutionStepStatus.enum.failed,
+			durationMs: 0,
+			error: { message: `Step '${step.name}' ${why}` }
+		},
+		shouldBreak: true,
+		failedStepName: step.name
+	};
+}
+/**
 * Run a single observer hook (beforeStep / afterStep). Failures only emit a
 * log line — they never change job status. Centralises the per-call boilerplate
 * so the per-step body can stay flat.
@@ -1169,6 +1228,8 @@ async function runStepIteration(step, stepIndex, opts) {
 			shouldBreak: false
 		};
 	}
+	const gate = await maybeGateStepApproval(step, stepIndex, opts);
+	if (gate) return gate;
 	if (opts.jobHooks?.beforeStep) await runObserverHook({
 		hook: opts.jobHooks.beforeStep,
 		hookType: "beforeStep",
@@ -2179,8 +2240,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.15";
-const AGENT_SDK_BUNDLE_HASH = "cee24b67bbb4a1d2a770e4063dd37a9af33409faeb5ce32f936703b4431316dd";
+const AGENT_SDK_VERSION = "0.1.16";
+const AGENT_SDK_BUNDLE_HASH = "cd4b8e0d91efe578c96e7c746f89b44a3df8fcaebaec2185399168ef8eb4ebca";
 /**
 * 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
@@ -2873,6 +2934,68 @@ function waitForCacheResponse(requestId) {
 	});
 }
 /**
+* Pending promises for approval.resolved messages from the agent.
+* Key: requestId (correlates approval.request -> approval.resolved).
+*/
+const pendingApprovalResolutions = /* @__PURE__ */ new Map();
+/**
+* Hard ceiling on how long the runner blocks a step waiting for an approval
+* resolution. The orchestrator enforces the real (org-/SDK-configured) expiry
+* and sends `expired` when it lapses; this is a safety net well above any sane
+* approval window so the runner cannot hang forever if the resolution is lost.
+*/
+const APPROVAL_RESOLUTION_TIMEOUT_MS = 10080 * 60 * 1e3;
+/** Wait for an approval.resolved from the agent with the given requestId. */
+function waitForApprovalResolution(requestId) {
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			pendingApprovalResolutions.delete(requestId);
+			resolve({
+				type: "approval.resolved",
+				requestId,
+				outcome: "expired"
+			});
+		}, APPROVAL_RESOLUTION_TIMEOUT_MS);
+		pendingApprovalResolutions.set(requestId, {
+			resolve: (response) => {
+				clearTimeout(timer);
+				pendingApprovalResolutions.delete(requestId);
+				resolve(response);
+			},
+			timer
+		});
+	});
+}
+/**
+* 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.
+*/
+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 }
+		};
+	};
+}
+/**
 * 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
@@ -2985,6 +3108,9 @@ function dispatchAgentMessage(msg) {
 	} else if (msg.type === "cache.response") {
 		const pending = pendingCacheResponses.get(msg.requestId);
 		if (pending) pending.resolve(msg);
+	} else if (msg.type === "approval.resolved") {
+		const pending = pendingApprovalResolutions.get(msg.requestId);
+		if (pending) pending.resolve(msg);
 	}
 }
 if (isForkMode) process.on("message", (msg) => {
@@ -4093,7 +4219,8 @@ async function main() {
 			if (disposeFn) await disposeFn();
 		},
 		beforeStepEnvFiles: stepEnvHooks.beforeStepEnvFiles,
-		afterStepApplyEnvFiles: stepEnvHooks.afterStepApplyEnvFiles
+		afterStepApplyEnvFiles: stepEnvHooks.afterStepApplyEnvFiles,
+		awaitStepApproval: buildAwaitStepApproval()
 	});
 	jobDeadline.clear();
 	await maybeSaveJobCache(jobCacheSpecs, jobCacheRestore, cachePhaseDeps, !aborted && loopResult.status === ExecutionStepStatus.enum.success);

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

@@ -1,7 +1,7 @@
-import { type AgentToOrchestratorMessage, type JobDispatch, type JobCancel } from '@kici-dev/engine';
-import type { CacheRequestIpc, CacheResponseIpc } from '../execution/sandbox/index.js';
+import { type AgentToOrchestratorMessage, type JobDispatch, type JobCancel, type FleetLogsRequest } from '@kici-dev/engine';
+import type { CacheRequestIpc, CacheResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from '../execution/sandbox/index.js';
 export type ConnectionState = 'disconnected' | 'connecting' | 'authenticating' | 'registering' | 'registered';
-interface OrchestratorClientOptions {
+export interface OrchestratorClientOptions {
     /** WebSocket URL of the orchestrator. */
     url: string;
     /** Agent's unique identifier. */
@@ -35,6 +35,18 @@ interface OrchestratorClientOptions {
      * doesn't have to read process.env directly.
      */
     scalerManaged?: boolean;
+    /**
+     * Supplies the inputs for the agent fleet mini-bundle on a fleet.logs.request.
+     * Returns the agent's resolved config (redacted inside the bundle assembler),
+     * the log directory, and the current Prometheus metrics text. Omitted in
+     * tests / contexts that don't participate in fleet collection — the handler
+     * then replies with an empty-config bundle.
+     */
+    getFleetBundleInputs?: () => Promise<{
+        config: Record<string, unknown>;
+        logDir?: string;
+        metricsText?: string;
+    }>;
 }
 /**
  * WebSocket client that connects the agent to the customer orchestrator.
@@ -70,6 +82,13 @@ export declare class OrchestratorClient {
     private readonly pendingApiRequests;
     /** Pending user-cache restore/save requests awaiting orchestrator response. */
     private readonly pendingUserCacheRequests;
+    /**
+     * Pending step-approval requests awaiting the orchestrator's resolution.
+     * No client-side timeout: the orchestrator owns the (org-/SDK-configured)
+     * expiry and sends `step.approval-resolved: expired` when it lapses. The
+     * workflow-runner carries an outer safety-net timeout.
+     */
+    private readonly pendingStepApprovals;
     /** Pending concurrency report requests awaiting orchestrator ack. */
     private readonly pendingConcurrencyRequests;
     private readonly url;
@@ -83,6 +102,7 @@ export declare class OrchestratorClient {
     private readonly getInFlightJobs?;
     private readonly roles;
     private readonly scalerManaged;
+    private readonly getFleetBundleInputs?;
     /** Timestamp when the connection was lost, used for gap marker outage duration. */
     private disconnectedAt;
     /** Set to true when auth.failure is received. Prevents retrying with a bad token. */
@@ -180,6 +200,12 @@ export declare class OrchestratorClient {
         deliveryId?: string;
         error?: string;
     }>;
+    /**
+     * Build this agent's fleet mini-bundle and stream it back to the orchestrator
+     * as ordered fleet.bundle.chunk frames (the WS frame cap forbids one frame).
+     * On failure, sends a single fleet.bundle.error. Public for unit testing.
+     */
+    streamFleetBundle(req: FleetLogsRequest): Promise<void>;
     /**
      * Send a typed API request to the orchestrator and await the response.
      *
@@ -202,6 +228,15 @@ export declare class OrchestratorClient {
      * Times out after 30 seconds for the round-trip ops.
      */
     requestUserCache(jobId: string, request: CacheRequestIpc): Promise<CacheResponseIpc>;
+    /**
+     * Relay a step-level approval request to the orchestrator. Sends a
+     * `step.approval-request` WS message and resolves with the orchestrator's
+     * `step.approval-resolved` mapped onto the IPC response shape. No client-side
+     * timeout — the orchestrator owns the approval expiry and replies with an
+     * `expired` outcome when it lapses. Rejects only on disconnect (the relay
+     * caller treats a rejection as a fail-closed reject).
+     */
+    sendStepApproval(runId: string, jobId: string, request: StepApprovalRequestIpc): Promise<StepApprovalResolvedIpc>;
     /**
      * Send a job.context message to the orchestrator.
      *
@@ -283,5 +318,4 @@ export declare class OrchestratorClient {
     private scheduleReconnect;
     private cancelReconnect;
 }
-export {};
 //# sourceMappingURL=orchestrator-client.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/agent",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "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",
@@ -54,6 +54,7 @@
   },
   "dependencies": {
     "@hono/node-server": "^2.0.0",
+    "archiver": "^7.0.1",
     "dockerode": "^5.0.0",
     "hono": "^4.12.18",
     "tar": "^7.5.13",
@@ -61,10 +62,10 @@
     "ws": "^8.20.0",
     "zod": "^4.3.6",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.15",
-    "@kici-dev/sdk": "0.1.15",
-    "@kici-dev/engine": "0.1.15",
-    "@kici-dev/shared": "0.1.15"
+    "@kici-dev/core": "0.1.16",
+    "@kici-dev/engine": "0.1.16",
+    "@kici-dev/shared": "0.1.16",
+    "@kici-dev/sdk": "0.1.16"
   },
   "kici": {
     "metrics": {
@@ -73,6 +74,7 @@
     }
   },
   "devDependencies": {
+    "@types/archiver": "^7.0.0",
     "@types/dockerode": "^4.0.1"
   },
   "scripts": {