@kici-dev/sdk 0.1.21 → 0.1.23

package/dist/api-types.d.ts

@@ -58,6 +58,56 @@ export interface InventoryApi {
     /** Look up one host by agent id; null when the host is not in the roster. */
     get(agentId: string): Promise<HostInventoryEntry | null>;
 }
+export interface HostApi {
+    /**
+     * Signal the orchestrator that the host this job runs on is about to reboot,
+     * and resolve once the orchestrator acks (which sets a persisted
+     * reboot-pending flag holding the pinned post-restart job). After this
+     * resolves, the agent issues the OS reboot once the current step completes.
+     *
+     * Used by the SDK `restartHost()` step. `deadlineMs` overrides the
+     * orchestrator's default host-reboot deadline. Only meaningful inside a
+     * running job step on an agent; a local `kici run` rejects (no orchestrator
+     * to ack, and a local run cannot reboot a remote host).
+     */
+    requestReboot(opts?: {
+        deadlineMs?: number;
+    }): Promise<void>;
+}
+export interface BootstrapApi {
+    /**
+     * Bring up a temporary privileged init-runner on a declared-but-un-agented
+     * host over SSH, so it auto-enrolls as a short-lived `kici:init` agent. The
+     * step calling this must run on an agent holding the
+     * `kici:capability:ssh-transport` capability (the orchestrator refuses
+     * otherwise). No-op (`broughtUp: false`) when the target already has a live
+     * agent. Each bring-up is access-logged.
+     *
+     * The target's reach metadata + the bring-up SSH key (a scoped secret) are
+     * resolved server-side from the host roster — the workflow author supplies
+     * only the target agent id.
+     */
+    ensureInitRunner(targetAgentId: string): Promise<{
+        broughtUp: boolean;
+    }>;
+    /**
+     * Ship an input to a host's pre-boot SSH channel (e.g. a LUKS passphrase to
+     * a dropbear/initramfs `cryptroot-unlock` prompt on port 2222). Generic
+     * "pipe stdin to a forced-command endpoint"; the unlock recipe is
+     * per-host-passphrase → `preBootSend` → `waitForHostAlive`. Same
+     * `kici:capability:ssh-transport` gate + access-log as `ensureInitRunner`.
+     *
+     * `inputSecret` is a scoped-secret ref (`scope/key`) the orchestrator
+     * resolves server-side; the plaintext never passes through the workflow.
+     * Success is the send completing (the session drops as the box boots) —
+     * compose `restartHost`/host-alive waits to confirm the boot.
+     */
+    preBootSend(targetAgentId: string, opts: {
+        inputSecret: string;
+        port?: number;
+        command?: string;
+    }): Promise<void>;
+}
 export interface KiciApi {
     /** Query orchestrator infrastructure (scalers, agents). */
     infrastructure: InfrastructureApi;
@@ -65,6 +115,10 @@ export interface KiciApi {
     inventory: InventoryApi;
     /** Request short-lived OIDC ID tokens for the current job (build provenance). */
     oidc: OidcApi;
+    /** Host-lifecycle operations on the agent's own host (e.g. reboot). */
+    host: HostApi;
+    /** Fresh-box bootstrap bring-up (init-runner over SSH, pre-boot unlock). */
+    bootstrap: BootstrapApi;
 }
 /**
  * Low-level transport function used to implement KiciApi.

package/dist/api-types.js

@@ -36,7 +36,15 @@ function buildKiciApi(transport, jobCtx) {
 				jobId: jobCtx.jobId,
 				audience: opts.audience
 			});
-		} }
+		} },
+		host: { requestReboot: (opts) => transport("host.requestReboot", { ...opts?.deadlineMs !== void 0 ? { deadlineMs: opts.deadlineMs } : {} }) },
+		bootstrap: {
+			ensureInitRunner: (targetAgentId) => transport("kici.ensureInitRunner", { targetAgentId }),
+			preBootSend: (targetAgentId, opts) => transport("kici.preBootSend", {
+				targetAgentId,
+				...opts
+			})
+		}
 	};
 }
 //#endregion

package/dist/approval.d.ts

@@ -1,8 +1,9 @@
 /**
  * Workflow-author API for declaring a manual approval gate at step, job, or
- * workflow level. The author writes `requireApproval`; the compiler normalizes
- * it into the lock file's `approval` block, and the orchestrator turns it into
- * a held element at dispatch time.
+ * workflow level. The author writes `approval`; the compiler normalizes it
+ * into the lock file's `approval` block, and the orchestrator turns it into a
+ * held element at dispatch time (for `when: 'always'`) or the agent turns it
+ * into a mid-step drift gate (for `when: 'drift'`).
  */
 /** A single approver clause: any member of a team, or a specific user. */
 export type ApproverClause = {
@@ -10,25 +11,39 @@ export type ApproverClause = {
 } | {
     user: string;
 };
+/**
+ * When the gate fires.
+ *
+ * - `always` (default) — gate BEFORE the element runs, with a static reason.
+ *   Valid at step / job / workflow scope.
+ * - `drift` — gate BETWEEN a step's `check` and `run`, only when `check`
+ *   returns drift in apply mode. Step-scope only; requires a `check` facet.
+ */
+export type ApprovalWhen = 'always' | 'drift';
 /**
  * Declarative approval requirement.
  *
  * - `true` — pause for ANY org member with the approval permission.
  * - `ApproverClause[]` — a flat AND list (all clauses must be satisfied).
- * - object form — clauses plus an optional human `reason` and a per-gate
- *   `timeout` (seconds) that overrides the org-default expiry.
+ * - object form — clauses plus an optional `when`, a human `reason`, and a
+ *   per-gate `timeout` (seconds) that overrides the org-default expiry.
  */
-export type RequireApproval = true | ApproverClause[] | {
-    approvers: ApproverClause[];
+export type ApprovalConfig = true | ApproverClause[] | {
+    when?: ApprovalWhen;
+    approvers?: ApproverClause[];
     reason?: string;
     timeout?: number;
 };
 /** The normalized shape written into the lock file. */
-export interface NormalizedRequireApproval {
+export interface NormalizedApproval {
     clauses: ApproverClause[];
     reason?: string;
     timeoutSeconds?: number;
+    when: ApprovalWhen;
 }
-/** Normalize any `RequireApproval` form into `{ clauses, reason?, timeoutSeconds? }`. */
-export declare function normalizeRequireApproval(r: RequireApproval): NormalizedRequireApproval;
+/**
+ * Normalize any `ApprovalConfig` form into
+ * `{ clauses, reason?, timeoutSeconds?, when }`. `when` defaults to `'always'`.
+ */
+export declare function normalizeApproval(c: ApprovalConfig): NormalizedApproval;
 //# sourceMappingURL=approval.d.ts.map

package/dist/approval.js

@@ -1,16 +1,26 @@
 import "./chunk-BTugEXQM.js";
 //#region src/approval.ts
-/** Normalize any `RequireApproval` form into `{ clauses, reason?, timeoutSeconds? }`. */
-function normalizeRequireApproval(r) {
-	if (r === true) return { clauses: [] };
-	if (Array.isArray(r)) return { clauses: r };
+/**
+* Normalize any `ApprovalConfig` form into
+* `{ clauses, reason?, timeoutSeconds?, when }`. `when` defaults to `'always'`.
+*/
+function normalizeApproval(c) {
+	if (c === true) return {
+		clauses: [],
+		when: "always"
+	};
+	if (Array.isArray(c)) return {
+		clauses: c,
+		when: "always"
+	};
 	return {
-		clauses: r.approvers,
-		reason: r.reason,
-		timeoutSeconds: r.timeout
+		clauses: c.approvers ?? [],
+		...c.reason !== void 0 && { reason: c.reason },
+		...c.timeout !== void 0 && { timeoutSeconds: c.timeout },
+		when: c.when ?? "always"
 	};
 }
 //#endregion
-export { normalizeRequireApproval };
+export { normalizeApproval };
 
 //# sourceMappingURL=approval.js.map

package/dist/context.d.ts

@@ -3,6 +3,7 @@ import type { MatrixValues } from './matrix/types.js';
 import type { EventEmitOptions } from './events/types.js';
 import type { StepSecrets } from './secrets.js';
 import type { KiciApi } from './api-types.js';
+import type { FanoutPosition } from './fanout-context.js';
 /** Logger interface for step execution */
 export interface Logger {
     info(message: string, ...args: unknown[]): void;
@@ -115,6 +116,12 @@ export interface StepContext<TInputs = Record<string, unknown>> {
     addPath(dir: string): void;
     /** Typed inputs from dependencies */
     inputs: TInputs;
+    /**
+     * Operator-supplied, validated + coerced workflow-dispatch inputs (from `dispatch({ inputs })`).
+     * Distinct from `inputs` (typed outputs from `needs` dependencies). Empty when none declared.
+     * Prefer the typed `defineDispatchInputs(...).from(ctx)` accessor for per-key types.
+     */
+    dispatchInputs: Readonly<Record<string, string | number | boolean | null>>;
     /** Current workflow metadata */
     workflow: WorkflowInfo;
     /** Current job metadata */
@@ -137,6 +144,12 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * platform, arch). Set only for jobs that use `runsOnAll`. Undefined otherwise.
      */
     agent?: AgentInfo;
+    /**
+     * Position of this child within its fan-out (a `runsOnAll` host or a matrix
+     * combination), deterministically ordered (host: by `agentId`; matrix: by
+     * variant label). Undefined on a non-fan-out job.
+     */
+    fanout?: FanoutPosition;
     /**
      * Raw webhook payload from the git provider.
      * Contains the full, unmodified payload as received from the webhook.
@@ -261,6 +274,15 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * the agent digests with SHA-256.
      */
     attestProvenance(opts: import('./provenance-types.js').AttestProvenanceOptions): Promise<import('./provenance-types.js').AttestProvenanceResult>;
+    /**
+     * Upstream needs resolved for this job, keyed by upstream job or group name.
+     * `ctx.needs.<job>.result` is the upstream's outputs proxy and
+     * `ctx.needs.<job>.status` its terminal status (`success | failed | skipped |
+     * …`). A group / matrix / `runsOnAll` fan-out upstream is an ordered array of
+     * `{ name, result, status }`, one entry per child. Undefined for a job with no
+     * declared `needs`.
+     */
+    needs?: import('./needs-context.js').NeedsContext;
 }
 export {};
 //# sourceMappingURL=context.d.ts.map

package/dist/dynamic-group.d.ts

@@ -6,22 +6,24 @@
  *
  * Usage in workflow definition:
  *   needs: [dynamicGroup('test-shards')]
- *   needs: [dynamicGroup('test-shards', { ifFailed: 'run' })]
+ *   needs: [dynamicGroup('test-shards', { when: 'always' })]
  */
+import type { NeedsWhenInput } from './types.js';
 declare const DYNAMIC_GROUP_TAG: unique symbol;
 export interface DynamicGroupRef {
     readonly [DYNAMIC_GROUP_TAG]: true;
     readonly group: string;
-    readonly ifFailed?: 'skip' | 'run';
+    /** Run condition for the edge: keyword sugar or a raw upstream-status set. */
+    readonly when?: NeedsWhenInput;
 }
 /**
  * Create a reference to a dynamic job group for use in a static job's `needs` array.
  *
  * @param name - The group name (must match the name used in `dynamicJob(name, fn)`)
- * @param opts - Optional failure policy override
+ * @param opts - Optional run condition for the edge
  */
 export declare function dynamicGroup(name: string, opts?: {
-    ifFailed?: 'skip' | 'run';
+    when?: NeedsWhenInput;
 }): DynamicGroupRef;
 /** Type guard to check if a value is a DynamicGroupRef. */
 export declare function isDynamicGroupRef(value: unknown): value is DynamicGroupRef;

package/dist/dynamic-group.js

@@ -1,27 +1,17 @@
 import "./chunk-BTugEXQM.js";
 //#region src/dynamic-group.ts
-/**
-* Dynamic group helpers for cross-domain needs.
-*
-* A DynamicGroupRef allows static jobs to declare a dependency on a dynamic
-* job group by name, without knowing the concrete generated job names.
-*
-* Usage in workflow definition:
-*   needs: [dynamicGroup('test-shards')]
-*   needs: [dynamicGroup('test-shards', { ifFailed: 'run' })]
-*/
 const DYNAMIC_GROUP_TAG = Symbol.for("kici:dynamicGroup");
 /**
 * Create a reference to a dynamic job group for use in a static job's `needs` array.
 *
 * @param name - The group name (must match the name used in `dynamicJob(name, fn)`)
-* @param opts - Optional failure policy override
+* @param opts - Optional run condition for the edge
 */
 function dynamicGroup(name, opts) {
 	return {
 		[DYNAMIC_GROUP_TAG]: true,
 		group: name,
-		...opts?.ifFailed && { ifFailed: opts.ifFailed }
+		...opts?.when !== void 0 && { when: opts.when }
 	};
 }
 /** Type guard to check if a value is a DynamicGroupRef. */

package/dist/fanout-context.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Deterministic position of a fan-out child within its fan-out.
+ *
+ * A fan-out child is one of:
+ * - a `runsOnAll` host execution (one pinned execution per matching roster host), or
+ * - a matrix combination (one execution per expanded combination).
+ *
+ * The order is deterministic: host fan-out is sorted by `agentId`, matrix fan-out by
+ * its variant label, so `first` is always reproducible across re-runs.
+ */
+export interface FanoutPosition {
+    /** 0-based position in the deterministically-ordered fan-out. */
+    index: number;
+    /** Number of children in this fan-out. */
+    total: number;
+    /** Whether this is the first child (`index === 0`). */
+    first: boolean;
+    /** Whether this is the last child (`index === total - 1`). */
+    last: boolean;
+}
+//# sourceMappingURL=fanout-context.d.ts.map

package/dist/fanout-context.js

@@ -0,0 +1,2 @@
+import "./chunk-BTugEXQM.js";
+export {};

package/dist/host-restart.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Workflow-level host restart + wait-for-host-alive steps.
+ *
+ * KiCI agents run ON each host while executing a job, so a workflow can reboot
+ * the machine it runs on (the Ansible `reboot` + `wait_for_connection` pattern,
+ * adapted to KiCI's no-remote-exec model). The flow is job-boundary:
+ *
+ * - `restartHost()` is the LAST step of a "restart" job. It signals the
+ *   orchestrator that this host is about to reboot (which holds the pinned
+ *   post-restart job and treats the imminent disconnect as expected), reports
+ *   success, and the agent issues the OS reboot once the step completes.
+ * - The post-restart work is a SEPARATE job pinned to the same host
+ *   (`runsOn: [hostId]`) that `needs` the restart job. The orchestrator holds
+ *   it until the host completes a reboot cycle, then dispatches it.
+ * - `waitForHostAlive(probe)` is the optional first step of that post-restart
+ *   job: the "host is back" guarantee comes free from the pinned-hold (the job
+ *   only dispatches after the agent reconnects); this step adds a
+ *   service-readiness gate for hosts where "agent connected" ≠ "services ready".
+ */
+import type { Step } from './types.js';
+export interface WaitForHostAliveOptions {
+    /** Step name surfaced in logs. Defaults to 'wait-for-host-alive'. */
+    name?: string;
+    /** Time between successive probe invocations, ms. Defaults to 3000. */
+    intervalMs?: number;
+    /** Total time budget for readiness, ms. Defaults to 300000 (5 min). */
+    timeoutMs?: number;
+}
+/**
+ * Optional first step of a post-restart job. Polls a readiness probe until it
+ * resolves (services back up after a reboot). The host being reconnected is
+ * already guaranteed by the pinned-hold; this gates on service readiness.
+ *
+ * A probe that throws/rejects keeps polling (the `waitFor` swallow-errors
+ * default — the "poll until healthy" pattern). Any non-null resolution means
+ * "ready". Exceeding `timeoutMs` fails the step ("services did not come up").
+ */
+export declare function waitForHostAlive(probe: () => Promise<unknown> | unknown, opts?: WaitForHostAliveOptions): Step<unknown>;
+export interface RestartHostOptions {
+    /**
+     * Max time the orchestrator waits for the host to return after the reboot,
+     * ms. Defaults to the orchestrator's `KICI_HOST_REBOOT_DEADLINE_MS`.
+     */
+    deadlineMs?: number;
+}
+/**
+ * Reboot the host this job runs on. MUST be the last step of a "restart" job;
+ * the post-restart work goes in a separate job that `needs` this one and is
+ * pinned to the same host (`runsOn: [hostId]`). The orchestrator holds that job
+ * until the host completes a reboot cycle, then dispatches it.
+ *
+ * The step signals the orchestrator (reboot-pending) and reports success; the
+ * agent issues the actual OS reboot after the step completes. Rebooting needs
+ * host privilege: if the OS reboot primitive is denied, the step fails with a
+ * clear privilege error and the orchestrator clears the reboot-pending flag.
+ */
+export declare function restartHost(opts?: RestartHostOptions): Step<void>;
+//# sourceMappingURL=host-restart.d.ts.map

package/dist/host-restart.js

@@ -0,0 +1,63 @@
+import "./chunk-BTugEXQM.js";
+import { step } from "./step.js";
+import { waitForStep } from "./wait-for.js";
+//#region src/host-restart.ts
+/**
+* Workflow-level host restart + wait-for-host-alive steps.
+*
+* KiCI agents run ON each host while executing a job, so a workflow can reboot
+* the machine it runs on (the Ansible `reboot` + `wait_for_connection` pattern,
+* adapted to KiCI's no-remote-exec model). The flow is job-boundary:
+*
+* - `restartHost()` is the LAST step of a "restart" job. It signals the
+*   orchestrator that this host is about to reboot (which holds the pinned
+*   post-restart job and treats the imminent disconnect as expected), reports
+*   success, and the agent issues the OS reboot once the step completes.
+* - The post-restart work is a SEPARATE job pinned to the same host
+*   (`runsOn: [hostId]`) that `needs` the restart job. The orchestrator holds
+*   it until the host completes a reboot cycle, then dispatches it.
+* - `waitForHostAlive(probe)` is the optional first step of that post-restart
+*   job: the "host is back" guarantee comes free from the pinned-hold (the job
+*   only dispatches after the agent reconnects); this step adds a
+*   service-readiness gate for hosts where "agent connected" ≠ "services ready".
+*/
+/**
+* Optional first step of a post-restart job. Polls a readiness probe until it
+* resolves (services back up after a reboot). The host being reconnected is
+* already guaranteed by the pinned-hold; this gates on service readiness.
+*
+* A probe that throws/rejects keeps polling (the `waitFor` swallow-errors
+* default — the "poll until healthy" pattern). Any non-null resolution means
+* "ready". Exceeding `timeoutMs` fails the step ("services did not come up").
+*/
+function waitForHostAlive(probe, opts = {}) {
+	return waitForStep(opts.name ?? "wait-for-host-alive", {
+		check: async () => {
+			return await probe() ?? true;
+		},
+		intervalMs: opts.intervalMs ?? 3e3,
+		timeoutMs: opts.timeoutMs ?? 3e5
+	});
+}
+/**
+* Reboot the host this job runs on. MUST be the last step of a "restart" job;
+* the post-restart work goes in a separate job that `needs` this one and is
+* pinned to the same host (`runsOn: [hostId]`). The orchestrator holds that job
+* until the host completes a reboot cycle, then dispatches it.
+*
+* The step signals the orchestrator (reboot-pending) and reports success; the
+* agent issues the actual OS reboot after the step completes. Rebooting needs
+* host privilege: if the OS reboot primitive is denied, the step fails with a
+* clear privilege error and the orchestrator clears the reboot-pending flag.
+*/
+function restartHost(opts = {}) {
+	return step("restart-host", { run: async (ctx) => {
+		ctx.log.info("Requesting host reboot…");
+		await ctx.kici.host.requestReboot({ deadlineMs: opts.deadlineMs });
+		ctx.log.info("Reboot acknowledged; host will reboot after this step completes.");
+	} });
+}
+//#endregion
+export { restartHost, waitForHostAlive };
+
+//# sourceMappingURL=host-restart.js.map

package/dist/idempotent.d.ts

@@ -21,7 +21,8 @@
  *   whose run function executes `idempotent(...)` and propagates ctx.log
  *   into the runner's status sink.
  */
-import type { Step } from './types.js';
+import type { Step, StepOptionsBase } from './types.js';
+import type { StepContext } from './context.js';
 export interface IdempotentOptions<TDrift, TInSync = void, TApplied = void> {
     /** Optional name surfaced in status lines and error messages. */
     name?: string;
@@ -68,4 +69,34 @@ export declare function idempotent<TDrift, TInSync = void, TApplied = void>(opts
  * The step's typed return value is the IdempotentResult union.
  */
 export declare function idempotentStep<TDrift, TInSync = void, TApplied = void>(name: string, opts: Omit<IdempotentOptions<TDrift, TInSync, TApplied>, 'name' | 'log'>): Step<IdempotentResult<TDrift, TInSync, TApplied>>;
+/**
+ * Options for {@link checkStep}. The same shape as `idempotentStep`'s options,
+ * except `apply` and `whenInSync` receive `ctx` first (matching the `step()`
+ * check facet's `run(ctx, drift)` form) so the apply logic has access to
+ * `ctx.$` / `ctx.log` / `ctx.secrets`. The remaining `StepOptionsBase`
+ * passthroughs (`continueOnError`, `timeout`, `rules`, `outputs`, `retry`, …)
+ * are forwarded to the underlying step.
+ */
+export interface CheckStepOptions<TDrift, TInSync = void, TApplied = void> extends Omit<StepOptionsBase, 'onCancel' | 'cleanup' | 'approval'> {
+    /** Read-only inspection: drift if apply would change state, or null if in sync. */
+    check: (ctx: StepContext) => Promise<TDrift | null>;
+    /** Brings the system to the desired state. Runs only in apply mode (skipped under `kici run --check`). */
+    apply: (ctx: StepContext, drift: TDrift) => Promise<TApplied>;
+    /** Required: human-readable summary of what apply() would do; shown in check-mode drift output. */
+    summarize: (drift: TDrift) => string;
+    /** Runs when check() returns null (already in sync). */
+    whenInSync?: (ctx: StepContext) => Promise<TInSync>;
+}
+/**
+ * Factory returning a check-facet SDK Step — the check-mode-aware sibling of
+ * {@link idempotentStep}. Unlike `idempotentStep` (which always applies on
+ * drift), a `checkStep` respects the run-level check mode: `kici run --check`
+ * reports the drift and skips `apply`, while apply mode applies it.
+ *
+ * It desugars to the `step()` check facet
+ * (`run: (ctx, drift) => apply(ctx, drift)`), so it inherits the agent
+ * step-loop and local-executor check-mode drive for free — no engine, agent,
+ * orchestrator, or lockfile change.
+ */
+export declare function checkStep<TDrift, TInSync = void, TApplied = void>(name: string, options: CheckStepOptions<TDrift, TInSync, TApplied>): Step<TApplied | TInSync>;
 //# sourceMappingURL=idempotent.d.ts.map

package/dist/idempotent.js

@@ -71,7 +71,32 @@ function idempotentStep(name, opts) {
 		log: (line) => ctx.log.info(line)
 	}) });
 }
+/**
+* Factory returning a check-facet SDK Step — the check-mode-aware sibling of
+* {@link idempotentStep}. Unlike `idempotentStep` (which always applies on
+* drift), a `checkStep` respects the run-level check mode: `kici run --check`
+* reports the drift and skips `apply`, while apply mode applies it.
+*
+* It desugars to the `step()` check facet
+* (`run: (ctx, drift) => apply(ctx, drift)`), so it inherits the agent
+* step-loop and local-executor check-mode drive for free — no engine, agent,
+* orchestrator, or lockfile change.
+*/
+function checkStep(name, options) {
+	return step(name, {
+		check: options.check,
+		summarize: options.summarize,
+		run: (ctx, drift) => options.apply(ctx, drift),
+		...options.whenInSync && { whenInSync: options.whenInSync },
+		...options.outputs !== void 0 && { outputs: options.outputs },
+		...options.continueOnError !== void 0 && { continueOnError: options.continueOnError },
+		...options.timeout !== void 0 && { timeout: options.timeout },
+		...options.retry !== void 0 && { retry: options.retry },
+		...options.cache !== void 0 && { cache: options.cache },
+		...options.rules !== void 0 && { rules: options.rules }
+	});
+}
 //#endregion
-export { idempotent, idempotentStep };
+export { checkStep, idempotent, idempotentStep };
 
 //# sourceMappingURL=idempotent.js.map

package/dist/index.d.ts

@@ -1,21 +1,21 @@
 export { step } from './step.js';
 export { job } from './job.js';
 export { workflow } from './workflow.js';
-export { normalizeRequireApproval } from './approval.js';
-export type { RequireApproval, ApproverClause, NormalizedRequireApproval } from './approval.js';
-export { pr, push, tag, comment, review, reviewComment, release, dispatch, create, delete as delete, status, workflowRun, fork, star, watch, webhook, kiciEvent, workflowComplete, jobComplete, genericWebhook, schedule, lifecycle, } from './triggers/index.js';
-export type { TriggerConfig, PrTriggerConfig, PushTriggerConfig, TagTriggerConfig, CommentTriggerConfig, ReviewTriggerConfig, ReviewCommentTriggerConfig, ReleaseTriggerConfig, DispatchTriggerConfig, CreateTriggerConfig, DeleteTriggerConfig, StatusTriggerConfig, WorkflowRunTriggerConfig, ForkTriggerConfig, StarTriggerConfig, WatchTriggerConfig, WebhookTriggerConfig, BranchPattern, BodyMatchPattern, PrEvent, PushEvent, PrConfigInput, PushConfigInput, TagConfigInput, CommentConfigInput, CommentAction, CommentSource, ReviewConfigInput, ReviewAction, ReviewState, ReviewCommentConfigInput, ReviewCommentAction, ReleaseConfigInput, ReleaseAction, DispatchConfigInput, CreateConfigInput, DeleteConfigInput, RefType, StatusConfigInput, StatusState, WorkflowRunConfigInput, WorkflowRunAction, ForkConfigInput, StarConfigInput, StarAction, WatchConfigInput, WatchAction, WebhookConfigInput, KiciEventConfigInput, KiciEventTriggerConfig, WorkflowCompleteConfigInput, WorkflowCompleteTriggerConfig, WorkflowCompleteStatus, JobCompleteConfigInput, JobCompleteTriggerConfig, JobCompleteStatus, GenericWebhookConfigInput, GenericWebhookTriggerConfig, GenericWebhookAuthMethod, GenericWebhookHmacAuth, GenericWebhookApiKeyAuth, GenericWebhookAuth, ScheduleConfigInput, ScheduleTriggerConfig, LifecycleEvent, LifecycleConfigInput, LifecycleTriggerConfig, } from './triggers/index.js';
+export { normalizeApproval } from './approval.js';
+export type { ApprovalConfig, ApprovalWhen, ApproverClause, NormalizedApproval, } from './approval.js';
+export { pr, push, tag, comment, review, reviewComment, release, dispatch, create, delete as delete, status, workflowRun, fork, star, watch, webhook, kiciEvent, workflowComplete, jobComplete, genericWebhook, schedule, lifecycle, defineDispatchInputs, } from './triggers/index.js';
+export type { DefinedDispatchInputs, InferDispatchInputs, DispatchInputsMap, TriggerConfig, PrTriggerConfig, PushTriggerConfig, TagTriggerConfig, CommentTriggerConfig, ReviewTriggerConfig, ReviewCommentTriggerConfig, ReleaseTriggerConfig, DispatchTriggerConfig, CreateTriggerConfig, DeleteTriggerConfig, StatusTriggerConfig, WorkflowRunTriggerConfig, ForkTriggerConfig, StarTriggerConfig, WatchTriggerConfig, WebhookTriggerConfig, BranchPattern, BodyMatchPattern, PrEvent, PushEvent, PrConfigInput, PushConfigInput, TagConfigInput, CommentConfigInput, CommentAction, CommentSource, ReviewConfigInput, ReviewAction, ReviewState, ReviewCommentConfigInput, ReviewCommentAction, ReleaseConfigInput, ReleaseAction, DispatchConfigInput, CreateConfigInput, DeleteConfigInput, RefType, StatusConfigInput, StatusState, WorkflowRunConfigInput, WorkflowRunAction, ForkConfigInput, StarConfigInput, StarAction, WatchConfigInput, WatchAction, WebhookConfigInput, KiciEventConfigInput, KiciEventTriggerConfig, WorkflowCompleteConfigInput, WorkflowCompleteTriggerConfig, WorkflowCompleteStatus, JobCompleteConfigInput, JobCompleteTriggerConfig, JobCompleteStatus, GenericWebhookConfigInput, GenericWebhookTriggerConfig, GenericWebhookAuthMethod, GenericWebhookHmacAuth, GenericWebhookApiKeyAuth, GenericWebhookAuth, ScheduleConfigInput, ScheduleTriggerConfig, LifecycleEvent, LifecycleConfigInput, LifecycleTriggerConfig, } from './triggers/index.js';
 export { onCancel, cleanup, onSuccess, onFailure, beforeStep, afterStep } from './hooks/index.js';
 export type { HookConfig, HookFn, HookInput, HookContext, OutcomeMetadata } from './hooks/index.js';
-export { rule, skip } from './rules/index.js';
+export { rule, skip, onlyOnFirstHost, onlyOnLastHost, onlyOnFanoutIndex } from './rules/index.js';
 export { evaluateRules } from './rules/index.js';
 export { isEventType } from './rules/index.js';
 export type { Rule, RuleContext, RuleCheckFn, RuleResult, EventPayload, RuleEvaluationResult, EventBase, PullRequestEventPayload, PushEventPayload, TagEventPayload, CommentEventPayload, ReviewEventPayload, ReviewCommentEventPayload, ReleaseEventPayload, DispatchEventPayload, CreateEventPayload, DeleteEventPayload, StatusEventPayload, WorkflowRunEventPayload, ForkEventPayload, StarEventPayload, WatchEventPayload, WebhookEventPayload, KiciEventPayload, WorkflowCompleteEventPayload, JobCompleteEventPayload, GenericWebhookEventPayload, ScheduleEventPayload, LifecycleEventPayload, GitHubRepository, GitHubUser, GitHubPullRequest, GitHubCommit, GitHubComment, GitHubReview, GitHubRelease, } from './rules/index.js';
 export { validateDag } from './validation/index.js';
 export type { DagNode, DagValidationResult } from './validation/index.js';
-export type { SourceLocation, OutputProxy, Step, StepOptions, StepOptionsBase, StepOptionsPlain, StepOptionsWithCheck, StepRunFn, BareStepFn, StepInput, OutputSchema, InferOutputs, Job, JobOptions, GenericInitConfig, MiseInitConfig, InitPreset, InitItem, InitConfig, ContainerConfig, RunsOnSelector, RunsOn, Workflow, WorkflowOptions, Registry, Trigger, DynamicJobFn, DynamicJobContext, JobOrFactory, } from './types.js';
+export type { SourceLocation, OutputProxy, Step, StepOptions, StepOptionsBase, StepOptionsPlain, StepOptionsWithCheck, StepRunFn, RetryConfig, NormalizedRetry, BareStepFn, StepInput, OutputSchema, InferOutputs, Job, JobOptions, GenericInitConfig, MiseInitConfig, InitPreset, InitItem, InitConfig, ContainerConfig, RunsOnSelector, RunsOn, RunsOnPick, Workflow, WorkflowOptions, Registry, Trigger, DynamicJobFn, DynamicJobContext, JobOrFactory, } from './types.js';
 export { isDynamicJobFn, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, } from './types.js';
-export type { TaggedDynamicJobFn, ResultAwareDynamicJobConfig, ResultAwareDynamicJobFn, DynamicJobNeed, } from './types.js';
+export type { TaggedDynamicJobFn, ResultAwareDynamicJobConfig, ResultAwareDynamicJobFn, DynamicJobNeed, NeedsWhen, NeedsWhenInput, } from './types.js';
 export { buildNeedsContext } from './needs-context.js';
 export type { UpstreamSnapshot, NeedsContext, NeedEntry, GroupNeedEntry } from './needs-context.js';
 export { CacheSpecSchema, normalizeCacheSpecs } from './cache-types.js';
@@ -27,8 +27,9 @@ export { dynamicGroup, isDynamicGroupRef, DYNAMIC_GROUP_TAG } from './dynamic-gr
 export type { DynamicGroupRef } from './dynamic-group.js';
 export type { StepContext, Logger, WorkflowInfo, JobInfo, AgentInfo, MatrixJobOutputs, HostJobOutputs, RepoInfo, StepSecretsTyped, KnownSecretKeys, } from './context.js';
 export { isMatrixJobOutputs, isHostJobOutputs } from './context.js';
+export type { FanoutPosition } from './fanout-context.js';
 export { buildKiciApi } from './api-types.js';
-export type { KiciApi, KiciApiTransport, InfrastructureApi, InfrastructureListResult, InventoryApi, HostInventoryEntry, InventorySelector, } from './api-types.js';
+export type { KiciApi, KiciApiTransport, InfrastructureApi, InfrastructureListResult, InventoryApi, HostApi, HostInventoryEntry, InventorySelector, } from './api-types.js';
 export { SecretNotFoundError } from './errors.js';
 export { createStepSecrets } from './secrets.js';
 export type { StepSecrets, TrackedStepSecrets, SecretMeta, SecretFileOptions, MountedFile, StepSecretsFileHost, StepSecretsFileWiring, StepSecretsHandle, StepSecretMountKind, StepSecretMountRecord, } from './secrets.js';
@@ -42,9 +43,11 @@ export type { EventDefinition } from './events/index.js';
 export type { EventEmitOptions } from './events/index.js';
 export { fixture } from './fixture.js';
 export type { Fixture, FixtureOptions } from './fixture.js';
-export { idempotent, idempotentStep } from './idempotent.js';
-export type { IdempotentOptions, IdempotentResult } from './idempotent.js';
+export { idempotent, idempotentStep, checkStep } from './idempotent.js';
+export type { IdempotentOptions, IdempotentResult, CheckStepOptions } from './idempotent.js';
 export { waitFor, waitForStep, WaitForTimeoutError } from './wait-for.js';
 export type { WaitForOptions, WaitForResult } from './wait-for.js';
+export { waitForHostAlive, restartHost } from './host-restart.js';
+export type { WaitForHostAliveOptions, RestartHostOptions } from './host-restart.js';
 export { z } from 'zod';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,6 +1,6 @@
 import "./chunk-BTugEXQM.js";
 import { buildKiciApi } from "./api-types.js";
-import { normalizeRequireApproval } from "./approval.js";
+import { normalizeApproval } from "./approval.js";
 import { CacheSpecSchema, normalizeCacheSpecs } from "./cache-types.js";
 import { isHostJobOutputs, isMatrixJobOutputs } from "./context.js";
 import { DYNAMIC_GROUP_TAG, dynamicGroup, isDynamicGroupRef } from "./dynamic-group.js";
@@ -8,7 +8,9 @@ import { SecretNotFoundError } from "./errors.js";
 import { fixture } from "./fixture.js";
 import { createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, getJobOutputsMap, getStepOutputsMap, getStepRefMap, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "./outputs.js";
 import { step } from "./step.js";
-import { idempotent, idempotentStep } from "./idempotent.js";
+import { WaitForTimeoutError, waitFor, waitForStep } from "./wait-for.js";
+import { restartHost, waitForHostAlive } from "./host-restart.js";
+import { checkStep, idempotent, idempotentStep } from "./idempotent.js";
 import { job } from "./job.js";
 import { workflow } from "./workflow.js";
 import { pr } from "./triggers/pr.js";
@@ -33,9 +35,10 @@ import { jobComplete } from "./triggers/job-complete.js";
 import { genericWebhook } from "./triggers/generic-webhook.js";
 import { schedule } from "./triggers/schedule.js";
 import { lifecycle } from "./triggers/lifecycle.js";
+import { defineDispatchInputs } from "./triggers/dispatch-inputs.js";
 import "./triggers/index.js";
 import { afterStep, beforeStep, cleanup, onCancel, onFailure, onSuccess } from "./hooks/index.js";
-import { rule, skip } from "./rules/rule.js";
+import { onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip } from "./rules/rule.js";
 import { evaluateRules } from "./rules/evaluator.js";
 import { isEventType } from "./events/event-payloads.js";
 import "./rules/index.js";
@@ -50,6 +53,5 @@ import { applyIncludeExclude, expandMatrix } from "./matrix/expand.js";
 import "./matrix/index.js";
 import { defineEvent } from "./events/define-event.js";
 import "./events/index.js";
-import { WaitForTimeoutError, waitFor, waitForStep } from "./wait-for.js";
 import { z } from "zod";
-export { CacheSpecSchema, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, applyIncludeExclude, beforeStep, buildKiciApi, buildNeedsContext, cleanup, comment, create, createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isHostJobOutputs, isMatrixJobOutputs, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeCacheSpecs, normalizeRequireApproval, onCancel, onFailure, onSuccess, pr, provenanceSubjectIsPath, push, release, resolveJobOutputs, resolveStepOutputs, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, z };
+export { CacheSpecSchema, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, applyIncludeExclude, beforeStep, buildKiciApi, buildNeedsContext, checkStep, cleanup, comment, create, createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineDispatchInputs, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isHostJobOutputs, isMatrixJobOutputs, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeApproval, normalizeCacheSpecs, onCancel, onFailure, onSuccess, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, pr, provenanceSubjectIsPath, push, release, resolveJobOutputs, resolveStepOutputs, restartHost, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForHostAlive, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, z };