@kici-dev/sdk 0.1.19 → 0.1.21

package/dist/api-types.d.ts

@@ -9,7 +9,9 @@
  * 2. Register the handler in the orchestrator's AgentApiRegistry
  */
 import { type OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
+import type { HostInventoryEntry, InventorySelector } from '@kici-dev/engine';
 export type { OidcTokenResult };
+export type { HostInventoryEntry, InventorySelector };
 export interface InfrastructureListResult {
     scalers: Array<{
         name: string;
@@ -42,9 +44,25 @@ export interface OidcApi {
         audience: string;
     }): Promise<OidcTokenResult>;
 }
+export interface InventoryApi {
+    /**
+     * Query the host roster of the caller's orchestrator cluster. Omit the
+     * selector ⇒ all hosts. Server-side filtering is label-based (reuses the
+     * runsOnAll glob/regex matchers); filter on `properties` client-side in the
+     * workflow. Available to steps and dynamic-job generators — a generator can
+     * fan out one job per matching host. The roster is live, so a dynamic-job
+     * generator inherits the same non-determinism contract as
+     * `infrastructure.list()`.
+     */
+    query(selector?: InventorySelector): Promise<HostInventoryEntry[]>;
+    /** Look up one host by agent id; null when the host is not in the roster. */
+    get(agentId: string): Promise<HostInventoryEntry | null>;
+}
 export interface KiciApi {
     /** Query orchestrator infrastructure (scalers, agents). */
     infrastructure: InfrastructureApi;
+    /** Query the host roster / inventory (labels + typed properties). */
+    inventory: InventoryApi;
     /** Request short-lived OIDC ID tokens for the current job (build provenance). */
     oidc: OidcApi;
 }

package/dist/api-types.js

@@ -26,6 +26,10 @@ import { OIDC_TOKEN_REQUEST_METHOD } from "@kici-dev/engine/protocol/messages/oi
 function buildKiciApi(transport, jobCtx) {
 	return {
 		infrastructure: { list: () => transport("infrastructure.list", {}) },
+		inventory: {
+			query: (selector) => transport("inventory.query", { ...selector ?? {} }),
+			get: (agentId) => transport("inventory.get", { agentId })
+		},
 		oidc: { token: (opts) => {
 			if (!jobCtx) return Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is only available inside a running job step"));
 			return transport(OIDC_TOKEN_REQUEST_METHOD, {

package/dist/index.d.ts

@@ -13,7 +13,7 @@ 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, 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, 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 { 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 { buildNeedsContext } from './needs-context.js';
@@ -28,7 +28,7 @@ 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 { buildKiciApi } from './api-types.js';
-export type { KiciApi, KiciApiTransport, InfrastructureApi, InfrastructureListResult, } from './api-types.js';
+export type { KiciApi, KiciApiTransport, InfrastructureApi, InfrastructureListResult, InventoryApi, 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';

package/dist/step.d.ts

@@ -1,4 +1,4 @@
-import type { Step, StepOptions, StepRunFn } from './types.js';
+import type { Step, StepOptions, StepOptionsWithCheck, StepRunFn } from './types.js';
 /**
  * Create an id-less step with just a run function.
  * The compiler assigns a counter-based ID (step-1, step-2, etc.) at lock file generation.
@@ -47,4 +47,24 @@ export declare function step(name: string, run: StepRunFn): Step<void>;
  * });
  */
 export declare function step<TResult = void>(name: string, options: StepOptions<TResult>): Step<TResult>;
+/**
+ * Create a named idempotent step with a check facet.
+ *
+ * `check` returns a drift value (or null when in sync); `run` becomes the apply
+ * function and receives that drift; `summarize` renders the drift for logs and
+ * the dashboard. `whenInSync` optionally produces the outputs when already in sync.
+ *
+ * @example
+ * const nginx = step('configure-nginx', {
+ *   check: async (ctx) => (await inSync(ctx)) ? null : { want: DESIRED },
+ *   summarize: (drift) => `would rewrite nginx.conf (${drift.want.length} bytes)`,
+ *   run: async (ctx, drift) => { await writeConfig(drift.want); return { reloaded: true }; },
+ *   whenInSync: async () => ({ reloaded: false }),
+ * });
+ */
+export declare function step<TResult = void, TDrift = unknown>(name: string, options: StepOptionsWithCheck<TResult, TDrift>): Step<TResult>;
+/**
+ * Create an id-less idempotent step with a check facet.
+ */
+export declare function step<TResult = void, TDrift = unknown>(options: StepOptionsWithCheck<TResult, TDrift>): Step<TResult>;
 //# sourceMappingURL=step.d.ts.map

package/dist/step.js

@@ -58,11 +58,16 @@ function step(nameOrRunOrOptions, runOrOptions) {
 		name = "";
 		options = nameOrRunOrOptions;
 	}
+	if (options.check && !options.summarize) throw new Error("summarize is required when check is set");
 	return {
 		_tag: "Step",
 		name,
 		outputs: options.outputs,
 		run: options.run,
+		...options.check !== void 0 && { check: options.check },
+		...options.summarize !== void 0 && { summarize: options.summarize },
+		...options.drift !== void 0 && { drift: options.drift },
+		...options.whenInSync !== void 0 && { whenInSync: options.whenInSync },
 		continueOnError: options.continueOnError,
 		timeout: options.timeout,
 		...options.cache !== void 0 && { cache: options.cache },

package/dist/types.d.ts

@@ -41,7 +41,18 @@ export interface Step<TResult = void> {
     readonly name: string;
     /** Optional Zod schema for runtime output validation. */
     readonly outputs?: OutputSchema;
-    readonly run: (ctx: StepContext) => Promise<TResult>;
+    readonly run: (ctx: StepContext, drift?: any) => Promise<TResult>;
+    /**
+     * Read-only inspection for an idempotent step. Returns a drift value when run()
+     * would change state, or null when the system is already in the desired state.
+     */
+    readonly check?: (ctx: StepContext) => Promise<unknown | null>;
+    /** Required when check is set: human-readable, serializable summary of the drift. */
+    readonly summarize?: (drift: any) => string;
+    /** Optional Zod schema validating the drift value. */
+    readonly drift?: z.ZodTypeAny;
+    /** Optional: produces the step's outputs when check() returns null (already in sync). */
+    readonly whenInSync?: (ctx: StepContext) => Promise<TResult>;
     /** When true, job proceeds even if this step fails (recorded as failed but not fatal). */
     readonly continueOnError?: boolean;
     /** Step-level timeout in milliseconds. Overrides the agent's default (30 minutes). */
@@ -77,11 +88,13 @@ export type BareStepFn<TResult = void> = (ctx: StepContext) => Promise<TResult>;
 export type StepInput = Step<any> | BareStepFn<any>;
 /** Options for step() factory - simple form (just async function) */
 export type StepRunFn = (ctx: StepContext) => Promise<void>;
-/** Options for step() factory - full form with outputs and generic return type */
-export interface StepOptions<TResult = void> {
+/**
+ * Facets shared by both the plain and the check variant of {@link StepOptions}.
+ * These compose unchanged whether or not a step declares a `check` facet.
+ */
+export interface StepOptionsBase {
     /** Optional Zod schema for runtime output validation. */
     outputs?: OutputSchema;
-    run: (ctx: StepContext) => Promise<TResult>;
     /** When true, job proceeds even if this step fails (recorded as failed but not fatal). */
     continueOnError?: boolean;
     /** Step-level timeout in milliseconds. Overrides the agent's default (30 minutes). */
@@ -97,6 +110,42 @@ export interface StepOptions<TResult = void> {
     /** Pause for a manual human approval before this step runs. */
     requireApproval?: RequireApproval;
 }
+/**
+ * Plain step options: `run` takes only the context — the existing, fully
+ * backward-compatible shape. No `check` facet.
+ */
+export interface StepOptionsPlain<TResult = void> extends StepOptionsBase {
+    run: (ctx: StepContext) => Promise<TResult>;
+    check?: undefined;
+    summarize?: undefined;
+    drift?: undefined;
+    whenInSync?: undefined;
+}
+/**
+ * Idempotent-step options: `check` declares read-only inspection, `run` becomes
+ * the *apply* function and receives the drift value `check` returned. `summarize`
+ * is required. `whenInSync` optionally produces the outputs when already in sync.
+ *
+ * `TDrift` is independent of `TResult` — one output shape per step (whichever of
+ * `run` / `whenInSync` executes), and a separate drift shape that `check` returns.
+ */
+export interface StepOptionsWithCheck<TResult = void, TDrift = unknown> extends StepOptionsBase {
+    /** Read-only inspection. Returns drift when run() would change state, or null when in sync. */
+    check: (ctx: StepContext) => Promise<TDrift | null>;
+    /** Required when check is set: human-readable, serializable summary of the drift. */
+    summarize: (drift: TDrift) => string;
+    /** Optional Zod schema validating the drift value. */
+    drift?: z.ZodTypeAny;
+    /** Apply: runs only when check returned drift (apply mode); receives that drift. */
+    run: (ctx: StepContext, drift: TDrift) => Promise<TResult>;
+    /** Optional: produces the step's outputs when check returned null (already in sync). */
+    whenInSync?: (ctx: StepContext) => Promise<TResult>;
+}
+/**
+ * Options for step() factory - full form with outputs and generic return type.
+ * Either the plain shape (`run(ctx)`) or the idempotent shape (`check` + `run(ctx, drift)`).
+ */
+export type StepOptions<TResult = void, TDrift = unknown> = StepOptionsPlain<TResult> | StepOptionsWithCheck<TResult, TDrift>;
 /** Trigger type (config objects returned by pr()/push() factory functions) */
 export type Trigger = TriggerConfig;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/sdk",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
   "keywords": [
     "ci",
@@ -49,8 +49,8 @@
     "micromatch": "^4.0.8",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.19",
-    "@kici-dev/engine": "0.1.19"
+    "@kici-dev/core": "0.1.21",
+    "@kici-dev/engine": "0.1.21"
   },
   "devDependencies": {
     "@types/micromatch": "^4.0.10"

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/sdk@0.1.19",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.19/bfecc4bc-a72b-4f35-b5d3-f2e9232e09f3",
+  "name": "@kici-dev/sdk@0.1.21",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.21/1834e1a9-6047-4754-a53b-056d1a5e091c",
   "creationInfo": {
-    "created": "2026-06-19T05:11:08Z",
+    "created": "2026-06-23T05:10:13Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -146,9 +146,9 @@
       "homepage": "https://ericsmekens.github.io/jsep/tree/master/packages/regex#readme"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.21",
       "name": "@kici-dev/core",
-      "versionInfo": "0.1.19",
+      "versionInfo": "0.1.21",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -159,16 +159,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.19"
+          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.21"
         }
       ],
       "description": "Light shared utilities for the KiCI stack (logging, errors, formatting, crypto, zx init, the TypeScript ESM loader hook). No server-side dependencies.",
       "homepage": "https://kici.dev"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.1.19",
+      "versionInfo": "0.1.21",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -179,7 +179,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.19"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.21"
         }
       ],
       "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",
@@ -188,7 +188,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/sdk",
-      "versionInfo": "0.1.19",
+      "versionInfo": "0.1.21",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -199,7 +199,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.19"
+          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.21"
         }
       ],
       "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
@@ -1584,68 +1584,68 @@
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-oxc-transform-0.135.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-picocolors-1.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-winston-daily-rotate-file-5.0.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-jose-6.2.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-jsonpath-plus-10.4.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.4",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-safe-regex-2.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.19",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.21",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.19",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.21",
       "relationshipType": "DEPENDS_ON"
     },
     {