@kici-dev/agent 0.6.0 → 0.7.0

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

@@ -1,4 +1,4 @@
-import type { CheckMode, CheckStepOutcome, LogStream } from '@kici-dev/engine';
+import type { CheckMode, CheckStepOutcome, LogStream, ProvenanceContext } from '@kici-dev/engine';
 import type { SandboxStepResult } from './types.js';
 /**
  * Structured clone auth. Wire-compatible with `gitAuthSchema` on the
@@ -500,6 +500,11 @@ export type AgentToRunnerMessage = ExecuteMessage | AbortMessage | EventEmitResp
  * The runner uses this to clone, install deps, compile, and execute steps.
  */
 export interface JobExecutionRequest {
+    /**
+     * Operator opt-out from `--ignore-scripts` on the `.kici/` dependency install
+     * (`KICI_ALLOW_INSTALL_SCRIPTS` on the agent). Absent means scripts stay off.
+     */
+    allowInstallScripts?: boolean;
     /**
      * Run UUID. Threaded into the step context so the OIDC token relay can name
      * the job/run a request is bound to. Correlation only — the orchestrator
@@ -550,6 +555,7 @@ export interface JobExecutionRequest {
     credentialHelperPath?: string;
     /** SHA-256 hash of the source tarball bytes for integrity verification. */
     sourceTarHash?: string;
+    sourceTarDigest?: string;
     /** URL to pre-built dependency tarball (skip install if present). */
     depsUrl?: string;
     /** SHA-256 hash of the dependency tarball for integrity verification. */
@@ -627,14 +633,16 @@ export interface JobExecutionRequest {
     /** Git provider that originated the triggering event (e.g. 'github', 'forgejo'). */
     provider?: string;
     /**
-     * Platform provenance issuer, threaded from the orchestrator for a deferred
-     * attestation's frozen `builder.id`. Best-effort: absent when the orchestrator
-     * has no issuer wired (e.g. never authenticated to the Platform), in which
-     * case the frozen statement records an unknown issuer honestly. Not
-     * verification load-bearing — a deferred bundle's later token binds to the
-     * frozen statement by hash, and the authoritative org id lives in that token.
+     * The orchestrator's own view of this build, from the job dispatch.
+     *
+     * Verification load-bearing. A deferred attestation's frozen statement is
+     * built from this so it is field-for-field what a live mint would have
+     * produced, and the orchestrator therefore cross-checks it against its own
+     * run row before storing it. Absent from an older orchestrator's dispatch, in
+     * which case the agent falls back to its local guess — a statement the
+     * capture check rejects, so the defer is dropped rather than stored unchecked.
      */
-    provenanceIssuer?: string;
+    provenanceContext?: ProvenanceContext;
     /** Whether to checkout the repo (default: true). */
     checkout?: boolean;
     /** Whether this job is part of a developer-initiated run triggered by `kici run`. */
@@ -739,5 +747,71 @@ export interface JobExecutionRequest {
         declaredNeeds?: readonly unknown[];
     };
 }
+/** Which evaluation the child should perform. */
+export type EvalRequestKind = 'init' | 'dynamic-job' | 'build-verify' | 'global-eval';
+/**
+ * One evaluation request. `config` is the dispatch's own `jobConfig` and
+ * `dispatch` the fields the evaluation reads, both passed through verbatim so
+ * the child builds the same contexts the agent used to build in-process.
+ *
+ * Carries no `secrets` and no `namespacedSecrets`: no evaluation surface
+ * consumes them, and adding them would put job secrets in the one process that
+ * runs customer module code.
+ */
+export interface EvalRequest {
+    kind: EvalRequestKind;
+    /** Absolute path of the already-materialized working directory. */
+    workDir: string;
+    /** The dispatch's `jobConfig`, verbatim. */
+    config: Record<string, unknown>;
+    /** The dispatch fields an evaluation reads (repo URL, ref, sha, auth, …). */
+    dispatch: Record<string, unknown>;
+}
+/** Instruct the eval child to run one evaluation. */
+interface EvalExecuteMessage {
+    type: 'eval';
+    request: EvalRequest;
+}
+/** Response to an `eval.api.request` the child relayed. */
+interface EvalApiResponseMessage {
+    type: 'eval.api.response';
+    id: string;
+    result?: unknown;
+    error?: string;
+}
+export type AgentToEvalMessage = EvalExecuteMessage | EvalApiResponseMessage;
+/** The eval child is initialized and ready to receive a request. */
+interface EvalReadyMessage {
+    type: 'ready';
+}
+/** One captured console / subprocess line, streamed onto the synthetic step-0 log. */
+interface EvalLogLineMessage {
+    type: 'log.line';
+    line: string;
+    stream?: LogStream;
+}
+/**
+ * Relay for `ctx.kici`. The one privileged message on this union, and it is
+ * privilege preservation rather than expansion: a `DynamicJobFn` and a
+ * global-eval generator are already handed a `kici` API built on this exact
+ * transport, so withholding it would break a documented SDK surface.
+ */
+interface EvalApiRequestMessage {
+    type: 'eval.api.request';
+    id: string;
+    method: string;
+    params: Record<string, unknown>;
+}
+/** The evaluation finished. `result` is the kind's own serialized outcome. */
+interface EvalResultMessage {
+    type: 'eval.result';
+    result: unknown;
+}
+/** The evaluation threw. */
+interface EvalErrorMessage {
+    type: 'eval.error';
+    error: string;
+}
+export type EvalToAgentMessage = EvalReadyMessage | EvalLogLineMessage | EvalApiRequestMessage | EvalResultMessage | EvalErrorMessage;
 export {};
 //# sourceMappingURL=ipc-protocol.d.ts.map

package/dist/execution/sandbox/job-network.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Egress filtering for nested job containers.
+ *
+ * A job container joins a dedicated `kici-jobs` bridge network, and the agent
+ * installs the same RFC1918 + cloud-metadata nftables drops the orchestrator's
+ * scaler installs for agent containers. Without them a job container keeps the
+ * runtime's default bridge, which reaches `169.254.169.254` and the host's whole
+ * private network — a step can take the instance role or sweep the customer's
+ * internal services.
+ *
+ * The rule builder is `@kici-dev/shared`'s, so the agent and the scaler apply
+ * one implementation rather than two copies that drift.
+ *
+ * `network: 'host'` (from `KICI_SANDBOX_NETWORK=host` or a per-job
+ * `sandbox: { network: 'host' }` grant) bypasses this by construction: asking
+ * for the host namespace is asking for the host's network.
+ */
+import type Docker from 'dockerode';
+import { JOB_NETWORK_SUBNET, type NetworkPolicy } from '@kici-dev/shared/net';
+/** Bridge network every filtered job container joins. */
+export declare const JOB_NETWORK_NAME = "kici-jobs";
+/**
+ * Subnet for {@link JOB_NETWORK_NAME}. Distinct from the scaler's agent network.
+ *
+ * Defined in `@kici-dev/shared/net` and re-exported here: the Firecracker host
+ * provisioner must recognise this subnet's rules to leave them alone, and it
+ * cannot import from the agent package.
+ */
+export { JOB_NETWORK_SUBNET };
+/** Gateway for {@link JOB_NETWORK_NAME} — the one destination the rules allow. */
+export declare const JOB_NETWORK_GATEWAY = "172.31.0.1";
+/**
+ * Resolve what a job container may reach on the host.
+ *
+ * The default is DNS on the bridge gateway and nothing else. A job container
+ * talks to the agent through `docker exec` rather than over the network, and it
+ * holds none of the agent's credentials, so name resolution is the one host
+ * service it genuinely needs. That carve-out is not cosmetic: rootful podman
+ * runs its resolver on the gateway, a host address, so a container with no such
+ * rule cannot resolve any name at all. Docker answers inside the container's
+ * own netns and is unaffected either way.
+ *
+ * The set is derived HERE, from the agent's own configuration, and takes no
+ * argument that could widen it. A `NetworkPolicy` reaching
+ * {@link applyJobEgressRules} governs the FORWARD hook only — what the job
+ * reaches through the host — so its `hostAccess` is deliberately not consulted:
+ * a job that could name its own host reachability is the escape hatch this
+ * boundary exists to close, and a signature that cannot carry one is what makes
+ * that structural rather than a convention.
+ */
+export declare function resolveJobHostAccess(gateway?: string): string[];
+/**
+ * Ensure the `kici-jobs` network exists, the nftables table is ready, and the
+ * subnet's default egress drops are installed.
+ *
+ * The drops land here — before any job container is created — and are keyed on
+ * the subnet rather than on a container address, so a customer image's own
+ * `ENTRYPOINT` never runs unfiltered.
+ *
+ * Returns whether egress filtering is actually in force. A host without `nft`
+ * or without `NET_ADMIN` — a rootless agent, most commonly — warns loudly and
+ * degrades to the network with no rules rather than refusing to run any job:
+ * `kici-admin agent install` is a compat-protected surface, and hard-requiring
+ * NET_ADMIN would break every existing rootless install with no additive path.
+ * The same trade-off the scaler already made for agent containers.
+ */
+export declare function ensureJobNetwork(docker: Docker): Promise<boolean>;
+/**
+ * Apply the per-container egress rules once the container has an IP.
+ *
+ * This is the per-job layer, not the control: the subnet drop set
+ * {@link ensureJobNetwork} installs is already in the chain and already covers
+ * this container. What a per-container rule set adds is a place to key a future
+ * per-job policy — an allowlist or `denyAll` — on one address rather than on
+ * the whole bridge.
+ *
+ * Returns the container IP the rules are keyed on, so teardown can remove
+ * exactly those rules; `undefined` when no IP could be read, which is logged
+ * rather than thrown — a job whose rules could not be keyed still runs behind
+ * the subnet drops, and the operator sees why.
+ */
+export declare function applyJobEgressRules(docker: Docker, containerId: string, policy: NetworkPolicy | undefined): Promise<string | undefined>;
+/**
+ * Remove the per-container rules at teardown.
+ *
+ * Never throws: a failed cleanup must not turn a finished job into a failed
+ * one. A leaked rule set is keyed on an IP the network will reuse, so it is
+ * reported at `warn` for the operator rather than swallowed.
+ */
+export declare function removeJobEgressRules(containerIp: string | undefined): Promise<void>;
+//# sourceMappingURL=job-network.d.ts.map

package/dist/execution/sandbox/log-masker.d.ts

@@ -7,6 +7,7 @@
  * Performance: Builds a single combined regex from all secret values, so each
  * log line is scanned in a single pass (not O(secrets * lines)).
  */
+import type { JobExecutionRequest, RunnerToAgentMessage } from './ipc-protocol.js';
 /**
  * Masks secret values in log lines.
  *
@@ -29,6 +30,21 @@ export declare class LogMasker {
      * Authorization: Basic headers, base64-encoded config values).
      * Values are sorted by length descending so longer values are matched first
      * (prevents partial masking when one secret is a substring of another).
+     *
+     * Multi-line values additionally register each of their individual lines.
+     * Log output is split into lines before it reaches the masker, so a value
+     * containing a newline can never match as a whole — a PEM private key or a
+     * kubeconfig would otherwise stream in clear text. Two consequences of the
+     * per-line registration are deliberate:
+     *
+     * - `MIN_MASK_LENGTH` is 3, so short structural lines of a structured secret
+     *   are registered too. A `---` YAML separator or a bare `{` from a
+     *   service-account JSON is masked wherever it appears in that job's logs.
+     * - PEM header and footer lines (`-----BEGIN OPENSSH PRIVATE KEY-----`) are
+     *   not secret on their own and are masked as a side effect.
+     *
+     * Both are strictly safer than leaking the body, and no heuristic separates a
+     * structural line from a body line without risking the reverse mistake.
      */
     registerSecrets(secrets: Record<string, string>): void;
     /**
@@ -42,4 +58,26 @@ export declare class LogMasker {
      */
     hasSecrets(): boolean;
 }
+/**
+ * Create a LogMasker initialized with all secret values from the request.
+ *
+ * Collects values from both flat secrets and all namespaced context secrets,
+ * deduplicating before registration.
+ *
+ * Both the runner child and the agent-side fork runner build a masker from the
+ * same request, so the crash tail the agent assembles from the child's stderr is
+ * masked with the same value set the child used for its own log lines.
+ */
+export declare function createSecretMasker(request: JobExecutionRequest): LogMasker;
+/**
+ * Mask every operator-visible text field of an outbound runner message.
+ *
+ * Each message type carrying free text is named here, so a new text-bearing
+ * message type is a visible omission rather than a silent leak. `step.complete`
+ * error text and the `job.complete` failure reason are persisted on the step and
+ * run rows the dashboard renders, so they need the same masking `log.line` gets.
+ *
+ * Returns the message unchanged when no secrets are registered.
+ */
+export declare function maskMessageText(msg: RunnerToAgentMessage, masker: LogMasker): RunnerToAgentMessage;
 //# sourceMappingURL=log-masker.d.ts.map

package/dist/execution/sandbox/types.d.ts

@@ -155,6 +155,12 @@ export interface JobExecutionOptions {
      * see the dual-mode container work.
      */
     credentialHelperPath?: string;
+    /**
+     * Operator opt-out from `--ignore-scripts` on the `.kici/` dependency install
+     * (`KICI_ALLOW_INSTALL_SCRIPTS`). Sourced from agent config only, so a
+     * dispatch payload or a workflow cannot re-enable lifecycle scripts.
+     */
+    allowInstallScripts?: boolean;
     /**
      * Callback for relaying a provenance bundle upload request from the sandbox to
      * the orchestrator. The sandbox runner sends `provenance.request` IPC; the

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

@@ -74,7 +74,7 @@ export declare function buildStepNeedsContext(declaredNeeds: readonly unknown[]
  * step$.log would only set it on the function object and NOT propagate to the
  * AsyncLocalStorage store that zx uses for ProcessPromise snapshots.
  */
-export declare function buildSandboxShell(cwd: string, stepIndex: number, maskedSendFn: (msg: RunnerToAgentMessage) => void): typeof $;
+export declare function buildSandboxShell(cwd: string, stepIndex: number, maskedSendFn: (msg: RunnerToAgentMessage) => void, signal?: AbortSignal): typeof $;
 /**
  * Resolve the on-the-wire event name for `ctx.emit`. Accepts either an ad-hoc
  * event-name string or a `defineEvent()` definition object (passed by the typed

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

@@ -6,10 +6,10 @@
  * into a deterministic gzip tarball. The tarball bytes are hashed for
  * integrity verification on the execution-job side.
  *
- * The artifact is content-addressed by the compiler's `contentHash` (hash of
- * the raw workflow entry + asset digest), not by the tarball bytes — so the
- * orchestrator's cache lookup keys unchanged while the stored bytes switch
- * from a Rolldown bundle to a raw-source tarball.
+ * The returned hash is the tarball's OWN digest. The orchestrator stores the
+ * object under it and the restoring agent verifies the downloaded bytes against
+ * it, the same contract the dependency tarball has always had; a separate
+ * pointer resolves the workflow `contentHash` to it.
  */
 export declare function packKiciSource(workDir: string): Promise<{
     tarball: Buffer;

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

@@ -2,22 +2,37 @@
  * `.kici/` source tarball restoration for execution agents.
  *
  * Downloads a pre-built `.kici/` source tarball from the orchestrator's cache
- * and extracts it into `workDir/` so the workflow entry point becomes
+ * and installs it at `workDir/.kici` so the workflow entry point becomes
  * importable. Mirrors the shape of `dep-restore.ts` but without the streaming
  * optimization — source tarballs are tiny (kilobytes, not the hundreds of
  * megabytes a `node_modules/` tarball carries).
  *
- * Note on integrity: `dispatch.sourceTarHash` is the workflow `contentHash`
- * (computed over the raw source per `workflow-loader.ts::computeContentHash`),
- * not the SHA-256 of the tarball bytes. The shared S3 cache key is derived
- * from that same contentHash, so a signed GET URL from the orchestrator
- * already establishes provenance for restored tarballs. Every
- * `loadWorkflowSource` call site — build, init, and dynamic eval — passes
- * the dispatched `contentHash` (and `resolvedHashFiles` when present) so
- * the lock-vs-source drift gate fires at each author-TS load site, not
- * only the build phase. That closes the corner cases where init or eval
- * runs without a preceding build (cache infrastructure unavailable, or a
- * build job that failed but left dynamic dispatch in flight).
+ * Two properties this path is responsible for, both of which it previously
+ * lacked:
+ *
+ * **Verification.** `dispatch.sourceTarDigest` is the SHA-256 of the tarball's
+ * own bytes, so the download is checked before anything is extracted — the same
+ * contract `restoreDeps` has always had via `depsHash`. The older
+ * `dispatch.sourceTarHash` field carries the workflow `contentHash` instead, so
+ * it never could serve this purpose; it stays on the wire for older peers and
+ * is deliberately not used as a verification input here. When no digest is
+ * dispatched (an older orchestrator, or a source that did not come from the
+ * content-addressed cache) the restore proceeds unverified rather than failing,
+ * so a mixed-version rollout still runs.
+ *
+ * **Replacement, not overlay.** Extraction lands in a scratch directory and the
+ * result REPLACES `workDir/.kici` wholesale, save for `node_modules/` — the one
+ * directory the tarball deliberately omits, which the deps restore has already
+ * written by the time this runs. Extracting over the existing tree left any file
+ * the tarball no longer carries in place, so a helper the author deleted
+ * survived every warm-cache run and kept being imported.
+ */
+/**
+ * Download, verify, and install the `.kici/` source tree.
+ *
+ * @param workDir - Root of the cloned repository; `.kici` is replaced under it
+ * @param sourceTarUrl - `http://`, `https://`, or `file://` URL to the tarball
+ * @param sourceTarDigest - Expected SHA-256 of the tarball bytes, when known
  */
-export declare function restoreSource(workDir: string, sourceTarUrl: string): Promise<void>;
+export declare function restoreSource(workDir: string, sourceTarUrl: string, sourceTarDigest?: string): Promise<void>;
 //# sourceMappingURL=source-restore.d.ts.map

package/dist/execution/workflow-loader.d.ts

@@ -34,20 +34,21 @@ export interface SdkOutputSetters {
  * ESM modules by resolved URL, so importing that path yields the workflow's live
  * singleton, not a fresh copy.
  *
- * Falls back to the agent's bundled setters when resolution fails (mirrors
+ * Both specifiers resolve to the same module-global maps — `internal.ts` and the
+ * root barrel re-export the same `outputs.js` bindings — so the fallback below
+ * changes which entry is imported, never which singleton is mutated.
+ *
+ * Falls back to the agent's bundled setters when neither resolves (mirrors
  * `resolveSdkSetters` in the compiler's test runner).
  */
 export declare function resolveWorkflowSdkSetters(workflowFilePath: string): Promise<SdkOutputSetters>;
 /**
- * Compile schema version — must match `@kici-dev/compiler` lockfile/hasher.ts.
- * Mixed into the content hash so compilation-approach changes produce different
- * hashes. Bumped 3 → 4 when the artifact model switched from a Rolldown-bundled
- * `.compiled.mjs` to a raw-source tarball consumed by the oxc-transform ESM
- * loader hook. Bumped 4 → 5 when the hash input started normalizing line
- * endings (CRLF → LF) so a Windows agent's checked-out CRLF source matches a
- * Linux compiler's LF source.
+ * Compile schema version, re-exported from its single definition in
+ * `@kici-dev/core/kici-source-digest`. The compiler mixes the same constant
+ * into every `contentHash` it writes, so a second copy here is exactly how a
+ * producer and its verifier drift apart.
  */
-export declare const COMPILE_SCHEMA_VERSION = 5;
+export { COMPILE_SCHEMA_VERSION } from '@kici-dev/core/kici-source-digest';
 export declare function ensureLoaderHookRegistered(): void;
 /**
  * Load a workflow module by dynamic-importing its source file.
@@ -57,10 +58,12 @@ export declare function ensureLoaderHookRegistered(): void;
  * `node_modules/` the same way any `tsx`-style runner would — so host-repo
  * helpers and `@kici-dev/sdk` Just Work.
  *
- * When `expectedContentHash` is provided, verifies the raw source matches
- * the hash in the lock file. Drift between source and lock file produces a
- * descriptive error that surfaces the baked agent SDK fingerprint (useful
- * when debugging "is the agent running a stale build?").
+ * When `expectedContentHash` is provided, verifies the extracted `.kici/` tree
+ * matches the hash in the lock file. It re-hashes the whole tree, not the entry
+ * file alone, so an edit to an imported helper is caught — that was the gap
+ * that let a warm cache restore a stale tarball and run the OLD helper green.
+ * Drift produces a descriptive error that surfaces the baked agent SDK
+ * fingerprint (useful when debugging "is the agent running a stale build?").
  */
 export declare function loadWorkflowSource(workDir: string, sourceFile: string, expectedContentHash?: string, resolvedHashFiles?: string[]): Promise<{
     module: Record<string, unknown>;

package/dist/execution/yarnrc-berry-config.d.ts

@@ -10,10 +10,12 @@
  *
  * `nodeLinker: node-modules` makes berry lay down a real `node_modules` tree
  * (no PnP `.pnp.cjs`), so the agent's packer / restore / sibling-walk /
- * workflow-loader work unchanged. `enableScripts: false` (when a private
- * registry is configured) keeps dependency lifecycle scripts from seeing the
- * synthesized token env vars — the same security model as npm/pnpm/classic
- * `--ignore-scripts`.
+ * workflow-loader work unchanged. `enableScripts: false` keeps dependency
+ * lifecycle scripts from running at all — for every install, not only one
+ * against a private registry — the same security model as npm/pnpm/classic
+ * `--ignore-scripts`. An operator opts back in with
+ * `KICI_ALLOW_INSTALL_SCRIPTS=true`, which arrives here as
+ * `ignoreScripts: false`.
  *
  * Reuses the same `ApplyNpmRegistryConfigArgs` / `ApplyNpmRegistryConfigResult`
  * shapes as the npm overlay so `dep-installer` can pick either by flavor.