@kici-dev/agent 0.0.0 → 0.1.2

package/dist/checkout/git-clone.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Structured clone auth. Mirrors `gitAuthSchema` on the orchestrator-agent
+ * protocol so a single shape carries both HTTPS Basic (GitHub App tokens,
+ * PATs) and SSH (universal-git, pinned host keys).
+ */
+export interface GitAuth {
+    kind: 'basic' | 'ssh';
+    /** Basic-auth username. Omit for SSH. */
+    user?: string;
+    /** Basic-auth password/PAT, or PEM-encoded SSH private key. */
+    secret: string;
+    /** SSH-only. `accept-new` (default) or `pinned`. */
+    sshHostKeyPolicy?: 'accept-new' | 'pinned';
+    /** SSH-only. Required when `sshHostKeyPolicy === 'pinned'`. */
+    sshKnownHostsPem?: string;
+}
+/**
+ * Options for cloning a git repository.
+ */
+interface CloneOptions {
+    /** Full HTTPS repo URL (e.g., https://github.com/org/repo.git) */
+    repoUrl: string;
+    /** Git ref to checkout (branch name or tag) */
+    ref: string;
+    /** Expected commit SHA (for verification after clone) */
+    sha: string;
+    /** Directory to clone into */
+    workDir: string;
+    /**
+     * Optional auth token (GitHub installation token or personal token).
+     * Deprecated in favour of `gitAuth`; retained for backward compatibility
+     * during the Phase 4 universal-git rollout. When both are set, `gitAuth`
+     * wins.
+     */
+    token?: string;
+    /**
+     * Structured auth material. When `kind === 'basic'`, gitAuth is used
+     * instead of `token` via the same `http.extraHeader` path. When
+     * `kind === 'ssh'`, the clone uses `GIT_SSH_COMMAND` with a temp
+     * private key (and optional pinned known_hosts).
+     */
+    gitAuth?: GitAuth;
+    /** Clone depth (default: 1 for shallow clone) */
+    depth?: number;
+}
+/**
+ * Shallow-clone a git repository at a specific ref with optional token auth.
+ *
+ * Token authentication uses git's `-c http.extraHeader` mechanism which keeps
+ * the token out of the clone URL (not visible in `git remote -v` or logs).
+ *
+ * After clone, verifies that HEAD matches the expected SHA to prevent
+ * wrong-ref execution.
+ *
+ * @throws Error if clone fails or SHA does not match
+ */
+export declare function gitClone(options: CloneOptions): Promise<void>;
+export {};
+//# sourceMappingURL=git-clone.d.ts.map

package/dist/checkout/ssh-auth.d.ts

@@ -0,0 +1,34 @@
+export interface SshAuthSetup {
+    /** Value for the `GIT_SSH_COMMAND` env var. */
+    gitSshCommand: string;
+    /** Absolute path of the tempdir — used by tests. Not safe to log. */
+    tempDir: string;
+    /** Removes the tempdir and its contents. Safe to call multiple times. */
+    cleanup(): Promise<void>;
+}
+export interface SetupSshAuthOpts {
+    /** PEM-encoded private key. Must include trailing newline. */
+    privateKey: string;
+    /** 'accept-new' (default) trusts first-seen host keys; 'pinned' requires `knownHosts`. */
+    hostKeyPolicy?: 'accept-new' | 'pinned';
+    /** OpenSSH known_hosts content. Required when `hostKeyPolicy === 'pinned'`. */
+    knownHosts?: string;
+}
+/**
+ * Materialize an SSH private key (and optional pinned known_hosts) into a
+ * tempdir and build the `GIT_SSH_COMMAND` that `git clone` needs.
+ *
+ * Permissions:
+ *   - private key mode 0o600 (required by OpenSSH — refuses to use world-
+ *     readable keys).
+ *   - known_hosts mode 0o600.
+ *   - tempdir mode 0o700.
+ *
+ * SSH flags composed:
+ *   - `-i <keyfile>` — identity file.
+ *   - `-o IdentitiesOnly=yes` — don't try other keys from ssh-agent / ~/.ssh.
+ *   - `-o BatchMode=yes` — never prompt for passwords / passphrases.
+ *   - host-key checking flags based on `hostKeyPolicy`.
+ */
+export declare function setupSshAuth(opts: SetupSshAuthOpts): Promise<SshAuthSetup>;
+//# sourceMappingURL=ssh-auth.d.ts.map

package/dist/config.d.ts

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+/** Execution mode for the agent's sandbox backend. Mirrors the runtime enum. */
+export declare const ExecutionMode: z.ZodEnum<{
+    container: "container";
+    "bare-metal": "bare-metal";
+    firecracker: "firecracker";
+}>;
+export type ExecutionMode = z.infer<typeof ExecutionMode>;
+declare const configSchema: z.ZodObject<{
+    orchestratorUrl: z.ZodString;
+    agentId: z.ZodOptional<z.ZodString>;
+    labels: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string[], string>>;
+    roles: z.ZodPipe<z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string[] | undefined, string | undefined>>, z.ZodTransform<string[] | undefined, string[] | undefined>>;
+    port: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    logLevel: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+    }>>;
+    agentToken: z.ZodOptional<z.ZodString>;
+    githubToken: z.ZodOptional<z.ZodString>;
+    maxLogSizeBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    defaultStepTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    dockerKeepFailed: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
+    jobHeartbeatIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    backpressureMode: z.ZodDefault<z.ZodEnum<{
+        pause: "pause";
+        drop: "drop";
+    }>>;
+    sandbox: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
+    sandboxNetwork: z.ZodDefault<z.ZodEnum<{
+        isolated: "isolated";
+        host: "host";
+    }>>;
+    scalerManaged: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean, string | undefined>>;
+    scalerIdleTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    scalerPendingDispatchTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    executionMode: z.ZodOptional<z.ZodEnum<{
+        container: "container";
+        "bare-metal": "bare-metal";
+        firecracker: "firecracker";
+    }>>;
+    otelExporterOtlpEndpoint: z.ZodOptional<z.ZodString>;
+    concurrencyWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/**
+ * App configuration type. Includes computed agentId when not provided.
+ */
+export type AppConfig = z.infer<typeof configSchema> & {
+    /** Unique identifier for this agent instance */
+    agentId: string;
+};
+/**
+ * Env-var definition for the agent. Exported so the docs generator and the
+ * deploy-stg pre-validator can inspect / re-parse without round-tripping
+ * through process.env.
+ */
+export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
+    orchestratorUrl: string;
+    labels: string[];
+    roles: string[] | undefined;
+    port: number;
+    logLevel: "error" | "debug" | "info" | "warn";
+    maxLogSizeBytes: number;
+    defaultStepTimeoutMs: number;
+    dockerKeepFailed: boolean;
+    jobHeartbeatIntervalMs: number;
+    backpressureMode: "pause" | "drop";
+    sandbox: boolean;
+    sandboxNetwork: "isolated" | "host";
+    scalerManaged: boolean;
+    scalerIdleTimeoutMs: number;
+    scalerPendingDispatchTimeoutMs: number;
+    concurrencyWaitTimeoutMs: number;
+    agentId?: string | undefined;
+    agentToken?: string | undefined;
+    githubToken?: string | undefined;
+    executionMode?: "container" | "bare-metal" | "firecracker" | undefined;
+    otelExporterOtlpEndpoint?: string | undefined;
+}>;
+/**
+ * Load and validate agent configuration from environment variables.
+ *
+ * Maps env vars with KICI_ prefix:
+ * - KICI_ORCHESTRATOR_URL (required)
+ * - KICI_AGENT_ID (optional, auto-generated from hostname-uuid8)
+ * - KICI_LABELS (comma-separated, e.g. "linux,docker"). Labels with 'kici-' prefix are reserved.
+ * - KICI_ROLES (comma-separated agent roles, e.g. "builder,init-runner". undefined=all, empty=execution-only)
+ * - KICI_PORT (default: 8080)
+ * - KICI_LOG_LEVEL (default: info)
+ * - KICI_AGENT_TOKEN (optional, kat_ prefixed PSK for orchestrator authentication)
+ * - KICI_GITHUB_TOKEN (optional)
+ * - KICI_MAX_LOG_SIZE_BYTES (default: 10MB)
+ * - KICI_DEFAULT_STEP_TIMEOUT_MS (default: 30 min)
+ * - KICI_DOCKER_KEEP_FAILED (default: false)
+ * - KICI_JOB_HEARTBEAT_INTERVAL_MS (default: 60000)
+ * - KICI_BACKPRESSURE_MODE (default: pause, options: pause | drop)
+ * - KICI_SANDBOX (default: false) — enable bubblewrap (bwrap) namespace isolation for bare-metal execution
+ * - KICI_SANDBOX_NETWORK (default: isolated, options: isolated | host) — when sandbox=true, controls bwrap network namespace
+ * - KICI_SCALER_MANAGED (set to "1" by the orchestrator's auto-scaler — agent self-shuts down on idle)
+ * - KICI_SCALER_IDLE_TIMEOUT (ms, default 5000) — how long a scaler-managed agent waits before shutdown after going idle
+ * - KICI_SCALER_PENDING_DISPATCH_TIMEOUT (ms, default 60000) — extended idle window when register.ack signals a queued bound job
+ * - KICI_EXECUTION_MODE (optional, options: container | bare-metal | firecracker) — override the runner's mode-pick logic
+ * - KICI_CONCURRENCY_WAIT_TIMEOUT_MS (default: 3_600_000) — workflow-runner timeout when long-polling for a slot-release follow-up `concurrency.ack`
+ */
+export declare function loadConfig(): AppConfig;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/execution/console-capture.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Sink for captured console lines.
+ *
+ * The agent wires this to a per-job LogStreamer so captured lines become
+ * log.chunk messages to the orchestrator and dashboard.
+ */
+export interface CaptureSink {
+    addLine(line: string): void;
+}
+/**
+ * Install monkey-patches on console.log / error / warn / info / debug.
+ *
+ * Idempotent: subsequent calls are no-ops.
+ *
+ * Does NOT patch process.stdout.write or process.stderr.write. Winston's
+ * Console transport writes through those streams directly, so patching them
+ * at the agent level would leak agent-internal logger output into user step
+ * streams whenever Winston fires on an async stack descended from a user
+ * function. Winston bypasses console.*, so patching only console.* is
+ * collision-free.
+ */
+export declare function installConsoleCapture(): void;
+/**
+ * Run `fn` with the given sink active. console.* calls inside `fn` and any
+ * async descendants route to the sink until the returned promise resolves.
+ *
+ * If `installConsoleCapture()` has not been called, the sink is still tracked
+ * in ALS but console.* calls are not intercepted.
+ */
+export declare function runCaptured<T>(sink: CaptureSink, fn: () => T | Promise<T>): Promise<T>;
+/** Test helper: uninstall the console.* patches and restore originals. */
+export declare function _uninstallConsoleCaptureForTests(): void;
+/** Test helper: read the currently active sink, if any. */
+export declare function _getActiveSinkForTests(): CaptureSink | undefined;
+//# sourceMappingURL=console-capture.d.ts.map

package/dist/execution/dep-installer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Inline dependency installation for graceful degradation.
+ *
+ * When dep cache is unavailable or download fails, the agent falls back
+ * to running npm install directly.
+ *
+ * Only npm is supported — it ships with every Node.js installation.
+ * .kici/package.json is required — its presence signals deps should be installed.
+ *
+ * Security: npm runs with an isolated per-invocation cache directory to prevent
+ * cache poisoning across build jobs. A malicious package.json in one repo cannot
+ * taint the cache used by subsequent builds. The same pressure rules out letting
+ * lifecycle scripts see synthesized auth env vars — npm runs with
+ * `--ignore-scripts` whenever a private registry is configured.
+ */
+import { type NpmRegistrySpec } from './npm-registry-config.js';
+export interface InstallDepsOptions {
+    /** Resolved private npm registries from the orchestrator dispatch. */
+    npmRegistries?: readonly NpmRegistrySpec[];
+    /** Bare-name secrets to project as install-subprocess env vars. */
+    installEnvSecrets?: Record<string, string>;
+    /** Short job-scoped nonce — used as suffix on synthesized env-var names. */
+    jobIdShort?: string;
+}
+/**
+ * Install dependencies inline using npm.
+ *
+ * Falls back to this when the dep cache is unavailable or download fails.
+ *
+ * npm runs with an isolated cache directory (created in os.tmpdir()) to prevent
+ * cache poisoning between build jobs. The cache is removed after installation.
+ *
+ * If `opts.npmRegistries` / `opts.installEnvSecrets` is provided, the helper
+ * synthesizes a job-scoped `.kici/.npmrc` overlay for the install, restores
+ * the original file in `finally`, and runs npm with `--ignore-scripts` so
+ * lifecycle scripts in committed `package.json` cannot exfiltrate the
+ * synthesized token env vars.
+ *
+ * @param kiciDir - Path to the .kici/ directory containing package.json
+ * @param opts    - Optional registry / installEnv configuration. When absent,
+ *                  behavior is identical to the pre-private-registry version.
+ */
+export declare function installDeps(kiciDir: string, opts?: InstallDepsOptions): Promise<void>;
+//# sourceMappingURL=dep-installer.d.ts.map

package/dist/execution/dep-packer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Node_modules tarball creation for build agents.
+ *
+ * After installing dependencies in .kici/, packs node_modules
+ * into a gzip tarball for upload to the dep cache.
+ *
+ * Uses tar.gz format (Node.js built-in zlib, no external binary needed).
+ * Uses portable mode to strip user/group info for cross-machine consistency.
+ */
+/**
+ * Pack node_modules into a gzip tarball and compute its SHA-256 hash.
+ *
+ * Creates a tar.gz archive of the `node_modules/` directory relative to
+ * kiciDir. The tarball is created in-memory and returned as a Buffer
+ * along with its content hash.
+ *
+ * @param kiciDir - Path to the .kici/ directory containing node_modules/
+ * @returns Object with tarball Buffer and SHA-256 hash string
+ * @throws Error if node_modules/ does not exist in kiciDir
+ */
+export declare function packNodeModules(kiciDir: string): Promise<{
+    tarball: Buffer;
+    hash: string;
+}>;
+//# sourceMappingURL=dep-packer.d.ts.map

package/dist/execution/dep-restore.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Dependency restoration from cached tarballs.
+ *
+ * Downloads a pre-built dependency tarball, verifies SHA-256 integrity,
+ * and extracts to .kici/node_modules/ in the work directory.
+ *
+ * HTTP/HTTPS downloads use a streaming pipeline (response -> hash transform ->
+ * gunzip -> tar extract) to avoid buffering entire tarballs in memory.
+ * file:// URLs use a buffer-based approach (local, no streaming benefit).
+ *
+ * Streaming downloads have a 5-minute timeout and up to 2 retries.
+ */
+/** Download timeout: 5 minutes. */
+export declare const DOWNLOAD_TIMEOUT_MS: number;
+/** Maximum number of retries for HTTP downloads (0 = no retries). */
+export declare const MAX_RETRIES = 2;
+/**
+ * Stream download and extract an HTTP/HTTPS tarball.
+ *
+ * Computes SHA-256 hash on the fly via a Transform stream.
+ * Returns the computed hash of the compressed tarball data.
+ */
+export declare function streamFetchAndExtract(url: string, targetDir: string): Promise<string>;
+/**
+ * Glob suitable for `.gitignore` / `.git/info/exclude` that matches every
+ * scratch dir created by `extractIntoScratch`, anchored to the workflow
+ * working tree's `.kici/` subdir.
+ */
+export declare const SCRATCH_DIR_GIT_EXCLUDE_GLOB = ".kici/.dep-restore-scratch-*";
+/**
+ * Append `SCRATCH_DIR_GIT_EXCLUDE_GLOB` to `${repoWorkDir}/.git/info/exclude`
+ * so any in-flight or orphaned dep-restore scratch dirs are invisible to
+ * `git status` / `git add` inside the customer's cloned working tree.
+ *
+ * Why `.git/info/exclude` and not `.gitignore`:
+ * - `.gitignore` lives in the customer's repo and is committed; we MUST NOT
+ *   modify it. Doing so would surface the rule in their PRs and create a
+ *   diff customers never asked for.
+ * - `.git/info/exclude` is per-clone, on-disk only, and exactly the git
+ *   mechanism for "ignore these patterns in THIS working tree". Git creates
+ *   an empty (template-commented) file on `git init` / `git clone`, so it
+ *   already exists by the time we're called.
+ *
+ * Why this lives next to `extractIntoScratch`:
+ * - The exclude glob is tied 1:1 to the scratch dir naming convention. If
+ *   the prefix ever changes, the rule must change too. Defining both in the
+ *   same file means a rename touches one place, not two.
+ *
+ * Best-effort: if the exclude file is missing (e.g. caller sandbox blocked
+ * `git clone` and the dir layout differs) we log and continue — failing the
+ * job over a missing git ignore wiring would be worse than the cosmetic
+ * issue we're solving.
+ *
+ * Idempotent: callers may invoke this multiple times (dual-clone path, retry
+ * after partial setup). We skip the append if the glob is already present.
+ *
+ * @param repoWorkDir - The git working tree root (the dir that contains
+ *   `.git/`). For normal workflows this is the agent's job workDir; for
+ *   global workflows it is the workflow repo dir (whose `.kici/` carries
+ *   the scratch dirs).
+ */
+export declare function excludeScratchFromGit(repoWorkDir: string): Promise<void>;
+/**
+ * Rewrite localhost URLs to use the orchestrator host.
+ *
+ * The orchestrator rewrites file:// cache URLs to http://localhost:PORT/...
+ * but agent containers can't reach localhost. This utility replaces the
+ * host with the orchestrator's host derived from KICI_ORCHESTRATOR_URL.
+ */
+export declare function resolveOrchestratorUrl(url: string): string;
+/**
+ * Restore dependencies from a cached tarball.
+ *
+ * For HTTP/HTTPS URLs: uses a streaming pipeline (response -> hash -> gunzip -> tar)
+ * with a 5-minute timeout and up to 2 retries. This avoids buffering entire tarballs
+ * in memory, eliminating memory spikes proportional to tarball size.
+ *
+ * For file:// URLs: uses a buffer-based approach (local, no streaming benefit).
+ *
+ * @param workDir - Root directory of the cloned repository
+ * @param depsUrl - URL to the dependency tarball (http://, https://, or file://)
+ * @param depsHash - Optional expected SHA-256 hash of the tarball
+ */
+export declare function restoreDeps(workDir: string, depsUrl: string, depsHash?: string): Promise<void>;
+//# sourceMappingURL=dep-restore.d.ts.map

package/dist/execution/download.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared HTTP/HTTPS download utility.
+ *
+ * Extracted from workflow-loader.ts to avoid duplication across
+ * dep-restore.ts and workflow-loader.ts.
+ */
+/**
+ * Download content from an HTTP/HTTPS URL.
+ *
+ * Includes a 5-minute timeout to prevent the agent from hanging indefinitely
+ * on slow or unresponsive endpoints.
+ *
+ * @param url - The URL to download from
+ * @returns The response body as a Buffer
+ */
+export declare function downloadUrl(url: string): Promise<Buffer>;
+/**
+ * Upload a buffer to a pre-signed S3 URL via HTTP PUT.
+ *
+ * Used for direct-to-S3 uploads of bundles and dep tarballs. Localhost /
+ * 127.0.0.1 URLs are rewritten via `resolveOrchestratorUrl` so the
+ * filesystem cache backend's signed URLs work from container agents that
+ * can't reach the orchestrator's host loopback directly.
+ *
+ * @param url - The pre-signed URL to upload to
+ * @param data - The buffer to upload
+ */
+export declare function uploadToPresignedUrl(url: string, data: Buffer): Promise<void>;
+//# sourceMappingURL=download.d.ts.map

package/dist/execution/dynamic-job-serializer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Serializes SDK Job[] objects returned by a DynamicJobFn into LockJob[] format.
+ *
+ * This is the runtime equivalent of the compiler's transformJob() in lockfile/generator.ts.
+ * It converts rich SDK Job objects (with function references) into the minimal lock file
+ * representation that the orchestrator can process.
+ *
+ * Dynamic env/environment/concurrencyGroup/matrix functions on generated jobs are
+ * evaluated inline against the eval context (the same `event`, `$`, `log`, `env`
+ * already passed to the parent DynamicJobFn) and embedded as static lock fields.
+ * Each dynamic function call is wrapped in `withTimeout` (default 60s) mirroring
+ * `init-runner.ts`. Functions returning `undefined`/`null` leave the field unset.
+ *
+ * Constraints:
+ * - Generated jobs are limited to MAX_DYNAMIC_JOBS per DynamicJobFn invocation
+ * - Generated job names must be unique within the same DynamicJobFn output
+ */
+import type { $ as Shell } from 'zx';
+import type { Job, Logger } from '@kici-dev/sdk';
+import type { LockJob } from '@kici-dev/engine';
+/** Maximum number of jobs a single DynamicJobFn can generate. */
+export declare const MAX_DYNAMIC_JOBS = 100;
+/**
+ * Context required to resolve dynamic env/environment/concurrencyGroup/matrix
+ * functions on generated jobs. The eval agent already has every field needed
+ * (it's the same context that was just passed to the parent DynamicJobFn), so
+ * we thread it through the serializer rather than re-creating it.
+ */
+export interface SerializerContext {
+    /** Webhook event payload — passed as the first argument to env/environment/concurrencyGroup fns. */
+    event: Record<string, unknown>;
+    /** zx shell — passed to dynamic matrix fns. */
+    $: typeof Shell;
+    /** Logger — passed to dynamic matrix fns. */
+    log: Logger;
+    /** Environment variables — passed to dynamic matrix fns. */
+    env: Record<string, string | undefined>;
+    /** Workflow name — surfaced through DynamicMatrixContext.ctx.workflow.name. */
+    workflowName: string;
+}
+/**
+ * Convert an array of SDK Job objects into LockJob format for the orchestrator.
+ *
+ * @param jobs - Jobs returned by a DynamicJobFn
+ * @param ctx - Eval-time context used to resolve dynamic fields on generated jobs
+ * @returns Serialized LockJob array ready for orchestrator dispatch
+ * @throws Error if validation fails (duplicates, limit exceeded) or if a user-supplied
+ *   dynamic function throws / times out / returns an unsupported value
+ */
+export declare function serializeJobsToLock(jobs: Job[], ctx: SerializerContext, staticNames?: Set<string>, allowedGroups?: Set<string>): Promise<LockJob[]>;
+//# sourceMappingURL=dynamic-job-serializer.d.ts.map

package/dist/execution/hook-executor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Hook executor module -- shared hook execution logic with timeout, error handling,
+ * and outcome metadata construction.
+ *
+ * Hooks run inline within the workflow-runner process (same sandbox), not as
+ * separate child processes. IPC messages are for status reporting to the
+ * fork-runner, which relays to the agent's job-runner.
+ */
+import type { HookConfig, OutcomeMetadata, HookInput } from '@kici-dev/sdk';
+import type { StepContext } from '@kici-dev/sdk';
+import type { RunnerToAgentMessage } from './sandbox/ipc-protocol.js';
+/**
+ * Build outcome metadata from execution state.
+ *
+ * Duration is calculated as elapsed time since startTime.
+ */
+export declare function buildOutcomeMetadata(opts: {
+    status: 'cancelled' | 'success' | 'failed';
+    reason?: string;
+    failedStep?: string;
+    stepOutputs: Record<string, unknown>;
+    startTime: number;
+}): OutcomeMetadata;
+interface ExecuteHookOptions {
+    hook: HookInput | HookConfig;
+    stepContext: StepContext;
+    outcome: OutcomeMetadata;
+    hookType: string;
+    stepIndex: number;
+    sendIpc: (msg: RunnerToAgentMessage) => void;
+    /** Default timeout in ms (overridden by hook-level timeout). Defaults to 5 minutes. */
+    timeout?: number;
+}
+interface ExecuteHookResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Execute a single hook with timeout enforcement and IPC reporting.
+ *
+ * Sends step.start and step.complete IPC messages with step_type = 'hook:{hookType}'.
+ * The hook runs in the same sandbox context as regular steps.
+ */
+export declare function executeHook(opts: ExecuteHookOptions): Promise<ExecuteHookResult>;
+export {};
+//# sourceMappingURL=hook-executor.d.ts.map

package/dist/execution/init-runner.d.ts

@@ -0,0 +1,33 @@
+import type { Workflow } from '@kici-dev/sdk';
+/**
+ * Result of evaluating dynamic fields on a job.
+ * Only fields that were flagged as dynamic and successfully resolved are set.
+ */
+export interface InitResult {
+    environmentName?: string;
+    env?: Record<string, string>;
+    concurrencyGroup?: string;
+}
+/**
+ * Evaluate dynamic fields (environment, env, concurrencyGroup) on a job.
+ *
+ * Only fields with their corresponding flag set to true AND whose property
+ * on the job is a function will be evaluated. All evaluations happen in a
+ * single call per.
+ *
+ * -: If a dynamic function throws, the error propagates (job fails).
+ * -: If a dynamic function returns undefined/null, the field is left undefined.
+ * -: Each dynamic function call is wrapped in a timeout (default 60s).
+ *
+ * @param workflow - The extracted Workflow object
+ * @param jobName - Name of the job whose dynamic fields to evaluate
+ * @param event - Normalized webhook event data, passed as argument to dynamic functions
+ * @param flags - Which fields are dynamic and need evaluation
+ * @param timeoutMs - Timeout per dynamic function call (default 60_000ms)
+ */
+export declare function evaluateDynamicFields(workflow: Workflow, jobName: string, event: Record<string, unknown>, flags: {
+    dynamicEnvironment: boolean;
+    dynamicEnv: boolean;
+    dynamicConcurrencyGroup: boolean;
+}, timeoutMs?: number): Promise<InitResult>;
+//# sourceMappingURL=init-runner.d.ts.map