@kici-dev/agent 0.5.0 → 0.6.1

package/dist/checkout/clone-job-repos.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Clone a job's repositories — from the host or from inside the sandbox.
+ *
+ * This used to live only inside the workflow runner, which meant the clone
+ * always happened wherever the runner ran: for a container job, inside the
+ * customer's image, which therefore had to ship git. Extracting it lets the
+ * AGENT clone on the host and copy the tree in, so the image needs no git —
+ * and it puts clone-time credentials on the host, where the credential helper
+ * already works, rather than needing a route into a container hardened with
+ * `CapDrop: ALL`.
+ *
+ * Both callers run the SAME code: the runner keeps calling it for bare-metal
+ * and for the legacy container path, and the agent calls it for a host-side
+ * checkout. A second implementation would be two subtly different clones.
+ */
+import { type GitAuth } from './git-clone.js';
+/** The clone-relevant slice of a job execution request. */
+export interface CloneJobReposRequest {
+    repoUrl: string;
+    ref: string;
+    sha: string;
+    token?: string | undefined;
+    sourceAuth?: GitAuth | undefined;
+    workflowAuth?: GitAuth | undefined;
+    workflowRepoUrl?: string | undefined;
+    workflowRef?: string | undefined;
+    workflowSha?: string | undefined;
+    checkout?: boolean | undefined;
+    fullRepo?: boolean | undefined;
+    credentialHelperPath?: string | undefined;
+}
+export interface CloneJobReposDirs {
+    workDir: string;
+    workflowDir: string;
+    sourceDir: string;
+}
+export interface CloneJobReposDeps {
+    /** Whether this job runs a global workflow (workflow repo + source repo). */
+    isGlobal: boolean;
+    /** Progress sink. The runner routes this to IPC; the agent to its logger. */
+    log: (line: string) => void;
+    /** Hide dep-restore scratch dirs from `git status` in a cloned tree. */
+    excludeScratchFromGit: (dir: string) => Promise<void>;
+}
+/**
+ * Clone whatever this job needs, or nothing.
+ *
+ * Three modes, unchanged from where this logic used to live: full-repo overlay
+ * (no clone), global dual-clone (workflow repo + source repo), and the ordinary
+ * single-repo clone.
+ */
+export declare function cloneJobRepos(request: CloneJobReposRequest, dirs: CloneJobReposDirs, deps: CloneJobReposDeps): Promise<void>;
+//# sourceMappingURL=clone-job-repos.d.ts.map

package/dist/checkout/credential-helper-bin.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The executable git spawns as `credential.helper`.
+ *
+ * Deliberately minimal: read stdin, forward to the agent over its local socket,
+ * write stdout. No state, no decisions, no logging — anything it printed would
+ * risk putting a token in a log, and git treats unexpected stdout as part of
+ * the credential reply.
+ *
+ * Every failure mode answers with an EMPTY reply rather than a non-zero exit:
+ * git then falls through to its own mechanisms and reports a normal
+ * authentication failure, instead of the helper turning a recoverable miss into
+ * a crash mid-push.
+ */
+export interface HelperDeps {
+    /** Round-trip to the agent over its local socket. */
+    send: (query: {
+        protocol?: string;
+        host?: string;
+        path?: string;
+    }) => Promise<{
+        kind: string;
+        user?: string;
+        secret: string;
+    } | null>;
+}
+/** Testable core. `argv` is git's operation word: `get`, `store`, or `erase`. */
+export declare function runHelperMain(argv: readonly string[], stdin: string, deps: HelperDeps): Promise<string>;
+//# sourceMappingURL=credential-helper-bin.d.ts.map

package/dist/checkout/credential-helper-host.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Host side of the git credential helper.
+ *
+ * Git spawns the helper as its own process, so it cannot call into the agent
+ * directly. This module gives it a route: a per-job unix socket the agent
+ * listens on, plus a tiny executable shim that connects to it and speaks git's
+ * credential protocol on stdin/stdout.
+ *
+ * The shim is deliberately self-contained — no imports beyond `node:net` — so it
+ * needs no module resolution, no bundle, and no dependency on where the agent
+ * was installed. Its only job is to move bytes.
+ *
+ * Scope: this is the HOST path, which covers bare-metal jobs. A container job
+ * clones and executes inside the container today and has no route to this
+ * socket; that is fixed by the dual-mode container work, which moves the clone
+ * to the host and injects `/opt/kici` read-only.
+ */
+/** What the shim asks for, and what it gets back. */
+export interface HelperQuery {
+    protocol?: string;
+    host?: string;
+    path?: string;
+}
+export type HelperAnswer = {
+    username: string;
+    password: string;
+} | null;
+/** The shim source. Kept inline so the helper has no build step of its own. */
+export declare function shimSource(socketPath: string): string;
+export interface CredentialHelperHost {
+    /** Absolute path to pass as `credential.helper`. */
+    helperPath: string;
+    /** Stop listening and release the socket. */
+    close(): Promise<void>;
+}
+/**
+ * Start the per-job helper socket and materialize the shim.
+ *
+ * `answer` is the agent's resolver: it consults the grant table and asks the
+ * orchestrator broker. Returning null means "no credential", which the shim
+ * turns into an empty reply so git falls through to its own mechanisms.
+ */
+export declare function startCredentialHelperHost(args: {
+    /** Job-scoped directory to hold the socket and the shim. */
+    dir: string;
+    answer: (query: HelperQuery) => Promise<HelperAnswer>;
+}): Promise<CredentialHelperHost>;
+//# sourceMappingURL=credential-helper-host.d.ts.map

package/dist/checkout/credential-helper.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Git credential-helper protocol, agent side.
+ *
+ * Git invokes the helper on EVERY network operation, which is the mechanism
+ * that defeats the one-hour GitHub App token expiry: a token is always minted
+ * seconds before it is used, and nothing is ever persisted to `.git/config`,
+ * the step environment, or a log.
+ *
+ * The default is read-only. An elevated credential is served only while a write
+ * grant covers the repository git is contacting.
+ */
+import type { GrantTable } from './grant-table.js';
+export interface CredentialQuery {
+    protocol?: string;
+    host?: string;
+    path?: string;
+}
+export interface CredentialReply {
+    username: string;
+    password: string;
+}
+/** Parse git's `key=value\n…\n\n` block. Unknown or malformed lines are skipped. */
+export declare function parseCredentialInput(stdin: string): CredentialQuery;
+/** Render a reply in the same `key=value` form. */
+export declare function formatCredentialOutput(reply: CredentialReply): string;
+export interface ServeCredentialDeps {
+    grants: GrantTable;
+    /** Round-trip to the orchestrator broker. Returns null when there is no credential. */
+    request: (args: {
+        repository: string;
+        permissions: Readonly<Record<string, string>>;
+    }) => Promise<{
+        kind: string;
+        user?: string;
+        secret: string;
+    } | null>;
+}
+/**
+ * Answer one `get`. Returns the reply block, or an empty string when we have no
+ * credential — an empty reply lets git fall through to its own mechanisms
+ * rather than failing outright.
+ */
+export declare function serveCredential(query: CredentialQuery, deps: ServeCredentialDeps): Promise<string>;
+//# sourceMappingURL=credential-helper.d.ts.map

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

@@ -42,7 +42,33 @@ interface CloneOptions {
     gitAuth?: GitAuth;
     /** Clone depth (default: 1 for shallow clone) */
     depth?: number;
+    /**
+     * When set, the clone is configured to use this credential helper, so every
+     * later git network operation asks the agent for a freshly minted credential
+     * instead of relying on one captured at clone time.
+     */
+    credentialHelperPath?: string;
+    /**
+     * When set, the temp SSH key is handed to the job rather than deleted when
+     * the clone returns — which is what lets a later step push. Omit and the
+     * existing cleanup applies unchanged.
+     */
+    sshCleanupRegistry?: SshCleanupRegistry;
 }
+/** Hands SSH key cleanup to the job, so the key outlives the clone. */
+export interface SshCleanupRegistry {
+    defer(cleanup: () => Promise<void>): void;
+}
+/**
+ * Point a clone at the agent's credential helper.
+ *
+ * Only the helper PATH is written — never a secret — which is what makes it
+ * safe to persist in `.git/config`. `useHttpPath` makes git include
+ * `path=owner/repo.git` in every credential query, without which the helper
+ * could not tell one repository from another and a write grant could not be
+ * confined to its own repo.
+ */
+export declare function configureCredentialHelper(workDir: string, helperPath: string): void;
 /**
  * Shallow-clone a git repository at a specific ref with optional token auth.
  *

package/dist/checkout/grant-table.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Live write grants for this job.
+ *
+ * `withWrite` adds a grant before running its callback and revokes it in a
+ * `finally`; the TTL is a backstop so a step that crashes cannot leave one
+ * standing. The credential helper consults this table to decide whether to ask
+ * the broker for a read-only or an elevated credential.
+ *
+ * Scope note, stated because the name could mislead: a grant is scoped to a
+ * REPOSITORY and a TIME WINDOW — not to a step. The agent forks one process per
+ * job and `parallel()` runs its children inside that process, so a concurrent
+ * sibling step can push to the same repository while a grant is live. It cannot
+ * reach a different repository.
+ */
+export interface WriteGrant {
+    /** `owner/repo`, however git spelled it. */
+    repoPath: string;
+    permissions: Readonly<Record<string, string>>;
+    /** Epoch millis after which the grant is dead regardless of revocation. */
+    expiresAt: number;
+}
+export declare class GrantTable {
+    private readonly grants;
+    add(grant: WriteGrant): string;
+    revoke(grantId: string): void;
+    lookup(repoPath: string, now?: number): WriteGrant | null;
+    /** Live grant count, after reaping expired entries. Test and diagnostics use. */
+    size(now?: number): number;
+}
+//# sourceMappingURL=grant-table.d.ts.map

package/dist/checkout/job-git-credentials.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-job git credential plumbing.
+ *
+ * Owns the three things a job needs to authenticate git: the grant table, the
+ * helper socket git talks to, and the relay to the orchestrator broker. Kept in
+ * its own module so the job runner wires one object rather than three, and so
+ * this logic is testable without standing up a job.
+ *
+ * Scope: this is the HOST path, which covers bare-metal jobs. A container job
+ * clones and executes inside the container today and has no route to the
+ * socket; that is fixed by the dual-mode container work, which moves the clone
+ * to the host and injects `/opt/kici` read-only.
+ */
+import type { GitGrantRequestIpc, GitGrantResponseIpc } from '../execution/sandbox/ipc-protocol.js';
+export interface JobGitCredentials {
+    /** Path to pass as `credential.helper` on every clone this job makes. */
+    helperPath: string;
+    /** Handler for `git.grant.request` IPC from the sandbox runner. */
+    onGitGrantRequest: (request: GitGrantRequestIpc) => Promise<GitGrantResponseIpc>;
+    /**
+     * Attach the job's declared credential to an outgoing broker request.
+     *
+     * `ctx.kici.git.github.getToken()` reaches the orchestrator directly rather
+     * than through the credential helper, so without this it would carry no ref
+     * and fall back to the source credential.
+     */
+    withRef(params: Record<string, unknown>): Record<string, unknown>;
+    /** Release the socket. Safe to call more than once. */
+    close(): Promise<void>;
+}
+/**
+ * Stand up git credentials for one job.
+ *
+ * `sendApiRequest` is the agent's existing orchestrator relay — the same one
+ * `ctx.kici` uses — so this adds no new transport.
+ */
+export declare function startJobGitCredentials(args: {
+    jobId: string;
+    /**
+     * Named credentials declared on the job (`gitCredentials`), carried through
+     * the lock file in `jobConfig`. Values are SECRET NAMES; the orchestrator
+     * resolves them. `default` applies when a call names none.
+     */
+    credentials?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /** Job-scoped directory for the socket and shim. */
+    dir: string;
+    sendApiRequest: (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+}): Promise<JobGitCredentials>;
+//# sourceMappingURL=job-git-credentials.d.ts.map

package/dist/checkout/write-elevation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Open a write window for one repository, pre-flighting the grant.
+ *
+ * The mint happens HERE — at elevation entry, before any git runs — and the
+ * forge returns the permissions it actually granted. Comparing the two turns
+ * "wrong permission requested" from a cryptic push-time git failure at the end
+ * of a long build into a legible failure at the call site.
+ *
+ * What pre-flight proves: the TOKEN holds the permission. What it cannot prove:
+ * that the push will succeed. A branch protection rule or repository ruleset
+ * can still reject, and no token inspection predicts that.
+ */
+import type { GrantTable } from './grant-table.js';
+type Permissions = Readonly<Record<string, string>>;
+type Grant = {
+    scoped: false;
+} | {
+    scoped: true;
+    permissions: Record<string, string>;
+};
+/** Requested entries the grant does not satisfy, as `key=value` strings. */
+export declare function missingPermissions(requested: Permissions, granted: Permissions): string[];
+export interface ElevateArgs {
+    repository: string;
+    permissions: Permissions;
+    grants: GrantTable;
+    request: (args: {
+        repository: string;
+        permissions: Permissions;
+    }) => Promise<{
+        grant: Grant;
+        expiresAt: string | null;
+    }>;
+}
+export declare function elevateForWrite(args: ElevateArgs): Promise<{
+    grantId: string;
+    granted: Grant;
+}>;
+export {};
+//# sourceMappingURL=write-elevation.d.ts.map

package/dist/config.d.ts

@@ -6,6 +6,12 @@ export declare const ExecutionMode: z.ZodEnum<{
     firecracker: "firecracker";
 }>;
 export type ExecutionMode = z.infer<typeof ExecutionMode>;
+/** When the operator between-jobs reset command runs. */
+export declare const BetweenJobsRunOn: z.ZodEnum<{
+    always: "always";
+    "on-failure": "on-failure";
+}>;
+export type BetweenJobsRunOn = z.infer<typeof BetweenJobsRunOn>;
 declare const configSchema: z.ZodObject<{
     orchestratorUrl: z.ZodString;
     agentId: z.ZodOptional<z.ZodString>;
@@ -45,6 +51,14 @@ declare const configSchema: z.ZodObject<{
     sandboxMemoryBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     sandboxNanoCpus: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     scalerManaged: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean, string | undefined>>;
+    jobImageAgent: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean, string | undefined>>;
+    runtimeImage: z.ZodOptional<z.ZodString>;
+    runtimeNodeSource: z.ZodOptional<z.ZodString>;
+    containerBuildCli: z.ZodOptional<z.ZodEnum<{
+        docker: "docker";
+        podman: "podman";
+    }>>;
+    scalerClaimCode: z.ZodOptional<z.ZodString>;
     scalerIdleTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     scalerPendingDispatchTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     executionMode: z.ZodOptional<z.ZodEnum<{
@@ -55,6 +69,14 @@ 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>>;
+    betweenJobsResetCommand: z.ZodOptional<z.ZodString>;
+    betweenJobsResetTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    betweenJobsResetRunOn: z.ZodDefault<z.ZodEnum<{
+        always: "always";
+        "on-failure": "on-failure";
+    }>>;
+    orphanCleanup: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
+    drainOnResetFailure: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
 }, z.core.$strip>;
 /**
  * App configuration type. Includes computed agentId when not provided.
@@ -96,12 +118,22 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     sandboxMemoryBytes: number;
     sandboxNanoCpus: number;
     scalerManaged: boolean;
+    jobImageAgent: boolean;
+    runtimeImage?: string | undefined;
+    runtimeNodeSource?: string | undefined;
+    containerBuildCli?: "docker" | "podman" | undefined;
+    scalerClaimCode?: string | undefined;
     scalerIdleTimeoutMs: number;
     scalerPendingDispatchTimeoutMs: number;
     executionMode?: "bare-metal" | "container" | "firecracker" | undefined;
     otelExporterOtlpEndpoint?: string | undefined;
     concurrencyWaitTimeoutMs: number;
     isOrchestratorHost: boolean;
+    betweenJobsResetCommand?: string | undefined;
+    betweenJobsResetTimeoutMs: number;
+    betweenJobsResetRunOn: "always" | "on-failure";
+    orphanCleanup: boolean;
+    drainOnResetFailure: boolean;
 }>;
 /**
  * Load and validate agent configuration from environment variables.
@@ -132,10 +164,16 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
  * - 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_CLAIM_CODE (optional single-use claim code the agent exchanges for its own ephemeral credentials before registering; ignored when KICI_AGENT_TOKEN is set)
  * - 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`
+ * - KICI_AGENT_BETWEEN_JOBS_RESET_COMMAND (optional) — host-reset command run between jobs on a reused agent (fail-open)
+ * - KICI_AGENT_BETWEEN_JOBS_RESET_TIMEOUT_MS (default: 60000) — reset command timeout
+ * - KICI_AGENT_BETWEEN_JOBS_RESET_RUN_ON (default: always, options: always | on-failure) — when the reset command runs
+ * - KICI_AGENT_ORPHAN_CLEANUP (default: true) — reap a finished job's leaked process tree (bare-metal); false = only signal the runner child
+ * - KICI_AGENT_DRAIN_ON_RESET_FAILURE (default: false) — drain the agent after repeated consecutive reset failures
  */
 export declare function loadConfig(): AppConfig;
 /**