@kici-dev/agent 0.1.20 → 0.1.22

package/dist/config.d.ts

@@ -10,6 +10,7 @@ declare const configSchema: z.ZodObject<{
     orchestratorUrl: z.ZodString;
     agentId: z.ZodOptional<z.ZodString>;
     labels: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string[], string>>;
+    properties: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<Record<string, string | number | boolean>, string>>;
     roles: z.ZodPipe<z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string[] | undefined, string | undefined>>, z.ZodTransform<string[] | undefined, string[] | undefined>>;
     port: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     logLevel: z.ZodDefault<z.ZodEnum<{
@@ -43,6 +44,7 @@ declare const configSchema: z.ZodObject<{
     }>>;
     otelExporterOtlpEndpoint: z.ZodOptional<z.ZodString>;
     concurrencyWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    isOrchestratorHost: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean, string | undefined>>;
 }, z.core.$strip>;
 /**
  * App configuration type. Includes computed agentId when not provided.
@@ -59,6 +61,7 @@ export type AppConfig = z.infer<typeof configSchema> & {
 export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     orchestratorUrl: string;
     labels: string[];
+    properties: Record<string, string | number | boolean>;
     roles: string[] | undefined;
     port: number;
     logLevel: "error" | "debug" | "info" | "warn";
@@ -73,6 +76,7 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     scalerIdleTimeoutMs: number;
     scalerPendingDispatchTimeoutMs: number;
     concurrencyWaitTimeoutMs: number;
+    isOrchestratorHost: boolean;
     agentId?: string | undefined;
     agentToken?: string | undefined;
     githubToken?: string | undefined;
@@ -86,6 +90,7 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
  * - KICI_ORCHESTRATOR_URL (required)
  * - KICI_AGENT_ID (optional, auto-generated from hostname-uuid8)
  * - KICI_LABELS (comma-separated, e.g. "linux,docker"). Labels with 'kici-' prefix are reserved.
+ * - KICI_PROPERTIES (comma-separated key=value host-vars, e.g. "region=eu,cores=8,gpu=true"). Typed (bool/number/string), reported into the host roster.
  * - KICI_ROLES (comma-separated agent roles, e.g. "builder,init-runner". undefined=all, empty=execution-only)
  * - KICI_PORT (default: 8080)
  * - KICI_LOG_LEVEL (default: info)
@@ -120,6 +125,7 @@ export declare function agentClientConnectionOptions(config: AppConfig): {
     url: string;
     agentId: string;
     labels: string[];
+    properties: Record<string, string | number | boolean>;
     scalerManaged: boolean;
     token: string | undefined;
 };

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 { buildNeedsContext } from '@kici-dev/sdk';
 import type { CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './sandbox/index.js';
 /**
  * Dependencies injected into JobRunner.
@@ -112,6 +113,15 @@ interface ActiveJob {
     completionPromise: Promise<void>;
     runId: 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).
+ */
+export declare function buildEvalNeedsContext(config: {
+    resultAware?: boolean;
+    declaredNeeds?: readonly unknown[];
+    upstreamSnapshot?: import('@kici-dev/engine').UpstreamSnapshot;
+}): ReturnType<typeof buildNeedsContext> | undefined;
 /**
  * Top-level job execution orchestrator for the agent.
  *

package/dist/execution/reboot.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Cross-OS host reboot for the workflow-level `restartHost()` step.
+ *
+ * The agent runs ON the host it executes jobs for, so a `restartHost()` step
+ * reboots that host. `rebootCommandFor` is the pure OS→command mapping (kept
+ * pure for unit-testing); `issueReboot` spawns it detached with a tiny grace so
+ * the job's final flush completes before the box goes down.
+ *
+ * Rebooting needs host privilege (root/admin). If the primitive is denied, the
+ * spawn fails and the caller clears the orchestrator's reboot-pending flag and
+ * surfaces the error — the deadline sweep is the backstop.
+ */
+/** The OS reboot primitive for a Node platform string. */
+export declare function rebootCommandFor(platform: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Issue the OS reboot detached. Resolves once the child has been spawned (the
+ * box is going down; there is nothing to await). Rejects synchronously if the
+ * spawn itself fails (e.g. the binary is missing). A privilege denial usually
+ * surfaces as a non-zero exit AFTER spawn — logged, not thrown, because by then
+ * the box may already be on its way down.
+ */
+export declare function issueReboot(platform?: NodeJS.Platform): Promise<void>;
+//# sourceMappingURL=reboot.d.ts.map

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

@@ -1,3 +1,4 @@
+import type { CheckMode, CheckStepOutcome } from '@kici-dev/engine';
 import type { SandboxStepResult } from './types.js';
 /**
  * Structured clone auth. Wire-compatible with `gitAuthSchema` on the
@@ -24,11 +25,11 @@ interface StepStartMessage {
     /** Distinguishes regular steps from hook executions (e.g., 'hook:onCancel', 'hook:cleanup'). Defaults to 'step'. */
     step_type?: string;
 }
-/** A step has completed (success or failure). */
+/** A step has completed (success, failure, or a check-mode skip). */
 interface StepCompleteMessage {
     type: 'step.complete';
     stepIndex: number;
-    status: 'success' | 'failed';
+    status: 'success' | 'failed' | 'skipped';
     durationMs: number;
     error?: {
         message: string;
@@ -47,6 +48,16 @@ interface StepCompleteMessage {
      * pseudo-steps carry `{ cacheOutcome, key, matchedKey?, bytes? }` here.
      */
     data?: Record<string, unknown>;
+    /**
+     * Idempotent per-step outcome (`CheckStepOutcome`). Present only when the run
+     * carried a check mode and the step has a `check` facet (or was a plain step
+     * skipped under check mode). Orthogonal to `status`.
+     */
+    checkOutcome?: CheckStepOutcome;
+    /** Human-readable drift summary (`summarize(drift)`). Present when drift was detected. */
+    driftSummary?: string;
+    /** Structured drift value returned by `check()`. Present when drift was detected. */
+    drift?: unknown;
 }
 /** A single log line from step execution. */
 interface LogLineMessage {
@@ -182,8 +193,13 @@ export interface StepApprovalRequestIpc {
     }>;
     /** Human label for the gate. */
     reason: string;
-    /** Per-gate timeout override (seconds) from the SDK `requireApproval.timeout`. */
+    /** Per-gate timeout override (seconds) from the SDK `approval.timeout`. */
     timeoutSeconds?: number;
+    /** Computed drift payload, present only for `when: 'drift'` gates. */
+    payload?: {
+        summaryMarkdown: string;
+        drift: unknown;
+    };
 }
 /** Which provenance upload operation to relay. */
 export type ProvenanceRequestOp = 'requestUploadUrl' | 'complete';
@@ -426,6 +442,13 @@ export interface JobExecutionRequest {
     checkout?: boolean;
     /** Whether this job is part of a test run triggered by `kici test`. */
     isTestRun?: boolean;
+    /**
+     * Run mode for idempotent steps (`apply` | `check` | `check-fail-on-drift`).
+     * Threaded from the dispatch event. In check / check-fail-on-drift mode the
+     * runner previews drift and never invokes a checked step's apply (`run`).
+     * Defaults to `apply` when unset.
+     */
+    checkMode?: CheckMode;
     /** When true, skip git clone -- use overlay tarball as complete workspace. */
     fullRepo?: boolean;
     /** URL to download the encrypted overlay tarball (test runs with uncommitted changes). */
@@ -460,6 +483,10 @@ export interface JobExecutionRequest {
     branch?: string;
     /** Plain outputs from upstream jobs (keyed by job name, then by step name). For ctx.jobOutputs(). */
     upstreamJobOutputs?: Record<string, Record<string, unknown>>;
+    /** Terminal status of each upstream job (keyed by job name; per-child for fan-out). For ctx.needs.<job>.status. */
+    upstreamJobStatuses?: Record<string, import('@kici-dev/engine').ExecutionJobStatus>;
+    /** This job's declared upstream needs (normalized lock edges) used to shape ctx.needs for steps. */
+    jobNeeds?: readonly unknown[];
     /** Resolved private npm registries for `npm install` auth (token bytes already filled). */
     npmRegistries?: ReadonlyArray<{
         url: string;

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

@@ -6,6 +6,7 @@
  * module loading, and calls this loop for step execution with hooks.
  */
 import type { Step, StepContext, HookInput, OutputsMap, StepSecretMountRecord } from '@kici-dev/sdk';
+import { CheckMode } from '@kici-dev/engine';
 import type { RunnerToAgentMessage } from './ipc-protocol.js';
 import type { SandboxStepResult } from './types.js';
 import { type CachePhaseDeps } from '../cache/index.js';
@@ -21,6 +22,11 @@ export interface JobHooks {
 /** Options for the step execution loop. */
 export interface StepLoopOptions {
     steps: Step[];
+    /**
+     * Run mode for idempotent steps. `apply` (default) converges; `check` /
+     * `check-fail-on-drift` preview drift and never invoke a checked step's apply.
+     */
+    checkMode?: CheckMode;
     /** Factory that creates a StepContext for a given step index and name. */
     createStepContext: (stepIndex: number, stepName: string) => StepContext;
     sendIpc: (msg: RunnerToAgentMessage) => void;
@@ -84,11 +90,11 @@ export interface StepLoopOptions {
      */
     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.
+     * Block an `approval` step (`when: 'always'`) 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;
@@ -101,6 +107,28 @@ export interface StepLoopOptions {
         reason: string;
         timeoutSeconds?: number;
     }) => Promise<StepApprovalResolution>;
+    /**
+     * Block an `approval: { when: 'drift' }` step mid-execution: after `check()`
+     * returns drift in apply mode, send a payload-bearing step-approval and await
+     * the resolution. The payload carries the computed drift (`summaryMarkdown` +
+     * structured `drift`) so the operator approves the actual diff. Absent ⇒ the
+     * drift gate is not enforced (CT / unit harnesses) and the step applies.
+     */
+    awaitStepApprovalWithPayload?: (req: {
+        stepIndex: number;
+        stepName: string;
+        clauses: Array<{
+            team: string;
+        } | {
+            user: string;
+        }>;
+        reason: string;
+        timeoutSeconds?: number;
+        payload: {
+            summaryMarkdown: string;
+            drift: unknown;
+        };
+    }) => Promise<StepApprovalResolution>;
 }
 /** Outcome of an awaited step-level approval hold. */
 export interface StepApprovalResolution {

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

@@ -13,10 +13,21 @@
  * This file is compiled alongside the agent by rolldown (existing build), but
  * runs as a SEPARATE process spawned by the sandbox backend.
  */
+import { ExecutionJobStatus } from '@kici-dev/engine';
 import type { StepContext } from '@kici-dev/sdk';
+import type { NeedsContext } from '@kici-dev/sdk';
 import type { OutputsMap, StepRefMap, TrackedStepSecrets } from '@kici-dev/sdk';
 import type { RunnerToAgentMessage, JobExecutionRequest } from './ipc-protocol.js';
 import { LogMasker } from './log-masker.js';
+/**
+ * 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.
+ */
+export declare function buildStepNeedsContext(declaredNeeds: readonly unknown[] | undefined, upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined, upstreamJobStatuses: Record<string, ExecutionJobStatus> | undefined): NeedsContext | undefined;
 /**
  * Create a StepContext natively inside the workflow runner.
  *

package/dist/index.js

@@ -3,7 +3,7 @@ import { homedir, hostname, tmpdir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
 import { LOGGER_ENV_VARS, defineEnv, validateUnknownKiciVars } from "@kici-dev/shared/env";
-import { KNOWN_ROLES, validateNoReservedLabels } from "@kici-dev/engine";
+import { KNOWN_ROLES, parseHostPropertyAssignments, validateNoReservedLabels } from "@kici-dev/engine";
 import { execFile } from "node:child_process";
 import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -50,6 +50,7 @@ const envDef = defineEnv({
 		orchestratorUrl: z.string().url().min(1, "KICI_ORCHESTRATOR_URL is required"),
 		agentId: z.string().optional(),
 		labels: z.string().default("").transform((s) => s.split(",").filter(Boolean)),
+		properties: z.string().default("").transform((s) => parseHostPropertyAssignments(s.split(",").filter(Boolean))),
 		roles: z.string().optional().transform((s) => {
 			if (s === void 0) return void 0;
 			if (s === "") return [];
@@ -85,16 +86,19 @@ const envDef = defineEnv({
 		scalerPendingDispatchTimeoutMs: z.coerce.number().default(6e4),
 		executionMode: ExecutionMode.optional(),
 		otelExporterOtlpEndpoint: z.string().optional(),
-		concurrencyWaitTimeoutMs: z.coerce.number().int().min(1e3).default(36e5)
+		concurrencyWaitTimeoutMs: z.coerce.number().int().min(1e3).default(36e5),
+		isOrchestratorHost: z.string().optional().transform((v) => v === "true")
 	}),
 	envMap: {
 		orchestratorUrl: "KICI_ORCHESTRATOR_URL",
 		agentId: "KICI_AGENT_ID",
 		labels: "KICI_LABELS",
+		properties: "KICI_PROPERTIES",
 		roles: "KICI_ROLES",
 		port: "KICI_PORT",
 		logLevel: "KICI_LOG_LEVEL",
 		agentToken: "KICI_AGENT_TOKEN",
+		isOrchestratorHost: "KICI_AGENT_IS_ORCHESTRATOR_HOST",
 		githubToken: "KICI_GITHUB_TOKEN",
 		maxLogSizeBytes: "KICI_MAX_LOG_SIZE_BYTES",
 		defaultStepTimeoutMs: "KICI_DEFAULT_STEP_TIMEOUT_MS",
@@ -118,6 +122,7 @@ const envDef = defineEnv({
 * - KICI_ORCHESTRATOR_URL (required)
 * - KICI_AGENT_ID (optional, auto-generated from hostname-uuid8)
 * - KICI_LABELS (comma-separated, e.g. "linux,docker"). Labels with 'kici-' prefix are reserved.
+* - KICI_PROPERTIES (comma-separated key=value host-vars, e.g. "region=eu,cores=8,gpu=true"). Typed (bool/number/string), reported into the host roster.
 * - KICI_ROLES (comma-separated agent roles, e.g. "builder,init-runner". undefined=all, empty=execution-only)
 * - KICI_PORT (default: 8080)
 * - KICI_LOG_LEVEL (default: info)