@kici-dev/sdk 0.5.0 → 0.6.1

package/dist/agent-cloud-init.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @deprecated Pass a claim code (ClaimCodeCredentials) so the token never
+ * transits cloud-init. Removed at v1.0.0.
+ */
+export interface CloudInitCredentials {
+    agentToken: string;
+    agentId: string;
+    orchestratorUrl: string;
+    labels: string[];
+}
+/** Preferred: the agent self-claims from a single-use code; the token is minted in-instance. */
+export interface ClaimCodeCredentials {
+    claimCode: string;
+    agentId: string;
+    orchestratorUrl: string;
+    labels: string[];
+}
+/** Either credential shape accepted by `buildAgentCloudInit`. */
+export type AgentCloudInitCredentials = CloudInitCredentials | ClaimCodeCredentials;
+/** How the agent binary is delivered onto the instance. */
+export type AgentDeliveryMode = 'container' | 'payload';
+/** How the rendered `user_data` string is encoded before it is returned. */
+export type UserDataEncoding = 'raw' | 'base64';
+/** A cloud-init `write_files` entry the caller adds. */
+export interface CloudInitWriteFile {
+    path: string;
+    content: string;
+    permissions?: string;
+    owner?: string;
+}
+export interface AgentCloudInitOptions {
+    /** Hard lifetime cap (minutes) after which the instance powers itself off (L2). */
+    maxLifetimeMinutes: number;
+    /** 'container' (docker run the published agent image) | 'payload' (fetch from orchestrator). */
+    deliveryMode?: AgentDeliveryMode;
+    /** Container image ref (container mode). */
+    agentImage?: string;
+    /** Escape hatch: fully override the agent-start command (ignores deliveryMode/agentImage). */
+    startCommand?: string;
+    /** apt/yum packages → cloud-init `packages:` (unioned with the base). */
+    packages?: string[];
+    /** Extra `write_files` entries (the reserved env-file path is rejected). */
+    writeFiles?: CloudInitWriteFile[];
+    /** runcmd lines injected BEFORE the agent starts. */
+    runcmdBefore?: string[];
+    /** runcmd lines injected AFTER the agent starts. */
+    runcmdAfter?: string[];
+    /** Extra env appended to the agent env file (keys validated, newline values rejected). */
+    agentEnv?: Record<string, string>;
+    /** Raw cloud-config YAML to merge everything into (users, ssh, apt, mounts, bootcmd, …). */
+    baseCloudConfig?: string;
+    /**
+     * Encoding of the returned `user_data` string. `'raw'` (the default) returns
+     * the plain `#cloud-config` text — what Hetzner `user_data` expects. `'base64'`
+     * returns the same text base64-encoded, the form AWS EC2 `UserData` and Azure
+     * `customData` expect.
+     */
+    userDataEncoding?: UserDataEncoding;
+}
+/**
+ * Build the cloud-config `user_data` string. In the token form the agent token
+ * appears only in the reserved env-file write entry (`0600`, root-only); the
+ * claim-code form keeps the token off the provisioning channel entirely.
+ */
+export declare function buildAgentCloudInit(creds: AgentCloudInitCredentials, options: AgentCloudInitOptions): string;
+//# sourceMappingURL=agent-cloud-init.d.ts.map

package/dist/agent-cloud-init.js

@@ -0,0 +1,128 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { parse, stringify } from "yaml";
+//#region src/agent-cloud-init.ts
+/**
+* Cloud-init `user_data` builder for a scaler-provisioned KiCI agent.
+*
+* Renders a `#cloud-config` that installs + starts the agent with the claimed
+* ephemeral credentials, plus teardown layer L2 — an in-instance max-lifetime
+* self-poweroff. The agent token is written ONLY into a root-only `0600` env
+* file; it never appears in a comment, a process argument, or any other file.
+*/
+const AGENT_ENV_FILE = "/etc/kici-agent.env";
+const DEFAULT_AGENT_IMAGE = "quay.io/kici-dev/kici-agent:latest";
+/**
+* The credential-specific env lines. The claim-code form emits a single-use
+* code the agent exchanges for its own token in-instance; the token form emits
+* the token directly (the ONLY place the token appears).
+*/
+function credentialEnvLines(creds) {
+	if ("claimCode" in creds) return [
+		`KICI_ORCHESTRATOR_URL=${creds.orchestratorUrl}`,
+		`KICI_SCALER_CLAIM_CODE=${creds.claimCode}`,
+		`KICI_AGENT_ID=${creds.agentId}`,
+		`KICI_LABELS=${creds.labels.join(",")}`
+	];
+	return [
+		`KICI_ORCHESTRATOR_URL=${creds.orchestratorUrl}`,
+		`KICI_AGENT_TOKEN=${creds.agentToken}`,
+		`KICI_AGENT_ID=${creds.agentId}`,
+		`KICI_LABELS=${creds.labels.join(",")}`
+	];
+}
+/** Render the agent env-file content (the ONLY place the token appears, in the token form). */
+function renderEnvFileContent(creds, agentEnv) {
+	return `${[
+		...credentialEnvLines(creds),
+		"KICI_SCALER_MANAGED=1",
+		...Object.entries(agentEnv ?? {}).map(([k, v]) => `${k}=${v}`)
+	].join("\n")}\n`;
+}
+/** Dedupe a list preserving first-seen order. */
+function dedupe(items) {
+	return [...new Set(items)];
+}
+/** POSIX env-name shape: a letter or underscore, then letters/digits/underscores. */
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Reject agentEnv keys that are not POSIX env names and values carrying a newline. */
+function validateAgentEnv(agentEnv) {
+	for (const [key, value] of Object.entries(agentEnv ?? {})) {
+		if (!ENV_NAME_RE.test(key)) throw new Error(`buildAgentCloudInit: invalid agentEnv key "${key}" (must be a POSIX env name)`);
+		if (value.includes("\n")) throw new Error(`buildAgentCloudInit: agentEnv value for "${key}" must not contain a newline`);
+	}
+}
+/** Reject any caller/base write_files entry targeting the reserved env-file path. */
+function assertNoReservedWrite(writeFiles, where) {
+	for (const wf of writeFiles ?? []) if (wf.path === AGENT_ENV_FILE) throw new Error(`buildAgentCloudInit: ${where} may not write the reserved path ${AGENT_ENV_FILE}`);
+}
+/** Parse + shape-check a caller-supplied base cloud-config. */
+function parseBase(baseCloudConfig) {
+	let parsed;
+	try {
+		parsed = parse(baseCloudConfig);
+	} catch (err) {
+		throw new Error(`buildAgentCloudInit: baseCloudConfig is not valid YAML: ${err.message}`);
+	}
+	if (parsed == null) return {};
+	if (typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("buildAgentCloudInit: baseCloudConfig must be a cloud-config mapping");
+	const base = parsed;
+	for (const key of [
+		"packages",
+		"runcmd",
+		"write_files"
+	]) if (base[key] !== void 0 && !Array.isArray(base[key])) throw new Error(`buildAgentCloudInit: baseCloudConfig.${key} must be a list`);
+	return base;
+}
+/** Render the command that starts the agent for the chosen delivery mode. */
+function renderStartCommand(opts) {
+	if (opts.startCommand) return opts.startCommand;
+	if (opts.deliveryMode === "payload") return "/usr/local/bin/kici-agent-bootstrap";
+	const image = opts.agentImage ?? DEFAULT_AGENT_IMAGE;
+	return `docker run -d --restart=no --name kici-agent --network host --env-file ${AGENT_ENV_FILE} ${image}`;
+}
+/**
+* Build the cloud-config `user_data` string. In the token form the agent token
+* appears only in the reserved env-file write entry (`0600`, root-only); the
+* claim-code form keeps the token off the provisioning channel entirely.
+*/
+function buildAgentCloudInit(creds, options) {
+	validateAgentEnv(options.agentEnv);
+	assertNoReservedWrite(options.writeFiles, "writeFiles");
+	const cap = Math.max(1, Math.floor(options.maxLifetimeMinutes));
+	const base = options.baseCloudConfig ? parseBase(options.baseCloudConfig) : {};
+	assertNoReservedWrite(base.write_files, "baseCloudConfig");
+	const baseWriteFiles = base.write_files ?? [];
+	const baseRuncmd = base.runcmd ?? [];
+	const basePackages = base.packages ?? [];
+	const envFile = {
+		path: AGENT_ENV_FILE,
+		permissions: "0600",
+		owner: "root:root",
+		content: renderEnvFileContent(creds, options.agentEnv)
+	};
+	const pkgs = dedupe([...basePackages, ...options.packages ?? []]);
+	const model = {
+		...base,
+		write_files: [
+			...baseWriteFiles,
+			envFile,
+			...options.writeFiles ?? []
+		],
+		runcmd: [
+			...baseRuncmd,
+			...options.runcmdBefore ?? [],
+			`systemd-run --on-active=${cap}m --timer-property=AccuracySec=1s /sbin/poweroff`,
+			renderStartCommand(options),
+			...options.runcmdAfter ?? []
+		]
+	};
+	if (pkgs.length > 0) model.packages = pkgs;
+	else delete model.packages;
+	const cloudConfig = `#cloud-config\n${stringify(model, { lineWidth: 0 })}`;
+	if (options.userDataEncoding === "base64") return Buffer.from(cloudConfig, "utf8").toString("base64");
+	return cloudConfig;
+}
+//#endregion
+export { buildAgentCloudInit };
+
+//# sourceMappingURL=agent-cloud-init.js.map

package/dist/api-types.d.ts

@@ -9,6 +9,7 @@
  * 2. Register the handler in the orchestrator's AgentApiRegistry
  */
 import { type OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
+import type { GitApi } from './git-types.js';
 import type { HostInventoryEntry, InventorySelector } from '@kici-dev/engine';
 export type { OidcTokenResult };
 export type { HostInventoryEntry, InventorySelector };
@@ -136,6 +137,27 @@ export interface BootstrapApi {
         restaged: boolean;
     }>;
 }
+/** Credentials a provisioning workflow uses to boot a scaler-provisioned agent. */
+export interface ClaimedAgentCredentials {
+    /** Single-use ephemeral agent token the provisioned instance registers with. */
+    agentToken: string;
+    /** Agent id the instance must register with (chosen by the scaler). */
+    agentId: string;
+    /** Orchestrator WS URL the instance connects back to. */
+    orchestratorUrl: string;
+    /** Labels the token authorizes. */
+    labels: string[];
+}
+export interface ScalerApi {
+    /**
+     * Exchange a single-use claim code — delivered on a `kici.scaler.scale-up`
+     * event to a provisioning workflow — for freshly minted ephemeral agent
+     * credentials. Boot a cloud instance whose agent registers with the returned
+     * `agentId` and `agentToken`, and the pending bound job runs on it. The token
+     * is minted lazily on this call and never appears in the persisted event log.
+     */
+    claimAgentCredentials(claimCode: string): Promise<ClaimedAgentCredentials>;
+}
 export interface KiciApi {
     /** Query orchestrator infrastructure (scalers, agents). */
     infrastructure: InfrastructureApi;
@@ -143,10 +165,14 @@ export interface KiciApi {
     inventory: InventoryApi;
     /** Request short-lived OIDC ID tokens for the current job (build provenance). */
     oidc: OidcApi;
+    /** Forge-typed git credentials for the current job. */
+    git: GitApi;
     /** Host-lifecycle operations on the agent's own host (e.g. reboot). */
     host: HostApi;
     /** Fresh-box bootstrap bring-up (init-runner over SSH, pre-boot unlock). */
     bootstrap: BootstrapApi;
+    /** Event-scaler provisioning: claim ephemeral agent credentials. */
+    scaler: ScalerApi;
 }
 /**
  * Low-level transport function used to implement KiciApi.

package/dist/api-types.js

@@ -1,5 +1,6 @@
 import "./rolldown-runtime-ClRpJifh.js";
 import { OIDC_TOKEN_REQUEST_METHOD } from "@kici-dev/engine/protocol/messages/oidc-token-relay";
+import { GIT_CREDENTIAL_REQUEST_METHOD } from "@kici-dev/engine/protocol/messages/git-credential-relay";
 //#region src/api-types.ts
 /**
 * Typed KiCI API available to workflows via ctx.kici.
@@ -37,6 +38,23 @@ function buildKiciApi(transport, jobCtx) {
 				audience: opts.audience
 			});
 		} },
+		git: { github: { getToken: (opts) => {
+			if (!jobCtx) return Promise.reject(/* @__PURE__ */ new Error("ctx.kici.git.github.getToken() is only available inside a running job step"));
+			if (opts.repositories.length === 0) return Promise.reject(/* @__PURE__ */ new Error("git.github.getToken requires at least one repository"));
+			return transport(GIT_CREDENTIAL_REQUEST_METHOD, {
+				jobId: jobCtx.jobId,
+				repositories: opts.repositories,
+				permissions: opts.permissions,
+				...opts.credential ? { credential: opts.credential } : {}
+			}).then((raw) => {
+				const r = raw;
+				return {
+					token: r.secret,
+					expiresAt: r.expiresAt,
+					granted: r.grant
+				};
+			});
+		} } },
 		host: { requestReboot: (opts) => transport("host.requestReboot", { ...opts?.deadlineMs !== void 0 ? { deadlineMs: opts.deadlineMs } : {} }) },
 		bootstrap: {
 			ensureInitRunner: (targetAgentId) => transport("kici.ensureInitRunner", { targetAgentId }),
@@ -46,7 +64,8 @@ function buildKiciApi(transport, jobCtx) {
 			}),
 			agentVersionStatus: (targetAgentId) => transport("kici.agentVersionStatus", { targetAgentId }),
 			restageAgent: (targetAgentId) => transport("kici.restageAgent", { targetAgentId })
-		}
+		},
+		scaler: { claimAgentCredentials: (claimCode) => transport("scaler.claim-credentials", { claimCode }) }
 	};
 }
 //#endregion

package/dist/context.d.ts

@@ -189,6 +189,27 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * Defaults to false for backward compatibility.
      */
     isTestRun: boolean;
+    /**
+     * The job's own checked-out repository.
+     *
+     * Present for every job that checks out (unlike `sourceRepo` / `workflowRepo`,
+     * which exist only for a global workflow). `withWrite` opens a write window
+     * for THIS repository, bounded by the repository and by the callback's
+     * duration — not by the step: steps running concurrently in the same job can
+     * push to the same repository while it is open, but cannot reach a different
+     * one. It throws before any git runs when the forge will not grant what was
+     * requested.
+     */
+    repo?: {
+        identifier: string;
+        path: string;
+        ref?: string;
+        sha?: string;
+        withWrite(opts: {
+            permissions?: Record<string, string>;
+            credential?: string;
+        }, fn: () => Promise<void>): Promise<void>;
+    };
     /**
      * Workflow repo metadata -- only set for global workflows.
      * The registering repo where the workflow code is defined.

package/dist/filter.test-d.d.ts

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

package/dist/filter.test-d.js

@@ -0,0 +1,30 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { workflow } from "./workflow.js";
+import { job } from "./job.js";
+import { step } from "./step.js";
+import { describe, expectTypeOf, it } from "vitest";
+//#region src/filter.test-d.ts
+const noop = job("noop", {
+	runsOn: "linux",
+	steps: [step("x", { run: async () => {} })]
+});
+describe("workflow filter — type level", () => {
+	it("rejects a non-function filter", () => {
+		workflow("org-ci", {
+			jobs: [noop],
+			filter: "yes"
+		});
+	});
+	it("accepts a function filter", () => {
+		const filter = ({ sourceRepo }) => sourceRepo.identifier !== "a/b";
+		const wf = workflow("org-ci", {
+			jobs: [noop],
+			filter
+		});
+		expectTypeOf(wf.filter).toEqualTypeOf();
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=filter.test-d.js.map

package/dist/git-types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Forge-typed git surface for workflow authors.
+ *
+ * The forge is a TYPE PARAMETER and nothing more. It is erased at runtime:
+ * `kici.git.clone<'github'>()` against a Forgejo source compiles cleanly, the
+ * requested permissions are ignored, and the result reports
+ * `granted: { scoped: false }`. It buys autocomplete and a compile error on a
+ * wrong-shaped permission object; it buys no safety. The runtime `granted`
+ * value is the only source of truth about what a credential can do.
+ */
+/** Forges that can back a git credential. Mirrors the engine's `ForgeName`. */
+export type ForgeName = 'github' | 'gitlab' | 'bitbucket' | 'generic';
+/**
+ * GitHub repository permissions.
+ *
+ * DELIBERATE CARVE-OUT from the enums-over-hardcoded-strings rule: the known
+ * keys below are typed so editors autocomplete them, but an index signature
+ * lets an unknown key through. GitHub adds permissions over time, and a closed
+ * enum would mean a permission shipped yesterday needs an SDK release — and the
+ * SDK is compat-protected and rides the single-version release train. Unknown
+ * keys are passed to GitHub verbatim for it to accept or reject.
+ */
+export interface GitHubPermissions {
+    contents?: 'read' | 'write';
+    metadata?: 'read';
+    workflows?: 'write';
+    actions?: 'read' | 'write';
+    pull_requests?: 'read' | 'write';
+    issues?: 'read' | 'write';
+    checks?: 'read' | 'write';
+    statuses?: 'read' | 'write';
+    deployments?: 'read' | 'write';
+    packages?: 'read' | 'write';
+    [permission: string]: string | undefined;
+}
+/**
+ * Options for a write elevation, shaped by the forge.
+ *
+ * `WriteOptions<'generic'>` carries no permission fields at all: a static
+ * credential has nothing to request, because an SSH key or PAT is read-write or
+ * it is not.
+ */
+export type WriteOptions<F extends ForgeName = 'github'> = F extends 'github' ? {
+    permissions: GitHubPermissions;
+} : Record<never, never>;
+/** What a credential turned out to be able to do. Never an echo of the request. */
+export type GitGrant = {
+    scoped: false;
+} | {
+    scoped: true;
+    permissions: Record<string, string>;
+};
+/**
+ * One half of a credential field pair. Exactly one form is set: a qualified
+ * `<context>:<secret-name>` reference resolved from the secrets backend, or
+ * material supplied at runtime.
+ *
+ * The field NAME is the discriminator, following the convention `workflow.ts`
+ * already sets with `registries[].tokenSecret` and `isQualifiedSecretRef`.
+ */
+export type Sourced<Name extends string> = {
+    [K in `${Name}Secret`]: string;
+} | {
+    [K in `${Name}Value`]: string;
+};
+/** Where credential material comes from, for each supported credential shape. */
+export type GitCredentialRef = ({
+    kind: 'app';
+} & Sourced<'appId'> & Sourced<'installationId'> & Sourced<'privateKey'>) | ({
+    kind: 'token';
+    user?: string;
+} & Sourced<'token'>) | ({
+    kind: 'ssh';
+} & Sourced<'privateKey'>);
+/** Named credentials for a job. `default` is used when a call names none. */
+export type GitCredentialMap = Record<string, GitCredentialRef>;
+/**
+ * Resolve a call site's credential.
+ *
+ * Order: an explicit per-call value wins; otherwise `default` from the job map;
+ * otherwise undefined, which means the source credential — all a read needs.
+ *
+ * An unknown name THROWS rather than falling back to `default`: silently using
+ * a different credential than the author named is precisely the confusion this
+ * map exists to remove.
+ */
+export declare function resolveCredential(perCall: string | GitCredentialRef | undefined, map: GitCredentialMap | undefined): GitCredentialRef | undefined;
+/**
+ * Every credential field names a secret. Catch the easy, silent mistake of
+ * pasting the credential itself — which would commit it to a git repository.
+ */
+export declare function assertSecretName(value: string, field: string, subject?: string): void;
+/**
+ * Private-registry credentials for pulling a job's container image.
+ *
+ * Built from `Sourced<Name>` so "this field names a secret" has ONE spelling
+ * across the SDK — the same one `gitCredentials` uses. `username` may be a
+ * plain string (a registry username is not a secret); the token may not be.
+ */
+export type ContainerRegistryAuth = Sourced<'token'> & {
+    /** Plain registry username. Mutually exclusive with `usernameSecret`. */
+    username?: string;
+    /**
+     * Registry host these credentials belong to (e.g. `reg.internal:5000`).
+     *
+     * Optional with `container.image`, where it is derived from the image
+     * reference. REQUIRED with `container.dockerfile`: the base image is named
+     * inside the Dockerfile, so there is nothing to derive it from.
+     */
+    registry?: string;
+} & Partial<Sourced<'username'>>;
+/** A checked-out repository. The forge travels with the handle. */
+export interface RepoHandle<F extends ForgeName = 'github'> {
+    /** `owner/repo`. */
+    identifier: string;
+    /** Absolute path to the working tree. */
+    path: string;
+    ref?: string;
+    sha?: string;
+    /**
+     * Run `fn` with write credentials for THIS repository.
+     *
+     * The grant is scoped to this repository and to the duration of `fn` — NOT to
+     * the calling step. The agent runs one process per job and `parallel()` runs
+     * its children inside it, so a concurrent sibling step can push to the same
+     * repository while the grant is live. It cannot reach a different repository.
+     *
+     * Throws at entry — before any git runs — when the forge grants less than was
+     * requested, naming the missing permission.
+     */
+    withWrite(opts: WriteOptions<F>, fn: () => Promise<void>): Promise<void>;
+}
+/** Result of an explicit token request. */
+export interface GitTokenResult {
+    token: string;
+    expiresAt: string | null;
+    granted: GitGrant;
+}
+/** Forge-specific minting. Only minted shapes appear here; static ones have nothing to mint. */
+export interface GitHubApi {
+    /**
+     * Mint a token as a VALUE, for the forge API, the `gh` CLI, or a third-party
+     * tool. Auto-masked in step logs; job-bound; throws outside a running step.
+     *
+     * For git operations prefer `handle.withWrite()`, which never puts a token in
+     * the step environment. `gh` does not read git credential helpers, which is
+     * why this exists.
+     */
+    getToken(opts: {
+        repositories: string[];
+        permissions: GitHubPermissions;
+        /**
+         * Name an entry in the job's `gitCredentials` map. Omit to use `default`;
+         * omit both and the source credential applies.
+         */
+        credential?: string;
+    }): Promise<GitTokenResult>;
+}
+export interface GitApi {
+    github: GitHubApi;
+}
+//# sourceMappingURL=git-types.d.ts.map

package/dist/git-types.js

@@ -0,0 +1,32 @@
+import "./rolldown-runtime-ClRpJifh.js";
+//#region src/git-types.ts
+/**
+* Resolve a call site's credential.
+*
+* Order: an explicit per-call value wins; otherwise `default` from the job map;
+* otherwise undefined, which means the source credential — all a read needs.
+*
+* An unknown name THROWS rather than falling back to `default`: silently using
+* a different credential than the author named is precisely the confusion this
+* map exists to remove.
+*/
+function resolveCredential(perCall, map) {
+	if (perCall && typeof perCall === "object") return perCall;
+	if (typeof perCall === "string") {
+		const found = map?.[perCall];
+		if (!found) throw new Error(`Unknown git credential '${perCall}'. Declare it in the job's gitCredentials map. Known: ${Object.keys(map ?? {}).join(", ") || "(none)"}`);
+		return found;
+	}
+	return map?.default;
+}
+/**
+* Every credential field names a secret. Catch the easy, silent mistake of
+* pasting the credential itself — which would commit it to a git repository.
+*/
+function assertSecretName(value, field, subject = "git credential") {
+	if (value.startsWith("-----BEGIN") || /^gh[pousr]_/.test(value) || value.startsWith("github_pat_")) throw new Error(`${subject} '${field}' looks like the credential itself, not the name of a secret holding it. Store it with \`kici-admin secret set\` and name it here.`);
+}
+//#endregion
+export { assertSecretName, resolveCredential };
+
+//# sourceMappingURL=git-types.js.map

package/dist/idempotent.js

@@ -83,7 +83,7 @@ function idempotentStep(name, opts) {
 * lockfile change.
 */
 function checkStep(name, options) {
-	return step(name, {
+	const checkOptions = {
 		check: options.check,
 		summarize: options.summarize,
 		run: (ctx, drift) => options.apply(ctx, drift),
@@ -94,7 +94,8 @@ function checkStep(name, options) {
 		...options.retry !== void 0 && { retry: options.retry },
 		...options.cache !== void 0 && { cache: options.cache },
 		...options.rules !== void 0 && { rules: options.rules }
-	});
+	};
+	return step(name, checkOptions);
 }
 //#endregion
 export { checkStep, idempotent, idempotentStep };

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { job } from './job.js';
 export { workflow } from './workflow.js';
 export { parallel, isParallelGroup, flattenStepInputs } from './parallel.js';
 export type { ParallelGroup, ParallelOptions } from './parallel.js';
+export { invokeSource } from './invoke.js';
+export type { InvokeConfig } from './invoke.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, workflowsFailedBatch, jobComplete, genericWebhook, schedule, lifecycle, defineDispatchInputs, } from './triggers/index.js';
@@ -21,7 +23,7 @@ export type { SourceLocation, OutputProxy, Step, StepOptions, StepOptionsBase, S
 export { isDynamicJobFn, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, } from './types.js';
 export type { TaggedDynamicJobFn, ResultAwareDynamicJobConfig, ResultAwareDynamicJobFn, DynamicJobNeed, NeedsWhen, NeedsWhenInput, } from './types.js';
 export { buildNeedsContext } from './needs-context.js';
-export type { UpstreamSnapshot, NeedsContext, NeedEntry, GroupNeedEntry } from './needs-context.js';
+export type { UpstreamSnapshot, NeedsContext, NeedEntry, GroupNeedEntry, InvokeNeedEntry, InvokeResult, } from './needs-context.js';
 export { CacheSpecSchema, normalizeCacheSpecs } from './cache-types.js';
 export type { CacheSpec, CacheInput } from './cache-types.js';
 export type { CacheRestoreResult, CacheApi } from './cache-types.js';
@@ -61,4 +63,9 @@ export type { WaitForHostAliveOptions, RestartHostOptions } from './host-restart
 export { agentVersionConverge } from './fleet/agent-version-converge.js';
 export type { AgentVersionConvergeOptions, AgentVersionDrift, } from './fleet/agent-version-converge.js';
 export { z } from 'zod';
+export { SCALER_EVENT_NAMES, ScaleDownReason, ScalerScaleUpPayload, ScalerScaleDownPayload, } from '@kici-dev/engine';
+export { buildAgentCloudInit } from './agent-cloud-init.js';
+export type { CloudInitCredentials, ClaimCodeCredentials, AgentCloudInitCredentials, AgentDeliveryMode, UserDataEncoding, CloudInitWriteFile, AgentCloudInitOptions, } from './agent-cloud-init.js';
+export { assertSecretName } from './git-types.js';
+export type { ForgeName, GitHubPermissions, WriteOptions, GitGrant, Sourced, ContainerRegistryAuth, GitCredentialRef, GitCredentialMap, RepoHandle, GitTokenResult, GitHubApi, GitApi, } from './git-types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,5 @@
 import "./rolldown-runtime-ClRpJifh.js";
+import { buildAgentCloudInit } from "./agent-cloud-init.js";
 import { buildKiciApi } from "./api-types.js";
 import { normalizeApproval } from "./approval.js";
 import { ARTIFACT_NAME_MAX_LENGTH, ArtifactNameSchema } from "./artifacts-types.js";
@@ -8,15 +9,17 @@ import { DYNAMIC_GROUP_TAG, dynamicGroup, isDynamicGroupRef } from "./dynamic-gr
 import { SecretNotFoundError } from "./errors.js";
 import { ChangedFilesUnavailableError } from "./rules/changed-files.js";
 import { createFilterContext } from "./filter-context.js";
-import { fixture } from "./fixture.js";
+import { workflow } from "./workflow.js";
 import { createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, getJobOutputsMap, getStepOutputsMap, getStepRefMap, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "./outputs.js";
+import { assertSecretName } from "./git-types.js";
+import { job } from "./job.js";
 import { step } from "./step.js";
+import { fixture } from "./fixture.js";
 import { WaitForTimeoutError, waitFor, waitForStep } from "./wait-for.js";
 import { restartHost, waitForHostAlive } from "./host-restart.js";
 import { checkStep, idempotent, idempotentStep } from "./idempotent.js";
-import { job } from "./job.js";
-import { workflow } from "./workflow.js";
 import { flattenStepInputs, isParallelGroup, parallel } from "./parallel.js";
+import { invokeSource } from "./invoke.js";
 import { pr } from "./triggers/pr.js";
 import { push } from "./triggers/push.js";
 import { tag } from "./triggers/tag.js";
@@ -60,5 +63,6 @@ import "./matrix/index.js";
 import { defineEvent, isEventDefinition } from "./events/define-event.js";
 import "./events/index.js";
 import { agentVersionConverge } from "./fleet/agent-version-converge.js";
+import { SCALER_EVENT_NAMES, ScaleDownReason, ScalerScaleDownPayload, ScalerScaleUpPayload } from "@kici-dev/engine";
 import { z } from "zod";
-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, createFilterContext, 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 };
+export { ARTIFACT_NAME_MAX_LENGTH, ArtifactNameSchema, CacheSpecSchema, ChangedFilesUnavailableError, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SCALER_EVENT_NAMES, ScaleDownReason, ScalerScaleDownPayload, ScalerScaleUpPayload, SecretNotFoundError, WaitForTimeoutError, afterStep, agentVersionConverge, applyIncludeExclude, assertSecretName, beforeStep, buildAgentCloudInit, buildKiciApi, buildNeedsContext, checkStep, cleanup, comment, create, createFilterContext, 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, invokeSource, 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/invoke.d.ts

@@ -0,0 +1,29 @@
+/** Config produced by {@link invokeSource}: emit a kici event at the source repo and gate on the runs it triggers. */
+export interface InvokeConfig {
+    readonly _tag: 'InvokeSource';
+    /** The kici event name to emit. Subscribers opt in with `kiciEvent({ name })`. */
+    readonly event: string;
+    /** Target scope. `'source'` targets exactly `ctx.sourceRepo` (the only v1 scope). */
+    readonly scope: 'source';
+    /** Optional event payload delivered to subscribers. */
+    readonly payload?: Readonly<Record<string, unknown>>;
+    /**
+     * When true, a zero-subscriber emit succeeds immediately (the repo may opt out).
+     * When false/unset (the default), a zero-subscriber emit FAILS the gate — a repo
+     * that never wired up its tests must not silently pass the org gate.
+     */
+    readonly optional?: boolean;
+}
+/**
+ * Invoke the source repo's opt-in workflows and gate on them.
+ *
+ * Targets exactly `ctx.sourceRepo`, so a global workflow can hand control back to
+ * the repo whose event triggered it without any org-wide fan-out. Subscribers opt
+ * in with `kiciEvent({ name })`. Required by default: if no workflow subscribes,
+ * the gate fails unless `optional: true` is set.
+ */
+export declare function invokeSource(event: string, opts?: {
+    payload?: Record<string, unknown>;
+    optional?: boolean;
+}): InvokeConfig;
+//# sourceMappingURL=invoke.d.ts.map