@kici-dev/sdk 0.1.26 → 0.2.0

package/dist/api-types.d.ts

@@ -74,6 +74,15 @@ export interface HostApi {
         deadlineMs?: number;
     }): Promise<void>;
 }
+/** Version-convergence status for a fleet host (the availability-gate probe). */
+export interface AgentVersionStatus {
+    /** The orchestrator's own version — the convergence target. */
+    targetVersion: string;
+    /** The version last staged onto the host, or null when never staged. */
+    stagedVersion: string | null;
+    /** True only when the target's payload objects exist for the host's platform. */
+    available: boolean;
+}
 export interface BootstrapApi {
     /**
      * Bring up a temporary privileged init-runner on a declared-but-un-agented
@@ -107,6 +116,25 @@ export interface BootstrapApi {
         port?: number;
         command?: string;
     }): Promise<void>;
+    /**
+     * Read a fleet host's agent-version convergence status: the orchestrator's
+     * target version, the version last staged on the host, and whether the
+     * target's self-contained payloads are available for the host's platform. The
+     * availability-gate probe the `agentVersionConverge()` check-step calls; a
+     * `false` `available` means the convergence HOLDS the host (never a skew).
+     */
+    agentVersionStatus(targetAgentId: string): Promise<AgentVersionStatus>;
+    /**
+     * Re-stage a fleet host onto the orchestrator's version and restart its agent,
+     * driven by THIS (ops) agent as an external actor over SSH — no
+     * self-update-handoff. Availability-gated server-side: refuses when the target
+     * version's payloads are unavailable. Returns `{ restaged: false }` when the
+     * host is already on the target version. The step calling this must run on an
+     * agent holding `kici:capability:ssh-transport`.
+     */
+    restageAgent(targetAgentId: string): Promise<{
+        restaged: boolean;
+    }>;
 }
 export interface KiciApi {
     /** Query orchestrator infrastructure (scalers, agents). */

package/dist/api-types.js

@@ -43,7 +43,9 @@ function buildKiciApi(transport, jobCtx) {
 			preBootSend: (targetAgentId, opts) => transport("kici.preBootSend", {
 				targetAgentId,
 				...opts
-			})
+			}),
+			agentVersionStatus: (targetAgentId) => transport("kici.agentVersionStatus", { targetAgentId }),
+			restageAgent: (targetAgentId) => transport("kici.restageAgent", { targetAgentId })
 		}
 	};
 }

package/dist/approval.d.ts

@@ -1,10 +1,3 @@
-/**
- * Workflow-author API for declaring a manual approval gate at step, job, or
- * 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 = {
     team: string;
@@ -26,7 +19,9 @@ export type ApprovalWhen = 'always' | 'drift';
  * - `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 `when`, a human `reason`, and a
- *   per-gate `timeout` (seconds) that overrides the org-default expiry.
+ *   per-gate `timeout` that overrides the org-default expiry. The `timeout`
+ *   must be a positive integer number of seconds; a non-positive or non-finite
+ *   value is rejected at compile time.
  */
 export type ApprovalConfig = true | ApproverClause[] | {
     when?: ApprovalWhen;

package/dist/approval.js

@@ -1,6 +1,14 @@
 import "./rolldown-runtime-ClRpJifh.js";
+import { approvalTimeoutSecondsSchema } from "@kici-dev/engine";
 //#region src/approval.ts
 /**
+* Workflow-author API for declaring a manual approval gate at step, job, or
+* 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'`).
+*/
+/**
 * Normalize any `ApprovalConfig` form into
 * `{ clauses, reason?, timeoutSeconds?, when }`. `when` defaults to `'always'`.
 */
@@ -13,6 +21,7 @@ function normalizeApproval(c) {
 		clauses: c,
 		when: "always"
 	};
+	if (c.timeout !== void 0 && !approvalTimeoutSecondsSchema.safeParse(c.timeout).success) throw new Error(`approval.timeout must be a positive integer number of seconds, got ${c.timeout}`);
 	return {
 		clauses: c.approvers ?? [],
 		...c.reason !== void 0 && { reason: c.reason },

package/dist/artifacts-types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Artifact name constraints: a filesystem/URL-safe token. The schema is hosted
+ * in `@kici-dev/engine` because it is a trust-boundary contract the orchestrator
+ * enforces on every inbound upload, not only an SDK-side call check. Re-exported
+ * here unchanged, so the public SDK surface is stable and a name the SDK accepts
+ * is exactly a name the orchestrator accepts.
+ */
+export { ArtifactNameSchema, ARTIFACT_NAME_MAX_LENGTH } from '@kici-dev/engine';
+/** Result of an artifact upload or download: the packed size and content hash. */
+export interface ArtifactResult {
+    /** Size of the packed tarball in bytes. */
+    size: number;
+    /** SHA-256 (hex) of the packed tarball bytes. */
+    sha256: string;
+}
+/**
+ * Imperative artifacts API exposed on `StepContext` as `ctx.artifacts`.
+ *
+ * Artifacts are named, durable build deliverables shared between jobs of the
+ * same run and surfaced in the dashboard run detail. Unlike the cache
+ * (content-keyed, eviction-tolerant speedup) and job outputs (small JSON passed
+ * via `needs`), an artifact is a first-class deliverable:
+ *
+ * - **Immutable per run:** the first upload of a name within a run wins; a
+ *   duplicate name fails loudly (parallel writers become a deterministic error,
+ *   never a silent clobber).
+ * - **Downloadable by any later job** of the same run, and by a human from the
+ *   run detail page.
+ */
+export interface ArtifactsApi {
+    /**
+     * Pack the given paths (repo-root-relative or `~`-prefixed) into a tarball
+     * and upload it as a named artifact. The first upload of a name in a run
+     * wins; a duplicate name, an over-cap size, or an exhausted quota throws with
+     * the rejection reason. Returns the packed size + sha256.
+     */
+    upload(name: string, paths: string[]): Promise<ArtifactResult>;
+    /**
+     * Download a named artifact uploaded earlier in this run and extract it into
+     * `destDir` (default: the step's working directory). Throws when the name was
+     * never uploaded in this run. Returns the artifact's size + sha256.
+     */
+    download(name: string, destDir?: string): Promise<ArtifactResult>;
+}
+//# sourceMappingURL=artifacts-types.d.ts.map

package/dist/artifacts-types.js

@@ -0,0 +1,3 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { ARTIFACT_NAME_MAX_LENGTH, ArtifactNameSchema } from "@kici-dev/engine";
+export { ARTIFACT_NAME_MAX_LENGTH, ArtifactNameSchema };

package/dist/context.d.ts

@@ -1,6 +1,10 @@
 import type { $ as Shell } from 'zx';
+import type { z } from 'zod';
+import type { TempHandle } from '@kici-dev/core/tmp';
+import type { Job } from './types.js';
 import type { MatrixValues } from './matrix/types.js';
 import type { EventEmitOptions } from './events/types.js';
+import type { EventDefinition } from './events/define-event.js';
 import type { StepSecrets } from './secrets.js';
 import type { KiciApi } from './api-types.js';
 import type { FanoutPosition } from './fanout-context.js';
@@ -37,7 +41,7 @@ export interface AgentInfo {
 /**
  * Outputs of a matrix job as seen by a downstream `needs:` consumer.
  * A downstream that consumes a matrix upstream receives this envelope instead of
- * a flat outputs object, identically under `kici run local` and the remote path.
+ * a flat outputs object, identically under `kici run --local` and the remote path.
  */
 export interface MatrixJobOutputs<T = Record<string, unknown>> {
     /** Keyed by the combination suffix (the text inside `(...)` of the child name). */
@@ -46,7 +50,7 @@ export interface MatrixJobOutputs<T = Record<string, unknown>> {
     merged: T;
 }
 /** Runtime discriminator: true when `ctx.jobOutputs(ref)` returned a matrix envelope. */
-export declare function isMatrixJobOutputs(value: Record<string, unknown> | MatrixJobOutputs | HostJobOutputs): value is MatrixJobOutputs;
+export declare function isMatrixJobOutputs<T = Record<string, unknown>>(value: T | MatrixJobOutputs<T> | HostJobOutputs<T>): value is MatrixJobOutputs<T>;
 /**
  * Outputs of a `runsOnAll` host-fanout job as seen by a downstream `needs:`
  * consumer. Keyed by hostname. Unlike {@link MatrixJobOutputs}, the summary does
@@ -65,7 +69,7 @@ export interface HostJobOutputs<T = Record<string, unknown>> {
     };
 }
 /** Runtime discriminator: true when `ctx.jobOutputs(ref)` returned a host envelope. */
-export declare function isHostJobOutputs(value: Record<string, unknown> | MatrixJobOutputs | HostJobOutputs): value is HostJobOutputs;
+export declare function isHostJobOutputs<T = Record<string, unknown>>(value: T | MatrixJobOutputs<T> | HostJobOutputs<T>): value is HostJobOutputs<T>;
 /**
  * Augmentable interface for known secret keys.
  * When augmented via `kici types` (.d.ts generation), narrows get/expose key parameter.
@@ -82,15 +86,24 @@ type IsAugmented<T> = [keyof T] extends [never] ? false : true;
  * Step secrets with async get/expose accessors.
  * Use ctx.secrets.get('KEY') to retrieve a value, ctx.secrets.expose('KEY') to inject into env.
  *
- * When KnownSecretKeys is augmented (via .d.ts generation), narrows get/expose key parameter.
- * When empty (no augmentation), falls back to StepSecrets with string keys.
+ * When KnownSecretKeys is augmented (via .d.ts generation), only the `get`/`expose`
+ * key parameter is narrowed to the known keys — every other accessor
+ * (`has`, `getMeta`, `list`, `mountFile`, `exposeFile`) is preserved verbatim
+ * from StepSecrets. When empty (no augmentation), the whole StepSecrets surface
+ * accepts any string key.
  */
-export type StepSecretsTyped = IsAugmented<KnownSecretKeys> extends true ? {
-    get(key: keyof KnownSecretKeys): Promise<string>;
-    expose(key: keyof KnownSecretKeys): Promise<void>;
-    has(key: string): boolean;
-    getMeta(key: string): import('./secrets.js').SecretMeta | undefined;
-} : StepSecrets;
+/**
+ * The augmented secrets surface: narrows `get`/`expose` to the provided key set
+ * while preserving every other StepSecrets accessor (`has`, `getMeta`, `list`,
+ * `mountFile`, `exposeFile`) verbatim. Deriving from StepSecrets via `Omit`
+ * keeps the file-mount accessors from silently dropping off whenever the
+ * StepSecrets surface grows a new method.
+ */
+export type AugmentedStepSecrets<TKeys> = Omit<StepSecrets, 'get' | 'expose'> & {
+    get(key: keyof TKeys): Promise<string>;
+    expose(key: keyof TKeys): Promise<void>;
+};
+export type StepSecretsTyped = IsAugmented<KnownSecretKeys> extends true ? AugmentedStepSecrets<KnownSecretKeys> : StepSecrets;
 /** Repository metadata for global workflow context */
 export interface RepoInfo {
     /** Repository identifier (e.g., "owner/repo") */
@@ -160,7 +173,7 @@ export interface StepContext<TInputs = Record<string, unknown>> {
     /**
      * Raw webhook payload from the git provider.
      * Contains the full, unmodified payload as received from the webhook.
-     * In local preview/run mode (`kici preview` / `kici run local`), contains the simulated payload.
+     * In local preview/run mode (`kici preview` / `kici run --local`), contains the simulated payload.
      * Use this for provider-specific data not covered by normalized fields.
      */
     rawPayload?: Record<string, unknown>;
@@ -189,13 +202,13 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      */
     sourceRepo?: RepoInfo;
     /**
-     * The resolved deployment environment name for this job.
-     * Set when the job declares an `environment` property.
-     * Undefined for jobs without an environment.
+     * The resolved context name for this job.
+     * Set when the job declares a `context` property.
+     * Undefined for jobs without a context.
      */
-    environment?: string;
+    context?: string;
     /**
-     * Secrets resolved for this job's environment.
+     * Secrets resolved for this job's context.
      * Use ctx.secrets.get('KEY') to retrieve a value asynchronously.
      * Use ctx.secrets.expose('KEY') to inject into process.env explicitly.
      * Use ctx.secrets.has('KEY') to check existence synchronously.
@@ -208,12 +221,18 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * Events are delivered immediately (mid-workflow, not queued until completion).
      *
      * @example
-     * // Emit a simple event
+     * // Typed via a defineEvent() definition — payload is schema-checked
+     * await ctx.emit(deployComplete, { env: 'prod', version: '1.2.3' });
+     *
+     * // Or by ad-hoc name (payload typed as Record<string, unknown>)
      * await ctx.emit('deploy-complete', { env: 'prod', version: '1.2.3' });
      *
      * // Emit with cross-repo targeting
      * await ctx.emit('deploy-complete', { env: 'prod' }, { target: { repos: ['org/other-repo'] } });
      */
+    emit<T extends z.ZodTypeAny>(definition: EventDefinition<T>, payload: z.infer<T>, options?: EventEmitOptions): Promise<{
+        deliveryId: string;
+    }>;
     emit(eventName: string, payload?: Record<string, unknown>, options?: EventEmitOptions): Promise<{
         deliveryId: string;
     }>;
@@ -239,7 +258,7 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * For a plain upstream this returns the job's collected outputs (step-keyed
      * for multi-step, flat for run shorthand). For a **matrix** upstream it returns
      * a {@link MatrixJobOutputs} envelope `{ byMatrix, merged }` keyed by the
-     * combination suffix — identical under `kici run local` and the remote path.
+     * combination suffix — identical under `kici run --local` and the remote path.
      * Use {@link isMatrixJobOutputs} (or `'byMatrix' in result`) to discriminate.
      *
      * @example
@@ -248,6 +267,7 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * const m = ctx.jobOutputs(buildMatrixJob);
      * if (isMatrixJobOutputs(m)) console.log(m.byMatrix['linux, arm64']);
      */
+    jobOutputs<T>(ref: Job<T>): T | MatrixJobOutputs<T> | HostJobOutputs<T>;
     jobOutputs(ref: {
         name: string;
     }): Record<string, unknown> | MatrixJobOutputs | HostJobOutputs;
@@ -273,14 +293,44 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * under `spec.key` (immutable — first save wins). Scoped per org + ref.
      */
     cache: import('./cache-types.js').CacheApi;
+    /**
+     * Imperative artifacts API for named, durable build deliverables.
+     *
+     * `ctx.artifacts.upload(name, paths)` packs the paths and uploads them under
+     * `name` (immutable per run — first upload wins, a duplicate name fails).
+     * `ctx.artifacts.download(name, destDir?)` retrieves an artifact uploaded by
+     * an earlier job of the same run. Artifacts are surfaced in the dashboard run
+     * detail and downloadable from there. Distinct from `cache` (content-keyed
+     * speedup) and job outputs (small JSON via `needs`).
+     */
+    artifacts: import('./artifacts-types.js').ArtifactsApi;
     /**
      * Build, sign, and persist a KiCI build-provenance attestation for a produced
-     * artifact. The in-toto statement's identity is derived from a Platform-minted
-     * identity token (unforgeable); the bundle is signed with an ephemeral key and
-     * is offline-verifiable. Pass the artifact via a precomputed digest or a path
-     * the agent digests with SHA-256.
+     * artifact. The in-toto statement's identity is derived from an
+     * orchestrator-minted identity token (unforgeable); the bundle is signed with
+     * an ephemeral key and is offline-verifiable. Pass the artifact via a
+     * precomputed digest or a path the agent digests with SHA-256.
      */
     attestProvenance(opts: import('./provenance-types.js').AttestProvenanceOptions): Promise<import('./provenance-types.js').AttestProvenanceResult>;
+    /**
+     * Allocate a scratch directory for this job. The directory is removed
+     * automatically when the job ends (success, failure, or cancel); the returned
+     * `cleanup()` may also be called manually at any time and is idempotent.
+     *
+     * When `label` is omitted it defaults to a sanitized step id. Use the returned
+     * handle's `path` for scratch work, or `await using h = await ctx.mktemp()` to
+     * tie the directory's lifetime to the enclosing scope.
+     */
+    mktemp(label?: string): Promise<TempHandle>;
+    /**
+     * Allocate a scratch file for this job. Like {@link mktemp}, the file (and its
+     * holder) is removed automatically when the job ends, and the returned
+     * `cleanup()` is idempotent and manually callable. `opts.suffix` appends a file
+     * extension to the generated name.
+     */
+    mktempFile(label?: string, opts?: {
+        suffix?: string;
+    }): Promise<TempHandle>;
     /**
      * Upstream needs resolved for this job, keyed by upstream job or group name.
      * `ctx.needs.<job>.result` is the upstream's outputs proxy and

package/dist/events/define-event.d.ts

@@ -3,12 +3,14 @@
  * Uses Zod for schema validation, re-exported from @kici-dev/sdk.
  */
 import type { z } from 'zod';
+/** Discriminant tag stamped on every value produced by {@link defineEvent}. */
+export declare const EVENT_DEFINITION_TAG: 'EventDefinition';
 /**
  * A typed event definition with a name and Zod validation schema.
  * Used to define custom events that can be emitted from steps via ctx.emit().
  */
 export interface EventDefinition<T extends z.ZodTypeAny = z.ZodTypeAny> {
-    readonly _tag: 'EventDefinition';
+    readonly _tag: typeof EVENT_DEFINITION_TAG;
     readonly name: string;
     readonly schema: T;
 }
@@ -25,8 +27,14 @@ export interface EventDefinition<T extends z.ZodTypeAny = z.ZodTypeAny> {
  *   services: z.array(z.string()),
  * }));
  *
- * // In a step:
- * await ctx.emit(deployComplete.name, { env: 'prod', version: '1.2.3', services: ['api'] });
+ * // In a step (the definition drives payload type-checking):
+ * await ctx.emit(deployComplete, { env: 'prod', version: '1.2.3', services: ['api'] });
  */
 export declare function defineEvent<T extends z.ZodTypeAny>(name: string, schema: T): EventDefinition<T>;
+/**
+ * Runtime type guard: true when `value` is an event definition produced by
+ * `defineEvent()`. Lets `ctx.emit(definition, payload)` accept either an event
+ * name string or a definition object, resolving the name from the object.
+ */
+export declare function isEventDefinition(value: unknown): value is EventDefinition;
 //# sourceMappingURL=define-event.d.ts.map

package/dist/events/define-event.js

@@ -1,5 +1,7 @@
 import "../rolldown-runtime-ClRpJifh.js";
 //#region src/events/define-event.ts
+/** Discriminant tag stamped on every value produced by {@link defineEvent}. */
+const EVENT_DEFINITION_TAG = "EventDefinition";
 /**
 * Create a typed event definition with a Zod schema.
 * Event definitions serve as the contract for custom event payloads.
@@ -13,17 +15,25 @@ import "../rolldown-runtime-ClRpJifh.js";
 *   services: z.array(z.string()),
 * }));
 *
-* // In a step:
-* await ctx.emit(deployComplete.name, { env: 'prod', version: '1.2.3', services: ['api'] });
+* // In a step (the definition drives payload type-checking):
+* await ctx.emit(deployComplete, { env: 'prod', version: '1.2.3', services: ['api'] });
 */
 function defineEvent(name, schema) {
 	return Object.freeze({
-		_tag: "EventDefinition",
+		_tag: EVENT_DEFINITION_TAG,
 		name,
 		schema
 	});
 }
+/**
+* Runtime type guard: true when `value` is an event definition produced by
+* `defineEvent()`. Lets `ctx.emit(definition, payload)` accept either an event
+* name string or a definition object, resolving the name from the object.
+*/
+function isEventDefinition(value) {
+	return typeof value === "object" && value !== null && value._tag === "EventDefinition" && typeof value.name === "string";
+}
 //#endregion
-export { defineEvent };
+export { EVENT_DEFINITION_TAG, defineEvent, isEventDefinition };
 
 //# sourceMappingURL=define-event.js.map

package/dist/events/emit-typing.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=emit-typing.test-d.d.ts.map

package/dist/events/emit-typing.test-d.js

@@ -0,0 +1,36 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { defineEvent } from "./define-event.js";
+import { z } from "zod";
+import { describe, expectTypeOf, it } from "vitest";
+//#region src/events/emit-typing.test-d.ts
+const deployComplete = defineEvent("deploy-complete", z.object({
+	env: z.string(),
+	version: z.string()
+}));
+describe("ctx.emit typed overload", () => {
+	it("accepts a matching payload when called with a definition", () => {
+		const emit = null.emit;
+		expectTypeOf(emit).toBeCallableWith(deployComplete, {
+			env: "prod",
+			version: "1.2.3"
+		});
+	});
+	it("rejects a payload missing a schema field (definition form)", () => {
+		null.emit(deployComplete, { env: "prod" });
+	});
+	it("rejects a payload with a wrong field type (definition form)", () => {
+		null.emit(deployComplete, {
+			env: 1,
+			version: "1.2.3"
+		});
+	});
+	it("still accepts the string-name signature with a loose payload", () => {
+		const ctx = null;
+		expectTypeOf(ctx.emit).toBeCallableWith("ad-hoc-event", { anything: true });
+		expectTypeOf(ctx.emit("ad-hoc-event")).resolves.toEqualTypeOf();
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=emit-typing.test-d.js.map

package/dist/events/event-payloads.d.ts

@@ -124,6 +124,10 @@ export interface EventBase {
     sourceRepo?: string;
     /** Files changed in this event (for path filtering). */
     changedFiles?: string[];
+    /**
+     * Availability of `changedFiles` — `fetched` (real diff), `unavailable` (no diff / could not compute), or `skipped` (orchestrator did not fetch; the agent recomputes from its clone).
+     */
+    changedFilesStatus?: import('@kici-dev/engine').ChangedFilesStatus;
     /** Raw webhook payload from the provider. May be absent in flattened event forms. */
     payload?: Record<string, unknown>;
     /** Index signature for backward compatibility — untyped fields resolve to unknown. */

package/dist/events/index.d.ts

@@ -1,4 +1,4 @@
-export { defineEvent } from './define-event.js';
+export { defineEvent, isEventDefinition } from './define-event.js';
 export type { EventDefinition } from './define-event.js';
 export type { EventEmitOptions } from './types.js';
 export { isEventType } from './event-payloads.js';

package/dist/events/index.js

@@ -1,4 +1,4 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { isEventType } from "./event-payloads.js";
-import { defineEvent } from "./define-event.js";
-export { defineEvent, isEventType };
+import { defineEvent, isEventDefinition } from "./define-event.js";
+export { defineEvent, isEventDefinition, isEventType };

package/dist/fleet/agent-version-converge.d.ts

@@ -0,0 +1,23 @@
+import type { Step } from '../types.js';
+/** Drift the convergence check reports; `blocked` is never applied. */
+export interface AgentVersionDrift {
+    /** True when the target payloads are unavailable — hold, never apply. */
+    blocked: boolean;
+    /** The host's current staged version (null when never staged). */
+    from: string | null;
+    /** The orchestrator target version to converge onto. */
+    to: string;
+}
+export interface AgentVersionConvergeOptions {
+    /** Step name surfaced in logs / the dashboard. Defaults to `agent-version-converge`. */
+    name?: string;
+}
+/**
+ * Build a check-step that converges `targetAgentId` onto the orchestrator's
+ * version, availability-gated (a missing payload holds the host, never a skew).
+ * MUST run on an agent holding `kici:capability:ssh-transport`.
+ */
+export declare function agentVersionConverge(targetAgentId: string, opts?: AgentVersionConvergeOptions): Step<{
+    restaged: boolean;
+}, string>;
+//# sourceMappingURL=agent-version-converge.d.ts.map

package/dist/fleet/agent-version-converge.js

@@ -0,0 +1,58 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { step } from "../step.js";
+//#region src/fleet/agent-version-converge.ts
+/**
+* Availability-gated fleet agent auto-upgrade — the `agentVersionConverge()`
+* check-step.
+*
+* Placed in a workflow job that runs on an ops agent (one holding
+* `kici:capability:ssh-transport`), it converges a target fleet host onto the
+* orchestrator's own version:
+*
+* - **check** compares the host's staged version against the orchestrator target.
+*   Equal ⇒ in-sync (skip). Different ⇒ drift. If the target's self-contained
+*   payloads are UNAVAILABLE for the host's platform, the drift is `blocked`:
+*   the runner surfaces it (held + alarmed) and the apply refuses it, so a
+*   version skew can never be applied.
+* - **apply** (run) re-stages the target payload onto the host and restarts its
+*   agent, driven by THIS ops agent as an external actor over SSH — no
+*   self-update-handoff. It THROWS on a `blocked` drift (belt-and-suspenders on
+*   top of the check + the orchestrator-side availability gate).
+*
+* The re-stage is external-actor driven because the host's own agent cannot
+* swap its running binary underneath itself; the ops agent holds the SSH
+* transport and the host reconnects on its own persistent credential.
+*
+* Rolling + drift-approval gating comes from the shipped check-facet machinery:
+* combine with the run-level check mode and `approval: { when: 'drift' }` for a
+* controlled, health-gated roll.
+*/
+/**
+* Build a check-step that converges `targetAgentId` onto the orchestrator's
+* version, availability-gated (a missing payload holds the host, never a skew).
+* MUST run on an agent holding `kici:capability:ssh-transport`.
+*/
+function agentVersionConverge(targetAgentId, opts = {}) {
+	return step(opts.name ?? "agent-version-converge", {
+		check: async (ctx) => {
+			const status = await ctx.kici.bootstrap.agentVersionStatus(targetAgentId);
+			if (status.stagedVersion === status.targetVersion) return null;
+			return {
+				blocked: !status.available,
+				from: status.stagedVersion,
+				to: status.targetVersion
+			};
+		},
+		summarize: (drift) => drift.blocked ? `blocked: payload for ${drift.to} unavailable — holding ${targetAgentId} at ${drift.from ?? "(none)"}` : `agent ${targetAgentId}: ${drift.from ?? "(none)"} → ${drift.to}`,
+		run: async (ctx, drift) => {
+			if (drift.blocked) throw new Error(`refusing to converge ${targetAgentId} to ${drift.to}: payload unavailable (held to avoid a version skew)`);
+			ctx.log.info(`Re-staging ${targetAgentId}: ${drift.from ?? "(none)"} → ${drift.to}`);
+			return ctx.kici.bootstrap.restageAgent(targetAgentId);
+		},
+		whenInSync: async () => ({ restaged: false })
+	});
+}
+//#endregion
+export { agentVersionConverge };
+
+//# sourceMappingURL=agent-version-converge.js.map

package/dist/idempotent.d.ts

@@ -95,8 +95,8 @@ export interface CheckStepOptions<TDrift, TInSync = void, TApplied = void> exten
  *
  * 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.
+ * step-loop 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

@@ -79,8 +79,8 @@ function idempotentStep(name, opts) {
 *
 * 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.
+* step-loop check-mode drive for free — no engine, agent, orchestrator, or
+* lockfile change.
 */
 function checkStep(name, options) {
 	return step(name, {

package/dist/index.d.ts

@@ -5,12 +5,14 @@ export { parallel, isParallelGroup, flattenStepInputs } from './parallel.js';
 export type { ParallelGroup, ParallelOptions } from './parallel.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 { pr, push, tag, comment, review, reviewComment, release, dispatch, create, delete as delete, status, workflowRun, fork, star, watch, webhook, kiciEvent, workflowComplete, workflowsFailedBatch, 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, WorkflowsFailedBatchConfigInput, WorkflowsFailedBatchTriggerConfig, 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, onlyOnFirstHost, onlyOnLastHost, onlyOnFanoutIndex } from './rules/index.js';
 export { evaluateRules } from './rules/index.js';
+export { createRuleContext, ChangedFilesUnavailableError } from './rules/index.js';
+export type { CreateRuleContextInput } 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';
@@ -23,6 +25,8 @@ export type { UpstreamSnapshot, NeedsContext, NeedEntry, GroupNeedEntry } from '
 export { CacheSpecSchema, normalizeCacheSpecs } from './cache-types.js';
 export type { CacheSpec, CacheInput } from './cache-types.js';
 export type { CacheRestoreResult, CacheApi } from './cache-types.js';
+export { ArtifactNameSchema, ARTIFACT_NAME_MAX_LENGTH } from './artifacts-types.js';
+export type { ArtifactsApi, ArtifactResult } from './artifacts-types.js';
 export { provenanceSubjectIsPath } from './provenance-types.js';
 export type { AttestProvenanceOptions, AttestProvenanceResult, ProvenanceSubjectInput, } from './provenance-types.js';
 export { dynamicGroup, isDynamicGroupRef, DYNAMIC_GROUP_TAG } from './dynamic-group.js';
@@ -40,7 +44,7 @@ export type { OutputsMap, StepRefMap } from './outputs.js';
 export type { StaticMatrixArray, StaticMatrixObject, DynamicMatrixFn, DynamicMatrixContext, Matrix, MatrixInclude, MatrixExclude, MatrixValues, } from './matrix/index.js';
 export { isStaticArray, isStaticObject, isDynamicFunction } from './matrix/index.js';
 export { expandMatrix, applyIncludeExclude } from './matrix/index.js';
-export { defineEvent } from './events/index.js';
+export { defineEvent, isEventDefinition } from './events/index.js';
 export type { EventDefinition } from './events/index.js';
 export type { EventEmitOptions } from './events/index.js';
 export { fixture } from './fixture.js';
@@ -51,5 +55,7 @@ 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 { agentVersionConverge } from './fleet/agent-version-converge.js';
+export type { AgentVersionConvergeOptions, AgentVersionDrift, } from './fleet/agent-version-converge.js';
 export { z } from 'zod';
 //# sourceMappingURL=index.d.ts.map