@kici-dev/sdk 0.1.14 → 0.1.16

package/README.md

@@ -1 +1,19 @@
-TBD
+# @kici-dev/sdk
+
+TypeScript SDK for defining KiCI workflows. Import it in `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations — with full type safety and editor autocomplete.
+
+Part of [KiCI](https://kici.dev) — CI/CD workflows as TypeScript code: author them with full language power, dry-run them locally, and run them on your own infrastructure.
+
+## Install
+
+```bash
+npm install --save-dev @kici-dev/sdk
+```
+
+Usually installed for you by `kici init`.
+
+## Links
+
+- Documentation: <https://docs.kici.dev/user/sdk/core/>
+- Source: <https://github.com/kici-dev/kici-public/tree/main/packages/sdk>
+- License: Apache-2.0

package/dist/approval.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Workflow-author API for declaring a manual approval gate at step, job, or
+ * workflow level. The author writes `requireApproval`; the compiler normalizes
+ * it into the lock file's `approval` block, and the orchestrator turns it into
+ * a held element at dispatch time.
+ */
+/** A single approver clause: any member of a team, or a specific user. */
+export type ApproverClause = {
+    team: string;
+} | {
+    user: string;
+};
+/**
+ * Declarative approval requirement.
+ *
+ * - `true` — pause for ANY org member with the approval permission.
+ * - `ApproverClause[]` — a flat AND list (all clauses must be satisfied).
+ * - object form — clauses plus an optional human `reason` and a per-gate
+ *   `timeout` (seconds) that overrides the org-default expiry.
+ */
+export type RequireApproval = true | ApproverClause[] | {
+    approvers: ApproverClause[];
+    reason?: string;
+    timeout?: number;
+};
+/** The normalized shape written into the lock file. */
+export interface NormalizedRequireApproval {
+    clauses: ApproverClause[];
+    reason?: string;
+    timeoutSeconds?: number;
+}
+/** Normalize any `RequireApproval` form into `{ clauses, reason?, timeoutSeconds? }`. */
+export declare function normalizeRequireApproval(r: RequireApproval): NormalizedRequireApproval;
+//# sourceMappingURL=approval.d.ts.map

package/dist/approval.js

@@ -0,0 +1,16 @@
+import "./chunk-gOLHoazu.js";
+//#region src/approval.ts
+/** Normalize any `RequireApproval` form into `{ clauses, reason?, timeoutSeconds? }`. */
+function normalizeRequireApproval(r) {
+	if (r === true) return { clauses: [] };
+	if (Array.isArray(r)) return { clauses: r };
+	return {
+		clauses: r.approvers,
+		reason: r.reason,
+		timeoutSeconds: r.timeout
+	};
+}
+//#endregion
+export { normalizeRequireApproval };
+
+//# sourceMappingURL=approval.js.map

package/dist/cache-types.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+/**
+ * Declarative + imperative cache specification.
+ *
+ * `key` is the immutable cache key — the first save under an exact key wins;
+ * re-saving the same exact key is a no-op. `paths` are the files/dirs to
+ * archive (repo-root-relative or `~`-prefixed). `restoreKeys` are ordered
+ * prefix fallbacks tried (newest matching entry wins) when the exact key
+ * misses on restore.
+ */
+export interface CacheSpec {
+    /** Exact cache key. First save wins; re-saving an existing key is a no-op. */
+    key: string;
+    /** Files/directories to cache. Repo-root-relative or `~`-prefixed. */
+    paths: string[];
+    /** Ordered prefix fallbacks for partial restore; newest matching entry wins. */
+    restoreKeys?: string[];
+}
+/** Zod schema validating a CacheSpec at compile/serialize time. */
+export declare const CacheSpecSchema: z.ZodObject<{
+    key: z.ZodString;
+    paths: z.ZodArray<z.ZodString>;
+    restoreKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Declarative cache field shape: one spec or many. */
+export type CacheInput = CacheSpec | CacheSpec[];
+/** Coerce the declarative `cache` field into an array (empty when unset). */
+export declare function normalizeCacheSpecs(input: CacheInput | undefined): CacheSpec[];
+/** Result of an imperative cache restore. */
+export interface CacheRestoreResult {
+    /** Whether any entry (exact key or a restoreKeys prefix match) was restored. */
+    hit: boolean;
+    /** The key that actually matched (exact key or the matched prefix entry's full key). */
+    matchedKey?: string;
+}
+/**
+ * Imperative cache API exposed on `StepContext` as `ctx.cache`.
+ *
+ * `restore` tries the exact `key`, then each `restoreKeys` prefix in order
+ * (newest matching entry wins). `save` is immutable — the first save under an
+ * exact key wins and re-saving an existing key is a no-op.
+ */
+export interface CacheApi {
+    restore(spec: CacheSpec): Promise<CacheRestoreResult>;
+    save(spec: CacheSpec): Promise<void>;
+}
+//# sourceMappingURL=cache-types.d.ts.map

package/dist/cache-types.js

@@ -0,0 +1,18 @@
+import "./chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/cache-types.ts
+/** Zod schema validating a CacheSpec at compile/serialize time. */
+const CacheSpecSchema = z.object({
+	key: z.string().min(1, "cache key must be non-empty"),
+	paths: z.array(z.string().min(1)).min(1, "cache paths must be non-empty"),
+	restoreKeys: z.array(z.string().min(1)).optional()
+});
+/** Coerce the declarative `cache` field into an array (empty when unset). */
+function normalizeCacheSpecs(input) {
+	if (input === void 0) return [];
+	return Array.isArray(input) ? input : [input];
+}
+//#endregion
+export { CacheSpecSchema, normalizeCacheSpecs };
+
+//# sourceMappingURL=cache-types.js.map

package/dist/context.d.ts

@@ -180,6 +180,14 @@ export interface StepContext<TInputs = Record<string, unknown>> {
     setSecretOutput(key: string, value: string): void;
     /** Typed KiCI API — orchestrator queries over WS (e.g., kici.infrastructure.list()) */
     kici: KiciApi;
+    /**
+     * Imperative cache API for fine-grained control.
+     *
+     * `ctx.cache.restore(spec)` restores from object storage (exact key, then
+     * restoreKeys prefix fallback). `ctx.cache.save(spec)` archives `spec.paths`
+     * under `spec.key` (immutable — first save wins). Scoped per org + ref.
+     */
+    cache: import('./cache-types.js').CacheApi;
 }
 export {};
 //# sourceMappingURL=context.d.ts.map

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

@@ -364,9 +364,20 @@ export interface RerunEventPayload extends EventBase {
 export interface ManualScheduleEventPayload extends EventBase {
     type: 'manual_schedule';
 }
-/** Fallback for unknown/future event types. */
+/**
+ * Compile-time fallback member of the {@link EventPayload} union for event
+ * types not yet modeled here.
+ *
+ * Its `type` is the literal `'unknown'` (not `string`) so that the union stays
+ * a *proper* discriminated union — a non-literal discriminant would collapse
+ * narrowing on `event.type` for every other member. At runtime, an event of an
+ * unmodeled kind still carries its real type string in `event.type`; this
+ * interface only governs how TypeScript narrows it. Code that must handle
+ * arbitrary future types can compare the raw value via `String(event.type) ===
+ * '...'`, or use the {@link isEventType} guard for the known types.
+ */
 export interface UnknownEventPayload extends EventBase {
-    type: string;
+    type: 'unknown';
 }
 /**
  * Typed event payload — discriminated union over the `type` field.

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

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

package/dist/events/event-payloads.test-d.js

@@ -0,0 +1,32 @@
+import "../chunk-gOLHoazu.js";
+import { describe, expectTypeOf, it } from "vitest";
+//#region src/events/event-payloads.test-d.ts
+describe("EventPayload narrowing", () => {
+	it("narrows to the per-type payload shape on event.type", () => {
+		const handle = (event) => {
+			if (event.type === "pull_request") {
+				expectTypeOf(event).toEqualTypeOf();
+				expectTypeOf(event.payload.pull_request.number).toBeNumber();
+			}
+		};
+		expectTypeOf(handle).toBeFunction();
+	});
+	it("exposes a literal-union discriminant (not string)", () => {
+		expectTypeOf().toEqualTypeOf();
+	});
+	it("job dynamic functions accept EventPayload-param functions", () => {
+		expectTypeOf().toMatchTypeOf();
+		expectTypeOf().toMatchTypeOf();
+		expectTypeOf().toMatchTypeOf();
+	});
+	it("workflow concurrency.group ctx carries the EventPayload envelope", () => {
+		expectTypeOf().toEqualTypeOf();
+	});
+	it("DynamicJobContext.ctx.event is the EventPayload envelope (optional)", () => {
+		expectTypeOf().toEqualTypeOf();
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=event-payloads.test-d.js.map

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { step } from './step.js';
 export { job } from './job.js';
 export { workflow } from './workflow.js';
+export { normalizeRequireApproval } from './approval.js';
+export type { RequireApproval, ApproverClause, NormalizedRequireApproval } from './approval.js';
 export { pr, push, tag, comment, review, reviewComment, release, dispatch, create, delete as delete, status, workflowRun, fork, star, watch, webhook, kiciEvent, workflowComplete, jobComplete, genericWebhook, schedule, lifecycle, } from './triggers/index.js';
 export type { TriggerConfig, PrTriggerConfig, PushTriggerConfig, TagTriggerConfig, CommentTriggerConfig, ReviewTriggerConfig, ReviewCommentTriggerConfig, ReleaseTriggerConfig, DispatchTriggerConfig, CreateTriggerConfig, DeleteTriggerConfig, StatusTriggerConfig, WorkflowRunTriggerConfig, ForkTriggerConfig, StarTriggerConfig, WatchTriggerConfig, WebhookTriggerConfig, BranchPattern, BodyMatchPattern, PrEvent, PushEvent, PrConfigInput, PushConfigInput, TagConfigInput, CommentConfigInput, CommentAction, CommentSource, ReviewConfigInput, ReviewAction, ReviewState, ReviewCommentConfigInput, ReviewCommentAction, ReleaseConfigInput, ReleaseAction, DispatchConfigInput, CreateConfigInput, DeleteConfigInput, RefType, StatusConfigInput, StatusState, WorkflowRunConfigInput, WorkflowRunAction, ForkConfigInput, StarConfigInput, StarAction, WatchConfigInput, WatchAction, WebhookConfigInput, KiciEventConfigInput, KiciEventTriggerConfig, WorkflowCompleteConfigInput, WorkflowCompleteTriggerConfig, WorkflowCompleteStatus, JobCompleteConfigInput, JobCompleteTriggerConfig, JobCompleteStatus, GenericWebhookConfigInput, GenericWebhookTriggerConfig, GenericWebhookAuthMethod, GenericWebhookHmacAuth, GenericWebhookApiKeyAuth, GenericWebhookAuth, ScheduleConfigInput, ScheduleTriggerConfig, LifecycleEvent, LifecycleConfigInput, LifecycleTriggerConfig, } from './triggers/index.js';
 export { onCancel, cleanup, onSuccess, onFailure, beforeStep, afterStep } from './hooks/index.js';
@@ -11,9 +13,12 @@ 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, ContainerConfig, RunsOnSelector, RunsOn, Workflow, WorkflowOptions, Registry, Trigger, DynamicJobFn, DynamicJobContext, JobOrFactory, } from './types.js';
+export type { SourceLocation, OutputProxy, Step, StepOptions, StepRunFn, BareStepFn, StepInput, OutputSchema, InferOutputs, Job, JobOptions, GenericInitConfig, ContainerConfig, RunsOnSelector, RunsOn, Workflow, WorkflowOptions, Registry, Trigger, DynamicJobFn, DynamicJobContext, JobOrFactory, } from './types.js';
 export { isDynamicJobFn, dynamicJob, getDynamicJobGroup, DYNAMIC_JOB_GROUP_TAG } from './types.js';
 export type { TaggedDynamicJobFn } from './types.js';
+export { CacheSpecSchema, normalizeCacheSpecs } from './cache-types.js';
+export type { CacheSpec, CacheInput } from './cache-types.js';
+export type { CacheRestoreResult, CacheApi } from './cache-types.js';
 export { dynamicGroup, isDynamicGroupRef, DYNAMIC_GROUP_TAG } from './dynamic-group.js';
 export type { DynamicGroupRef } from './dynamic-group.js';
 export type { StepContext, Logger, WorkflowInfo, JobInfo, RepoInfo, StepSecretsTyped, KnownSecretKeys, } from './context.js';

package/dist/index.js

@@ -1,5 +1,7 @@
 import "./chunk-gOLHoazu.js";
 import { buildKiciApi } from "./api-types.js";
+import { normalizeRequireApproval } from "./approval.js";
+import { CacheSpecSchema, normalizeCacheSpecs } from "./cache-types.js";
 import { DYNAMIC_GROUP_TAG, dynamicGroup, isDynamicGroupRef } from "./dynamic-group.js";
 import { SecretNotFoundError } from "./errors.js";
 import { fixture } from "./fixture.js";
@@ -47,4 +49,4 @@ import { defineEvent } from "./events/define-event.js";
 import "./events/index.js";
 import { WaitForTimeoutError, waitFor, waitForStep } from "./wait-for.js";
 import { z } from "zod";
-export { DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, applyIncludeExclude, beforeStep, buildKiciApi, cleanup, comment, create, createJobOutputProxy, createStepOutputProxy, createStepSecrets, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, fork, genericWebhook, getDynamicJobGroup, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, onCancel, onFailure, onSuccess, pr, push, release, resolveJobOutputs, resolveStepOutputs, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, z };
+export { CacheSpecSchema, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, applyIncludeExclude, beforeStep, buildKiciApi, cleanup, comment, create, createJobOutputProxy, createStepOutputProxy, createStepSecrets, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, fork, genericWebhook, getDynamicJobGroup, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeCacheSpecs, normalizeRequireApproval, onCancel, onFailure, onSuccess, pr, push, release, resolveJobOutputs, resolveStepOutputs, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, z };

package/dist/job.js

@@ -3,6 +3,17 @@ import { createJobOutputProxy } from "./outputs.js";
 import { randomUUID } from "node:crypto";
 //#region src/job.ts
 /**
+* Validate a job's `init` config. `undefined` / `false` are no-ops; every
+* remaining spec (one, or each element of an array) must carry a non-empty
+* `run` command. Throws with the offending index when validation fails.
+*/
+function validateInit(init, jobName) {
+	if (init === void 0 || init === false) return;
+	(Array.isArray(init) ? init : [init]).forEach((spec, i) => {
+		if (typeof spec.run !== "string" || spec.run.trim().length === 0) throw new Error(`job('${jobName}'): init[${i}].run must be a non-empty command`);
+	});
+}
+/**
 * Implementation of job() factory.
 */
 function job(nameOrOptions, maybeOptions) {
@@ -13,6 +24,7 @@ function job(nameOrOptions, maybeOptions) {
 		if (options.steps && options.steps.length > 0) throw new Error("job() cannot have both \"run\" and \"steps\" -- use one or the other");
 		steps = [options.run];
 	}
+	validateInit(options.init, name);
 	return {
 		_tag: "Job",
 		name,
@@ -36,7 +48,11 @@ function job(nameOrOptions, maybeOptions) {
 		beforeStep: options.beforeStep,
 		afterStep: options.afterStep,
 		gracePeriod: options.gracePeriod,
+		timeout: options.timeout,
 		resources: options.resources,
+		init: options.init,
+		...options.cache !== void 0 && { cache: options.cache },
+		...options.requireApproval !== void 0 && { requireApproval: options.requireApproval },
 		result: createJobOutputProxy(name)
 	};
 }

package/dist/step.js

@@ -65,9 +65,11 @@ function step(nameOrRunOrOptions, runOrOptions) {
 		run: options.run,
 		continueOnError: options.continueOnError,
 		timeout: options.timeout,
+		...options.cache !== void 0 && { cache: options.cache },
 		rules: options.rules,
 		onCancel: options.onCancel,
 		cleanup: options.cleanup,
+		...options.requireApproval !== void 0 && { requireApproval: options.requireApproval },
 		_sourceLocation,
 		result: createStepOutputProxy(name)
 	};

package/dist/types.d.ts

@@ -8,6 +8,8 @@ import type { Matrix, MatrixInclude, MatrixExclude } from './matrix/types.js';
 import type { HookInput } from './hooks/types.js';
 import type { KiciApi } from './api-types.js';
 import type { DynamicGroupRef } from './dynamic-group.js';
+import type { EventPayload } from './events/event-payloads.js';
+import type { RequireApproval } from './approval.js';
 export type { ResourceRequest, ResourceSpec } from '@kici-dev/engine';
 /** Source location captured at a step() call site. */
 export interface SourceLocation {
@@ -44,12 +46,16 @@ export interface Step<TResult = void> {
     readonly continueOnError?: boolean;
     /** Step-level timeout in milliseconds. Overrides the agent's default (30 minutes). */
     readonly timeout?: number;
+    /** Declarative cache: restored before this step, saved after on key miss. */
+    readonly cache?: import('./cache-types.js').CacheInput;
     /** Step-level conditional rules (evaluated agent-side). */
     readonly rules?: Rule[];
     /** Runs on cancellation. */
     readonly onCancel?: HookInput;
     /** Always runs after step (success, failure, or cancel). */
     readonly cleanup?: HookInput;
+    /** Pause for a manual human approval before this step runs. */
+    readonly requireApproval?: RequireApproval;
     /** Internal: source location captured at step() call site. Not part of public API. */
     readonly _sourceLocation?: SourceLocation;
     /**
@@ -80,12 +86,16 @@ export interface StepOptions<TResult = void> {
     continueOnError?: boolean;
     /** Step-level timeout in milliseconds. Overrides the agent's default (30 minutes). */
     timeout?: number;
+    /** Declarative cache: restored before this step, saved after on key miss. */
+    cache?: import('./cache-types.js').CacheInput;
     /** Step-level conditional rules (evaluated agent-side). */
     rules?: Rule[];
     /** Runs on cancellation. */
     onCancel?: HookInput;
     /** Always runs after step (success, failure, or cancel). */
     cleanup?: HookInput;
+    /** Pause for a manual human approval before this step runs. */
+    requireApproval?: RequireApproval;
 }
 /** Trigger type (config objects returned by pr()/push() factory functions) */
 export type Trigger = TriggerConfig;
@@ -114,7 +124,8 @@ export interface DynamicJobContext {
         workflow: {
             name: string;
         };
-        event?: Record<string, unknown>;
+        /** Normalized event envelope that triggered this run. */
+        event?: EventPayload;
     };
     /** Structured logger */
     log: Logger;
@@ -176,6 +187,29 @@ export interface ContainerConfig {
     /** Additional environment variables for the container */
     env?: Record<string, string>;
 }
+/**
+ * Generic per-job initialization config. Runs a hand-written command after the
+ * repo is cloned and before the job's steps execute, so a repo-declared
+ * toolchain (mise, a custom setup script, …) is provisioned and put on the
+ * step environment's PATH.
+ *
+ * The command writes env it wants visible to later steps to the file at
+ * `$KICI_ENV` (one `KEY=value` line each) and PATH additions to `$KICI_PATH`
+ * (one directory per line) — the agent reads both after the command and applies
+ * the delta to every subsequent step.
+ */
+export interface GenericInitConfig {
+    /** Command run after clone, before steps. Runs in the job's sandbox at the clone root. */
+    run: string;
+    /** Shell used to run `run`. Defaults to 'bash'. */
+    shell?: string;
+    /** Cache spec for binaries the command fetches/installs (restored before, saved after on key miss). */
+    cache?: import('./cache-types.js').CacheSpec;
+    /** Max wall-clock for this init command in ms. Reuses the step/job timeout semantics. */
+    timeout?: number;
+    /** Static environment variables available to the command. */
+    env?: Record<string, string>;
+}
 /**
  * Structured runsOn selector with required and excluded labels.
  * Used when jobs need to target specific agents while excluding others.
@@ -226,12 +260,12 @@ export interface Job {
     readonly checkout?: boolean;
     /** Docker image for job execution. All steps run inside the container. */
     readonly container?: string | ContainerConfig;
-    /** Deployment environment for this job. String for static, async function for dynamic (resolved at orchestrator two-phase eval). */
-    readonly environment?: string | ((event: Record<string, unknown>) => string | Promise<string>);
-    /** Environment variables. Static object or async function (resolved at orchestrator two-phase eval). */
-    readonly env?: Record<string, string> | ((event: Record<string, unknown>) => Record<string, string> | Promise<Record<string, string>>);
-    /** Concurrency group name. Defaults to environment name if not set. String or async function. */
-    readonly concurrencyGroup?: string | ((event: Record<string, unknown>) => string | Promise<string>);
+    /** Deployment environment for this job. String for static, or a function of the normalized event envelope for dynamic (resolved at orchestrator two-phase eval). */
+    readonly environment?: string | ((event: EventPayload) => string | Promise<string>);
+    /** Environment variables. Static object or a function of the normalized event envelope (resolved at orchestrator two-phase eval). */
+    readonly env?: Record<string, string> | ((event: EventPayload) => Record<string, string> | Promise<Record<string, string>>);
+    /** Concurrency group name. Defaults to environment name if not set. String or a function of the normalized event envelope. */
+    readonly concurrencyGroup?: string | ((event: EventPayload) => string | Promise<string>);
     /** Runs on cancellation. */
     readonly onCancel?: HookInput;
     /** Always runs after job (success, failure, or cancel). */
@@ -246,6 +280,8 @@ export interface Job {
     readonly afterStep?: HookInput;
     /** Seconds before SIGKILL after SIGTERM during cancellation. */
     readonly gracePeriod?: number;
+    /** Total job wall-clock timeout in milliseconds (init + all steps + hooks). On breach the job is aborted and reported timed out. Agent-enforced. Independent of step-level timeout. */
+    readonly timeout?: number;
     /**
      * Resource request and limit for this job. Used by the scaler to enforce
      * per-scaler / per-orchestrator / per-machine caps and the kernel-side limits
@@ -260,6 +296,16 @@ export interface Job {
      * toward the agent-count cap.
      */
     readonly resources?: ResourceRequest;
+    /**
+     * Per-job initialization. Runs after clone, before steps.
+     * - A `GenericInitConfig` (or array, run in order) provisions a toolchain.
+     * - `false` is an explicit opt-out (reserved for the future auto-detect layer).
+     */
+    readonly init?: GenericInitConfig | GenericInitConfig[] | false;
+    /** Declarative cache: restored before steps, saved after the job on key miss. */
+    readonly cache?: import('./cache-types.js').CacheInput;
+    /** Pause for a manual human approval before this job dispatches. */
+    readonly requireApproval?: RequireApproval;
     /**
      * Type-safe proxy for accessing this job's outputs.
      * For multi-step jobs: jobRef.result.stepName.field
@@ -317,12 +363,12 @@ export interface JobOptions {
      * When set, all steps run inside the container.
      */
     container?: string | ContainerConfig;
-    /** Deployment environment for this job. String for static, async function for dynamic (resolved at orchestrator two-phase eval). */
-    environment?: string | ((event: Record<string, unknown>) => string | Promise<string>);
-    /** Environment variables. Static object or async function (resolved at orchestrator two-phase eval). */
-    env?: Record<string, string> | ((event: Record<string, unknown>) => Record<string, string> | Promise<Record<string, string>>);
-    /** Concurrency group name. Defaults to environment name if not set. String or async function. */
-    concurrencyGroup?: string | ((event: Record<string, unknown>) => string | Promise<string>);
+    /** Deployment environment for this job. String for static, or a function of the normalized event envelope for dynamic (resolved at orchestrator two-phase eval). */
+    environment?: string | ((event: EventPayload) => string | Promise<string>);
+    /** Environment variables. Static object or a function of the normalized event envelope (resolved at orchestrator two-phase eval). */
+    env?: Record<string, string> | ((event: EventPayload) => Record<string, string> | Promise<Record<string, string>>);
+    /** Concurrency group name. Defaults to environment name if not set. String or a function of the normalized event envelope. */
+    concurrencyGroup?: string | ((event: EventPayload) => string | Promise<string>);
     /** Runs on cancellation. */
     onCancel?: HookInput;
     /** Always runs after job (success, failure, or cancel). */
@@ -337,6 +383,8 @@ export interface JobOptions {
     afterStep?: HookInput;
     /** Seconds before SIGKILL after SIGTERM during cancellation. */
     gracePeriod?: number;
+    /** Total job wall-clock timeout in milliseconds (init + all steps + hooks). On breach the job is aborted and reported timed out. Agent-enforced. Independent of step-level timeout. */
+    timeout?: number;
     /**
      * Resource request and limit for this job. Used by the scaler to enforce
      * per-scaler / per-orchestrator / per-machine caps and the kernel-side limits
@@ -351,6 +399,16 @@ export interface JobOptions {
      * toward the agent-count cap.
      */
     resources?: ResourceRequest;
+    /**
+     * Per-job initialization. Runs after clone, before steps.
+     * - A `GenericInitConfig` (or array, run in order) provisions a toolchain.
+     * - `false` is an explicit opt-out (reserved for the future auto-detect layer).
+     */
+    init?: GenericInitConfig | GenericInitConfig[] | false;
+    /** Declarative cache: restored before steps, saved after the job on key miss. */
+    cache?: import('./cache-types.js').CacheInput;
+    /** Pause for a manual human approval before this job dispatches. */
+    requireApproval?: RequireApproval;
 }
 /**
  * Private npm registry declaration. Tells the agent to authenticate against
@@ -409,6 +467,8 @@ export interface Workflow {
      * prefix is stripped for the env-var name).
      */
     readonly installEnv?: readonly string[];
+    /** Whole-run wall-clock timeout in milliseconds across all jobs. On breach the orchestrator cancels outstanding/queued jobs and marks the run timed out. Orchestrator-enforced. Independent of job-level timeout. */
+    readonly timeout?: number;
     /** Runs on cancellation. */
     readonly onCancel?: HookInput;
     /** Always runs after workflow (success, failure, or cancel). */
@@ -421,11 +481,13 @@ export interface Workflow {
     readonly concurrency?: {
         readonly group: (ctx: {
             branch: string;
-            event: Record<string, unknown>;
+            event: EventPayload;
         }) => string;
         readonly cancelInProgress?: boolean;
         readonly max?: number;
     };
+    /** Pause for a manual human approval before the whole workflow dispatches. */
+    readonly requireApproval?: RequireApproval;
 }
 /** Options for workflow() factory */
 export interface WorkflowOptions {
@@ -458,6 +520,8 @@ export interface WorkflowOptions {
      * exposed to the install subprocess under the `<secret-name>` key.
      */
     installEnv?: string[];
+    /** Whole-run wall-clock timeout in milliseconds across all jobs. On breach the orchestrator cancels outstanding/queued jobs and marks the run timed out. Orchestrator-enforced. Independent of job-level timeout. */
+    timeout?: number;
     /** Runs on cancellation. */
     onCancel?: HookInput;
     /** Always runs after workflow (success, failure, or cancel). */
@@ -470,11 +534,13 @@ export interface WorkflowOptions {
     concurrency?: {
         group: (ctx: {
             branch: string;
-            event: Record<string, unknown>;
+            event: EventPayload;
         }) => string;
         cancelInProgress?: boolean;
         max?: number;
     };
+    /** Pause for a manual human approval before the whole workflow dispatches. */
+    requireApproval?: RequireApproval;
 }
 export type { TriggerConfig, PrTriggerConfig, PushTriggerConfig } from './triggers/types.js';
 export type { Rule, RuleContext, RuleCheckFn, RuleResult } from './rules/types.js';

package/dist/workflow.js

@@ -70,11 +70,13 @@ function workflow(name, options) {
 		hashFiles: options.hashFiles,
 		registries: options.registries,
 		installEnv: options.installEnv,
+		timeout: options.timeout,
 		onCancel: options.onCancel,
 		cleanup: options.cleanup,
 		onSuccess: options.onSuccess,
 		onFailure: options.onFailure,
-		concurrency: options.concurrency
+		concurrency: options.concurrency,
+		requireApproval: options.requireApproval
 	};
 }
 //#endregion

package/package.json

@@ -1,18 +1,22 @@
 {
   "name": "@kici-dev/sdk",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
   "keywords": [
-    "kici",
     "ci",
-    "cd",
-    "ci-cd",
+    "cicd",
+    "continuous-integration",
     "typescript",
-    "workflows",
-    "devops",
+    "workflow",
     "sdk",
-    "dsl"
+    "pipeline"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kici-dev/kici-public.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": "https://github.com/kici-dev/kici-public/issues",
   "homepage": "https://kici.dev",
   "author": {
     "name": "KiCI",
@@ -46,8 +50,8 @@
     "micromatch": "^4.0.8",
     "zod": "^4.3.6",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.14",
-    "@kici-dev/engine": "0.1.14"
+    "@kici-dev/core": "0.1.16",
+    "@kici-dev/engine": "0.1.16"
   },
   "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.14",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.14/89096b19-0fba-4f00-884f-26dadf7c8045",
+  "name": "@kici-dev/sdk@0.1.16",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.16/49f54029-d7dc-48b9-ad51-af6b845b321f",
   "creationInfo": {
-    "created": "2026-05-30T03:06:03Z",
+    "created": "2026-06-12T09:41:41Z",
     "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.14",
+      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.16",
       "name": "@kici-dev/core",
-      "versionInfo": "0.1.14",
+      "versionInfo": "0.1.16",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -159,16 +159,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.14"
+          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.16"
         }
       ],
       "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.14",
+      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.1.16",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.1.14",
+      "versionInfo": "0.1.16",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -179,7 +179,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.14"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.16"
         }
       ],
       "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.14",
+      "versionInfo": "0.1.16",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -199,7 +199,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.14"
+          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.16"
         }
       ],
       "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
@@ -1544,58 +1544,58 @@
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-oxc-transform-0.128.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-picocolors-1.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-winston-daily-rotate-file-5.0.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.3.6",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.14",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-jsonpath-plus-10.4.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.14",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.4",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.14",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.16",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.3.6",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.16",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.14",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.16",
       "relationshipType": "DEPENDS_ON"
     },
     {