@kici-dev/agent 0.1.27 → 0.3.0

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

@@ -1,32 +1,33 @@
-/**
- * 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';
+import { type DeliveryMode } from './stage-agent-payload.js';
+import type { AgentPayloadSource } from './payload-source.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.
+     * A fixed command used to start the init-runner on the target — the
+     * golden-image escape hatch. When set, payload staging is SKIPPED (the image
+     * already ships `kici-agent` + a Node runtime at this path). Leave unset for a
+     * stock rescue box: the payload source below is staged instead.
      */
     agentCommand?: string;
+    /**
+     * The source of the self-contained agent+Node payload staged onto a bare box.
+     * When set (and no `agentCommand` override), `ensureInitRunner` probes the
+     * target platform, stages the version-keyed payload, and boots it on its
+     * vendored Node. Constructed from `KICI_AGENT_PAYLOAD_DIR` at the agent entry.
+     */
+    payloadSource?: AgentPayloadSource;
+    /**
+     * Force the delivery mode, overriding the orchestrator's per-host choice.
+     * Normally the orchestrator picks the mode (from the host's `s3_reachable`
+     * hint) and returns it in the bring-up material; this is a test/escape hatch.
+     */
+    delivery?: DeliveryMode;
+    /** Override the on-box extract dir (default `/opt/kici-init`). */
+    extractDir?: string;
+    /** Ops-agent-side file-hash boundary, injectable for tests. */
+    hashLocalFile?: (filePath: string) => Promise<string>;
 }
 /**
  * Bring up a temporary init-runner on `targetAgentId`. Returns `{ broughtUp }`:

package/dist/bootstrap/payload-source.d.ts

@@ -0,0 +1,32 @@
+import type { AgentPlatform } from '@kici-dev/shared';
+/** A staged payload ready to deliver: a local tarball path + its expected hash. */
+export interface StagedPayload {
+    tarballPath: string;
+    /** The expected sha256 (hex), or `null` when the producer wrote no sidecar. */
+    sha256: string | null;
+}
+/** Resolves the payload tarball for a given platform + version. */
+export interface AgentPayloadSource {
+    resolve(platform: AgentPlatform, version: string): Promise<StagedPayload>;
+}
+/** Filesystem boundary — injectable so unit tests need no real files. */
+export interface PayloadFs {
+    exists(filePath: string): Promise<boolean>;
+    readFile(filePath: string): Promise<string>;
+}
+/** Default fs boundary backed by `node:fs/promises`. */
+export declare const defaultPayloadFs: PayloadFs;
+/**
+ * Reads version-keyed payloads from a local directory:
+ * `<baseDir>/<version>/kici-agent-<platform>.tar.gz` with an optional
+ * `.sha256` sidecar (the producer writes a `<hex>  <basename>` line — we parse
+ * the leading hex token). Selected via `KICI_AGENT_PAYLOAD_DIR`; the air-gap /
+ * offline fallback when no object-storage source is configured.
+ */
+export declare class LocalDirPayloadSource implements AgentPayloadSource {
+    private readonly baseDir;
+    private readonly fs;
+    constructor(baseDir: string, fs?: PayloadFs);
+    resolve(platform: AgentPlatform, version: string): Promise<StagedPayload>;
+}
+//# sourceMappingURL=payload-source.d.ts.map

package/dist/bootstrap/probe-platform.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Probe a bring-up target's platform over SSH.
+ *
+ * A stock rescue box has nothing but sshd — no `kici-agent`, no Node — so we
+ * cannot ask the box what to run; we must ask what it IS, then stage the
+ * matching self-contained payload. One `uname -s -m` (+ a libc check) maps to
+ * an `AgentPlatform`; an unsupported target (musl-only, non-Linux, unknown
+ * arch) throws early, naming what was detected, rather than staging bytes that
+ * won't boot.
+ */
+import { AgentPlatform } from '@kici-dev/shared';
+import { type SshDeps } from './ssh-exec.js';
+import type { HostReach } from './reach.js';
+/**
+ * Map `uname -s -m` (+ libc line) output to an `AgentPlatform`. Pure + directly
+ * unit-tested. Throws a self-describing error for any unsupported target.
+ */
+export declare function parseUname(stdout: string): AgentPlatform;
+/** SSH into `reach` and detect its `AgentPlatform` (one probe, fail-fast on unsupported). */
+export declare function probeTargetPlatform(reach: HostReach, privateKey: string, deps?: SshDeps): Promise<AgentPlatform>;
+//# sourceMappingURL=probe-platform.d.ts.map

package/dist/bootstrap/restage-agent.d.ts

@@ -0,0 +1,43 @@
+import type { AgentPlatform } from '@kici-dev/shared';
+import { type SshDeps } from './ssh-exec.js';
+import type { HostReach } from './reach.js';
+import { type DeliveryMode } from './stage-agent-payload.js';
+import type { AgentPayloadSource } from './payload-source.js';
+/**
+ * How to drain + restart the target's agent after the swap. The ops agent runs
+ * `stop` (a graceful drain — SIGTERM + grace) then `start`. For a systemd unit
+ * this is `systemctl --user restart <svc>`; for a bare-process fixture it is a
+ * kill + relaunch of the install's own launcher (the box's persistent token
+ * lives in its env, so no reconnect material is threaded here).
+ */
+export interface RestartSpec {
+    stop: string;
+    start: string;
+}
+export interface RestageOpts {
+    /** Target platform; probed over SSH when omitted. */
+    platform?: AgentPlatform;
+    /** Target version to converge the host onto (the orchestrator's version). */
+    version: string;
+    /** How the payload reaches the box (ssh-push | s3-direct). */
+    delivery: DeliveryMode;
+    /** Folder-anchored install base (default `/opt/kici-agent`). */
+    installDir?: string;
+    /** Drain + restart commands run after the atomic swap. */
+    restart: RestartSpec;
+}
+export interface RestageDeps extends SshDeps {
+    /** Payload source for the `ssh-push` delivery path (unused for `s3-direct`). */
+    payloadSource?: AgentPayloadSource;
+    /** Ops-agent-side file-hash boundary, injectable for tests. */
+    hashLocalFile?: (filePath: string) => Promise<string>;
+}
+/**
+ * Re-stage the target version onto `reach` and restart its agent. Returns
+ * `{ restaged: false }` when the host is already on the target version (no
+ * stage, no swap, no restart), `{ restaged: true }` when this call swapped it.
+ */
+export declare function restageAgent(reach: HostReach, privateKey: string, opts: RestageOpts, deps: RestageDeps): Promise<{
+    restaged: boolean;
+}>;
+//# sourceMappingURL=restage-agent.d.ts.map

package/dist/bootstrap/run-restage.d.ts

@@ -0,0 +1,12 @@
+import { type RestageDeps } from './restage-agent.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>;
+/**
+ * Drive one external-actor re-stage: fetch the material, probe the target
+ * platform, resolve delivery, then stage + swap + restart via {@link restageAgent}.
+ * Returns `{ restaged: false }` when the host is already on the target version.
+ */
+export declare function runRestage(transport: ApiTransport, targetAgentId: string, deps: RestageDeps): Promise<{
+    restaged: boolean;
+}>;
+//# sourceMappingURL=run-restage.d.ts.map

package/dist/bootstrap/s3-payload-source.d.ts

@@ -0,0 +1,35 @@
+import { type AgentPlatform } from '@kici-dev/shared';
+import type { AgentPayloadSource, StagedPayload } from './payload-source.js';
+/** What the orchestrator returns for a presign request. */
+export interface PresignedPayload {
+    url: string;
+    /** The expected sha256 (hex), or null when the producer wrote no sidecar. */
+    sha256: string | null;
+}
+export interface S3PayloadSourceDeps {
+    /**
+     * Ask the orchestrator to mint a presigned download URL for the version-keyed
+     * payload. Bound to the `kici.presignAgentPackage` RPC over the agent-WS
+     * channel; the orchestrator keys the presign by its own version + the probed
+     * platform. Returns null when no payload object exists for the version.
+     */
+    presign(platform: AgentPlatform, version: string): Promise<PresignedPayload | null>;
+    /** Stream a URL to a local file (binary-safe). Injectable for tests. */
+    fetchToFile(url: string, dest: string): Promise<void>;
+    /** Local cache root; payloads land under `<cacheDir>/<version>/…` (cache-once). */
+    cacheDir: string;
+    /** Filesystem existence check for the cache-once short-circuit. Injectable. */
+    exists?(filePath: string): Promise<boolean>;
+}
+export declare class S3PayloadSource implements AgentPayloadSource {
+    private readonly deps;
+    constructor(deps: S3PayloadSourceDeps);
+    resolve(platform: AgentPlatform, version: string): Promise<StagedPayload>;
+}
+/** Default cache root the ops agent stores pulled payloads under (cache-once). */
+export declare function defaultPayloadCacheDir(): string;
+/** Default existence check for the cache-once short-circuit. */
+export declare function payloadFileExists(filePath: string): Promise<boolean>;
+/** Stream a (presigned) URL into a local file, binary-safe (no in-memory buffer). */
+export declare function fetchUrlToFile(url: string, dest: string): Promise<void>;
+//# sourceMappingURL=s3-payload-source.d.ts.map

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

@@ -55,4 +55,18 @@ export declare function sshPush(reach: HostReach, privateKey: string, localBytes
     port?: number;
     hostKeyMode?: SshHostKeyMode;
 }, deps?: SshDeps): Promise<void>;
+/**
+ * Ship a local FILE to a remote path over `scp` (a binary channel), using the
+ * same ephemeral-key discipline as `sshExec`/`sshPush`.
+ *
+ * Unlike `sshPush` — which pipes a JS string through `ssh 'cat > path'` and so
+ * corrupts binary payloads (a ~50 MB tarball) — `scp` streams the file's raw
+ * bytes untouched. This is the ONLY sanctioned path for a binary payload
+ * transfer; the string `cat >` path is for text (launcher scripts) only. Throws
+ * on a non-zero exit (a payload push must succeed end-to-end).
+ */
+export declare function sshPushFile(reach: HostReach, privateKey: string, localFilePath: string, remotePath: string, opts?: {
+    port?: number;
+    hostKeyMode?: SshHostKeyMode;
+}, deps?: SshDeps): Promise<void>;
 //# sourceMappingURL=ssh-exec.d.ts.map

package/dist/bootstrap/stage-agent-payload.d.ts

@@ -0,0 +1,41 @@
+import type { AgentPlatform } from '@kici-dev/shared';
+import { type SshDeps } from './ssh-exec.js';
+import type { HostReach } from './reach.js';
+import type { AgentPayloadSource } from './payload-source.js';
+/**
+ * How the payload reaches the box. `s3-direct` carries the box-pullable
+ * presigned URL + the expected sha256 the box verifies before extract (so the
+ * payload never transits the ops agent).
+ */
+export type DeliveryMode = {
+    mode: 'ssh-push';
+} | {
+    mode: 's3-direct';
+    presignedUrl: string;
+    sha256: string;
+};
+export interface StageDeps extends SshDeps {
+    /**
+     * Where payload tarballs come from for the `ssh-push` path (object storage via
+     * `S3PayloadSource`, or a local dir for air-gap). Not needed for `s3-direct`
+     * (the box pulls the presigned URL itself).
+     */
+    payloadSource?: AgentPayloadSource;
+    /** Where the payload is extracted on the box (default `/opt/kici-init`). */
+    extractDir?: string;
+    /** Ops-agent-side file-hash boundary, injectable for tests. Defaults to a streamed sha256. */
+    hashLocalFile?: (filePath: string) => Promise<string>;
+}
+export interface StageOpts {
+    platform: AgentPlatform;
+    version: string;
+    delivery: DeliveryMode;
+}
+/**
+ * Stage a payload onto `reach` and return the launcher path the caller runs as
+ * the init-runner's `agentCommand`.
+ */
+export declare function stageAgentPayload(reach: HostReach, privateKey: string, opts: StageOpts, deps: StageDeps): Promise<{
+    launcherPath: string;
+}>;
+//# sourceMappingURL=stage-agent-payload.d.ts.map

package/dist/checkout/changed-files.d.ts

@@ -0,0 +1,34 @@
+import type { EventPayload } from '@kici-dev/sdk';
+import type { ChangedFilesStatus } from '@kici-dev/engine';
+import type { GitAuth } from './git-clone.js';
+/** Result of computing the changed-files list from the local clone. */
+export interface ChangedFilesResult {
+    files: string[];
+    status: ChangedFilesStatus;
+}
+/**
+ * Authentication context threaded into every git invocation so the deepen /
+ * fetch calls that reach the remote are authenticated the same way the clone
+ * was. The clone's own credentials are ephemeral (git-clone.ts wipes the SSH
+ * key and never persists the token into `.git/config`), so a fetch here would
+ * otherwise run unauthenticated and fail on a private remote.
+ */
+export interface GitAuthCtx {
+    /** Per-command `-c` flags (http.extraHeader for basic auth). */
+    args: string[];
+    /** Env overrides (GIT_SSH_COMMAND for ssh auth). */
+    env?: Record<string, string>;
+    /** Tears down any temp SSH key material. */
+    cleanup?: () => Promise<void>;
+}
+/** Build the auth context for the fetches, mirroring git-clone.ts's auth. */
+export declare function buildAuthCtx(auth: GitAuth | undefined): Promise<GitAuthCtx>;
+/**
+ * Compute the changed-files list from the agent's local clone (HEAD is the
+ * checked-out head commit). Ground truth for job/step rule evaluation. `auth`
+ * (the same credentials used for the clone) authenticates the deepen / fetch
+ * calls so a private remote resolves. Returns `unavailable` for diff-less
+ * events (schedule/tag/manual) or any git failure — never throws.
+ */
+export declare function computeChangedFiles(workDir: string, event: EventPayload, auth?: GitAuth): Promise<ChangedFilesResult>;
+//# sourceMappingURL=changed-files.d.ts.map

package/dist/config.d.ts

@@ -1,8 +1,8 @@
 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";
+    container: "container";
     firecracker: "firecracker";
 }>;
 export type ExecutionMode = z.infer<typeof ExecutionMode>;
@@ -14,8 +14,8 @@ declare const configSchema: z.ZodObject<{
     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";
+        error: "error";
         info: "info";
         warn: "warn";
     }>>;
@@ -26,22 +26,30 @@ declare const configSchema: z.ZodObject<{
     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";
+        pause: "pause";
     }>>;
+    agentPayloadDir: z.ZodOptional<z.ZodString>;
+    agentCommand: z.ZodOptional<z.ZodString>;
     sandbox: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
     trustedEnv: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
     inPlace: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
     sandboxNetwork: z.ZodDefault<z.ZodEnum<{
-        isolated: "isolated";
         host: "host";
+        isolated: "isolated";
     }>>;
+    sandboxHardened: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
+    sandboxReadonlyRootfs: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
+    sandboxUser: z.ZodOptional<z.ZodString>;
+    sandboxPidsLimit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    sandboxMemoryBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    sandboxNanoCpus: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     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";
+        container: "container";
         firecracker: "firecracker";
     }>>;
     otelExporterOtlpEndpoint: z.ZodOptional<z.ZodString>;
@@ -62,30 +70,38 @@ export type AppConfig = z.infer<typeof configSchema> & {
  */
 export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     orchestratorUrl: string;
+    agentId?: string | undefined;
     labels: string[];
     properties: Record<string, string | number | boolean>;
     roles: string[] | undefined;
     port: number;
-    logLevel: "error" | "debug" | "info" | "warn";
+    logLevel: "debug" | "error" | "info" | "warn";
+    agentToken?: string | undefined;
+    githubToken?: string | undefined;
     maxLogSizeBytes: number;
     defaultStepTimeoutMs: number;
     dockerKeepFailed: boolean;
     jobHeartbeatIntervalMs: number;
-    backpressureMode: "pause" | "drop";
+    backpressureMode: "drop" | "pause";
+    agentPayloadDir?: string | undefined;
+    agentCommand?: string | undefined;
     sandbox: boolean;
     trustedEnv: boolean;
     inPlace: boolean;
-    sandboxNetwork: "isolated" | "host";
+    sandboxNetwork: "host" | "isolated";
+    sandboxHardened: boolean;
+    sandboxReadonlyRootfs: boolean;
+    sandboxUser?: string | undefined;
+    sandboxPidsLimit: number;
+    sandboxMemoryBytes: number;
+    sandboxNanoCpus: number;
     scalerManaged: boolean;
     scalerIdleTimeoutMs: number;
     scalerPendingDispatchTimeoutMs: number;
+    executionMode?: "bare-metal" | "container" | "firecracker" | undefined;
+    otelExporterOtlpEndpoint?: string | undefined;
     concurrencyWaitTimeoutMs: number;
     isOrchestratorHost: boolean;
-    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.
@@ -108,7 +124,13 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
  * - KICI_SANDBOX (default: false) — enable bubblewrap (bwrap) namespace isolation for bare-metal execution
  * - KICI_TRUSTED_ENV (default: false) — trusted fleet-agent profile: pass the ambient host env (minus the agent's own KiCI identity secrets) through to steps
  * - KICI_IN_PLACE (default: false) — in-place no-clone profile: for a file:// source, use the real repo path as workDir and skip the clone (the routed deploy:stg profile)
- * - KICI_SANDBOX_NETWORK (default: isolated, options: isolated | host) — when sandbox=true, controls bwrap network namespace
+ * - KICI_SANDBOX_NETWORK (default: isolated, options: isolated | host) — sandbox network posture for BOTH backends: the bwrap network namespace (when sandbox=true) and the container job network. `host` shares the host network (container backend also binds host /etc/hosts read-only for name resolution); applies to the container backend under the default hardened posture (KICI_SANDBOX_HARDENED=true)
+ * - KICI_SANDBOX_HARDENED (default: true) — hardened-by-default job containers (CapDrop ALL, no-new-privileges, cgroup caps, tmpfs /tmp); set false to roll back to the legacy unhardened posture
+ * - KICI_SANDBOX_READONLY_ROOTFS (default: false) — opt-in read-only container rootfs (/tmp stays a writable tmpfs)
+ * - KICI_SANDBOX_USER (optional) — container user override (uid, uid:gid, or name); honors the image user when unset
+ * - KICI_SANDBOX_PIDS_LIMIT (default: 512) — max PIDs in the job container cgroup
+ * - KICI_SANDBOX_MEMORY_BYTES (default: 2 GiB) — memory cap in bytes for the job container cgroup
+ * - KICI_SANDBOX_NANO_CPUS (default: 2 CPUs) — CPU cap in nano-CPUs for the job container cgroup
  * - 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