@kici-dev/agent 0.1.21 → 0.1.23

package/dist/bootstrap/api-intercept.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent-process interception of the bootstrap bring-up API methods.
+ *
+ * `ctx.kici.bootstrap.ensureInitRunner` / `preBootSend` are relayed from the
+ * workflow sandbox as `agent.api.request` IPC. The agent process intercepts
+ * those two methods HERE (rather than relaying them straight to the
+ * orchestrator) so the SSH transport — and the bring-up key / bootstrap token
+ * the orchestrator hands back — stay in the agent process, never reaching user
+ * workflow code. Every other method falls through to the orchestrator relay
+ * unchanged.
+ */
+import { type ApiTransport, type EnsureInitRunnerDeps } from './ensure-init-runner.js';
+/**
+ * Wrap the orchestrator API transport so the two bootstrap methods are handled
+ * in-process (SSH transport here; privileged resolve relayed to the
+ * orchestrator). `relay` is the raw orchestrator transport (the WS
+ * `sendApiRequest`).
+ */
+export declare function withBootstrapInterception(relay: ApiTransport, deps?: EnsureInitRunnerDeps): (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+//# sourceMappingURL=api-intercept.d.ts.map

package/dist/bootstrap/ensure-init-runner.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Agent-side init-runner bring-up.
+ *
+ * Runs in the AGENT process (never the workflow sandbox), so the bring-up SSH
+ * key and bootstrap token the orchestrator hands back never reach user
+ * workflow code. The flow:
+ *
+ *   1. Call the orchestrator's privileged `kici.ensureInitRunner` handler — it
+ *      gates on this agent's `kici:capability:ssh-transport` capability,
+ *      resolves the target's reach + SSH key, mints a single-use bootstrap
+ *      token, audits, and returns the material (or `{ broughtUp: false }` when
+ *      the target already has a live agent).
+ *   2. Over SSH (ephemeral key, never on disk): drop a launcher onto the target
+ *      that starts `kici-agent` with the bootstrap env (token + agent id +
+ *      orchestrator URL + labels), and start it detached.
+ *
+ * The init-runner then connects → `auth.request` (bootstrap token) →
+ * `agent.register` auto-enroll as a temporary `kici:init` agent.
+ */
+import { type SshDeps } from './ssh-exec.js';
+/** Transport that relays an API request to the orchestrator and awaits the result. */
+export type ApiTransport = (method: string, params: Record<string, unknown>) => Promise<unknown>;
+export interface EnsureInitRunnerDeps extends SshDeps {
+    /**
+     * The command used to start the init-runner on the target. Defaults to
+     * `kici-agent` (resolved on the target's PATH). Override for a rescue env
+     * that stages the binary at a fixed path.
+     */
+    agentCommand?: string;
+}
+/**
+ * Bring up a temporary init-runner on `targetAgentId`. Returns `{ broughtUp }`:
+ * false when the target already had a live agent (the orchestrator no-op'd),
+ * true when this call dropped + started the init-runner.
+ */
+export declare function ensureInitRunner(transport: ApiTransport, targetAgentId: string, deps?: EnsureInitRunnerDeps): Promise<{
+    broughtUp: boolean;
+}>;
+//# sourceMappingURL=ensure-init-runner.d.ts.map

package/dist/bootstrap/pre-boot-send.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Agent-side pre-boot input send (dropbear / initramfs unlock).
+ *
+ * Runs in the AGENT process. Asks the orchestrator's privileged
+ * `kici.preBootSend` handler to gate on the `kici:capability:ssh-transport`
+ * capability, resolve the input secret (e.g. a LUKS passphrase), and audit;
+ * then pipes the resolved input to the target's pre-boot SSH endpoint
+ * (default dropbear port 2222, forced `cryptroot-unlock`). The unlock drops
+ * the session as the box boots — success is the send completing, not the SSH
+ * exit code; the caller composes a host-alive wait to confirm boot.
+ */
+import { type SshDeps } from './ssh-exec.js';
+import type { ApiTransport } from './ensure-init-runner.js';
+export interface PreBootSendOpts {
+    inputSecret: string;
+    port?: number;
+    command?: string;
+}
+/**
+ * Ship a pre-boot input to the target's dropbear/initramfs SSH channel. The
+ * input plaintext is resolved server-side and never logged. Resolves once the
+ * send completes (the SSH session legitimately drops as the box boots).
+ */
+export declare function preBootSend(transport: ApiTransport, targetAgentId: string, opts: PreBootSendOpts, deps?: SshDeps): Promise<void>;
+//# sourceMappingURL=pre-boot-send.d.ts.map

package/dist/bootstrap/reach.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Agent-facing host reach metadata: how to SSH to a target for bootstrap.
+ *
+ * This is the subset the agent's SSH helper needs — the connection
+ * coordinates only. It deliberately does NOT carry the `sshKeySecret` ref:
+ * the orchestrator resolves the scoped secret server-side and hands the agent
+ * the already-resolved private key separately, so the secret ref never reaches
+ * the agent. `sshPort` is the OS-sshd port for bring-up; a pre-boot dropbear
+ * port is supplied per-call via `SshExecOpts.port`.
+ */
+export interface HostReach {
+    agentId: string;
+    address: string | null;
+    sshUser: string | null;
+    sshPort: number | null;
+}
+//# sourceMappingURL=reach.d.ts.map

package/dist/bootstrap/ssh-exec.d.ts

@@ -0,0 +1,58 @@
+import type { HostReach } from './reach.js';
+/** Host-key verification mode for the SSH connection. */
+export type SshHostKeyMode = 'accept-new' | 'strict';
+/** Result of an SSH invocation: exit code is reported, never thrown away. */
+export interface SshResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface SshExecOpts {
+    /** Piped to the remote command's stdin (e.g. a LUKS passphrase to cryptroot-unlock). */
+    stdin?: string;
+    /** Override the default SSH port (22). E.g. 2222 for a dropbear initramfs prompt. */
+    port?: number;
+    /**
+     * Host-key verification. Defaults to `accept-new` — the dropbear initramfs
+     * host key differs from the OS sshd key, so a pinned OS entry must not be
+     * reused. `strict` enforces a known_hosts match.
+     */
+    hostKeyMode?: SshHostKeyMode;
+}
+/**
+ * Low-level process spawn boundary, injectable so unit tests can assert the
+ * exact argv / env / stdin without running a real `ssh`. Mirrors the relevant
+ * subset of `child_process.spawn`'s contract.
+ */
+export interface SpawnFn {
+    (command: string, args: string[], opts: {
+        env: NodeJS.ProcessEnv;
+        stdin?: string;
+    }): Promise<SshResult>;
+}
+/** Default spawn boundary backed by `node:child_process.spawn`. */
+export declare const defaultSpawn: SpawnFn;
+/** Deps for the SSH helper — the spawn boundary is injectable for tests. */
+export interface SshDeps {
+    spawnFn?: SpawnFn;
+}
+/**
+ * Run a command on the target over SSH using an ephemeral, in-memory key.
+ *
+ * The key is loaded into a per-call ssh-agent (never written to disk) and the
+ * agent is killed in `finally`. The remote command's exit code / stdout /
+ * stderr are returned verbatim — a non-zero exit is reported, not swallowed
+ * (a pre-boot unlock legitimately drops the session, so the caller decides
+ * what a "success" looks like).
+ */
+export declare function sshExec(reach: HostReach, privateKey: string, command: string, opts?: SshExecOpts, deps?: SshDeps): Promise<SshResult>;
+/**
+ * Ship local bytes to a remote path over SSH (`ssh 'cat > path'`), using the
+ * same ephemeral-key discipline. Throws on a non-zero exit (a push must
+ * succeed end-to-end, unlike a pre-boot unlock).
+ */
+export declare function sshPush(reach: HostReach, privateKey: string, localBytes: string, remotePath: string, opts?: {
+    port?: number;
+    hostKeyMode?: SshHostKeyMode;
+}, deps?: SshDeps): Promise<void>;
+//# sourceMappingURL=ssh-exec.d.ts.map

package/dist/config.d.ts

@@ -44,6 +44,7 @@ declare const configSchema: z.ZodObject<{
     }>>;
     otelExporterOtlpEndpoint: z.ZodOptional<z.ZodString>;
     concurrencyWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    isOrchestratorHost: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean, string | undefined>>;
 }, z.core.$strip>;
 /**
  * App configuration type. Includes computed agentId when not provided.
@@ -75,6 +76,7 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     scalerIdleTimeoutMs: number;
     scalerPendingDispatchTimeoutMs: number;
     concurrencyWaitTimeoutMs: number;
+    isOrchestratorHost: boolean;
     agentId?: string | undefined;
     agentToken?: string | undefined;
     githubToken?: string | undefined;

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

@@ -1,5 +1,6 @@
 import type { AgentToOrchestratorMessage, JobDispatch } from '@kici-dev/engine';
 import type { AppConfig } from '../config.js';
+import { buildNeedsContext } from '@kici-dev/sdk';
 import type { CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './sandbox/index.js';
 /**
  * Dependencies injected into JobRunner.
@@ -112,6 +113,15 @@ interface ActiveJob {
     completionPromise: Promise<void>;
     runId: string;
 }
+/**
+ * Build the result-aware `ctx.needs` for a dynamic eval from its frozen upstream
+ * snapshot. Returns undefined for an event-only generator (no snapshot).
+ */
+export declare function buildEvalNeedsContext(config: {
+    resultAware?: boolean;
+    declaredNeeds?: readonly unknown[];
+    upstreamSnapshot?: import('@kici-dev/engine').UpstreamSnapshot;
+}): ReturnType<typeof buildNeedsContext> | undefined;
 /**
  * Top-level job execution orchestrator for the agent.
  *
@@ -205,6 +215,18 @@ export declare class JobRunner {
      * failure diagnostics, and send the terminal `job.status` message.
      */
     private reportExecutionResult;
+    /**
+     * Handle a bring-up job: bring up a temporary init-runner on a declared-but-
+     * un-agented host over SSH (fresh-box bootstrap convergence). The orchestrator
+     * dispatches this synthetic `__bringup__` job to an agent holding the
+     * `kici:capability:ssh-transport` capability; here we run the agent-side
+     * `ensureInitRunner` helper (the privileged resolve is relayed to the
+     * orchestrator, the SSH transport happens in this agent process — never
+     * reaching workflow code). No clone, no sandbox — the init-runner then
+     * connects under the target's agent id and the orchestrator's pinned-hold
+     * drains the target's bootstrap steps onto it.
+     */
+    private handleBringupJob;
     /**
      * Handle a build-only job.
      *

package/dist/execution/reboot.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Cross-OS host reboot for the workflow-level `restartHost()` step.
+ *
+ * The agent runs ON the host it executes jobs for, so a `restartHost()` step
+ * reboots that host. `rebootCommandFor` is the pure OS→command mapping (kept
+ * pure for unit-testing); `issueReboot` spawns it detached with a tiny grace so
+ * the job's final flush completes before the box goes down.
+ *
+ * Rebooting needs host privilege (root/admin). If the primitive is denied, the
+ * spawn fails and the caller clears the orchestrator's reboot-pending flag and
+ * surfaces the error — the deadline sweep is the backstop.
+ */
+/** The OS reboot primitive for a Node platform string. */
+export declare function rebootCommandFor(platform: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Issue the OS reboot detached. Resolves once the child has been spawned (the
+ * box is going down; there is nothing to await). Rejects synchronously if the
+ * spawn itself fails (e.g. the binary is missing). A privilege denial usually
+ * surfaces as a non-zero exit AFTER spawn — logged, not thrown, because by then
+ * the box may already be on its way down.
+ */
+export declare function issueReboot(platform?: NodeJS.Platform): Promise<void>;
+//# sourceMappingURL=reboot.d.ts.map

package/dist/execution/rule-evaluator.d.ts

@@ -1,11 +1,13 @@
-import type { RuleContext } from '@kici-dev/sdk';
+import type { RuleContext, FanoutPosition } from '@kici-dev/sdk';
 /**
  * Create RuleContext for agent-side rule evaluation.
  *
  * @param event - Event payload from the dispatch message
  * @param changedFiles - List of files changed in this event
  * @param env - Merged environment variables
+ * @param dispatchInputs - Operator dispatch inputs (`ctx.dispatchInputs`)
+ * @param fanout - Fan-out position (`ctx.fanout`); undefined on a non-fan-out job
  */
-export declare function createRuleContext(event: Record<string, unknown>, changedFiles?: string[], env?: Record<string, string | undefined>): RuleContext;
+export declare function createRuleContext(event: Record<string, unknown>, changedFiles?: string[], env?: Record<string, string | undefined>, dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>, fanout?: FanoutPosition): RuleContext;
 export { evaluateRules, type RuleEvaluationResult } from '@kici-dev/sdk';
 //# sourceMappingURL=rule-evaluator.d.ts.map

package/dist/execution/sandbox/ipc-protocol.d.ts

@@ -193,8 +193,13 @@ export interface StepApprovalRequestIpc {
     }>;
     /** Human label for the gate. */
     reason: string;
-    /** Per-gate timeout override (seconds) from the SDK `requireApproval.timeout`. */
+    /** Per-gate timeout override (seconds) from the SDK `approval.timeout`. */
     timeoutSeconds?: number;
+    /** Computed drift payload, present only for `when: 'drift'` gates. */
+    payload?: {
+        summaryMarkdown: string;
+        drift: unknown;
+    };
 }
 /** Which provenance upload operation to relay. */
 export type ProvenanceRequestOp = 'requestUploadUrl' | 'complete';
@@ -405,6 +410,20 @@ export interface JobExecutionRequest {
         platform?: string;
         arch?: string;
     };
+    /**
+     * Operator-supplied, validated + coerced + defaulted workflow-dispatch inputs
+     * (from `kici run --input`), exposed to steps + rules as `ctx.dispatchInputs`.
+     * Absent for webhook runs.
+     */
+    dispatchInputs?: Record<string, unknown>;
+    /**
+     * For a fan-out child (`runsOnAll` host or matrix combination): the 0-based
+     * deterministic position in the fan-out, assembled into `ctx.fanout`. Absent
+     * for non-fan-out jobs.
+     */
+    fanoutIndex?: number;
+    /** For a fan-out child: the number of children in this fan-out. */
+    fanoutTotal?: number;
     /** Secrets to merge into step environment (highest precedence). */
     secrets?: Record<string, string>;
     /** Namespaced secrets by context name for ctx.secrets['context-name'].KEY access. */
@@ -478,6 +497,10 @@ export interface JobExecutionRequest {
     branch?: string;
     /** Plain outputs from upstream jobs (keyed by job name, then by step name). For ctx.jobOutputs(). */
     upstreamJobOutputs?: Record<string, Record<string, unknown>>;
+    /** Terminal status of each upstream job (keyed by job name; per-child for fan-out). For ctx.needs.<job>.status. */
+    upstreamJobStatuses?: Record<string, import('@kici-dev/engine').ExecutionJobStatus>;
+    /** This job's declared upstream needs (normalized lock edges) used to shape ctx.needs for steps. */
+    jobNeeds?: readonly unknown[];
     /** Resolved private npm registries for `npm install` auth (token bytes already filled). */
     npmRegistries?: ReadonlyArray<{
         url: string;

package/dist/execution/sandbox/step-loop.d.ts

@@ -5,7 +5,7 @@
  * Extracted for testability: the workflow-runner's main() handles IPC, clone, deps,
  * module loading, and calls this loop for step execution with hooks.
  */
-import type { Step, StepContext, HookInput, OutputsMap, StepSecretMountRecord } from '@kici-dev/sdk';
+import type { Step, StepContext, HookInput, OutputsMap, StepSecretMountRecord, FanoutPosition } from '@kici-dev/sdk';
 import { CheckMode } from '@kici-dev/engine';
 import type { RunnerToAgentMessage } from './ipc-protocol.js';
 import type { SandboxStepResult } from './types.js';
@@ -36,6 +36,10 @@ export interface StepLoopOptions {
     event: Record<string, unknown>;
     /** Environment variables for rule context. */
     env: Record<string, string | undefined>;
+    /** Operator dispatch inputs for the rule context (`ctx.dispatchInputs`). */
+    dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>;
+    /** Fan-out position for the rule context (`ctx.fanout`); undefined on a non-fan-out job. */
+    fanout?: FanoutPosition;
     /** Job-level hooks. */
     jobHooks?: JobHooks;
     /**
@@ -90,11 +94,11 @@ export interface StepLoopOptions {
      */
     afterStepApplyEnvFiles?: () => Promise<void>;
     /**
-     * Block a `requireApproval` step pending an orchestrator-side approval hold.
-     * The runner sends the normalized requirement and awaits the resolution; the
-     * agent keeps job heartbeats flowing during the wait so the agent isn't
-     * reaped. Absent ⇒ approvals are not gated (CT / unit harnesses) and steps
-     * run unconditionally.
+     * Block an `approval` step (`when: 'always'`) pending an orchestrator-side
+     * approval hold. The runner sends the normalized requirement and awaits the
+     * resolution; the agent keeps job heartbeats flowing during the wait so the
+     * agent isn't reaped. Absent ⇒ approvals are not gated (CT / unit harnesses)
+     * and steps run unconditionally.
      */
     awaitStepApproval?: (req: {
         stepIndex: number;
@@ -107,6 +111,28 @@ export interface StepLoopOptions {
         reason: string;
         timeoutSeconds?: number;
     }) => Promise<StepApprovalResolution>;
+    /**
+     * Block an `approval: { when: 'drift' }` step mid-execution: after `check()`
+     * returns drift in apply mode, send a payload-bearing step-approval and await
+     * the resolution. The payload carries the computed drift (`summaryMarkdown` +
+     * structured `drift`) so the operator approves the actual diff. Absent ⇒ the
+     * drift gate is not enforced (CT / unit harnesses) and the step applies.
+     */
+    awaitStepApprovalWithPayload?: (req: {
+        stepIndex: number;
+        stepName: string;
+        clauses: Array<{
+            team: string;
+        } | {
+            user: string;
+        }>;
+        reason: string;
+        timeoutSeconds?: number;
+        payload: {
+            summaryMarkdown: string;
+            drift: unknown;
+        };
+    }) => Promise<StepApprovalResolution>;
 }
 /** Outcome of an awaited step-level approval hold. */
 export interface StepApprovalResolution {

package/dist/execution/sandbox/workflow-runner.d.ts

@@ -13,10 +13,21 @@
  * This file is compiled alongside the agent by rolldown (existing build), but
  * runs as a SEPARATE process spawned by the sandbox backend.
  */
+import { ExecutionJobStatus } from '@kici-dev/engine';
 import type { StepContext } from '@kici-dev/sdk';
+import type { NeedsContext, FanoutPosition } from '@kici-dev/sdk';
 import type { OutputsMap, StepRefMap, TrackedStepSecrets } from '@kici-dev/sdk';
 import type { RunnerToAgentMessage, JobExecutionRequest } from './ipc-protocol.js';
 import { LogMasker } from './log-masker.js';
+/**
+ * Build `ctx.needs` for a job's steps from the dispatch envelope. Reconstructs
+ * an {@link UpstreamSnapshot} from `upstreamJobOutputs` (flat per single job;
+ * `byMatrix` / `byHost` envelopes per fan-out) + `upstreamJobStatuses` (keyed by
+ * each upstream job/child name), then resolves the job's declared needs into the
+ * `{ result, status }` / ordered-array shape via the shared SDK builder. Returns
+ * undefined when the job declares no needs.
+ */
+export declare function buildStepNeedsContext(declaredNeeds: readonly unknown[] | undefined, upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined, upstreamJobStatuses: Record<string, ExecutionJobStatus> | undefined): NeedsContext | undefined;
 /**
  * Create a StepContext natively inside the workflow runner.
  *
@@ -25,6 +36,12 @@ import { LogMasker } from './log-masker.js';
  * inside this process with full shell access.
  */
 export declare function createSandboxStepContext(workDir: string, stepIndex: number, stepName: string, request: JobExecutionRequest, maskedSendFn: (msg: RunnerToAgentMessage) => void, outputsMap: OutputsMap, refMap: StepRefMap, operatorSecretKeys: Set<string>, secretOutputs: Map<string, string>, jobOutputsMap: OutputsMap, secrets: TrackedStepSecrets, masker: LogMasker): StepContext;
+/**
+ * Derive the fan-out position (`ctx.fanout`) from a dispatch request. Returns
+ * `undefined` for a non-fan-out job (no `fanoutTotal`), so `ctx.fanout` is only
+ * set for `runsOnAll` host children and matrix combinations.
+ */
+export declare function deriveFanout(request: JobExecutionRequest): FanoutPosition | undefined;
 /** Raw provider webhook body for ctx.rawPayload — nested in the envelope. */
 export declare function rawPayloadFromEvent(event: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
 //# sourceMappingURL=workflow-runner.d.ts.map

package/dist/index.js

@@ -86,7 +86,8 @@ const envDef = defineEnv({
 		scalerPendingDispatchTimeoutMs: z.coerce.number().default(6e4),
 		executionMode: ExecutionMode.optional(),
 		otelExporterOtlpEndpoint: z.string().optional(),
-		concurrencyWaitTimeoutMs: z.coerce.number().int().min(1e3).default(36e5)
+		concurrencyWaitTimeoutMs: z.coerce.number().int().min(1e3).default(36e5),
+		isOrchestratorHost: z.string().optional().transform((v) => v === "true")
 	}),
 	envMap: {
 		orchestratorUrl: "KICI_ORCHESTRATOR_URL",
@@ -97,6 +98,7 @@ const envDef = defineEnv({
 		port: "KICI_PORT",
 		logLevel: "KICI_LOG_LEVEL",
 		agentToken: "KICI_AGENT_TOKEN",
+		isOrchestratorHost: "KICI_AGENT_IS_ORCHESTRATOR_HOST",
 		githubToken: "KICI_GITHUB_TOKEN",
 		maxLogSizeBytes: "KICI_MAX_LOG_SIZE_BYTES",
 		defaultStepTimeoutMs: "KICI_DEFAULT_STEP_TIMEOUT_MS",