@kici-dev/sdk 0.1.27 → 0.3.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';
@@ -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") */
@@ -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;
     }>;
@@ -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/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

package/dist/index.js

@@ -1,6 +1,7 @@
 import "./rolldown-runtime-ClRpJifh.js";
 import { buildKiciApi } from "./api-types.js";
 import { normalizeApproval } from "./approval.js";
+import { ARTIFACT_NAME_MAX_LENGTH, ArtifactNameSchema } from "./artifacts-types.js";
 import { CacheSpecSchema, normalizeCacheSpecs } from "./cache-types.js";
 import { isHostJobOutputs, isMatrixJobOutputs } from "./context.js";
 import { DYNAMIC_GROUP_TAG, dynamicGroup, isDynamicGroupRef } from "./dynamic-group.js";
@@ -32,6 +33,7 @@ import { watch } from "./triggers/watch.js";
 import { webhook } from "./triggers/webhook.js";
 import { kiciEvent } from "./triggers/kici-event.js";
 import { workflowComplete } from "./triggers/workflow-complete.js";
+import { workflowsFailedBatch } from "./triggers/workflows-failed-batch.js";
 import { jobComplete } from "./triggers/job-complete.js";
 import { genericWebhook } from "./triggers/generic-webhook.js";
 import { schedule } from "./triggers/schedule.js";
@@ -40,6 +42,7 @@ import { defineDispatchInputs } from "./triggers/dispatch-inputs.js";
 import "./triggers/index.js";
 import { afterStep, beforeStep, cleanup, onCancel, onFailure, onSuccess } from "./hooks/index.js";
 import { onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip } from "./rules/rule.js";
+import { ChangedFilesUnavailableError, createRuleContext } from "./rules/context.js";
 import { evaluateRules } from "./rules/evaluator.js";
 import { isEventType } from "./events/event-payloads.js";
 import "./rules/index.js";
@@ -52,7 +55,8 @@ import { createStepSecrets } from "./secrets.js";
 import { isDynamicFunction, isStaticArray, isStaticObject } from "./matrix/types.js";
 import { applyIncludeExclude, expandMatrix } from "./matrix/expand.js";
 import "./matrix/index.js";
-import { defineEvent } from "./events/define-event.js";
+import { defineEvent, isEventDefinition } from "./events/define-event.js";
 import "./events/index.js";
+import { agentVersionConverge } from "./fleet/agent-version-converge.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, checkStep, cleanup, comment, create, createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineDispatchInputs, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, flattenStepInputs, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isHostJobOutputs, isMatrixJobOutputs, isParallelGroup, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeApproval, normalizeCacheSpecs, onCancel, onFailure, onSuccess, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, parallel, 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 };
+export { ARTIFACT_NAME_MAX_LENGTH, ArtifactNameSchema, CacheSpecSchema, ChangedFilesUnavailableError, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, agentVersionConverge, applyIncludeExclude, beforeStep, buildKiciApi, buildNeedsContext, checkStep, cleanup, comment, create, createJobOutputProxy, createRuleContext, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineDispatchInputs, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, flattenStepInputs, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventDefinition, isEventType, isHostJobOutputs, isMatrixJobOutputs, isParallelGroup, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeApproval, normalizeCacheSpecs, onCancel, onFailure, onSuccess, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, parallel, 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, workflowsFailedBatch, z };

package/dist/job-outputs.test-d.d.ts

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